@cello-protocol/protocol-types 0.0.21 → 0.0.23

package/dist/envelope.d.ts

@@ -1,170 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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"}