@cello-protocol/protocol-types 0.0.2

package/dist/session.d.ts

@@ -0,0 +1,239 @@
+/**
+ * CELLO-SESSION-002/MSG-004/SESSION-003/SESSION-004/SESSION-005 — session.ts
+ *
+ * SessionAssignment: shared wire type used by directory (sender), client (receiver),
+ * and relay (verifier). Lives here so client can import it without touching @cello-protocol/directory.
+ *
+ * SESSION-004 additions to SessionAssignment:
+ *   signature_type: 'frost' | 'single'
+ *     - 'frost': the directory_signature field carries the 64-byte combined FROST output
+ *     - 'single': M1-era single-key directory signature (refused by M2 clients)
+ *   signer_pubkey?: Uint8Array (32 bytes, present when signature_type === 'frost')
+ *     - The initiator's primary_pubkey (group FROST key). Embedded so the counterparty
+ *       can verify without a separate directory round-trip.
+ *
+ * FROST TBS for session establishment (RFC 9591, domain separation per CONTEXT.md):
+ *   context: "cello-frost-session-establishment-v1"
+ *   tbs: canonical CBOR([session_id, agent_A_pubkey, agent_B_pubkey, genesis_prev_root, timestamp])
+ *   framing: <context>\0<tbs_cbor>
+ *   Note: signer_pubkey is NOT in the TBS — it is derived from DKG and embedded in the frame.
+ *
+ * SealPayload: canonical CBOR of [session_id, final_root, close_timestamp, "PENDING"].
+ * Per SESSION-003. content_hash = SHA-256(0x00 || SealPayload) per MERKLE-001.
+ *
+ * computeGenesisPrevRoot: deterministic genesis prev_root for a two-party session.
+ *
+ * Formula (SI-004):
+ *   SHA-256(min(A_pubkey, B_pubkey) || max(A_pubkey, B_pubkey) || session_id || timestamp_be8)
+ *
+ * Pubkeys are sorted bytewise-lexicographically (Buffer.compare).
+ * timestamp_be8 is the session_timestamp encoded as an 8-byte big-endian unsigned integer
+ * (milliseconds since Unix epoch). Raw byte concatenation — no CBOR at this boundary,
+ * which would introduce width ambiguity on the timestamp encoding.
+ *
+ * Per FIPS 180-4 (SHA-256) and SESSION-002 SI-004.
+ *
+ * ─── Phase P: SESSION-004 Pseudocode ─────────────────────────────────────────
+ *
+ * SessionAssignment type changes (MEDIUM-6: discriminated union enforces signer_pubkey):
+ *   // Use a discriminated union so TypeScript enforces signer_pubkey is present for 'frost'
+ *   type SessionAssignmentFrost = { ...common fields..., signature_type: 'frost', signer_pubkey: Uint8Array }
+ *   type SessionAssignmentSingle = { ...common fields..., signature_type: 'single' }
+ *   type SessionAssignment = SessionAssignmentFrost | SessionAssignmentSingle
+ *
+ *   // Common fields (all existing SessionAssignment fields plus signature_type + signer_pubkey):
+ *   session_id, participant_a, participant_b, relay_endpoint, directory_endpoint,
+ *   session_timestamp, directory_pubkey, directory_signature
+ *
+ * buildSessionEstablishmentTbs(sessionId, pubA, pubB, genesisPrevRoot, timestamp):
+ *   // HIGH-5: exported from protocol-types so both directory and client use identical CBOR encoding
+ *   //         Any encoding drift would cause silent verification failures.
+ *   // TBS = canonical CBOR([session_id, agent_A_pubkey, agent_B_pubkey, genesis_prev_root, timestamp])
+ *   // Per CONTEXT.md: uses CBOR_ENC.encode() with tagUint8Array: false
+ *   // timestamp is uint32 or BigInt depending on size (>0xffffffff → BigInt)
+ *   return CBOR_ENC.encode([sessionId, pubA, pubB, genesisPrevRoot,
+ *                           timestamp > 0xffffffff ? BigInt(timestamp) : timestamp])
+ *
+ * IMPORTANT-8: Existing test files that build SessionAssignment objects need updating to
+ * include signature_type. Files affected (all M1 tests add signature_type: 'single'):
+ *   - packages/client/src/__tests__/session.test.ts (makeDirectoryAssignment helper)
+ *   - packages/client/src/__tests__/msg004.test.ts (makeDirectoryAssignment helper)
+ *   - packages/client/src/__tests__/session003.test.ts (multiple construction sites)
+ *   - packages/client/src/__tests__/session006.test.ts (makeDirectoryAssignment helper)
+ *   - packages/e2e-tests/src/__tests__/mcp-002.test.ts (assignment construction)
+ *   - packages/relay/src/__tests__/relay-node.test.ts (makeAssignment helper)
+ *   - packages/relay/src/__tests__/relay-incremental.test.ts (makeAssignment helper)
+ *   - packages/directory/src/directory-frames.ts (decodeOutboundSignalingFrame parser)
+ *
+ * IMPORTANT-9: ReceiveAssignmentResult in client/src/types.ts needs 'unsupported_signature_type'
+ *   added to its reason union.
+ *
+ * ─── End Phase P Pseudocode ───────────────────────────────────────────────────
+ *
+ * buildSealTbs: FROST TBS for conversation seal (SESSION-005).
+ * FROST TBS fields: [session_id, sealed_root, leaf_count, timestamp]
+ * Context string: "cello-frost-seal-v1" (per CONTEXT.md)
+ * Both sides (directory as signer, client as verifier) must use the same encoding.
+ * Per RFC 9591 (FROST), RFC 8949 (CBOR canonical), FIPS 180-4 (SHA-256).
+ */
+export interface ParticipantInfo {
+    pubkey: Uint8Array;
+    peer_id: string;
+    multiaddrs: string[];
+}
+export interface RelayEndpointInfo {
+    peer_id: string;
+    multiaddrs: string[];
+}
+/** Common fields shared by both SessionAssignment variants. */
+interface SessionAssignmentCommon {
+    session_id: Uint8Array;
+    participant_a: ParticipantInfo;
+    participant_b: ParticipantInfo;
+    relay_endpoint: RelayEndpointInfo;
+    directory_endpoint: RelayEndpointInfo;
+    session_timestamp: number;
+    directory_pubkey: Uint8Array;
+    directory_signature: Uint8Array;
+}
+/**
+ * SESSION-004: FROST-signed assignment. `signer_pubkey` is the initiator's
+ * group public key (primary_pubkey from DKG / trustedDealer commitments[0]).
+ * Embedded so the counterparty can verify without a directory round-trip.
+ */
+export interface SessionAssignmentFrost extends SessionAssignmentCommon {
+    signature_type: "frost";
+    signer_pubkey: Uint8Array;
+}
+/**
+ * M1-era single-key directory signature. Refused by M2+ clients.
+ */
+export interface SessionAssignmentSingle extends SessionAssignmentCommon {
+    signature_type: "single";
+}
+/**
+ * Discriminated union. TypeScript enforces `signer_pubkey` is present only
+ * when `signature_type === 'frost'`.
+ *
+ * SESSION-004: M2+ code should only handle 'frost'. M1 assignments with
+ * 'single' are rejected with `unsupported_signature_type`.
+ */
+export type SessionAssignment = SessionAssignmentFrost | SessionAssignmentSingle;
+/**
+ * Build the FROST to-be-signed bytes for session establishment.
+ *
+ * Exported from protocol-types so BOTH the directory (signer) and the client
+ * (verifier) use identical canonical CBOR encoding. Any drift would silently
+ * break verification.
+ *
+ * TBS = canonical CBOR([session_id, agent_A_pubkey, agent_B_pubkey, genesis_prev_root, timestamp])
+ *
+ * Per CONTEXT.md: tagUint8Array: false. Timestamp encoded as BigInt when > 0xffffffff.
+ *
+ * @param sessionId - 16-byte session identifier
+ * @param pubA - 32-byte K_local pubkey of participant A
+ * @param pubB - 32-byte K_local pubkey of participant B
+ * @param genesisPrevRoot - 32-byte genesis prev_root (output of computeGenesisPrevRoot)
+ * @param timestamp - session_timestamp in Unix milliseconds
+ * @returns canonical CBOR bytes of the TBS array
+ */
+export declare function buildSessionEstablishmentTbs(sessionId: Uint8Array, pubA: Uint8Array, pubB: Uint8Array, genesisPrevRoot: Uint8Array, timestamp: number | bigint): Uint8Array;
+/**
+ * SEAL control payload carried as the content_bytes of a ctrl leaf.
+ * Canonical CBOR encoding: [session_id, final_root, close_timestamp, "PENDING"].
+ * Per SESSION-003 behavior spec.
+ */
+export interface SealPayload {
+    session_id: Uint8Array;
+    final_root: Uint8Array;
+    close_timestamp: number;
+    attestation: "PENDING";
+}
+/**
+ * Encode a SealPayload as canonical CBOR: [session_id, final_root, close_timestamp, "PENDING"].
+ * Per SESSION-003 behavior spec and RFC 8949 §4.2.1.
+ */
+export declare function encodeSealPayload(payload: SealPayload): Uint8Array;
+/**
+ * Decode a SEAL payload CBOR. Returns null on malformed input.
+ */
+export declare function decodeSealPayload(bytes: Uint8Array): SealPayload | null;
+/**
+ * Build the FROST to-be-signed bytes for a conversation seal ceremony.
+ *
+ * FROST TBS for seal (CONTEXT.md): canonical CBOR([session_id, sealed_root, leaf_count, timestamp])
+ * Context string: "cello-frost-seal-v1" (domain separation, prevents establishment replay)
+ * Per RFC 9591 (FROST) and RFC 8949 §4.2.1 (canonical CBOR).
+ *
+ * Both the directory (as ceremony participant verifying the signature) and the client
+ * (as the coordinator who submits the signature) MUST use this exact encoding.
+ *
+ * @param sessionId - 16-byte session identifier
+ * @param sealedRoot - 32-byte final Merkle root
+ * @param leafCount - total number of leaves in the sealed tree
+ * @param timestamp - Unix milliseconds at the time of verification
+ */
+export declare function buildSealTbs(sessionId: Uint8Array, sealedRoot: Uint8Array, leafCount: number, timestamp: number): Uint8Array;
+export interface SessionAbandoned {
+    type: "session_abandoned";
+    session_id: Uint8Array;
+}
+/**
+ * M1 session_sealed frame (single-key directory signature).
+ * Refused in M2 clients per SESSION-005 SI-003.
+ * @deprecated Use SessionSealedFrost instead in M2+.
+ */
+export interface SessionSealedSingle {
+    type: "session_sealed";
+    signature_type: "single";
+    session_id: Uint8Array;
+    sealed_root: Uint8Array;
+    directory_signature: Uint8Array;
+    close_timestamp: number;
+}
+/**
+ * M2 session_sealed frame (FROST-notarized ceremony signature).
+ * SESSION-005: seal_type is 'frost' when the FROST ceremony completes.
+ */
+export interface SessionSealedFrost {
+    type: "session_sealed";
+    signature_type: "frost";
+    session_id: Uint8Array;
+    sealed_root: Uint8Array;
+    frost_signature: Uint8Array;
+    signer_pubkey: Uint8Array;
+    close_timestamp: number;
+    leaf_count?: number;
+}
+/** Discriminated union: M2 sends SessionSealedFrost; old M1 wire format is SessionSealedSingle. */
+export type SessionSealed = SessionSealedSingle | SessionSealedFrost;
+export type SealRejectionReason = "merkle_root_mismatch" | "leaf_signature_invalid" | "prev_root_chain_broken" | "causal_chain_violated" | "seal_leaves_invalid" | "seal_signature_invalid";
+export interface SessionSealRejected {
+    type: "session_seal_rejected";
+    session_id: Uint8Array;
+    reason: SealRejectionReason;
+}
+/**
+ * seal_verified: directory → seal initiator, after all three verification passes pass.
+ * Tells the initiator: "I've verified the tree — coordinate the FROST ceremony now."
+ * Per SESSION-005 step 4 in the seal ceremony flow.
+ */
+export interface SealVerified {
+    type: "seal_verified";
+    session_id: Uint8Array;
+    sealed_root: Uint8Array;
+    leaf_count: number;
+    timestamp: number;
+}
+/**
+ * Compute the genesis prev_root for a two-party CELLO session.
+ *
+ * @param pubkeyA - K_local pubkey of participant A (32 bytes)
+ * @param pubkeyB - K_local pubkey of participant B (32 bytes)
+ * @param sessionId - session_id from the directory (16 bytes)
+ * @param sessionTimestampMs - session_timestamp in milliseconds since Unix epoch
+ * @returns 32-byte genesis prev_root (SHA-256 output)
+ */
+export declare function computeGenesisPrevRoot(pubkeyA: Uint8Array, pubkeyB: Uint8Array, sessionId: Uint8Array, sessionTimestampMs: number | bigint): Uint8Array;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

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

package/dist/session.js

@@ -0,0 +1,198 @@
+/**
+ * CELLO-SESSION-002/MSG-004/SESSION-003/SESSION-004/SESSION-005 — session.ts
+ *
+ * SessionAssignment: shared wire type used by directory (sender), client (receiver),
+ * and relay (verifier). Lives here so client can import it without touching @cello-protocol/directory.
+ *
+ * SESSION-004 additions to SessionAssignment:
+ *   signature_type: 'frost' | 'single'
+ *     - 'frost': the directory_signature field carries the 64-byte combined FROST output
+ *     - 'single': M1-era single-key directory signature (refused by M2 clients)
+ *   signer_pubkey?: Uint8Array (32 bytes, present when signature_type === 'frost')
+ *     - The initiator's primary_pubkey (group FROST key). Embedded so the counterparty
+ *       can verify without a separate directory round-trip.
+ *
+ * FROST TBS for session establishment (RFC 9591, domain separation per CONTEXT.md):
+ *   context: "cello-frost-session-establishment-v1"
+ *   tbs: canonical CBOR([session_id, agent_A_pubkey, agent_B_pubkey, genesis_prev_root, timestamp])
+ *   framing: <context>\0<tbs_cbor>
+ *   Note: signer_pubkey is NOT in the TBS — it is derived from DKG and embedded in the frame.
+ *
+ * SealPayload: canonical CBOR of [session_id, final_root, close_timestamp, "PENDING"].
+ * Per SESSION-003. content_hash = SHA-256(0x00 || SealPayload) per MERKLE-001.
+ *
+ * computeGenesisPrevRoot: deterministic genesis prev_root for a two-party session.
+ *
+ * Formula (SI-004):
+ *   SHA-256(min(A_pubkey, B_pubkey) || max(A_pubkey, B_pubkey) || session_id || timestamp_be8)
+ *
+ * Pubkeys are sorted bytewise-lexicographically (Buffer.compare).
+ * timestamp_be8 is the session_timestamp encoded as an 8-byte big-endian unsigned integer
+ * (milliseconds since Unix epoch). Raw byte concatenation — no CBOR at this boundary,
+ * which would introduce width ambiguity on the timestamp encoding.
+ *
+ * Per FIPS 180-4 (SHA-256) and SESSION-002 SI-004.
+ *
+ * ─── Phase P: SESSION-004 Pseudocode ─────────────────────────────────────────
+ *
+ * SessionAssignment type changes (MEDIUM-6: discriminated union enforces signer_pubkey):
+ *   // Use a discriminated union so TypeScript enforces signer_pubkey is present for 'frost'
+ *   type SessionAssignmentFrost = { ...common fields..., signature_type: 'frost', signer_pubkey: Uint8Array }
+ *   type SessionAssignmentSingle = { ...common fields..., signature_type: 'single' }
+ *   type SessionAssignment = SessionAssignmentFrost | SessionAssignmentSingle
+ *
+ *   // Common fields (all existing SessionAssignment fields plus signature_type + signer_pubkey):
+ *   session_id, participant_a, participant_b, relay_endpoint, directory_endpoint,
+ *   session_timestamp, directory_pubkey, directory_signature
+ *
+ * buildSessionEstablishmentTbs(sessionId, pubA, pubB, genesisPrevRoot, timestamp):
+ *   // HIGH-5: exported from protocol-types so both directory and client use identical CBOR encoding
+ *   //         Any encoding drift would cause silent verification failures.
+ *   // TBS = canonical CBOR([session_id, agent_A_pubkey, agent_B_pubkey, genesis_prev_root, timestamp])
+ *   // Per CONTEXT.md: uses CBOR_ENC.encode() with tagUint8Array: false
+ *   // timestamp is uint32 or BigInt depending on size (>0xffffffff → BigInt)
+ *   return CBOR_ENC.encode([sessionId, pubA, pubB, genesisPrevRoot,
+ *                           timestamp > 0xffffffff ? BigInt(timestamp) : timestamp])
+ *
+ * IMPORTANT-8: Existing test files that build SessionAssignment objects need updating to
+ * include signature_type. Files affected (all M1 tests add signature_type: 'single'):
+ *   - packages/client/src/__tests__/session.test.ts (makeDirectoryAssignment helper)
+ *   - packages/client/src/__tests__/msg004.test.ts (makeDirectoryAssignment helper)
+ *   - packages/client/src/__tests__/session003.test.ts (multiple construction sites)
+ *   - packages/client/src/__tests__/session006.test.ts (makeDirectoryAssignment helper)
+ *   - packages/e2e-tests/src/__tests__/mcp-002.test.ts (assignment construction)
+ *   - packages/relay/src/__tests__/relay-node.test.ts (makeAssignment helper)
+ *   - packages/relay/src/__tests__/relay-incremental.test.ts (makeAssignment helper)
+ *   - packages/directory/src/directory-frames.ts (decodeOutboundSignalingFrame parser)
+ *
+ * IMPORTANT-9: ReceiveAssignmentResult in client/src/types.ts needs 'unsupported_signature_type'
+ *   added to its reason union.
+ *
+ * ─── End Phase P Pseudocode ───────────────────────────────────────────────────
+ *
+ * buildSealTbs: FROST TBS for conversation seal (SESSION-005).
+ * FROST TBS fields: [session_id, sealed_root, leaf_count, timestamp]
+ * Context string: "cello-frost-seal-v1" (per CONTEXT.md)
+ * Both sides (directory as signer, client as verifier) must use the same encoding.
+ * Per RFC 9591 (FROST), RFC 8949 (CBOR canonical), FIPS 180-4 (SHA-256).
+ */
+import { createHash } from "node:crypto";
+import { Encoder, decode as cborDecode } from "cbor-x";
+const CBOR_ENC = new Encoder({ tagUint8Array: false });
+// ─── Session establishment TBS builder (SESSION-004 / HIGH-5) ─────────────────
+/**
+ * Build the FROST to-be-signed bytes for session establishment.
+ *
+ * Exported from protocol-types so BOTH the directory (signer) and the client
+ * (verifier) use identical canonical CBOR encoding. Any drift would silently
+ * break verification.
+ *
+ * TBS = canonical CBOR([session_id, agent_A_pubkey, agent_B_pubkey, genesis_prev_root, timestamp])
+ *
+ * Per CONTEXT.md: tagUint8Array: false. Timestamp encoded as BigInt when > 0xffffffff.
+ *
+ * @param sessionId - 16-byte session identifier
+ * @param pubA - 32-byte K_local pubkey of participant A
+ * @param pubB - 32-byte K_local pubkey of participant B
+ * @param genesisPrevRoot - 32-byte genesis prev_root (output of computeGenesisPrevRoot)
+ * @param timestamp - session_timestamp in Unix milliseconds
+ * @returns canonical CBOR bytes of the TBS array
+ */
+export function buildSessionEstablishmentTbs(sessionId, pubA, pubB, genesisPrevRoot, timestamp) {
+    return CBOR_ENC.encode([
+        sessionId,
+        pubA,
+        pubB,
+        genesisPrevRoot,
+        typeof timestamp === "bigint" || timestamp > 0xffffffff ? BigInt(timestamp) : timestamp,
+    ]);
+}
+/**
+ * Encode a SealPayload as canonical CBOR: [session_id, final_root, close_timestamp, "PENDING"].
+ * Per SESSION-003 behavior spec and RFC 8949 §4.2.1.
+ */
+export function encodeSealPayload(payload) {
+    return CBOR_ENC.encode([
+        payload.session_id,
+        payload.final_root,
+        payload.close_timestamp > 0xffffffff
+            ? BigInt(payload.close_timestamp)
+            : payload.close_timestamp,
+        payload.attestation,
+    ]);
+}
+/**
+ * Decode a SEAL payload CBOR. Returns null on malformed input.
+ */
+export function decodeSealPayload(bytes) {
+    let arr;
+    try {
+        arr = cborDecode(bytes);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(arr) || arr.length !== 4)
+        return null;
+    const [_sid, _root, _ts, _attest] = arr;
+    const sid = _sid instanceof Uint8Array ? _sid : Buffer.isBuffer(_sid) ? new Uint8Array(_sid) : null;
+    const root = _root instanceof Uint8Array ? _root : Buffer.isBuffer(_root) ? new Uint8Array(_root) : null;
+    if (!sid || sid.length !== 16)
+        return null;
+    if (!root || root.length !== 32)
+        return null;
+    const ts = typeof _ts === "number" ? _ts : typeof _ts === "bigint" ? Number(_ts) : null;
+    if (ts === null)
+        return null;
+    if (_attest !== "PENDING")
+        return null;
+    return { session_id: sid, final_root: root, close_timestamp: ts, attestation: "PENDING" };
+}
+// ─── buildSealTbs (SESSION-005) ───────────────────────────────────────────────
+/**
+ * Build the FROST to-be-signed bytes for a conversation seal ceremony.
+ *
+ * FROST TBS for seal (CONTEXT.md): canonical CBOR([session_id, sealed_root, leaf_count, timestamp])
+ * Context string: "cello-frost-seal-v1" (domain separation, prevents establishment replay)
+ * Per RFC 9591 (FROST) and RFC 8949 §4.2.1 (canonical CBOR).
+ *
+ * Both the directory (as ceremony participant verifying the signature) and the client
+ * (as the coordinator who submits the signature) MUST use this exact encoding.
+ *
+ * @param sessionId - 16-byte session identifier
+ * @param sealedRoot - 32-byte final Merkle root
+ * @param leafCount - total number of leaves in the sealed tree
+ * @param timestamp - Unix milliseconds at the time of verification
+ */
+export function buildSealTbs(sessionId, sealedRoot, leafCount, timestamp) {
+    return CBOR_ENC.encode([
+        sessionId,
+        sealedRoot,
+        leafCount,
+        timestamp > 0xffffffff ? BigInt(timestamp) : timestamp,
+    ]);
+}
+// ─── End session outcome notification frame types ─────────────────────────────
+/**
+ * Compute the genesis prev_root for a two-party CELLO session.
+ *
+ * @param pubkeyA - K_local pubkey of participant A (32 bytes)
+ * @param pubkeyB - K_local pubkey of participant B (32 bytes)
+ * @param sessionId - session_id from the directory (16 bytes)
+ * @param sessionTimestampMs - session_timestamp in milliseconds since Unix epoch
+ * @returns 32-byte genesis prev_root (SHA-256 output)
+ */
+export function computeGenesisPrevRoot(pubkeyA, pubkeyB, sessionId, sessionTimestampMs) {
+    const a = Buffer.from(pubkeyA);
+    const b = Buffer.from(pubkeyB);
+    const [min, max] = Buffer.compare(a, b) <= 0 ? [a, b] : [b, a];
+    const tsBe = Buffer.alloc(8);
+    tsBe.writeBigUInt64BE(typeof sessionTimestampMs === "bigint" ? sessionTimestampMs : BigInt(sessionTimestampMs));
+    return new Uint8Array(createHash("sha256")
+        .update(min)
+        .update(max)
+        .update(sessionId)
+        .update(tsBe)
+        .digest());
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEvD,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;AAsDvD,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,4BAA4B,CAC1C,SAAqB,EACrB,IAAgB,EAChB,IAAgB,EAChB,eAA2B,EAC3B,SAA0B;IAE1B,OAAO,QAAQ,CAAC,MAAM,CAAC;QACrB,SAAS;QACT,IAAI;QACJ,IAAI;QACJ,eAAe;QACf,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;KACxF,CAAe,CAAC;AACnB,CAAC;AAgBD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAoB;IACpD,OAAO,QAAQ,CAAC,MAAM,CAAC;QACrB,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,UAAU;QAClB,OAAO,CAAC,eAAe,GAAG,UAAU;YAClC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC;YACjC,CAAC,CAAC,OAAO,CAAC,eAAe;QAC3B,OAAO,CAAC,WAAW;KACpB,CAAe,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9G,MAAM,IAAI,GAAG,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnH,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,EAAE,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxF,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC5F,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAqB,EACrB,UAAsB,EACtB,SAAiB,EACjB,SAAiB;IAEjB,OAAO,QAAQ,CAAC,MAAM,CAAC;QACrB,SAAS;QACT,UAAU;QACV,SAAS;QACT,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;KACvD,CAAe,CAAC;AACnB,CAAC;AAsED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAmB,EACnB,OAAmB,EACnB,SAAqB,EACrB,kBAAmC;IAEnC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE/B,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,gBAAgB,CAAC,OAAO,kBAAkB,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAEhH,OAAO,IAAI,UAAU,CACnB,UAAU,CAAC,QAAQ,CAAC;SACjB,MAAM,CAAC,GAAG,CAAC;SACX,MAAM,CAAC,GAAG,CAAC;SACX,MAAM,CAAC,SAAS,CAAC;SACjB,MAAM,CAAC,IAAI,CAAC;SACZ,MAAM,EAAE,CACZ,CAAC;AACJ,CAAC"}

package/dist/structure2.d.ts

@@ -0,0 +1,75 @@
+/**
+ * CELLO-MERKLE-002 — Structure 2 wire type and codec.
+ *
+ * Structure 2 is the relay-built Merkle leaf:
+ *   [sequence_number, sender_pubkey, content_hash, sender_signature, scan_result, prev_root]
+ *
+ * scan_result in M1 is a sentinel placeholder: {score: null, verdict: "unscanned", model_hash: <32 zero bytes>}.
+ * The field is present to keep the wire layout stable for future scanner integration (M4+).
+ *
+ * Canonical CBOR per RFC 8949 §4.2.1.
+ * Ed25519 verification per RFC 8032.
+ *
+ * Structure 1 TBS (for signature verification):
+ *   [1, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]
+ * This is what the sender signs; verifyStructure2Signature reconstructs it from Structure 2 fields
+ * plus the session_id, last_seen_seq, and timestamp carried through the relay path.
+ */
+import type { EnvelopeError } from "./types.js";
+export interface ScanResultSentinel {
+    score: null;
+    verdict: "unscanned";
+    model_hash: Uint8Array;
+}
+export interface Structure2 {
+    sequence_number: number;
+    sender_pubkey: Uint8Array;
+    content_hash: Uint8Array;
+    sender_signature: Uint8Array;
+    scan_result: ScanResultSentinel;
+    prev_root: Uint8Array;
+}
+export type BuildStructure2Result = {
+    ok: true;
+    structure2: Structure2;
+} | {
+    ok: false;
+    error: EnvelopeError;
+};
+/** M1 placeholder scan_result sentinel. The scanner field is stable but unset until M4+. */
+export declare const SCAN_RESULT_SENTINEL: ScanResultSentinel;
+/**
+ * Encodes the scan_result sentinel as canonical CBOR (RFC 8949 §4.2.1).
+ *
+ * Keys are sorted by byte length per RFC 8949 §4.2.1 core deterministic encoding:
+ *   "score" (5) < "verdict" (7) < "model_hash" (10)
+ *
+ * cbor-x's default POJO encoding uses non-canonical map-size encoding (uint16 length prefix).
+ * We construct the canonical bytes manually to guarantee RFC 8949 §4.2.1 compliance.
+ */
+export declare function encodeScanResultSentinel(): Uint8Array;
+/**
+ * Constructs a Structure 2 object after validating all field lengths.
+ * scan_result is always the M1 sentinel — callers do not supply it.
+ */
+export declare function buildStructure2(sequence_number: number, sender_pubkey: Uint8Array, content_hash: Uint8Array, sender_signature: Uint8Array, prev_root: Uint8Array): BuildStructure2Result;
+/**
+ * Encodes Structure 2 as canonical CBOR (RFC 8949 §4.2.1).
+ * Wire format: [sequence_number, sender_pubkey, content_hash, sender_signature, scan_result, prev_root]
+ */
+export declare function encodeStructure2(s2: Structure2): Uint8Array;
+/**
+ * Reconstructs canonical CBOR of Structure 1 from Structure 2 fields plus the
+ * session_id, last_seen_seq, and timestamp carried through the relay path,
+ * then verifies the sender's Ed25519 signature.
+ *
+ * Structure 1 TBS: [1, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]
+ * Per RFC 8032 (Ed25519) and RFC 8949 §4.2.1 (canonical CBOR).
+ *
+ * @param timestamp - Unix milliseconds. May be number or bigint. cbor-x decodes uint64
+ *   timestamps as bigint; relay callers that deserialize Structure 1 CBOR must pass the
+ *   decoded value directly here rather than converting to number (which is lossy above
+ *   Number.MAX_SAFE_INTEGER).
+ */
+export declare function verifyStructure2Signature(s2: Structure2, session_id: Uint8Array, last_seen_seq: number, timestamp: number | bigint): boolean;
+//# sourceMappingURL=structure2.d.ts.map

package/dist/structure2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure2.d.ts","sourceRoot":"","sources":["../src/structure2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,UAAU,CAAC;IAC1B,YAAY,EAAE,UAAU,CAAC;IACzB,gBAAgB,EAAE,UAAU,CAAC;IAC7B,WAAW,EAAE,kBAAkB,CAAC;IAChC,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAIxC,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,EAAE,kBAIjC,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,CAiBrD;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,UAAU,EACzB,YAAY,EAAE,UAAU,EACxB,gBAAgB,EAAE,UAAU,EAC5B,SAAS,EAAE,UAAU,GACpB,qBAAqB,CAqCvB;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,UAAU,CAc3D;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,UAAU,EACtB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,OAAO,CAWT"}