@zanii/data-custody

Prove what happened to the DATA an agent touched — every touch of a user's document, where it went, and when the original was destroyed. A page the user can verify without trusting the operator.

Not @zanii/custody. That package is supply-chain custody (co-signed handoffs of physical goods). This is data custody — what an agent did with a bank statement, an ID, a message.

npm install @zanii/data-custody @zanii/core

import { deriveRef, buildTouch, verifyObjectChain, custodyView } from '@zanii/data-custody';

// 1. every document gets a versioned, content-free ref (this becomes the subject_tag):
const ref = deriveRef('bank-statement-42', tenantCustodyKey);   // hmac:v1:…

// 2. each touch is a receipt whose TARGET is data.<class>.<op> — so scope = purpose:
const t = buildTouch({ ref, dataClass: 'financial.statement', op: 'read', ts: now,
  junction: { to: 'anthropic', agreement: 'zero-retention-v3' } });
await zanii.record({ target: t.target, payload: t.payload, subjectTag: t.subjectTag });

// 3. the user (or anyone) verifies every touch of THEIR object, offline:
const touches = /* from GET /v1/subjects/{ref}, operator reveals each payload */;
const r = verifyObjectChain(touches, { ref });   // { ok, error, failedIndex } — never throws
custodyView(ref, r.touches);                      // "your data, right now" — agents, ops, destinations, destroyed_at

Python: from zanii.data_custody import derive_ref, build_touch, verify_object_chain, ... — byte-identical ref derivation (locked vector).

Zero server changes — the "one network" rule

A custody record is not a new object: it's a Proof receipt with the data ref as its subject_tag. Same agent DID, same per-agent hash chain, same Merkle batch, same anchor. It verifies with verifyReceiptChain unchanged, writes via the existing /v1/receipts, and its touches are read via the existing tag-agnostic GET /v1/subjects/{tag}. No separate custody log, no custody anchor, no special verifier. That's the moat — DSPM vendors have the data movement and have never seen a delegation cert; agent-governance tools have the agent and can't say what happened to the data. Both live in one signed record because it is one record.

Purpose binding with zero new logic

The touch receipt's target is data.<class>.<op> (e.g. data.pii.customer.read), so the ledger's existing scope check enforces purpose at record time: a delegation scoped data.pii.customer.read physically cannot produce a …export receipt. Not "we watched and it behaved" — "it had no power to do otherwise, verify the certificate yourself." purposeAllows() mirrors the check client-side.

The limit, stated up front — the party being audited is us

We run the servers, so a log we control is our word, not evidence. This package proves what was recorded, and that the record is unrewritten and publicly anchored. It does not by itself prove we never took an off-record copy — that needs an attested enclave (@zanii/attest: only the published image hash ever sees plaintext). A ref commits an identifier, never content; the ledger holds hashes only. And never render "we were not looking" as "nothing happened" — a gap in the touch history is unknown, not clean.