@cello-protocol/protocol-types 0.0.21 → 0.0.23

package/dist/trust-signal.js

@@ -0,0 +1,252 @@
+/**
+ * The canonical trust-signal envelope (M10 / DOD-CBOR-1): serialize, hash, verify.
+ *
+ * Four parties independently re-derive this hash — the portal at mint, the directory at submission
+ * (INV-CHOKEPOINT's re-hash before store), the directory again at presentation (dumb check 1), and
+ * the holder/recipient daemons on receipt and at verification. They must agree byte-for-byte,
+ * forever, across three repos and two languages' worth of tooling. A single divergent byte turns a
+ * valid signal into a false `hash_mismatch` — unpresentable, and censorship-shaped, because it can
+ * differ per node or per client version.
+ *
+ * THE PREIMAGE IS AN ARRAY, NOT A MAP, AND THAT IS LOAD-BEARING (M10-D15).
+ * The shared encoder (`cbor.ts`) is not RFC 8949 §4.2 deterministic for MAPS: map keys follow
+ * INSERTION ORDER, and map headers are not minimal-length (a 2-entry map emits `b9 0002`, not `a2`).
+ * Arrays, text strings, byte strings, integers and null are all minimal and order-fixed. Encoding
+ * the preimage as a fixed-order array therefore makes determinism STRUCTURAL — a property of the
+ * shape, not of the encoder's configuration — and costs no encoder change and no migration of the
+ * blobs already on disk. Every signed TBS in CELLO is an array for this same reason
+ * (`buildAgentRevocationTbs`, `buildPrimaryTransferTbs`, `buildSealTbs`, `buildParkContentTbs`).
+ *
+ * Consequences, all enforced below:
+ *   - FIELD ORDER IS THE WIRE FORMAT. Reordering the array is a breaking hash change, not a
+ *     refactor. Retrofitting a canonical form later breaks every hash already minted (spec §5).
+ *   - THE FIELD SET IS CLOSED (spec §4). An unknown field is REJECTED, never ignored: silently
+ *     dropping it would let two parties who disagree about the field set still agree on the hash,
+ *     making the extra field unauthenticated data riding inside a "verified" signal.
+ *   - `status` / `class` / `verified_at` ARE NOT IN THE PREIMAGE. They are mutable after minting —
+ *     that is the entire point of excluding them. If `status` were hashed, revoking a signal would
+ *     change its hash and the directory could never find it again.
+ *   - OPTIONAL FIELDS ARE AN EXPLICIT `null` IN A FIXED SLOT, NEVER OMITTED (M10-D17). In an array,
+ *     omitting a field shifts every later field and changes the arity, so an absent `expires_at`
+ *     becomes confusable with a misaligned `supersedes_hash`.
+ *   - NO FLOATING POINT. Timestamps are integer epoch SECONDS. A float would not survive
+ *     byte-agreement across languages.
+ *   - `payload` IS OPAQUE BYTES, never decoded or re-encoded. A payload parsed and re-serialized
+ *     would change bytes under a different encoder version. This is also what INV-ZERO-BUMP rests
+ *     on: a type this code has never seen must hash and flow through untouched.
+ */
+import { hash as sha256 } from "@cello-protocol/crypto";
+import { encodeCbor } from "./cbor.js";
+/** Domain separation, bound as element 0 of the preimage array — the house convention
+ *  (`AGENT_REVOCATION_DOMAIN`, `PRIMARY_TRANSFER_DOMAIN`). A trust-signal hash can therefore never
+ *  collide with, or be replayed as, any other hashed/signed CELLO structure. */
+export const TRUST_SIGNAL_DOMAIN = "CELLO-TSIG-v1";
+/** The preimage field order. THIS ARRAY IS THE WIRE FORMAT — reordering it breaks every hash ever
+ *  minted. It also doubles as the closed-set definition used to reject unknown fields. */
+const PREIMAGE_FIELDS = [
+    "subject_kind",
+    "subject",
+    "issuer_kind",
+    "issuer_pubkey",
+    "type",
+    "schema_version",
+    "payload",
+    "issued_at",
+    "expires_at",
+    "supersedes_hash",
+];
+/** Sanity bound on epoch-SECOND timestamps. A millisecond timestamp (~1.7e12) is the classic
+ *  cross-implementation skew: it is a valid integer, so nothing would complain, and it would mint a
+ *  signal that expires roughly thirty thousand years from now. Refuse it at the door. */
+const MAX_EPOCH_SECONDS = 100_000_000_000; // ~year 5138
+/** Above this, a JS `number` is encoded by cbor-x as an IEEE **float64** (major type 7), not as a
+ *  uint64 — see `asCborInteger`. Anything hashed must cross this boundary as a BigInt. */
+const CBOR_UINT32_MAX = 0xffff_ffff;
+/** SHA-256. Named separately from SUPERSEDES_HASH_BYTES even though both are 32 today: they are
+ *  independent sizes, and coupling them means a future change to one silently breaks the other. */
+const SIGNAL_HASH_BYTES = 32;
+const SUPERSEDES_HASH_BYTES = 32;
+/**
+ * Integers above 2³² MUST cross into CBOR as BigInt, or they are hashed as a FLOAT.
+ *
+ * Measured with this package's encoder:
+ *
+ *   encode(1768000000)          -> 1a 69618a00           uint32   (fine)
+ *   encode(4920000000)          -> fb 41f25413e0000000   FLOAT64  (WRONG)
+ *   encode(BigInt(4920000000))  -> 1b 0000000125413e00   uint64   (what RFC 8949 requires)
+ *
+ * cbor-x emits any JS `number` above 0xffffffff as major type 7 float64. A conforming CBOR
+ * implementation in Rust, Go, or Python emits a uint64 — so the two disagree on the preimage, and
+ * therefore on the hash, permanently and unfixably (spec §5: retrofitting the canonical form breaks
+ * every hash already minted).
+ *
+ * This is NOT hypothetical and NOT a 2106 problem: an `expires_at` a hundred years out is
+ * 1.768e9 + 3.15e9 = 4.92e9, well past 2³², and reachable by the first long-dated signal the portal
+ * mints. `buildSealTbs` (session.ts) and `buildAgentRevocationTbs` (revocation.ts) both carry this
+ * coercion. The trust-signal envelope shipped without it and a reviewer caught it.
+ */
+function asCborInteger(value) {
+    return value > CBOR_UINT32_MAX ? BigInt(value) : value;
+}
+/** A non-negative integer safe to hash — rejected if it is a float, NaN, Infinity, or negative, and
+ *  coerced to BigInt past 2³² so it never encodes as a float64. */
+function requireHashableInteger(name, value, max, hint) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`trust-signal envelope: ${name} must be a finite integer, got ${String(value)}`);
+    }
+    if (!Number.isInteger(value)) {
+        throw new Error(`trust-signal envelope: ${name} must be an integer — no floating point is hashable across implementations, got ${value}`);
+    }
+    if (value < 0) {
+        throw new Error(`trust-signal envelope: ${name} must not be negative, got ${value}`);
+    }
+    if (value > Number.MAX_SAFE_INTEGER) {
+        // Past 2^53 a JS number cannot even represent consecutive integers, so the value the caller
+        // meant and the value we hash may already differ. Refuse rather than hash an approximation.
+        throw new Error(`trust-signal envelope: ${name} exceeds Number.MAX_SAFE_INTEGER (${value}) — it cannot be hashed exactly`);
+    }
+    if (value >= max) {
+        throw new Error(`trust-signal envelope: ${name} is out of range (${value}) — ${hint}`);
+    }
+    return asCborInteger(value);
+}
+const requireEpochSeconds = (name, value) => requireHashableInteger(name, value, MAX_EPOCH_SECONDS, "this looks like a millisecond timestamp; the contract is epoch SECONDS");
+/**
+ * Every hashed STRING must be NFC-normalized, and we REFUSE a string that is not — we never
+ * normalize it silently.
+ *
+ * Spec §5's list of cross-language hash-breakers names Unicode normalization explicitly. The same
+ * logical string differs on the wire: "é" is `62 c3a9` in NFC and `63 65cc81` in NFD. CBOR does not
+ * normalize, and RFC 8949's deterministic profile does not require NFC, so nothing downstream saves
+ * us.
+ *
+ * Refusing rather than normalizing is deliberate: silently normalizing would make two DIFFERENT
+ * inputs hash to the SAME signal — a collision we manufactured ourselves, which is strictly worse
+ * than refusing the odd one at the door.
+ */
+function requireNfcString(name, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`trust-signal envelope: ${name} must be a non-empty string, got ${String(value)}`);
+    }
+    if (value.normalize("NFC") !== value) {
+        throw new Error(`trust-signal envelope: ${name} must be Unicode NFC-normalized — the same logical string hashes ` +
+            `differently in NFD ("é" is c3a9 in NFC, 65cc81 in NFD), so a non-NFC value would produce a ` +
+            `signal no other implementation can reproduce. Normalize it before minting.`);
+    }
+    return value;
+}
+/**
+ * Validate against the CLOSED preimage set and return the fixed-order array to encode.
+ *
+ * Every rejection here is deliberate and loud. An envelope that cannot be canonicalized must never
+ * be hashed "best effort" — a best-effort hash is a hash two parties can disagree about.
+ */
+function toPreimage(envelope) {
+    if (envelope === null || typeof envelope !== "object") {
+        throw new Error(`trust-signal envelope: expected an object, got ${String(envelope)}`);
+    }
+    // Closed set, both directions: no unknown fields, no missing fields.
+    const known = new Set(PREIMAGE_FIELDS);
+    for (const key of Object.keys(envelope)) {
+        if (!known.has(key)) {
+            throw new Error(`trust-signal envelope: unknown envelope field "${key}". The preimage is a CLOSED set (spec §4) — ` +
+                `an unhashed field riding inside a verified signal is unauthenticated data. ` +
+                `Note status/class/verified_at are deliberately NOT hashed (they are mutable after minting) ` +
+                `and do not belong on this object.`);
+        }
+    }
+    for (const field of PREIMAGE_FIELDS) {
+        if (!(field in envelope)) {
+            throw new Error(`trust-signal envelope: missing mandatory field "${field}" (the preimage is a closed set — spec §4)`);
+        }
+    }
+    const { subject_kind, subject, issuer_kind, issuer_pubkey, type, schema_version, payload, expires_at, supersedes_hash } = envelope;
+    if (subject_kind !== "account" && subject_kind !== "agent") {
+        throw new Error(`trust-signal envelope: subject_kind must be "account" or "agent", got ${String(subject_kind)}`);
+    }
+    if (issuer_kind !== "portal" && issuer_kind !== "agent") {
+        throw new Error(`trust-signal envelope: issuer_kind must be "portal" or "agent", got ${String(issuer_kind)}`);
+    }
+    requireNfcString("subject", subject);
+    requireNfcString("type", type);
+    // issuer_pubkey is hex, and hex has a CASE. "AABB" and "aabb" are the same key and DIFFERENT bytes,
+    // so a portal that stores it uppercase and a directory that lowercases it on read would produce
+    // two different signal_hashes for one signal — a false hash_mismatch, per-node and per-version.
+    // Lowercase-only removes the ambiguity at zero cost. (Length/validity is NOT checked here: this
+    // component's job is byte-agreement, and the key's validity is the directory's to judge when it
+    // checks it against the authorized-issuer set.)
+    requireNfcString("issuer_pubkey", issuer_pubkey);
+    if (!/^[0-9a-f]+$/.test(issuer_pubkey) || issuer_pubkey.length % 2 !== 0) {
+        throw new Error(`trust-signal envelope: issuer_pubkey must be LOWERCASE hex with an even length, got "${issuer_pubkey}". ` +
+            `Hex has a case, and "AABB" and "aabb" are the same key but different preimage bytes — which would ` +
+            `mint two different hashes for one signal.`);
+    }
+    const schemaVersion = requireHashableInteger("schema_version", schema_version, CBOR_UINT32_MAX + 1, "a schema version is a small counter, not an identifier");
+    // The payload must be RAW BYTES. An object here would be encoded as a CBOR map — the one
+    // non-deterministic shape in the encoder — and the hash would silently depend on key insertion
+    // order. Callers serialize their own payload and hand us the bytes.
+    if (!(payload instanceof Uint8Array)) {
+        throw new Error(`trust-signal envelope: payload must be raw bytes (Uint8Array), got ${payload === null ? "null" : typeof payload}. ` +
+            `An object payload would be map-encoded, and CBOR maps are not deterministic under this encoder — ` +
+            `serialize the payload yourself and pass the bytes.`);
+    }
+    const issuedAt = requireEpochSeconds("issued_at", envelope.issued_at);
+    const expiresAt = expires_at === null ? null : requireEpochSeconds("expires_at", expires_at);
+    if (supersedes_hash !== null) {
+        if (!(supersedes_hash instanceof Uint8Array)) {
+            throw new Error(`trust-signal envelope: supersedes_hash must be 32 raw bytes or null, got ${typeof supersedes_hash}`);
+        }
+        if (supersedes_hash.length !== SUPERSEDES_HASH_BYTES) {
+            throw new Error(`trust-signal envelope: supersedes_hash must be exactly ${SUPERSEDES_HASH_BYTES} bytes, got ${supersedes_hash.length}`);
+        }
+    }
+    // FIXED ORDER. Element 0 is the domain tag; the nullable slots keep their position so arity is
+    // always 11 and no field can be mistaken for another (M10-D17).
+    return [
+        TRUST_SIGNAL_DOMAIN,
+        subject_kind,
+        subject,
+        issuer_kind,
+        issuer_pubkey,
+        type,
+        schemaVersion,
+        payload,
+        issuedAt,
+        expiresAt,
+        supersedes_hash,
+    ];
+}
+/** The canonical preimage bytes. Deterministic across every party that runs this code. */
+export function encodeTrustSignalEnvelope(envelope) {
+    return encodeCbor(toPreimage(envelope));
+}
+/** The signal's identity: SHA-256 over the canonical preimage. This is the `signal_hash` that the
+ *  directory stores, the holder presents, and the recipient re-derives. */
+export function hashTrustSignalEnvelope(envelope) {
+    return sha256(encodeTrustSignalEnvelope(envelope));
+}
+/**
+ * Does this envelope actually hash to `expected`? Length is checked first, so a truncated hash can
+ * never pass by matching a prefix. The comparison is constant-time in the length of the input: a
+ * signal hash is public, but the habit is cheap and the alternative invites a timing oracle the day
+ * one of these stops being public.
+ *
+ * ⚠️ THIS RETURNS `false` FOR A WRONG HASH BUT **THROWS** FOR A MALFORMED ENVELOPE, AND THAT
+ * ASYMMETRY IS DELIBERATE. A wrong hash is a normal, expected answer ("no, this doesn't match"). A
+ * malformed envelope is not an answer at all — it is an envelope that cannot be canonicalized, so
+ * there is no hash to compare and any boolean would be a lie.
+ *
+ * The directory calls this on hostile input. DO NOT wrap it in `try { … } catch { return false }`:
+ * that converts "this envelope is unhashable garbage" into "this envelope simply didn't match",
+ * which is the silent swallow that hides the attack. Let it throw, and log the cause.
+ */
+export function verifyTrustSignalHash(envelope, expected) {
+    if (!(expected instanceof Uint8Array) || expected.length !== SIGNAL_HASH_BYTES)
+        return false;
+    const actual = hashTrustSignalEnvelope(envelope);
+    let diff = 0;
+    for (let i = 0; i < actual.length; i++)
+        diff |= actual[i] ^ expected[i];
+    return diff === 0;
+}
+//# sourceMappingURL=trust-signal.js.map

package/dist/trust-signal.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cello-protocol/protocol-types",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "private": false,
   "type": "module",
   "engines": {
@@ -15,15 +15,18 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
-    }
+    },
+    "./test/vectors/*": "./test/vectors/*",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist/",
+    "test/vectors/",
     "package.json"
   ],
   "dependencies": {
     "cbor-x": "^1.6.4",
-    "@cello-protocol/crypto": "0.0.19"
+    "@cello-protocol/crypto": "0.0.22"
   },
   "devDependencies": {
     "@claude-flow/testing": "3.0.0-alpha.6",

package/test/vectors/connection-package-canonical.json

@@ -0,0 +1,10 @@
+{
+  "description": "CELLO-CONNREQ-001: connection package canonical CBOR fixture",
+  "seed_hex": "deadbeefcafe0102030405060708090a0b0c0d0e0f101112131415161718191a",
+  "pseudonym_label": "ac009-agent",
+  "klocal_pubkey_derive": "ac009-klocal",
+  "primary_pubkey_derive": "ac009-primary",
+  "created_at": 1746057600000,
+  "expected_cbor_hex": "b900037170736575646f6e796d5f62696e64696e67b900066f70736575646f6e796d5f6c6162656c6b61633030392d6167656e746e6b5f6c6f63616c5f7075626b657958204c4dc1cdb4434b1cf0efc479f57f71c3e095ca28835ebf0fdd295fe48b6247916e7072696d6172795f7075626b657958409a8f5157d02c2588c6468da9e74b8414fe3719cd254de95689a045e01afa3bf69a8f5157d02c2588c6468da9e74b8414fe3719cd254de95689a045e01afa3bf66d6d6c5f6473615f7075626b65795905202e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad2e329a65af7790d0d9374d4893a5d5dcbab74f3c5b9f4cfe5788d57fb58273ad6a637265617465645f61741b0000019689249c00706d6c5f6473615f7369676e617475726559097494de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d60830a5d0f5bf7021ab000caf8a6994de5f68123bf5f8eaaf206a1daf32fa13d608306c656e646f7273656d656e7473806c6174746573746174696f6e7380",
+  "_encoding": "Plain CBOR (RFC 8949). Byte fields are CBOR byte strings; objects are CBOR maps. NOT cbor-x's record extension (tag 57343) \u2014 that is a cbor-x-private format no other CBOR reader can parse."
+}

package/test/vectors/envelope-v1-canonical.json

@@ -0,0 +1,16 @@
+{
+  "description": "CELLO-MSG-003 AC-007 canonical v1 envelope fixture. Cross-implementation regression guard. RFC 8949 §4.2.1.",
+  "_note": "full_envelope_cbor_hex excludes sender_signature (keypair-dependent). Tests verify tbs_cbor_hex and content_hash_hex; signature is tested separately with a generated keypair.",
+  "inputs": {
+    "protocol_version": 1,
+    "content_hex": "68656c6c6f",
+    "sender_pubkey_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "session_id_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "last_seen_seq": 0,
+    "timestamp": 1700000000000
+  },
+  "expected": {
+    "content_hash_hex": "8a2a5c9b768827de5a9552c38a044c66959c68f6d2f21b5260af54d2f87db827",
+    "tbs_cbor_hex": "860158208a2a5c9b768827de5a9552c38a044c66959c68f6d2f21b5260af54d2f87db8275820aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa50bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb001b0000018bcfe56800"
+  }
+}

package/test/vectors/genesis-prev-root.json

@@ -0,0 +1,53 @@
+{
+  "description": "CELLO-SESSION-002 SI-004: genesis prev_root fixture. SHA-256(min(A,B) || max(A,B) || session_id || session_timestamp_be8) where pubkeys are sorted bytewise-lexicographically and timestamp is 8-byte big-endian unsigned integer (milliseconds since Unix epoch).",
+  "fixtures": [
+    {
+      "_note": "A < B (0xaa < 0xbb) — no reordering needed",
+      "inputs": {
+        "pubkey_a_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "pubkey_b_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "session_id_hex": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        "session_timestamp_ms": 1700000000000
+      },
+      "intermediate": {
+        "min_pubkey_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "max_pubkey_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "timestamp_be8_hex": "0000018bcfe56800",
+        "preimage_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000018bcfe56800"
+      },
+      "expected_genesis_prev_root_hex": "e2f3e8e2eff39907ea59df96aa4f63dbdae3ca8cebe35ed5e5240b1543161932"
+    },
+    {
+      "_note": "B < A (0xaa < 0xbb) — args supplied in reversed order; result must be identical to fixture 1 with same effective min/max",
+      "inputs": {
+        "pubkey_a_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "pubkey_b_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "session_id_hex": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        "session_timestamp_ms": 1700000000000
+      },
+      "intermediate": {
+        "min_pubkey_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "max_pubkey_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "timestamp_be8_hex": "0000018bcfe56800",
+        "preimage_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000018bcfe56800"
+      },
+      "expected_genesis_prev_root_hex": "e2f3e8e2eff39907ea59df96aa4f63dbdae3ca8cebe35ed5e5240b1543161932"
+    },
+    {
+      "_note": "Different pubkeys and timestamp — cross-check for distinct inputs",
+      "inputs": {
+        "pubkey_a_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "pubkey_b_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "session_id_hex": "11111111111111111111111111111111",
+        "session_timestamp_ms": 1746000000000
+      },
+      "intermediate": {
+        "min_pubkey_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "max_pubkey_hex": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "timestamp_be8_hex": "0000019685b5b400",
+        "preimage_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb111111111111111111111111111111110000019685b5b400"
+      },
+      "expected_genesis_prev_root_hex": "b78b94839803ec7f1654518c0fbb796f1ba2992f7f40d611cca7948b92ff2848"
+    }
+  ]
+}

package/test/vectors/scan-result-unscanned.json

@@ -0,0 +1,5 @@
+{
+  "description": "CELLO-MERKLE-002 AC-007: M1 scan_result sentinel — canonical CBOR map. RFC 8949 §4.2.1.",
+  "_note": "CBOR map with 3 keys sorted by byte-length (RFC 8949 §4.2.1): score(5) < verdict(7) < model_hash(10). score=null, verdict='unscanned' (9 bytes), model_hash=<32 zero bytes>.",
+  "expected_cbor_hex": "a36573636f7265f6677665726469637469756e7363616e6e65646a6d6f64656c5f6861736858200000000000000000000000000000000000000000000000000000000000000000"
+}

package/test/vectors/structure1-canonical.json

@@ -0,0 +1,13 @@
+{
+  "description": "CELLO-MERKLE-002 AC-001: Structure 1 canonical CBOR fixture. RFC 8949 §4.2.1.",
+  "_note": "Canonical CBOR of the 6-element positional TBS array for protocol_version=1.",
+  "inputs": {
+    "protocol_version": 1,
+    "content_hash_hex": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "sender_pubkey_hex": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+    "session_id_hex": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+    "last_seen_seq": 3,
+    "timestamp": 1700000000000
+  },
+  "expected_cbor_hex": "86015820cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc5820dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd50eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee031b0000018bcfe56800"
+}

package/test/vectors/structure2-canonical.json

@@ -0,0 +1,12 @@
+{
+  "description": "CELLO-MERKLE-002 AC-002: Structure 2 canonical CBOR fixture. RFC 8949 §4.2.1.",
+  "_note": "Canonical CBOR of the 6-element positional relay-built leaf: [sequence_number, sender_pubkey, content_hash, sender_signature, scan_result, prev_root]. scan_result is the M1 sentinel: {score:null, verdict:'unscanned', model_hash:<32 zero bytes>}.",
+  "inputs": {
+    "sequence_number": 1,
+    "sender_pubkey_hex": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+    "content_hash_hex": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "sender_signature_hex": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "prev_root_hex": "0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "expected_cbor_hex": "86015820dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd5820cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc5840aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa36573636f7265f6677665726469637469756e7363616e6e65646a6d6f64656c5f686173685820000000000000000000000000000000000000000000000000000000000000000058200000000000000000000000000000000000000000000000000000000000000000"
+}

package/test/vectors/tbs-v0-canonical.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "CELLO-MSG-001 TBS v0 canonical CBOR fixture. Cross-implementation regression guard. RFC 8949 \u00a74.2.1.",
+  "protocol_version": 0,
+  "content_hash_hex": "0000000000000000000000000000000000000000000000000000000000000000",
+  "sender_pubkey_hex": "abababababababababababababababababababababababababababababababab",
+  "timestamp": 1746057600000,
+  "expected_cbor_hex": "8400582000000000000000000000000000000000000000000000000000000000000000005820abababababababababababababababababababababababababababababababab1b0000019689249c00"
+}

package/test/vectors/trust-signal-envelope-canonical.json

@@ -0,0 +1,136 @@
+{
+  "_comment": [
+    "DOD-CBOR-1 / DOD-INV-CANONICAL — FROZEN cross-party vectors for the trust-signal envelope.",
+    "Every party that derives a signal_hash — the portal at mint, the directory at submission and at",
+    "presentation, the holder and recipient daemons — MUST reproduce these bytes exactly. All three",
+    "repos check their SHIPPED @cello-protocol/protocol-types against this file, so a version skew",
+    "between repos fails loud here instead of silently forking the hash in production.",
+    "Preimage (array, fixed order, domain tag in slot 0 — M10-D15/D17):",
+    "  [ 'CELLO-TSIG-v1', subject_kind, subject, issuer_kind, issuer_pubkey, type, schema_version,",
+    "    payload, issued_at, expires_at|null, supersedes_hash|null ]",
+    "payload and supersedes_hash are hex-encoded HERE for legibility only; they are RAW BYTES in the",
+    "preimage. status/class/verified_at are deliberately NOT hashed (mutable after minting).",
+    "CHANGING A BYTE IN THIS FILE IS A PROTOCOL BREAK — it invalidates every signal ever minted."
+  ],
+  "vectors": [
+    {
+      "name": "reference — agent subject, portal issuer, no expiry, first mint",
+      "envelope": {
+        "subject_kind": "agent",
+        "subject": "agent-1",
+        "issuer_kind": "portal",
+        "issuer_pubkey": "aabb",
+        "type": "phone",
+        "schema_version": 1,
+        "payload": "01020304",
+        "issued_at": 1000000000,
+        "expires_at": null,
+        "supersedes_hash": null
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631656167656e74676167656e742d3166706f7274616c64616162626570686f6e650144010203041a3b9aca00f6f6",
+      "signal_hash_hex": "760af64a292f96bffde522e21a8fcae0c31fc7826c4e2c947939a2da50803672"
+    },
+    {
+      "name": "account subject — one envelope, every agent under the account presents it (M10-D5)",
+      "envelope": {
+        "subject_kind": "account",
+        "subject": "acct_7f3a",
+        "issuer_kind": "portal",
+        "issuer_pubkey": "3d4f6a2b8c1e",
+        "type": "email",
+        "schema_version": 1,
+        "payload": "a1646b696e64",
+        "issued_at": 1768000000,
+        "expires_at": 1799536000,
+        "supersedes_hash": null
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631676163636f756e7469616363745f3766336166706f7274616c6c33643466366132623863316565656d61696c0146a1646b696e641a69618a001a6b42bd80f6",
+      "signal_hash_hex": "2b7ace095f07efbd1c8f5efef701a8969d2c6c8efb3f6291b27eefcd287fba16"
+    },
+    {
+      "name": "supersession — a re-minted track-record signal replacing an earlier one",
+      "envelope": {
+        "subject_kind": "agent",
+        "subject": "agent-1",
+        "issuer_kind": "portal",
+        "issuer_pubkey": "aabb",
+        "type": "session_count",
+        "schema_version": 2,
+        "payload": "deadbeef",
+        "issued_at": 1768000123,
+        "expires_at": 1768604923,
+        "supersedes_hash": "1111111111111111111111111111111111111111111111111111111111111111"
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631656167656e74676167656e742d3166706f7274616c64616162626d73657373696f6e5f636f756e740244deadbeef1a69618a7b1a696ac4fb58201111111111111111111111111111111111111111111111111111111111111111",
+      "signal_hash_hex": "0184ae76433d9c4caf892d438bff3f64d44f0eed57470f0c141fee86b18e0bbb"
+    },
+    {
+      "name": "agent issuer — quoted-untrusted framing at the LLM (INV-FRAMING)",
+      "envelope": {
+        "subject_kind": "agent",
+        "subject": "agent-2",
+        "issuer_kind": "agent",
+        "issuer_pubkey": "ff00ff00",
+        "type": "endorsement",
+        "schema_version": 1,
+        "payload": "",
+        "issued_at": 1768000000,
+        "expires_at": null,
+        "supersedes_hash": null
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631656167656e74676167656e742d32656167656e746866663030666630306b656e646f7273656d656e7401401a69618a00f6f6",
+      "signal_hash_hex": "39d148391745fa3ea26b8fe57b5633c4bec7064a896527abb9300355b02ec5a6"
+    },
+    {
+      "name": "UNKNOWN type — a type this code has never seen must hash identically (INV-TYPE-CARRY)",
+      "envelope": {
+        "subject_kind": "agent",
+        "subject": "agent-1",
+        "issuer_kind": "portal",
+        "issuer_pubkey": "aabb",
+        "type": "some_type_invented_next_year",
+        "schema_version": 1,
+        "payload": "00",
+        "issued_at": 1768000000,
+        "expires_at": null,
+        "supersedes_hash": null
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631656167656e74676167656e742d3166706f7274616c6461616262781c736f6d655f747970655f696e76656e7465645f6e6578745f796561720141001a69618a00f6f6",
+      "signal_hash_hex": "9a637f2ca5b4fbb0f78c9eb2d33cfc433706290a7c4a4e6bf2628d258b90f1c9"
+    },
+    {
+      "name": "payload that LOOKS like CBOR — embedded verbatim, never parsed",
+      "envelope": {
+        "subject_kind": "agent",
+        "subject": "agent-1",
+        "issuer_kind": "portal",
+        "issuer_pubkey": "aabb",
+        "type": "canary_test",
+        "schema_version": 1,
+        "payload": "d840009fff",
+        "issued_at": 1768000000,
+        "expires_at": null,
+        "supersedes_hash": null
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631656167656e74676167656e742d3166706f7274616c64616162626b63616e6172795f746573740145d840009fff1a69618a00f6f6",
+      "signal_hash_hex": "5dc67366d7b8fc515a6d638b432d90e29a2f9841101a3ac1745ca7b602e2f837"
+    },
+    {
+      "name": "FAR-FUTURE expiry past 2^32 — must hash as a CBOR uint64 (1b...), NEVER a float64 (fb...)",
+      "envelope": {
+        "subject_kind": "agent",
+        "subject": "agent-1",
+        "issuer_kind": "portal",
+        "issuer_pubkey": "aabb",
+        "type": "phone",
+        "schema_version": 1,
+        "payload": "01020304",
+        "issued_at": 1768000000,
+        "expires_at": 4920000000,
+        "supersedes_hash": null
+      },
+      "preimage_hex": "8b6d43454c4c4f2d545349472d7631656167656e74676167656e742d3166706f7274616c64616162626570686f6e650144010203041a69618a001b0000000125413e00f6",
+      "signal_hash_hex": "3c95520077ca1bb25f360c886008691bab1114e1ecad43ba90558df5d5a0b79e"
+    }
+  ]
+}