Add verifiable visual redaction of shared copies with the original left sealed

[ChelseaKR]

What

Shared copies can already have location stripped by policy. Photographs of a bedroom mould patch often include a child, a face, or a prescription bottle. Add visual redaction for shared copies: the tenant draws boxes in the app (or supplies coordinates on the CLI), the derived copy is rendered with those regions blacked out, and a redaction record (region list, method, hash of the derived copy) is committed to custody and bound to the sealed original. The packet shows the redacted copy, states "N regions redacted by the tenant", and verify proves the derived copy descends from the sealed original whose hash the timestamp covers.

Why it matters

The threat model is a landlord who retaliates; over-sharing is a harm the tool should prevent at the point of export, and minimal disclosure (docs/legal/minimal-disclosure.md, RR-15) is a stated goal. Doing it verifiably keeps the tamper-evidence story intact: the original is never edited, and a reviewer later granted the original can confirm the redaction was only what was declared. It reuses the media-policy pipeline that already produces location-stripped copies.

Scope

• A redaction record type; capture redact on the CLI and an app editor with keyboard-operable region entry; a pure-Python raster fill for JPEG and PNG.
• Disclosure policy and packet copy (EN/ES); a decision-table row.
• A guard test: the sealed original's bytes and hash are unchanged by any redaction.

Out of scope

• Automatic face or text detection.
• Redacting video or audio (declared as a limit).

Done when

• A redacted copy verifies as derived from its original with the declared regions; an undeclared extra edit fails.
• The original in the vault is byte-identical before and after.
• A redaction with an empty region list is refused.

Pointers

• src/habitable/media.py, src/habitable/disclosure.py, src/habitable/evidence.py, src/habitable/htmlpacket.py, docs/legal/minimal-disclosure.md
• docs/RESEARCH-ROADMAP.md (RR-15); Restore scoped and rehashed custody views (P0 restoration, workstream A) #262

Proposed with AI assistance.

[ChelseaKR]

Triage: buildable, and the premise needs one correction.

Five-check against origin/main @ bf631af. The word redact appears in seven modules (share.py, disclosure.py via evidence.py, model.py, vault.py, relay.py, appserver.py, cli.py) — but that is field-level redaction in the disclosure policy, not visual redaction of image content. There is no region list, no raster fill, no redaction record type and no decision-table row for one. So the ask is genuinely unbuilt, and the issue's own framing (shared copies can already have location stripped by policy) is the accurate one.

The design is right in the way that matters: the sealed original is never edited, the derived copy carries the boxes, and verify proves descent. That keeps the tamper-evidence story intact instead of trading it for privacy.

Left for a builder, with the one warning worth writing down before anyone starts:

A redaction that can be undone is worse than no redaction. The failure mode is not cryptographic — it is that the "blacked out" region is composited in a way that leaves the original pixels recoverable, which has burned larger projects than this one repeatedly. The guard test must assert the derived copy's bytes contain no recoverable original content in the redacted regions, not merely that the rendered image looks black. The issue's existing guard (the sealed original's bytes and hash are unchanged) protects the evidence chain but not the tenant — both tests are needed.

Second note: pure-Python raster fill for JPEG and PNG is the right instinct for avoiding a dependency, but JPEG is lossy and block-structured, so a fill-and-re-encode changes the whole image, not the region. Whether that matters for the descent proof should be settled before implementation.

Related: #262 (the scoping work this sits beside), docs/legal/minimal-disclosure.md.

---

Triage pass against origin/main @ bf631af. Verdict only; nothing was changed. Prepared with AI assistance.

[ChelseaKR]

Measured: this is not blocked on additionalProperties: false

This issue was parked behind the packet-format question #313 frames. I measured it rather
than inheriting it, and the answer changes the shape of the block.

Method. docs/packet-bundle.schema.json at main (5d5ad26), validated with
jsonschema 4.26.0 under Draft 2020-12 in a throwaway venv kept out of the repository.
Baseline: all seven committed bundles validated unmutated, so pre-existing errors are
subtracted (packet-v1 missing archive_timestamps, packet-v4's three custody actions
— both #313's, both still present). Then the minimal document mutation this issue's own
Done when demands was applied to tests/golden/packet-v4/bundle.json (the richest
corpus member: 2 items, 1 artifact, 1 relationship, 1 v3 timeline entry, 13 custody
entries) and the error set diffed against the baseline.

Two controls fired, so the probe can return a rejection: adding kind to a v3 timeline
entry is refused by that object's not/required guard, and a non-string value in
custodyEntry.details is refused by its additionalProperties: {"type": "string"}.

Verdict for #303: not blocked, provided the redaction is modelled on the item and not as a relationship.

shape	validates?
item.redaction = {redaction_schema, method, regions: [{x,y,w,h}], derived_hash}	yes — item is additionalProperties: true
custody binding via the existing copied_for_sharing action with details: {"content_hash": …, "shared_hash": …, "stripped": "gps", "redacted_regions": "1", "redaction_method": "opaque_fill"}	yes — custodyEntry.details is an open map, values must be strings (a list or an int there is rejected; that was one of the two controls)
relationships[] = {relationship_type: "redacted_copy_of", …, regions: [...]}	no — two refusals: /$defs/relationship is additionalProperties: false so regions is rejected, and relationship_type has no redacted_copy_of value

So the answer to "which object and which property" is /$defs/relationship and regions —
but only for the relationship-shaped design, and that design is avoidable. The item-shaped
one carries the same facts, sits next to shared_name/shared_hash/stripped which already
describe the derived copy, and validates today.

The verification story survives the move. shared_hash already binds the derived copy to
the item whose content_hash the timestamp token covers, so "the derived copy descends from
the sealed original" is a check the packet can already express; the redaction record adds
what was removed, which is what a later reviewer granted the original needs in order to
confirm the redaction was only what was declared.

One note on the guard test. "The original in the vault is byte-identical before and
after" is the load-bearing assertion, and it passes trivially if the redaction path never
ran. Assert in the same test that the derived copy's hash did change — otherwise a
no-op redaction reads as a perfectly preserved original.

The general correction, for all six

additionalProperties: false on seven objects is not what holds this set. Every one of
the six has a shape that validates against the published schema exactly as it stands today,
because item, issue, timelineEntryV3 (top level), custodyProof, timestampToken,
appendix, scope, handoffManifest, signature and the document root are all
additionalProperties: true.

What actually rejects is the closed vocabularies — and those are on a different axis
from object closedness, which is why naming the seven closed objects does not describe the
constraint:

vocabulary	where	closed object?
custodyEntry.action	8 values	yes
artifact.artifact_type	13 values	yes
relationship.relationship_type	11 values	yes
workflowIntegrity.custody_action	2 values	yes
timelineEntryV3.integrity.custody_action	const — one value	yes
timelineEntryV3.event_type	9 values	no, the object is open
timelineEntryV3.source	6 values	no, the object is open
timestampToken.kind	2 values	no, the object is open
item.record_kind	2 values	no, the object is open

And the two are not the same kind of breakage, which is the part worth settling once:

• A new optional field on an open object is invisible to a consumer following the rule
  docs/bundle-schema.md already states — "consumers must ignore unknown fields". It costs
  nothing and needs no version bump.
• A new enum value cannot be ignored. The published schema itself rejects the packet, so
  a third party who pinned the $id fails on a document this code considers valid. That is
  the same failure additionalProperties: false produces, arrived at from the other
  direction, and it is where five of these six touch the contract. The machinery that
  already exists for it is packet_version plus the verifier's forward rejection.

So the decision the six are really waiting on is "may a feature mint a new custody action /
artifact type / relationship type inside packet_version 4, or does that need 5?" — not
"should the seven objects be reopened?". Only #300 needs a new property on a closed
object, and even #300 is reachable without one.

Reproduction script (not committed): the mutation set and its two controls are in the
campaign scratch as probe_six.py; every number above is from a run of it.

Prepared with AI assistance; reviewed before submission.

[ChelseaKR]

Measured: the "pure-Python raster fill" constraint does not exist, and the real constraint is that a JPEG shared copy cannot carry a checkable redaction

I built #296 in this lane and did not start this one. But #296's triage described #303 as needing "a pure-Python raster fill for JPEG and PNG" against "a project whose minimal-dependency rule is load-bearing", and that framing is wrong in a way that changes the size and the shape of the work. Everything below is measured against main @ c13ce4f.

1. Pillow is already a top-level runtime dependency, and the shared-copy path already re-encodes JPEG

pyproject.toml [project] dependencies lists pillow>=12.3.0 alongside cryptography, asn1crypto, reportlab and piexif. The minimal-dependency rule is real but it governs the verify and kernel extras — cryptography + asn1crypto only — because those are what a court or legal-aid group vendors to run the standalone verifier. Redaction is producer-side and never enters that closure.

More directly: exif._strip_all_jpeg_metadata, the default strip_all_metadata path for every still image in every packet, already does exactly the operation this issue calls hard:

with Image.open(source) as image:
    image.load()
    ImageOps.exif_transpose(image, in_place=True)
    ...
    clean.save(encoded, format="JPEG", quality=95, subsampling=0)

So "draw black boxes on decoded pixels and re-encode" is an afternoon inside the pipeline that exists, not a new codec. Writing a pure-Python JPEG encoder beside Pillow would be a step backwards.

That also settles the earlier triage's "a redaction that can be undone is worse than no redaction" concern in the right direction: because the fill lands on decoded pixels before the encode, the content under the box is destroyed rather than composited over. That is the correct implementation and it is what the current pipeline shape naturally produces.

2. What is actually hard is the proof, and it splits into three claims of very different strength

Claim	Who can check it	Status today
The sealed original is byte-identical before and after	anyone with the vault	trivial — the vault never writes it
The derived copy the packet carries is the one custody bound to that original	any packet recipient	already exists — copied_for_sharing binds content_hash ↔ shared_hash (verify_packet §4.3)
The redaction was only what was declared	only someone holding both the original and the derived copy	not built, and not verify_packet's job

The third is the one the issue's Done when rests on ("an undeclared extra edit fails"), and it cannot live in verify_packet: a packet, by construction, does not contain the sealed original. It needs its own surface — a verb a reviewer who has been granted the original runs over both files, comparing decoded pixels: identical outside the declared regions, uniform inside them.

3. And that comparison cannot be made against a JPEG shared copy — measured

The project's own metadata sanitizer already moves most of the pixels, so "identical outside the declared regions" is false for a perfectly honest copy.

On a 320×240 synthetic photo-like JPEG (gradients plus ±18 noise), make_shared_copy under the default policy:

• 44,233 of 76,800 pixels (58%) differ from the sealed original
• max channel delta 4
• two runs of the sanitizer were byte-identical on this machine and this Pillow (cross-version determinism not measured)

And the redacted region does not survive as a region either. An 80×60 box filled (0,0,0) before the sanitizer runs comes back as:

format	distinct colours inside the box	brightest channel
JPEG shared copy (q95, subsampling 0)	222	16
PNG	1	0

So under JPEG neither half of the property is checkable exactly. The only ways out are:

• (a) make the redacted derived copy lossless (PNG). Both checks then become exact equality, version-independent, and trivial to write.
• (b) keep JPEG and state the check with a tolerance — "no pixel outside the declared regions differs by more than N". That is an attacker-sized hole: at max delta 4 over 58% of the image there is room to hide a small edit, and a tolerance is precisely the kind of guard that passes for the wrong reason.

I think (a) is the only honest option, which makes this issue's real blocking question:

May a redacted shared copy be PNG rather than JPEG?

4. That question has a cost, and it points straight back at #296

PNG is lossless, so it is larger for photographic content. Measured on 1280×960 synthetic images with one 340×320 box — neither is a photograph, and the real figure needs a real one:

content	JPEG q95	PNG	PNG/JPEG
smooth gradient	191,998	45,034	0.23×
fine detail / noise	1,868,791	2,858,518	1.53×

A real photograph sits between those and on the wrong side of 1×. That is a direct trade against RR-08 — the storage-footprint work whose offload half just shipped in #333 — so it is a decision, not an implementation detail. A middle option exists: PNG only for items that carry a redaction, JPEG for everything else, which confines the cost to the images that need the proof and makes shared_name's extension the visible signal that one is present.

5. Two smaller things for whoever builds it

• The region list has to be committed before the derived copy is hashed, or the redaction record and the bytes can disagree. copied_for_sharing's details is an open map of strings (a list or an int there is rejected — measured in the 2026-09-08 schema pass), so the regions travel as item.redaction on the open item object and the custody entry carries their digest.
• The guard test's load-bearing assertion is the one that is easy to leave out. "The original is byte-identical before and after" passes trivially if the redaction never ran. Assert in the same test that the derived copy's hash did change, and that the fill is present in the derived pixels — otherwise a no-op reads as a perfectly preserved original.

Verdict

Not blocked by the packet schema (confirmed 2026-09-08) and not blocked by a dependency rule that does not apply. Blocked on one owner call: lossless derived copies for redacted items, or a tolerance-based check that I would not ship. With (a) chosen, the rest is ordinary work in a pipeline that already decodes and re-encodes these images.

---

Measured against origin/main @ c13ce4f with the repo's own exif.make_shared_copy. Nothing was changed. Prepared with AI assistance.