@cello-protocol/protocol-types 0.0.2

package/dist/connection-request.d.ts

@@ -0,0 +1,271 @@
+/**
+ * CELLO Connection Request Wire Types — CONNREQ-002
+ *
+ * Phase P — Pseudocode
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ROUND 1 flow (always happens):
+ *
+ * CLIENT A → DIRECTORY (on authenticated signaling stream):
+ *   1. A sends connection_request { target_pubkey, package_cbor }
+ *
+ * DIRECTORY pre-checks:
+ *   a. sender is registered → else connection_request_error { reason: 'not_registered' }
+ *   b. target has active profile → else connection_request_error { reason: 'target_not_found' }
+ *   c. no existing active connection → else connection_request_error { reason: 'already_connected' }
+ *   d. fetch target's registered_at and is_provisional
+ *   e. relay to target's stream as connection_request_inbound { from_pubkey, package_cbor,
+ *      sender_registered_at, sender_is_provisional }
+ *   If target offline → queue (up to 32), deliver on reconnect; if > 32, drop oldest, send
+ *      connection_request_error { reason: 'target_unavailable' } to sender
+ *
+ * TARGET CLIENT receives connection_request_inbound:
+ *   1. Check whitelist → if sender whitelisted, send connection_response { verdict: 'accept' }
+ *      without calling evaluateConnectionPackage()
+ *   2. validateConnectionPackage (CONNREQ-001: pseudonym binding, signatures, expiry)
+ *   3. Build DirectoryContext from sender_registered_at, sender_is_provisional
+ *   4. evaluateConnectionPackage() (CONNPOL-001)
+ *   5. Act on ConnectionReport verdict:
+ *      - auto_accept → send connection_response { verdict: 'accept' }
+ *      - auto_reject → send connection_response { verdict: 'reject', reason }
+ *      - auto_insufficient → send connection_response { verdict: 'insufficient', unmet_requirements }
+ *      - pending_agent_review → queue report, fire onConnectionPendingReview
+ *
+ * DIRECTORY receives connection_response { verdict: 'accept' }:
+ *   1. Generate 16-byte CSPRNG connection_id (FIPS 180-4 randomness)
+ *   2. Create connection records in DirectoryStore
+ *   3. Push connection_established { counterparty_pubkey, connection_id } to BOTH clients
+ *
+ * DIRECTORY receives connection_response { verdict: 'reject', reason }:
+ *   Relay connection_rejected { target_pubkey, reason } to sender. No record created.
+ *
+ * DIRECTORY receives connection_response { verdict: 'insufficient', unmet_requirements }:
+ *   Relay connection_insufficient { target_pubkey, unmet_requirements } to sender. No record.
+ *
+ * ROUND 2 (only when inference mode + agent calls cello_request_more_disclosure):
+ *
+ * TARGET calls cello_request_more_disclosure({ connection_request_id, requested_items[] }):
+ *   Verify Round 1 (not already Round 2) → else { error: 'max_rounds_reached' }
+ *   Send disclosure_request { connection_request_id, requested_items[] } to directory.
+ *   Directory relays as disclosure_request_inbound { from_pubkey, connection_request_id,
+ *     requested_items[] } to sender's stream.
+ *   Start 2-minute Round 2 silence timer (round2TimeoutMs).
+ *
+ * SENDER receives disclosure_request_inbound:
+ *   Fire onDisclosureRequested.
+ *   cello_request_connection returns { result: 'disclosure_requested', connection_request_id,
+ *     requested_items[] } — UNBLOCKS sender.
+ *
+ * SENDER calls cello_respond_to_disclosure_request({ connection_request_id, ... }):
+ *   Construct package_v2, send disclosure_response { connection_request_id, package_cbor }.
+ *   Directory relays as disclosure_response_inbound { connection_request_id, package_cbor }.
+ *
+ * TARGET receives disclosure_response_inbound:
+ *   Validate package_v2, re-run evaluateConnectionPackage().
+ *   Queue updated ConnectionReport; return via cello_await_connection_request.
+ *   Agent may only call cello_accept_connection or cello_reject_connection now.
+ *   If agent attempts cello_request_more_disclosure on Round 2 → { error: 'max_rounds_reached' }.
+ *
+ * ROUND 2 SILENCE TIMEOUT (2-minute timer at target):
+ *   Target sends connection_response { verdict: 'reject', reason: 'disclosure_timeout' }.
+ *   Directory relays connection_rejected { reason: 'disclosure_timeout' } to sender.
+ *   cello_request_connection returns { result: 'rejected', reason: 'disclosure_timeout' }.
+ *
+ * 5-MINUTE OVERALL TIMEOUT (at sender):
+ *   If no final response arrives within connectionTimeoutMs (default 300_000ms),
+ *   cello_request_connection returns { result: 'timeout' }.
+ *
+ * SESSION-006 — session_request connection gate:
+ *   client.initiateSession() checks local #connections map first.
+ *   If no connection → return { error: { reason: 'no_connection', target_pubkey } }.
+ *   session_request frame gains required connection_id field.
+ *   Directory verifies connection_id matches active connection between initiator + target.
+ *   Reject with no_connection or connection_id_required before any FROST ceremony.
+ *
+ * Crypto refs:
+ *   ML-DSA-44 package signatures: NIST FIPS 204
+ *   SHA-256 for connection_id entropy mix (if needed): FIPS 180-4
+ *   FROST threshold signing: RFC 9591
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * Sent by the initiator on its authenticated signaling stream.
+ * package_cbor is the CBOR-encoded ConnectionPackage (CONNREQ-001).
+ * The directory does NOT inspect package_cbor — it is opaque (ML-DSA signed by sender).
+ */
+export interface ConnectionRequest {
+    type: "connection_request";
+    /** Hex-encoded 32-byte K_local pubkey of the desired target */
+    target_pubkey: string;
+    /** CBOR-encoded ConnectionPackage bytes (opaque to directory) */
+    package_cbor: Uint8Array;
+}
+/**
+ * Relayed by the directory to the target's signaling stream.
+ * Augmented with sender's directory context fields.
+ */
+export interface ConnectionRequestInbound {
+    type: "connection_request_inbound";
+    /** Hex-encoded 32-byte K_local pubkey of the sender */
+    from_pubkey: string;
+    /** Connection request ID (directory-assigned, 16-byte hex) for Round 2 correlation */
+    connection_request_id: string;
+    /** CBOR-encoded ConnectionPackage (opaque relay — cannot be modified by directory) */
+    package_cbor: Uint8Array;
+    /** Unix ms timestamp when sender registered (from directory profile) */
+    sender_registered_at: number;
+    /** Whether sender's profile is provisional */
+    sender_is_provisional: boolean;
+}
+/** Verdict variants for the target client's response */
+export type ConnectionResponseVerdict = {
+    verdict: "accept";
+} | {
+    verdict: "reject";
+    reason: string;
+} | {
+    verdict: "insufficient";
+    unmet_requirements: unknown[];
+};
+export interface ConnectionResponse {
+    type: "connection_response";
+    /** Connection request ID assigned by directory at relay time */
+    connection_request_id: string;
+    verdict: "accept" | "reject" | "insufficient";
+    /** Present when verdict === 'reject' */
+    reason?: string;
+    /** Present when verdict === 'insufficient' */
+    unmet_requirements?: unknown[];
+}
+/**
+ * Delivered to both A and B after directory creates the connection record.
+ * counterparty_pubkey is the other side's K_local (A receives B's, B receives A's).
+ */
+export interface ConnectionEstablished {
+    type: "connection_established";
+    /** Hex-encoded counterparty K_local pubkey */
+    counterparty_pubkey: string;
+    /** Hex-encoded 16-byte CSPRNG connection ID */
+    connection_id: string;
+}
+export interface ConnectionRejected {
+    type: "connection_rejected";
+    /** Hex-encoded 32-byte target K_local pubkey */
+    target_pubkey: string;
+    reason: string;
+}
+export interface ConnectionInsufficient {
+    type: "connection_insufficient";
+    /** Hex-encoded 32-byte target K_local pubkey */
+    target_pubkey: string;
+    unmet_requirements: unknown[];
+}
+export interface ConnectionRequestError {
+    type: "connection_request_error";
+    reason: ConnectionRequestErrorReason;
+    /** Only set when reason === "already_connected" — the existing connection_id so the client can hydrate and proceed immediately */
+    connection_id?: string;
+}
+export type ConnectionRequestErrorReason = "not_registered" | "target_not_found" | "already_connected" | "target_unavailable";
+/**
+ * Target → directory: initiate Round 2 disclosure request.
+ */
+export interface DisclosureRequest {
+    type: "disclosure_request";
+    connection_request_id: string;
+    requested_items: DisclosureRequestItem[];
+}
+export interface DisclosureRequestItem {
+    type: "endorsement" | "attestation";
+    /** For endorsement: minimum count required */
+    min_count?: number;
+    /** For attestation: attestation type string */
+    attestation_type?: string;
+}
+/**
+ * Directory → sender: relayed disclosure request.
+ */
+export interface DisclosureRequestInbound {
+    type: "disclosure_request_inbound";
+    /** Hex-encoded target K_local pubkey */
+    from_pubkey: string;
+    connection_request_id: string;
+    requested_items: DisclosureRequestItem[];
+}
+/**
+ * Sender → directory: provide additional package items (or empty to decline).
+ */
+export interface DisclosureResponse {
+    type: "disclosure_response";
+    connection_request_id: string;
+    /** CBOR-encoded updated ConnectionPackage (package_v2) */
+    package_cbor: Uint8Array;
+}
+/**
+ * Directory → target: relayed disclosure response.
+ */
+export interface DisclosureResponseInbound {
+    type: "disclosure_response_inbound";
+    connection_request_id: string;
+    /** CBOR-encoded updated ConnectionPackage (package_v2) */
+    package_cbor: Uint8Array;
+}
+/**
+ * Connection record stored in the directory.
+ * Indexed by both participants' pubkeys and by connection_id.
+ */
+export interface ConnectionRecord {
+    /** Hex-encoded 16-byte CSPRNG connection ID */
+    connection_id: string;
+    /** Hex-encoded K_local pubkey of participant A */
+    participant_a: string;
+    /** Hex-encoded K_local pubkey of participant B */
+    participant_b: string;
+    /** Unix ms timestamp when the connection was established */
+    established_at: number;
+    status: "active";
+}
+/**
+ * Pending connection request queued for an offline target.
+ */
+export interface PendingConnectionRequest {
+    /** Connection request ID (directory-assigned) */
+    connection_request_id: string;
+    /** Hex-encoded sender K_local pubkey */
+    sender_pubkey: string;
+    /** The inbound frame to deliver when target reconnects */
+    frame: ConnectionRequestInbound;
+    /** Unix ms timestamp when queued (oldest = first to drop) */
+    queued_at: number;
+}
+/**
+ * CLIENT-SIDE connection record (CONNREQ-002).
+ * Cached so future session establishments can use the connection_id without re-querying.
+ */
+export interface ClientConnectionRecord {
+    /** Hex-encoded 16-byte CSPRNG connection ID */
+    connection_id: string;
+    /** Hex-encoded counterparty K_local pubkey */
+    counterparty_pubkey: string;
+    /** Hex-encoded counterparty FROST primary_pubkey (from the connection exchange) */
+    counterparty_primary_pubkey: string;
+    /** Hex-encoded counterparty ML-DSA public key (from the connection package) */
+    counterparty_ml_dsa_pubkey: string;
+    /** Unix ms timestamp when established */
+    established_at: number;
+    status: "active";
+    /** True when directory was unreachable during ml_dsa_pubkey cross-check */
+    profile_unchecked?: boolean;
+}
+/**
+ * M3 session_request wire type — gains required connection_id field.
+ * Defined here so protocol-types owns the canonical wire schema.
+ */
+export interface SessionRequestM3 {
+    type: "session_request";
+    /** Hex-encoded 32-byte K_local pubkey of the desired counterparty */
+    target_pubkey: Uint8Array;
+    /** Hex-encoded 16-byte connection ID — REQUIRED in M3 */
+    connection_id: string;
+}
+export type SessionRequestM3ErrorReason = "no_connection" | "connection_id_required";
+//# sourceMappingURL=connection-request.d.ts.map

package/dist/connection-request.d.ts.map

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

package/dist/connection-request.js

@@ -0,0 +1,91 @@
+/**
+ * CELLO Connection Request Wire Types — CONNREQ-002
+ *
+ * Phase P — Pseudocode
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ROUND 1 flow (always happens):
+ *
+ * CLIENT A → DIRECTORY (on authenticated signaling stream):
+ *   1. A sends connection_request { target_pubkey, package_cbor }
+ *
+ * DIRECTORY pre-checks:
+ *   a. sender is registered → else connection_request_error { reason: 'not_registered' }
+ *   b. target has active profile → else connection_request_error { reason: 'target_not_found' }
+ *   c. no existing active connection → else connection_request_error { reason: 'already_connected' }
+ *   d. fetch target's registered_at and is_provisional
+ *   e. relay to target's stream as connection_request_inbound { from_pubkey, package_cbor,
+ *      sender_registered_at, sender_is_provisional }
+ *   If target offline → queue (up to 32), deliver on reconnect; if > 32, drop oldest, send
+ *      connection_request_error { reason: 'target_unavailable' } to sender
+ *
+ * TARGET CLIENT receives connection_request_inbound:
+ *   1. Check whitelist → if sender whitelisted, send connection_response { verdict: 'accept' }
+ *      without calling evaluateConnectionPackage()
+ *   2. validateConnectionPackage (CONNREQ-001: pseudonym binding, signatures, expiry)
+ *   3. Build DirectoryContext from sender_registered_at, sender_is_provisional
+ *   4. evaluateConnectionPackage() (CONNPOL-001)
+ *   5. Act on ConnectionReport verdict:
+ *      - auto_accept → send connection_response { verdict: 'accept' }
+ *      - auto_reject → send connection_response { verdict: 'reject', reason }
+ *      - auto_insufficient → send connection_response { verdict: 'insufficient', unmet_requirements }
+ *      - pending_agent_review → queue report, fire onConnectionPendingReview
+ *
+ * DIRECTORY receives connection_response { verdict: 'accept' }:
+ *   1. Generate 16-byte CSPRNG connection_id (FIPS 180-4 randomness)
+ *   2. Create connection records in DirectoryStore
+ *   3. Push connection_established { counterparty_pubkey, connection_id } to BOTH clients
+ *
+ * DIRECTORY receives connection_response { verdict: 'reject', reason }:
+ *   Relay connection_rejected { target_pubkey, reason } to sender. No record created.
+ *
+ * DIRECTORY receives connection_response { verdict: 'insufficient', unmet_requirements }:
+ *   Relay connection_insufficient { target_pubkey, unmet_requirements } to sender. No record.
+ *
+ * ROUND 2 (only when inference mode + agent calls cello_request_more_disclosure):
+ *
+ * TARGET calls cello_request_more_disclosure({ connection_request_id, requested_items[] }):
+ *   Verify Round 1 (not already Round 2) → else { error: 'max_rounds_reached' }
+ *   Send disclosure_request { connection_request_id, requested_items[] } to directory.
+ *   Directory relays as disclosure_request_inbound { from_pubkey, connection_request_id,
+ *     requested_items[] } to sender's stream.
+ *   Start 2-minute Round 2 silence timer (round2TimeoutMs).
+ *
+ * SENDER receives disclosure_request_inbound:
+ *   Fire onDisclosureRequested.
+ *   cello_request_connection returns { result: 'disclosure_requested', connection_request_id,
+ *     requested_items[] } — UNBLOCKS sender.
+ *
+ * SENDER calls cello_respond_to_disclosure_request({ connection_request_id, ... }):
+ *   Construct package_v2, send disclosure_response { connection_request_id, package_cbor }.
+ *   Directory relays as disclosure_response_inbound { connection_request_id, package_cbor }.
+ *
+ * TARGET receives disclosure_response_inbound:
+ *   Validate package_v2, re-run evaluateConnectionPackage().
+ *   Queue updated ConnectionReport; return via cello_await_connection_request.
+ *   Agent may only call cello_accept_connection or cello_reject_connection now.
+ *   If agent attempts cello_request_more_disclosure on Round 2 → { error: 'max_rounds_reached' }.
+ *
+ * ROUND 2 SILENCE TIMEOUT (2-minute timer at target):
+ *   Target sends connection_response { verdict: 'reject', reason: 'disclosure_timeout' }.
+ *   Directory relays connection_rejected { reason: 'disclosure_timeout' } to sender.
+ *   cello_request_connection returns { result: 'rejected', reason: 'disclosure_timeout' }.
+ *
+ * 5-MINUTE OVERALL TIMEOUT (at sender):
+ *   If no final response arrives within connectionTimeoutMs (default 300_000ms),
+ *   cello_request_connection returns { result: 'timeout' }.
+ *
+ * SESSION-006 — session_request connection gate:
+ *   client.initiateSession() checks local #connections map first.
+ *   If no connection → return { error: { reason: 'no_connection', target_pubkey } }.
+ *   session_request frame gains required connection_id field.
+ *   Directory verifies connection_id matches active connection between initiator + target.
+ *   Reject with no_connection or connection_id_required before any FROST ceremony.
+ *
+ * Crypto refs:
+ *   ML-DSA-44 package signatures: NIST FIPS 204
+ *   SHA-256 for connection_id entropy mix (if needed): FIPS 180-4
+ *   FROST threshold signing: RFC 9591
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export {};
+//# sourceMappingURL=connection-request.js.map

package/dist/connection-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-request.js","sourceRoot":"","sources":["../src/connection-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG"}

package/dist/envelope.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @cello-protocol/protocol-types — CELLO-MSG-001 (v0) + CELLO-MSG-003 (v1)
+ * Envelope construction, validation, serialization, and deserialization.
+ *
+ * ──── v0 Pseudocode (CELLO-MSG-001) ────
+ *
+ * buildEnvelope(content, keyProvider, timestamp):
+ *   1. Reject if content.length > MAX_CONTENT_BYTES (1,048,576)  → content_too_large
+ *   2. Compute content_hash = msgLeafHash(content)               [FIPS 180-4: SHA-256(0x00||content)]
+ *   3. Fetch sender_pubkey = await keyProvider.getPublicKey()
+ *   4. Build TBS positional array: [0, content_hash, sender_pubkey, timestamp]
+ *      — timestamp encoded as BigInt so cbor-x emits uint64, not float64
+ *   5. tbs_bytes = encodeTBS([0, content_hash, sender_pubkey, BigInt(timestamp)])
+ *      [RFC 8949 §4.2.1: canonical CBOR, Encoder({tagUint8Array:false})]
+ *   6. sender_signature = await keyProvider.sign(tbs_bytes)      [RFC 8032: Ed25519]
+ *   7. Return envelope with all six fields populated
+ *
+ * validateEnvelope(envelope):
+ *   1. Check protocol_version === 0                              → unsupported_version
+ *   2. Check presence + exact byte lengths of all typed fields:
+ *        sender_pubkey: 32 bytes                                 → missing_field / invalid_field
+ *        content_hash:  32 bytes                                 → missing_field / invalid_field
+ *        sender_signature: 64 bytes                             → missing_field / invalid_field
+ *   3. Check timestamp >= 0                                      → invalid_field
+ *   4. Check content.length <= MAX_CONTENT_BYTES                 → content_too_large
+ *   5. Recompute expected_hash = msgLeafHash(content)
+ *      Compare byte-by-byte to content_hash                     → content_hash_mismatch (BEFORE sig check)
+ *   6. Rebuild TBS bytes (same as step 5 in build)
+ *   7. verify(sender_pubkey, tbs_bytes, sender_signature)        → invalid_field('sender_signature')
+ *   8. Return ok: true
+ *
+ * ──── v1 Pseudocode (CELLO-MSG-003) ────
+ *
+ * buildEnvelopeV1(content, keyProvider, timestamp, session_id, last_seen_seq):
+ *   1. Reject if content.length > MAX_CONTENT_BYTES              → content_too_large
+ *      [no hash/sig computed before this check — AC-009]
+ *   2. Compute content_hash = msgLeafHash(content)               [FIPS 180-4: SHA-256(0x00||content)]
+ *      Caller-supplied hashes ignored — SI-001
+ *   3. Fetch sender_pubkey = await keyProvider.getPublicKey()
+ *   4. Build Structure 1 (TBS) positional 6-element array:
+ *      [1, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]
+ *      — protocol_version=1 (CBOR uint)
+ *      — content_hash: 32-byte CBOR bstr (SHA-256(0x00||content))
+ *      — sender_pubkey: 32-byte CBOR bstr (Ed25519 public key, RFC 8032)
+ *      — session_id: 16-byte CBOR bstr
+ *      — last_seen_seq: CBOR uint (non-negative integer)
+ *      — timestamp: CBOR uint (Unix ms; BigInt when > 0xFFFFFFFF for minimal encoding
+ *        per RFC 8949 §4.2.1)
+ *   5. tbs_bytes = CBOR_ENC.encode(tbs_array)
+ *      [RFC 8949 §4.2.1: canonical CBOR, Encoder({tagUint8Array:false})]
+ *   6. sender_signature = await keyProvider.sign(tbs_bytes)      [RFC 8032: Ed25519]
+ *   7. Return MessageEnvelopeV1 with all eight fields populated
+ *
+ * validateEnvelopeV1(envelope):
+ *   1. Check protocol_version === 1                              → unsupported_version (AC-003, AC-004)
+ *      Hard-reject: no v0 fallback, no negotiation (M1 drops v0)
+ *   2. Field presence + byte-length checks:
+ *        sender_pubkey: 32 bytes                                 → missing_field / invalid_field
+ *        content_hash:  32 bytes                                 → missing_field / invalid_field
+ *        session_id:    16 bytes                                 → missing_field / invalid_field
+ *        sender_signature: 64 bytes                             → missing_field / invalid_field
+ *   3. Check last_seen_seq >= 0, integer                         → invalid_field
+ *   4. Check timestamp >= 0, integer                             → invalid_field
+ *   5. Check content.length <= MAX_CONTENT_BYTES                 → content_too_large
+ *   6. Recompute expected_hash = msgLeafHash(content)
+ *      Compare byte-by-byte to content_hash                     → content_hash_mismatch (BEFORE sig check)
+ *   7. Rebuild Structure 1 TBS bytes (same as step 5 in build)
+ *   8. verify(sender_pubkey, tbs_bytes, sender_signature)        → invalid_field('sender_signature')
+ *   9. Return ok: true
+ *
+ * extractStructure1(envelope: MessageEnvelopeV1) → Uint8Array:
+ *   1. Build positional 6-element array from envelope fields
+ *   2. Return CBOR_ENC.encode([1, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp])
+ *      This is the exact bytes the relay uses to build Structure 2 (MERKLE-002)
+ *
+ * References:
+ *   RFC 8949 §4.2.1 — Core Deterministic Encoding Requirements
+ *   RFC 8032 — Edwards-Curve Digital Signature Algorithm (EdDSA)
+ *   FIPS 180-4 — SHA-256 (used by msgLeafHash for content_hash computation)
+ */
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { MessageEnvelope, MessageEnvelopeV1, BuildResult, BuildResultV1, ValidateResult, ValidateResultV1, DeserializeResult, DeserializeResultV1 } from "./types.js";
+/** Maximum allowed content size: 1 MiB (AC-009, AC-010, AC-011). */
+export declare const MAX_CONTENT_BYTES = 1048576;
+/**
+ * Build a signed MessageEnvelope.
+ *
+ * SI-001: content_hash is ALWAYS recomputed; any caller-supplied value is ignored.
+ * AC-010: content > 1 MiB → content_too_large, no hash or signature computed.
+ *
+ * @param content - Raw message bytes
+ * @param keyProvider - Signing key abstraction (K_local)
+ * @param timestamp - Unix milliseconds (non-negative)
+ */
+export declare function buildEnvelope(content: Uint8Array, keyProvider: KeyProvider, timestamp: number): Promise<BuildResult>;
+/**
+ * Validate a MessageEnvelope.
+ *
+ * Validation order (fail-fast):
+ *   1. protocol_version check (AC-013, SI-004) — before any other check
+ *   2. Field presence and byte-length checks (AC-003, AC-004)
+ *   3. timestamp range check (AC-005)
+ *   4. content size check (AC-011)
+ *   5. content_hash recomputation and comparison (AC-012) — BEFORE signature check
+ *   6. Signature verification (AC-002, AC-007, SI-003)
+ */
+export declare function validateEnvelope(envelope: MessageEnvelope): ValidateResult;
+/**
+ * Serialize a MessageEnvelope to canonical CBOR bytes (RFC 8949 §4.2.1).
+ *
+ * The envelope is encoded as a CBOR map with string keys.
+ * timestamp uses minimal encoding per RFC 8949 §4.2.1 — see encodeTBS comment.
+ */
+export declare function serializeEnvelope(envelope: MessageEnvelope): Uint8Array;
+/**
+ * Deserialize a MessageEnvelope from CBOR bytes.
+ *
+ * Performs structural validation only (field presence, types, sizes).
+ * Does NOT re-validate the signature or content_hash — call validateEnvelope for that.
+ */
+export declare function deserializeEnvelope(bytes: Uint8Array): DeserializeResult;
+/**
+ * Build a signed v1 MessageEnvelopeV1 (CELLO-MSG-003).
+ *
+ * SI-001: content_hash is ALWAYS recomputed from content; any caller-supplied value is ignored.
+ * AC-009: content > 1 MiB → content_too_large, no hash or signature computed.
+ *
+ * @param content - Raw message bytes (up to 1 MiB)
+ * @param keyProvider - Signing key abstraction (K_local)
+ * @param timestamp - Unix milliseconds (non-negative)
+ * @param session_id - 16-byte session identifier
+ * @param last_seen_seq - Highest canonical seq number seen from relay (0 for first message)
+ */
+export declare function buildEnvelopeV1(content: Uint8Array, keyProvider: KeyProvider, timestamp: number, session_id: Uint8Array, last_seen_seq: number): Promise<BuildResultV1>;
+/**
+ * Validate a v1 MessageEnvelopeV1 (CELLO-MSG-003).
+ *
+ * Validation order (fail-fast):
+ *   1. protocol_version === 1 check — hard-reject v0 and any other version (AC-003, AC-004)
+ *   2. Field presence and byte-length checks
+ *   3. last_seen_seq and timestamp range checks
+ *   4. content size check
+ *   5. content_hash recomputation (BEFORE signature check) (AC-006)
+ *   6. Signature verification over Structure 1 TBS
+ */
+export declare function validateEnvelopeV1(envelope: MessageEnvelopeV1): ValidateResultV1;
+/**
+ * Serialize a v1 MessageEnvelopeV1 to canonical CBOR bytes (RFC 8949 §4.2.1).
+ *
+ * The envelope is encoded as a CBOR map with string keys.
+ * timestamp uses minimal encoding per RFC 8949 §4.2.1.
+ */
+export declare function serializeEnvelopeV1(envelope: MessageEnvelopeV1): Uint8Array;
+/**
+ * Deserialize a v1 MessageEnvelopeV1 from CBOR bytes.
+ *
+ * Performs structural validation only (field presence, types, sizes).
+ * Does NOT re-validate the signature or content_hash — call validateEnvelopeV1 for that.
+ */
+export declare function deserializeEnvelopeV1(bytes: Uint8Array): DeserializeResultV1;
+/**
+ * Extract Structure 1 from a v1 envelope — returns the canonical CBOR bytes that were signed.
+ *
+ * Structure 1: canonical_CBOR([1, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp])
+ *
+ * This is the exact bytes the relay uses to build Structure 2 (CELLO-MERKLE-002).
+ * Per RFC 8949 §4.2.1 canonical CBOR and RFC 8032 Ed25519.
+ */
+export declare function extractStructure1(envelope: MessageEnvelopeV1): Uint8Array;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAsC3C;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAiCtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CA+H1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,UAAU,CAUvE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,iBAAiB,CA8FxE;AA8BD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,CAAC,CA+CxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAuJhF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,UAAU,CAY3E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,CAmH5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,UAAU,CAQzE"}