@cello-protocol/protocol-types 0.0.2

package/dist/envelope.js

@@ -0,0 +1,776 @@
+/**
+ * @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 { Encoder } from "cbor-x";
+import { decode as cborDecode } from "cbor-x";
+import { msgLeafHash, verify } from "@cello-protocol/crypto";
+/** Maximum allowed content size: 1 MiB (AC-009, AC-010, AC-011). */
+export const MAX_CONTENT_BYTES = 1_048_576;
+/**
+ * Canonical CBOR encoder per RFC 8949 §4.2.1.
+ * tagUint8Array: false — encode Uint8Array as CBOR byte strings (major type 2),
+ * not as typed-array tags (tag 64). This is the standard wire representation.
+ */
+const CBOR_ENC = new Encoder({ tagUint8Array: false });
+/**
+ * Encode the TBS positional array as canonical CBOR.
+ *
+ * TBS layout: [protocol_version, content_hash, sender_pubkey, timestamp]
+ * - protocol_version: CBOR uint (0)
+ * - content_hash: CBOR byte string (32 bytes)
+ * - sender_pubkey: CBOR byte string (32 bytes)
+ * - timestamp: CBOR uint64 (BigInt to force integer encoding, not float64)
+ *
+ * RFC 8949 §4.2.1: integers use the shortest encoding; byte strings are verbatim.
+ * Using BigInt(timestamp) ensures cbor-x emits 0x1b (8-byte uint64) not 0xfb (float64).
+ */
+function encodeTBS(protocolVersion, contentHash, senderPubkey, timestamp) {
+    // RFC 8949 §4.2.1: integers must use the shortest encoding.
+    // cbor-x encodes JS numbers ≤ 0xFFFFFFFF as 4-byte uint (minimal) but numbers
+    // above that threshold as float64 (0xfb…) — not canonical. BigInt always emits
+    // 8-byte uint64 regardless of value — non-minimal for small values.
+    // Solution: use BigInt only when the value exceeds uint32 range, ensuring
+    // shortest encoding across all valid Unix millisecond timestamps.
+    const tsEncoded = timestamp > 0xFFFFFFFF ? BigInt(timestamp) : timestamp;
+    const tbs = [protocolVersion, contentHash, senderPubkey, tsEncoded];
+    return CBOR_ENC.encode(tbs);
+}
+/**
+ * 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 async function buildEnvelope(content, keyProvider, timestamp) {
+    // AC-010: reject oversized content before any crypto
+    if (content.length > MAX_CONTENT_BYTES) {
+        return {
+            ok: false,
+            error: {
+                reason: "content_too_large",
+                message: `content length ${content.length} exceeds maximum ${MAX_CONTENT_BYTES} bytes`,
+            },
+        };
+    }
+    // SI-001: always recompute — never trust caller-supplied hash
+    const content_hash = msgLeafHash(content);
+    const sender_pubkey = await keyProvider.getPublicKey();
+    // TBS: positional array [protocol_version, content_hash, sender_pubkey, timestamp]
+    const tbsBytes = encodeTBS(0, content_hash, sender_pubkey, timestamp);
+    // Ed25519 sign per RFC 8032
+    const sender_signature = await keyProvider.sign(tbsBytes);
+    return {
+        ok: true,
+        envelope: {
+            protocol_version: 0,
+            sender_pubkey,
+            content,
+            content_hash,
+            timestamp,
+            sender_signature,
+        },
+    };
+}
+/**
+ * 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 function validateEnvelope(envelope) {
+    // Step 1: version check — first so unknown versions are detectable without parsing (SI-004)
+    if (envelope.protocol_version !== 0) {
+        return {
+            ok: false,
+            error: {
+                reason: "unsupported_version",
+                message: `unsupported protocol_version: ${envelope.protocol_version}`,
+            },
+        };
+    }
+    // Step 2: field presence and size checks
+    if (envelope.sender_pubkey === undefined ||
+        envelope.sender_pubkey === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "sender_pubkey", message: "sender_pubkey is missing" },
+        };
+    }
+    if (envelope.sender_pubkey.length !== 32) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "sender_pubkey",
+                message: `sender_pubkey must be 32 bytes, got ${envelope.sender_pubkey.length}`,
+            },
+        };
+    }
+    if (envelope.content_hash === undefined ||
+        envelope.content_hash === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "content_hash", message: "content_hash is missing" },
+        };
+    }
+    if (envelope.content_hash.length !== 32) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "content_hash",
+                message: `content_hash must be 32 bytes, got ${envelope.content_hash.length}`,
+            },
+        };
+    }
+    if (envelope.sender_signature === undefined ||
+        envelope.sender_signature === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "sender_signature", message: "sender_signature is missing" },
+        };
+    }
+    if (envelope.sender_signature.length !== 64) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "sender_signature",
+                message: `sender_signature must be 64 bytes, got ${envelope.sender_signature.length}`,
+            },
+        };
+    }
+    // Step 3: timestamp range
+    if (envelope.timestamp < 0 || !Number.isInteger(envelope.timestamp)) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "timestamp",
+                message: `timestamp must be a non-negative integer, got ${envelope.timestamp}`,
+            },
+        };
+    }
+    // Step 4: content size
+    if (envelope.content.length > MAX_CONTENT_BYTES) {
+        return {
+            ok: false,
+            error: {
+                reason: "content_too_large",
+                message: `content length ${envelope.content.length} exceeds maximum ${MAX_CONTENT_BYTES} bytes`,
+            },
+        };
+    }
+    // Step 5: content_hash recomputation — checked BEFORE signature (AC-012)
+    const expectedHash = msgLeafHash(envelope.content);
+    if (!bytesEqual(expectedHash, envelope.content_hash)) {
+        return {
+            ok: false,
+            error: {
+                reason: "content_hash_mismatch",
+                message: "content_hash does not match SHA-256(0x00 || content)",
+            },
+        };
+    }
+    // Step 6: signature verification
+    const tbsBytes = encodeTBS(envelope.protocol_version, envelope.content_hash, envelope.sender_pubkey, envelope.timestamp);
+    if (!verify(envelope.sender_pubkey, tbsBytes, envelope.sender_signature)) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "sender_signature",
+                message: "signature verification failed",
+            },
+        };
+    }
+    return { ok: true };
+}
+/**
+ * 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 function serializeEnvelope(envelope) {
+    const map = {
+        protocol_version: envelope.protocol_version,
+        sender_pubkey: envelope.sender_pubkey,
+        content: envelope.content,
+        content_hash: envelope.content_hash,
+        timestamp: envelope.timestamp > 0xFFFFFFFF ? BigInt(envelope.timestamp) : envelope.timestamp,
+        sender_signature: envelope.sender_signature,
+    };
+    return CBOR_ENC.encode(map);
+}
+/**
+ * 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 function deserializeEnvelope(bytes) {
+    let raw;
+    try {
+        raw = cborDecode(bytes);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "bytes",
+                message: `CBOR decode failed: ${e.message}`,
+            },
+        };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "bytes",
+                message: "decoded value is not a map",
+            },
+        };
+    }
+    const obj = raw;
+    // protocol_version
+    if (!("protocol_version" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "protocol_version", message: "protocol_version is missing" } };
+    }
+    const pv = obj["protocol_version"];
+    if (typeof pv !== "number" || pv !== 0) {
+        return { ok: false, error: { reason: "unsupported_version", message: `unsupported protocol_version: ${pv}` } };
+    }
+    // sender_pubkey
+    if (!("sender_pubkey" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "sender_pubkey", message: "sender_pubkey is missing" } };
+    }
+    const spk = toUint8Array(obj["sender_pubkey"]);
+    if (!spk || spk.length !== 32) {
+        return { ok: false, error: { reason: "invalid_field", field: "sender_pubkey", message: `sender_pubkey must be 32 bytes` } };
+    }
+    // content
+    if (!("content" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "content", message: "content is missing" } };
+    }
+    const content = toUint8Array(obj["content"]);
+    if (!content) {
+        return { ok: false, error: { reason: "invalid_field", field: "content", message: "content must be bytes" } };
+    }
+    // content_hash
+    if (!("content_hash" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "content_hash", message: "content_hash is missing" } };
+    }
+    const ch = toUint8Array(obj["content_hash"]);
+    if (!ch || ch.length !== 32) {
+        return { ok: false, error: { reason: "invalid_field", field: "content_hash", message: `content_hash must be 32 bytes` } };
+    }
+    // timestamp
+    if (!("timestamp" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "timestamp", message: "timestamp is missing" } };
+    }
+    const tsRaw = obj["timestamp"];
+    const ts = typeof tsRaw === "bigint" ? Number(tsRaw) : (typeof tsRaw === "number" ? tsRaw : NaN);
+    if (!Number.isInteger(ts) || ts < 0 || ts > Number.MAX_SAFE_INTEGER) {
+        return { ok: false, error: { reason: "invalid_field", field: "timestamp", message: `invalid timestamp: ${tsRaw}` } };
+    }
+    // sender_signature
+    if (!("sender_signature" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "sender_signature", message: "sender_signature is missing" } };
+    }
+    const sig = toUint8Array(obj["sender_signature"]);
+    if (!sig || sig.length !== 64) {
+        return { ok: false, error: { reason: "invalid_field", field: "sender_signature", message: `sender_signature must be 64 bytes` } };
+    }
+    return {
+        ok: true,
+        envelope: {
+            protocol_version: 0,
+            sender_pubkey: spk,
+            content,
+            content_hash: ch,
+            timestamp: ts,
+            sender_signature: sig,
+        },
+    };
+}
+// ─── v1 functions (CELLO-MSG-003) ────────────────────────────────────────────
+/**
+ * Encode the v1 Structure 1 (TBS) positional 6-element array as canonical CBOR.
+ *
+ * Structure 1 layout: [protocol_version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]
+ * - protocol_version: CBOR uint, always 1
+ * - content_hash: CBOR byte string (32 bytes, SHA-256(0x00||content))
+ * - sender_pubkey: CBOR byte string (32 bytes, Ed25519 public key per RFC 8032)
+ * - session_id: CBOR byte string (16 bytes)
+ * - last_seen_seq: CBOR uint (non-negative integer)
+ * - timestamp: CBOR uint (Unix ms; BigInt for values > 0xFFFFFFFF per RFC 8949 §4.2.1 minimal encoding)
+ *
+ * RFC 8949 §4.2.1: integers must use shortest encoding. BigInt forces 8-byte uint64 for
+ * timestamps above uint32 range (all valid Unix ms timestamps since ~Feb 2106).
+ */
+function encodeTBSV1(contentHash, senderPubkey, sessionId, lastSeenSeq, timestamp) {
+    const tsEncoded = timestamp > 0xFFFFFFFF ? BigInt(timestamp) : timestamp;
+    const tbs = [1, contentHash, senderPubkey, sessionId, lastSeenSeq, tsEncoded];
+    return CBOR_ENC.encode(tbs);
+}
+/**
+ * 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 async function buildEnvelopeV1(content, keyProvider, timestamp, session_id, last_seen_seq) {
+    // session_id must be exactly 16 bytes — catch at build time, not just validation time
+    if (session_id.length !== 16) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "session_id",
+                message: `session_id must be 16 bytes, got ${session_id.length}`,
+            },
+        };
+    }
+    // AC-009: reject oversized content before any crypto
+    if (content.length > MAX_CONTENT_BYTES) {
+        return {
+            ok: false,
+            error: {
+                reason: "content_too_large",
+                message: `content length ${content.length} exceeds maximum ${MAX_CONTENT_BYTES} bytes`,
+            },
+        };
+    }
+    // SI-001: always recompute — never trust caller-supplied hash
+    const content_hash = msgLeafHash(content);
+    const sender_pubkey = await keyProvider.getPublicKey();
+    // Structure 1 (TBS): [1, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]
+    const tbsBytes = encodeTBSV1(content_hash, sender_pubkey, session_id, last_seen_seq, timestamp);
+    // Ed25519 sign per RFC 8032
+    const sender_signature = await keyProvider.sign(tbsBytes);
+    return {
+        ok: true,
+        envelope: {
+            protocol_version: 1,
+            sender_pubkey,
+            content,
+            content_hash,
+            session_id,
+            last_seen_seq,
+            timestamp,
+            sender_signature,
+        },
+    };
+}
+/**
+ * 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 function validateEnvelopeV1(envelope) {
+    // Step 1: version gate — hard-reject any version != 1 (M1 drops v0; no negotiation)
+    if (envelope.protocol_version !== 1) {
+        return {
+            ok: false,
+            error: {
+                reason: "unsupported_version",
+                message: `unsupported protocol_version: ${envelope.protocol_version}`,
+            },
+        };
+    }
+    // Step 2a: sender_pubkey — 32 bytes
+    if (envelope.sender_pubkey === undefined || envelope.sender_pubkey === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "sender_pubkey", message: "sender_pubkey is missing" },
+        };
+    }
+    if (envelope.sender_pubkey.length !== 32) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "sender_pubkey",
+                message: `sender_pubkey must be 32 bytes, got ${envelope.sender_pubkey.length}`,
+            },
+        };
+    }
+    // Step 2b: content_hash — 32 bytes
+    if (envelope.content_hash === undefined || envelope.content_hash === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "content_hash", message: "content_hash is missing" },
+        };
+    }
+    if (envelope.content_hash.length !== 32) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "content_hash",
+                message: `content_hash must be 32 bytes, got ${envelope.content_hash.length}`,
+            },
+        };
+    }
+    // Step 2c: session_id — 16 bytes
+    if (envelope.session_id === undefined || envelope.session_id === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "session_id", message: "session_id is missing" },
+        };
+    }
+    if (envelope.session_id.length !== 16) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "session_id",
+                message: `session_id must be 16 bytes, got ${envelope.session_id.length}`,
+            },
+        };
+    }
+    // Step 2d: sender_signature — 64 bytes
+    if (envelope.sender_signature === undefined || envelope.sender_signature === null) {
+        return {
+            ok: false,
+            error: { reason: "missing_field", field: "sender_signature", message: "sender_signature is missing" },
+        };
+    }
+    if (envelope.sender_signature.length !== 64) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "sender_signature",
+                message: `sender_signature must be 64 bytes, got ${envelope.sender_signature.length}`,
+            },
+        };
+    }
+    // Step 3: last_seen_seq range
+    if (!Number.isInteger(envelope.last_seen_seq) || envelope.last_seen_seq < 0) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "last_seen_seq",
+                message: `last_seen_seq must be a non-negative integer, got ${envelope.last_seen_seq}`,
+            },
+        };
+    }
+    // Step 4: timestamp range
+    if (!Number.isInteger(envelope.timestamp) || envelope.timestamp < 0) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "timestamp",
+                message: `timestamp must be a non-negative integer, got ${envelope.timestamp}`,
+            },
+        };
+    }
+    // Step 5: content size
+    if (envelope.content.length > MAX_CONTENT_BYTES) {
+        return {
+            ok: false,
+            error: {
+                reason: "content_too_large",
+                message: `content length ${envelope.content.length} exceeds maximum ${MAX_CONTENT_BYTES} bytes`,
+            },
+        };
+    }
+    // Step 6: content_hash recomputation — checked BEFORE signature (AC-006)
+    const expectedHash = msgLeafHash(envelope.content);
+    if (!bytesEqual(expectedHash, envelope.content_hash)) {
+        return {
+            ok: false,
+            error: {
+                reason: "content_hash_mismatch",
+                message: "content_hash does not match SHA-256(0x00 || content)",
+            },
+        };
+    }
+    // Step 7: signature verification over Structure 1 TBS
+    const tbsBytes = encodeTBSV1(envelope.content_hash, envelope.sender_pubkey, envelope.session_id, envelope.last_seen_seq, envelope.timestamp);
+    if (!verify(envelope.sender_pubkey, tbsBytes, envelope.sender_signature)) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "sender_signature",
+                message: "signature verification failed",
+            },
+        };
+    }
+    return { ok: true };
+}
+/**
+ * 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 function serializeEnvelopeV1(envelope) {
+    const map = {
+        protocol_version: envelope.protocol_version,
+        sender_pubkey: envelope.sender_pubkey,
+        content: envelope.content,
+        content_hash: envelope.content_hash,
+        session_id: envelope.session_id,
+        last_seen_seq: envelope.last_seen_seq,
+        timestamp: envelope.timestamp > 0xFFFFFFFF ? BigInt(envelope.timestamp) : envelope.timestamp,
+        sender_signature: envelope.sender_signature,
+    };
+    return CBOR_ENC.encode(map);
+}
+/**
+ * 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 function deserializeEnvelopeV1(bytes) {
+    let raw;
+    try {
+        raw = cborDecode(bytes);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "bytes",
+                message: `CBOR decode failed: ${e.message}`,
+            },
+        };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid_field",
+                field: "bytes",
+                message: "decoded value is not a map",
+            },
+        };
+    }
+    const obj = raw;
+    // protocol_version — must be exactly 1
+    if (!("protocol_version" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "protocol_version", message: "protocol_version is missing" } };
+    }
+    const pv = obj["protocol_version"];
+    if (typeof pv !== "number" || pv !== 1) {
+        return { ok: false, error: { reason: "unsupported_version", message: `unsupported protocol_version: ${pv}` } };
+    }
+    // sender_pubkey — 32 bytes
+    if (!("sender_pubkey" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "sender_pubkey", message: "sender_pubkey is missing" } };
+    }
+    const spk = toUint8Array(obj["sender_pubkey"]);
+    if (!spk || spk.length !== 32) {
+        return { ok: false, error: { reason: "invalid_field", field: "sender_pubkey", message: "sender_pubkey must be 32 bytes" } };
+    }
+    // content
+    if (!("content" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "content", message: "content is missing" } };
+    }
+    const content = toUint8Array(obj["content"]);
+    if (!content) {
+        return { ok: false, error: { reason: "invalid_field", field: "content", message: "content must be bytes" } };
+    }
+    // content_hash — 32 bytes
+    if (!("content_hash" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "content_hash", message: "content_hash is missing" } };
+    }
+    const ch = toUint8Array(obj["content_hash"]);
+    if (!ch || ch.length !== 32) {
+        return { ok: false, error: { reason: "invalid_field", field: "content_hash", message: "content_hash must be 32 bytes" } };
+    }
+    // session_id — 16 bytes
+    if (!("session_id" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "session_id", message: "session_id is missing" } };
+    }
+    const sid = toUint8Array(obj["session_id"]);
+    if (!sid || sid.length !== 16) {
+        return { ok: false, error: { reason: "invalid_field", field: "session_id", message: "session_id must be 16 bytes" } };
+    }
+    // last_seen_seq — non-negative integer
+    if (!("last_seen_seq" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "last_seen_seq", message: "last_seen_seq is missing" } };
+    }
+    const lssRaw = obj["last_seen_seq"];
+    const lss = typeof lssRaw === "bigint" ? Number(lssRaw) : (typeof lssRaw === "number" ? lssRaw : NaN);
+    if (!Number.isInteger(lss) || lss < 0 || lss > Number.MAX_SAFE_INTEGER) {
+        return { ok: false, error: { reason: "invalid_field", field: "last_seen_seq", message: `invalid last_seen_seq: ${lssRaw}` } };
+    }
+    // timestamp — non-negative integer
+    if (!("timestamp" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "timestamp", message: "timestamp is missing" } };
+    }
+    const tsRaw = obj["timestamp"];
+    const ts = typeof tsRaw === "bigint" ? Number(tsRaw) : (typeof tsRaw === "number" ? tsRaw : NaN);
+    if (!Number.isInteger(ts) || ts < 0 || ts > Number.MAX_SAFE_INTEGER) {
+        return { ok: false, error: { reason: "invalid_field", field: "timestamp", message: `invalid timestamp: ${tsRaw}` } };
+    }
+    // sender_signature — 64 bytes
+    if (!("sender_signature" in obj)) {
+        return { ok: false, error: { reason: "missing_field", field: "sender_signature", message: "sender_signature is missing" } };
+    }
+    const sig = toUint8Array(obj["sender_signature"]);
+    if (!sig || sig.length !== 64) {
+        return { ok: false, error: { reason: "invalid_field", field: "sender_signature", message: "sender_signature must be 64 bytes" } };
+    }
+    return {
+        ok: true,
+        envelope: {
+            protocol_version: 1,
+            sender_pubkey: spk,
+            content,
+            content_hash: ch,
+            session_id: sid,
+            last_seen_seq: lss,
+            timestamp: ts,
+            sender_signature: sig,
+        },
+    };
+}
+/**
+ * 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 function extractStructure1(envelope) {
+    return encodeTBSV1(envelope.content_hash, envelope.sender_pubkey, envelope.session_id, envelope.last_seen_seq, envelope.timestamp);
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Constant-time byte comparison.
+ * Note: for HMAC verification, use a real constant-time compare.
+ * For hash comparison this is sufficient since timing leaks only reveal
+ * content we already possess.
+ */
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+/**
+ * Coerce a CBOR-decoded value to Uint8Array.
+ * cbor-x with tagUint8Array:false returns Buffer (a Node.js Buffer is a Uint8Array subclass).
+ */
+function toUint8Array(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Buffer.isBuffer(v))
+        return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+    return null;
+}
+//# sourceMappingURL=envelope.js.map