@zanii/custody 0.1.0

package/LICENSE

@@ -0,0 +1,159 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zanii
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,48 @@
+# @zanii/custody
+
+**Supply-chain provenance.** "Where did this actually come from" — verifiable without any
+party trusting another's database. Each **handoff** (factory → shipper → customs →
+retailer) is a 2-party **co-signed** receipt (giver + receiver sign one neutral statement;
+`POST /v1/interactions`); a **multi-party event** (a customs inspection witnessed by N
+parties) is an M-of-N swarm receipt (`POST /v1/swarm`). This package adds the item layer:
+
+- **`itemTag(itemId, namespace)`** — pseudonymous item identity. The serial/batch never
+  appears on-ledger (competitors can't enumerate your volumes), but any holder of the real
+  id can find and verify the item's full history via `GET /v1/subjects/{tag}`.
+- **`buildHandoff` / `buildCustodyEvent`** — co-signable bodies stamped with the item tag
+  *inside the signed bytes*; sensitive details (weights, values, seals, docs) are
+  salt-committed, disclosable later via `@zanii/redact` / `verifyPayload`.
+- **`verifyCustodyChain(entries, { tag })`** — continuity: the receiver of handoff *n* is
+  the giver of handoff *n + 1*, timestamps monotonic, every entry valid and tag-bound;
+  returns the first break. `custodySummary` gives the human answer.
+
+```sh
+npm install @zanii/custody @zanii/core @zanii/swarm
+```
+
+```ts
+import { itemTag, buildHandoff, verifyCustodyChain } from '@zanii/custody';
+import { signA2ABody, assembleA2AReceipt } from '@zanii/core';
+
+const draft = buildHandoff({ itemId: 'SN-12345', namespace: 'acme-logistics',
+  step: 'factory-out', from: factoryStub, to: shipperStub, ts, evidence: { seal: 'S-9', kg: 12.4 } });
+const receipt = assembleA2AReceipt(draft.body,
+  signA2ABody(draft.body, factoryKey), signA2ABody(draft.body, shipperKey));
+// POST /v1/interactions — keep draft.nonce to later prove the evidence
+
+verifyCustodyChain(chain, { tag: itemTag('SN-12345', 'acme-logistics') }).ok;
+```
+
+## Honest limit — the oracle problem, stated plainly
+Cryptography verifies **attestations, not atoms**. A custody chain proves *who signed for
+the goods at each step, under whose authority, in what order, unalterable after the fact* —
+it cannot prove box contents weren't swapped by a party willing to sign falsely. What it
+changes: fraud now requires a **specific, identified party to sign a false statement** with
+their accountable key. Detection becomes attribution. Bind the physical world (seals,
+weights, photos) in the salted `evidence`, disclosable selectively.
+
+## Changelog
+- **0.1.0** — initial release: `itemTag`, `buildHandoff`, `buildCustodyEvent`, `verifyCustodyChain`, `custodySummary`.
+
+## License
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @zanii/custody — supply-chain provenance: co-signed custody chains for physical goods.
+ *
+ * "Where did this actually come from" without any party trusting another's database.
+ * A **handoff** (factory → shipper → customs → retailer) is a 2-party co-signed a2a
+ * receipt (live at `POST /v1/interactions`); a **multi-party event** (an inspection
+ * witnessed by N parties) is a swarm receipt (`POST /v1/swarm`). This package adds the
+ * *item layer* on top — no new crypto, no new server verification:
+ *
+ * - `itemTag(itemId, namespace)` — pseudonymous item identity (the serial/batch never
+ *   appears on-ledger; competitors can't enumerate volumes; any holder of the real id
+ *   can find + verify the item's history via the subject index, `GET /v1/subjects/{tag}`).
+ * - `buildHandoff` / `buildCustodyEvent` — receipt bodies stamped with the item tag,
+ *   sensitive details (weights, values, docs) salt-committed, disclosable later.
+ * - `verifyCustodyChain` — the custody-specific check on top of receipt validity:
+ *   **continuity** — the receiver of handoff *n* is the giver of handoff *n+1*,
+ *   timestamps monotonic; returns the first break.
+ *
+ * Honest limit (the oracle problem, stated plainly): cryptography verifies
+ * **attestations, not atoms**. A chain proves who signed for the goods at each step,
+ * under whose authority, in what order, unalterable after the fact — it cannot prove
+ * box contents weren't swapped by a party willing to sign falsely. What changes: fraud
+ * now requires a specific, identified party to sign a false statement with their
+ * accountable key. Detection becomes attribution. Bind the physical world (seals,
+ * weights, photos) in the salted `evidence` payload, disclosable via `@zanii/redact`.
+ */
+import { type A2AReceipt, type DelegationCert } from '@zanii/core';
+import { type SwarmBody, type SwarmLedgerReceipt } from '@zanii/swarm';
+/** Pseudonymous, namespace-scoped item identity. Deterministic (RFC 8785), cross-language. */
+export declare function itemTag(itemId: string, namespace: string): string;
+export interface HandoffInput {
+    /** The raw item id (serial/batch/EPC — opaque string, caller normalizes)… */
+    itemId?: string;
+    namespace?: string;
+    /** …or a precomputed `itemTag`. */
+    tag?: string;
+    /** Custody step, e.g. `factory-out`, `customs-in`. Becomes `custody.handoff.<step>`. */
+    step: string;
+    /** Giver / receiver party stubs: `{ agent_id, delegation, prev }` (no sig yet). */
+    from: {
+        agent_id: string;
+        delegation: DelegationCert[];
+        prev: string | null;
+    };
+    to: {
+        agent_id: string;
+        delegation: DelegationCert[];
+        prev: string | null;
+    };
+    ts: string;
+    /** Sensitive details (location, weights, seals, docs) — salt-committed, never raw on-ledger. */
+    evidence?: Record<string, unknown>;
+}
+export interface HandoffDraft {
+    /** The a2a body both parties sign (stamped with the item tag; sign with `signA2ABody`). */
+    body: Record<string, unknown>;
+    tag: string;
+    /** Keep to later prove the evidence with `verifyPayload` (evidence is always salt-committed). */
+    nonce: string;
+}
+/** Build the co-signable handoff body. Giver + receiver sign it; submit via `POST /v1/interactions`. */
+export declare function buildHandoff(input: HandoffInput): HandoffDraft;
+export interface CustodyEventInput {
+    itemId?: string;
+    namespace?: string;
+    tag?: string;
+    /** e.g. `customs-inspection`. Becomes task `custody.event.<kind>`. */
+    kind: string;
+    target: string;
+    participants: string[];
+    threshold: number;
+    ts: string;
+    evidence?: Record<string, unknown>;
+}
+/** Build the N-party event body (swarm). Participants sign it; submit via `POST /v1/swarm`. */
+export declare function buildCustodyEvent(input: CustodyEventInput): {
+    body: SwarmBody & {
+        subject_tag?: string;
+    };
+    tag: string;
+    nonce: string;
+};
+export interface CustodyCheck {
+    ok: boolean;
+    reasons: string[];
+    /** Ordered custodian DIDs (giver of the first handoff, then each receiver). */
+    custodians: string[];
+    handoffs: number;
+    events: number;
+}
+type Entry = A2AReceipt | SwarmLedgerReceipt | Record<string, unknown>;
+/**
+ * Verify an item's custody chain: every entry cryptographically valid AND stamped with
+ * this item's tag, handoffs continuous (receiver of *n* = giver of *n+1*), timestamps
+ * monotonic. Events are validated + tag-matched but don't transfer custody.
+ */
+export declare function verifyCustodyChain(entries: Entry[], opts: {
+    tag: string;
+    revoked?: Set<string>;
+}): CustodyCheck;
+/** The human answer: origin, every custodian, every step. */
+export declare function custodySummary(entries: Entry[]): {
+    origin: string | null;
+    custodians: string[];
+    steps: string[];
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,139 @@
+/**
+ * @zanii/custody — supply-chain provenance: co-signed custody chains for physical goods.
+ *
+ * "Where did this actually come from" without any party trusting another's database.
+ * A **handoff** (factory → shipper → customs → retailer) is a 2-party co-signed a2a
+ * receipt (live at `POST /v1/interactions`); a **multi-party event** (an inspection
+ * witnessed by N parties) is a swarm receipt (`POST /v1/swarm`). This package adds the
+ * *item layer* on top — no new crypto, no new server verification:
+ *
+ * - `itemTag(itemId, namespace)` — pseudonymous item identity (the serial/batch never
+ *   appears on-ledger; competitors can't enumerate volumes; any holder of the real id
+ *   can find + verify the item's history via the subject index, `GET /v1/subjects/{tag}`).
+ * - `buildHandoff` / `buildCustodyEvent` — receipt bodies stamped with the item tag,
+ *   sensitive details (weights, values, docs) salt-committed, disclosable later.
+ * - `verifyCustodyChain` — the custody-specific check on top of receipt validity:
+ *   **continuity** — the receiver of handoff *n* is the giver of handoff *n+1*,
+ *   timestamps monotonic; returns the first break.
+ *
+ * Honest limit (the oracle problem, stated plainly): cryptography verifies
+ * **attestations, not atoms**. A chain proves who signed for the goods at each step,
+ * under whose authority, in what order, unalterable after the fact — it cannot prove
+ * box contents weren't swapped by a party willing to sign falsely. What changes: fraud
+ * now requires a specific, identified party to sign a false statement with their
+ * accountable key. Detection becomes attribution. Bind the physical world (seals,
+ * weights, photos) in the salted `evidence` payload, disclosable via `@zanii/redact`.
+ */
+import { buildA2ABody, jcsHash, saltedPayloadHash, verifyA2AReceipt, } from '@zanii/core';
+import { verifySwarmReceipt, buildSwarmBody } from '@zanii/swarm';
+/** Pseudonymous, namespace-scoped item identity. Deterministic (RFC 8785), cross-language. */
+export function itemTag(itemId, namespace) {
+    if (!itemId || !namespace)
+        throw new Error('itemId and namespace are required');
+    return jcsHash({ v: 1, type: 'item_tag', namespace, item: itemId });
+}
+/** Build the co-signable handoff body. Giver + receiver sign it; submit via `POST /v1/interactions`. */
+export function buildHandoff(input) {
+    if (!input.step)
+        throw new Error('step is required');
+    const tag = input.tag ?? itemTag(input.itemId ?? '', input.namespace ?? '');
+    const { payload_hash, nonce } = saltedPayloadHash(JSON.stringify(input.evidence ?? {}));
+    const body = buildA2ABody({
+        action: 'handoff',
+        target: `custody.handoff.${input.step}`,
+        payloadHash: payload_hash,
+        ts: input.ts,
+        initiator: input.from,
+        responder: input.to,
+    });
+    // Stamped INSIDE the co-signed body: both signatures cover the item tag.
+    body.subject_tag = tag;
+    return { body, tag, nonce };
+}
+/** Build the N-party event body (swarm). Participants sign it; submit via `POST /v1/swarm`. */
+export function buildCustodyEvent(input) {
+    const tag = input.tag ?? itemTag(input.itemId ?? '', input.namespace ?? '');
+    const { payload_hash, nonce } = saltedPayloadHash(JSON.stringify(input.evidence ?? {}));
+    const body = buildSwarmBody({
+        task: `custody.event.${input.kind}`,
+        target: input.target,
+        participants: input.participants,
+        threshold: input.threshold,
+        ts: input.ts,
+        payloadHash: payload_hash,
+    });
+    body.subject_tag = tag; // inside the signed body — every co-signer covers the item tag
+    return { body, tag, nonce };
+}
+function isSwarm(e) {
+    return e.type === 'swarm';
+}
+/**
+ * Verify an item's custody chain: every entry cryptographically valid AND stamped with
+ * this item's tag, handoffs continuous (receiver of *n* = giver of *n+1*), timestamps
+ * monotonic. Events are validated + tag-matched but don't transfer custody.
+ */
+export function verifyCustodyChain(entries, opts) {
+    const reasons = [];
+    const custodians = [];
+    let holder = null;
+    let lastTs = '';
+    let handoffs = 0;
+    let events = 0;
+    entries.forEach((e, i) => {
+        if (isSwarm(e)) {
+            events += 1;
+            const check = verifySwarmReceipt(e, { revoked: opts.revoked });
+            if (!check.ok)
+                reasons.push(`entry ${i} (event): ${check.error}`);
+            if (e.body.subject_tag !== opts.tag)
+                reasons.push(`entry ${i} (event): wrong or missing item tag`);
+            return;
+        }
+        const r = e;
+        handoffs += 1;
+        const check = verifyA2AReceipt(r, { revoked: opts.revoked });
+        if (!check.ok) {
+            reasons.push(`entry ${i} (handoff): ${check.error}`);
+            return;
+        }
+        if (r.subject_tag !== opts.tag)
+            reasons.push(`entry ${i} (handoff): wrong or missing item tag`);
+        if (holder === null) {
+            custodians.push(r.initiator.agent_id);
+        }
+        else if (r.initiator.agent_id !== holder) {
+            reasons.push(`entry ${i} (handoff): custody break — giver ${r.initiator.agent_id} is not the current holder ${holder}`);
+        }
+        if (lastTs && r.ts < lastTs)
+            reasons.push(`entry ${i} (handoff): timestamp goes backwards`);
+        holder = r.responder.agent_id;
+        custodians.push(holder);
+        lastTs = r.ts;
+    });
+    if (handoffs === 0)
+        reasons.push('no handoffs in chain');
+    return { ok: reasons.length === 0, reasons, custodians, handoffs, events };
+}
+/** The human answer: origin, every custodian, every step. */
+export function custodySummary(entries) {
+    const steps = [];
+    const custodians = [];
+    let origin = null;
+    for (const e of entries) {
+        if (isSwarm(e)) {
+            steps.push(String(e.body.task));
+            continue;
+        }
+        const r = e;
+        if (origin === null)
+            origin = r.initiator.agent_id;
+        steps.push(r.target);
+        if (!custodians.includes(r.initiator.agent_id))
+            custodians.push(r.initiator.agent_id);
+        if (!custodians.includes(r.responder.agent_id))
+            custodians.push(r.responder.agent_id);
+    }
+    return { origin, custodians, steps };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@zanii/custody",
+  "version": "0.1.0",
+  "description": "Supply-chain provenance: co-signed custody chains for physical goods. Each handoff (factory→shipper→customs→retailer) is a 2-party co-signed receipt, multi-party events are N-party swarm receipts, and item history is a pseudonymous verifiable slice — no party trusts another's database.",
+  "license": "Apache-2.0",
+  "homepage": "https://ledger.zanii.agency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "dependencies": {
+    "@zanii/core": "0.4.0",
+    "@zanii/swarm": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * @zanii/custody — supply-chain provenance: co-signed custody chains for physical goods.
+ *
+ * "Where did this actually come from" without any party trusting another's database.
+ * A **handoff** (factory → shipper → customs → retailer) is a 2-party co-signed a2a
+ * receipt (live at `POST /v1/interactions`); a **multi-party event** (an inspection
+ * witnessed by N parties) is a swarm receipt (`POST /v1/swarm`). This package adds the
+ * *item layer* on top — no new crypto, no new server verification:
+ *
+ * - `itemTag(itemId, namespace)` — pseudonymous item identity (the serial/batch never
+ *   appears on-ledger; competitors can't enumerate volumes; any holder of the real id
+ *   can find + verify the item's history via the subject index, `GET /v1/subjects/{tag}`).
+ * - `buildHandoff` / `buildCustodyEvent` — receipt bodies stamped with the item tag,
+ *   sensitive details (weights, values, docs) salt-committed, disclosable later.
+ * - `verifyCustodyChain` — the custody-specific check on top of receipt validity:
+ *   **continuity** — the receiver of handoff *n* is the giver of handoff *n+1*,
+ *   timestamps monotonic; returns the first break.
+ *
+ * Honest limit (the oracle problem, stated plainly): cryptography verifies
+ * **attestations, not atoms**. A chain proves who signed for the goods at each step,
+ * under whose authority, in what order, unalterable after the fact — it cannot prove
+ * box contents weren't swapped by a party willing to sign falsely. What changes: fraud
+ * now requires a specific, identified party to sign a false statement with their
+ * accountable key. Detection becomes attribution. Bind the physical world (seals,
+ * weights, photos) in the salted `evidence` payload, disclosable via `@zanii/redact`.
+ */
+import {
+  buildA2ABody, jcsHash, saltedPayloadHash, verifyA2AReceipt,
+  type A2AReceipt, type DelegationCert, type VerifyResult,
+} from '@zanii/core';
+import { verifySwarmReceipt, buildSwarmBody, type SwarmBody, type SwarmLedgerReceipt } from '@zanii/swarm';
+
+/** Pseudonymous, namespace-scoped item identity. Deterministic (RFC 8785), cross-language. */
+export function itemTag(itemId: string, namespace: string): string {
+  if (!itemId || !namespace) throw new Error('itemId and namespace are required');
+  return jcsHash({ v: 1, type: 'item_tag', namespace, item: itemId });
+}
+
+export interface HandoffInput {
+  /** The raw item id (serial/batch/EPC — opaque string, caller normalizes)… */
+  itemId?: string;
+  namespace?: string;
+  /** …or a precomputed `itemTag`. */
+  tag?: string;
+  /** Custody step, e.g. `factory-out`, `customs-in`. Becomes `custody.handoff.<step>`. */
+  step: string;
+  /** Giver / receiver party stubs: `{ agent_id, delegation, prev }` (no sig yet). */
+  from: { agent_id: string; delegation: DelegationCert[]; prev: string | null };
+  to: { agent_id: string; delegation: DelegationCert[]; prev: string | null };
+  ts: string;
+  /** Sensitive details (location, weights, seals, docs) — salt-committed, never raw on-ledger. */
+  evidence?: Record<string, unknown>;
+}
+
+export interface HandoffDraft {
+  /** The a2a body both parties sign (stamped with the item tag; sign with `signA2ABody`). */
+  body: Record<string, unknown>;
+  tag: string;
+  /** Keep to later prove the evidence with `verifyPayload` (evidence is always salt-committed). */
+  nonce: string;
+}
+
+/** Build the co-signable handoff body. Giver + receiver sign it; submit via `POST /v1/interactions`. */
+export function buildHandoff(input: HandoffInput): HandoffDraft {
+  if (!input.step) throw new Error('step is required');
+  const tag = input.tag ?? itemTag(input.itemId ?? '', input.namespace ?? '');
+  const { payload_hash, nonce } = saltedPayloadHash(JSON.stringify(input.evidence ?? {}));
+  const body = buildA2ABody({
+    action: 'handoff',
+    target: `custody.handoff.${input.step}`,
+    payloadHash: payload_hash,
+    ts: input.ts,
+    initiator: input.from,
+    responder: input.to,
+  }) as unknown as Record<string, unknown>;
+  // Stamped INSIDE the co-signed body: both signatures cover the item tag.
+  body.subject_tag = tag;
+  return { body, tag, nonce };
+}
+
+export interface CustodyEventInput {
+  itemId?: string;
+  namespace?: string;
+  tag?: string;
+  /** e.g. `customs-inspection`. Becomes task `custody.event.<kind>`. */
+  kind: string;
+  target: string;
+  participants: string[];
+  threshold: number;
+  ts: string;
+  evidence?: Record<string, unknown>;
+}
+
+/** Build the N-party event body (swarm). Participants sign it; submit via `POST /v1/swarm`. */
+export function buildCustodyEvent(input: CustodyEventInput): { body: SwarmBody & { subject_tag?: string }; tag: string; nonce: string } {
+  const tag = input.tag ?? itemTag(input.itemId ?? '', input.namespace ?? '');
+  const { payload_hash, nonce } = saltedPayloadHash(JSON.stringify(input.evidence ?? {}));
+  const body = buildSwarmBody({
+    task: `custody.event.${input.kind}`,
+    target: input.target,
+    participants: input.participants,
+    threshold: input.threshold,
+    ts: input.ts,
+    payloadHash: payload_hash,
+  }) as SwarmBody & { subject_tag?: string };
+  body.subject_tag = tag; // inside the signed body — every co-signer covers the item tag
+  return { body, tag, nonce };
+}
+
+export interface CustodyCheck {
+  ok: boolean;
+  reasons: string[];
+  /** Ordered custodian DIDs (giver of the first handoff, then each receiver). */
+  custodians: string[];
+  handoffs: number;
+  events: number;
+}
+
+type Entry = A2AReceipt | SwarmLedgerReceipt | Record<string, unknown>;
+
+function isSwarm(e: Entry): e is SwarmLedgerReceipt {
+  return (e as { type?: string }).type === 'swarm';
+}
+
+/**
+ * Verify an item's custody chain: every entry cryptographically valid AND stamped with
+ * this item's tag, handoffs continuous (receiver of *n* = giver of *n+1*), timestamps
+ * monotonic. Events are validated + tag-matched but don't transfer custody.
+ */
+export function verifyCustodyChain(entries: Entry[], opts: { tag: string; revoked?: Set<string> }): CustodyCheck {
+  const reasons: string[] = [];
+  const custodians: string[] = [];
+  let holder: string | null = null;
+  let lastTs = '';
+  let handoffs = 0;
+  let events = 0;
+  entries.forEach((e, i) => {
+    if (isSwarm(e)) {
+      events += 1;
+      const check: VerifyResult = verifySwarmReceipt(e, { revoked: opts.revoked });
+      if (!check.ok) reasons.push(`entry ${i} (event): ${check.error}`);
+      if ((e.body as { subject_tag?: string }).subject_tag !== opts.tag) reasons.push(`entry ${i} (event): wrong or missing item tag`);
+      return;
+    }
+    const r = e as A2AReceipt & { subject_tag?: string };
+    handoffs += 1;
+    const check = verifyA2AReceipt(r, { revoked: opts.revoked });
+    if (!check.ok) {
+      reasons.push(`entry ${i} (handoff): ${check.error}`);
+      return;
+    }
+    if (r.subject_tag !== opts.tag) reasons.push(`entry ${i} (handoff): wrong or missing item tag`);
+    if (holder === null) {
+      custodians.push(r.initiator.agent_id);
+    } else if (r.initiator.agent_id !== holder) {
+      reasons.push(`entry ${i} (handoff): custody break — giver ${r.initiator.agent_id} is not the current holder ${holder}`);
+    }
+    if (lastTs && r.ts < lastTs) reasons.push(`entry ${i} (handoff): timestamp goes backwards`);
+    holder = r.responder.agent_id;
+    custodians.push(holder);
+    lastTs = r.ts;
+  });
+  if (handoffs === 0) reasons.push('no handoffs in chain');
+  return { ok: reasons.length === 0, reasons, custodians, handoffs, events };
+}
+
+/** The human answer: origin, every custodian, every step. */
+export function custodySummary(entries: Entry[]): { origin: string | null; custodians: string[]; steps: string[] } {
+  const steps: string[] = [];
+  const custodians: string[] = [];
+  let origin: string | null = null;
+  for (const e of entries) {
+    if (isSwarm(e)) {
+      steps.push(String(e.body.task));
+      continue;
+    }
+    const r = e as A2AReceipt;
+    if (origin === null) origin = r.initiator.agent_id;
+    steps.push(r.target);
+    if (!custodians.includes(r.initiator.agent_id)) custodians.push(r.initiator.agent_id);
+    if (!custodians.includes(r.responder.agent_id)) custodians.push(r.responder.agent_id);
+  }
+  return { origin, custodians, steps };
+}