@sempdev/semp 0.4.3

package/dist/envelope/compose.js

@@ -0,0 +1,237 @@
+/**
+ * Envelope compose / open per ENVELOPE.md §4 + §6.5 + §7.1 + §7.2.
+ *
+ * The envelope is the wire object that carries one SEMP message
+ * between servers. Compose builds it; open recovers the brief and
+ * enclosure from a received envelope.
+ *
+ * This module exposes both the production path (fresh randomness)
+ * and the deterministic path (caller-pinned randomness for vectors
+ * + audits). The deterministic path is what the cross-language
+ * vectors-runner exercises; production callers MUST use the
+ * fresh-randomness form.
+ *
+ * Layered on top of:
+ *   - canonical/marshal      §4.3 canonical bytes (and elision)
+ *   - seal/wrap              §4.4.1 per-recipient key wrap
+ *   - crypto/aead            §7.1.1 brief / enclosure AEAD
+ *   - keys/sign              §6.5 sender_signature
+ *   - HMAC-SHA-256           §4.3 session_mac
+ *
+ * @module
+ */
+import { aeadOpen, aeadSeal, computeMAC, } from "../crypto/index.js";
+import { marshal as canonicalMarshal, marshalWithElision, } from "../canonical/index.js";
+import { sign as ed25519Sign } from "../keys/index.js";
+import { unwrap as sealUnwrap, wrapWithRandomness, } from "../seal/index.js";
+/** Algorithm prefix for the seal signature, per ENVELOPE.md §4.3. */
+const EnvelopePrefix = "SEMP-ENVELOPE:";
+/** AEAD algorithm tied to the suite for brief/enclosure encryption. */
+function suiteBriefEnclosureAEAD(suite) {
+    // Both currently defined suites use ChaCha20-Poly1305 for brief
+    // and enclosure (12-byte nonce per §7.1.1). Only the KEM is PQ.
+    void suite;
+    return "chacha20-poly1305";
+}
+/**
+ * Compose a wire envelope. Deterministic given the inputs (every
+ * randomness source is caller-supplied). Returns the wire envelope
+ * with seal.signature and seal.session_mac populated.
+ *
+ * Compose order:
+ *
+ *   1. AEAD-Seal the brief (canonical) under K_brief with the
+ *      brief AEAD nonce and postmark.id as AAD per §7.1.1.
+ *      `envelope.brief = base64(nonce || aead_ct)`.
+ *   2. AEAD-Seal the enclosure same way under K_enclosure.
+ *   3. Wrap K_brief to every brief recipient.
+ *   4. Wrap K_enclosure to every enclosure recipient.
+ *   5. Build the envelope object with seal.signature = "" and
+ *      seal.session_mac = "" placeholders.
+ *   6. Compute canonical bytes per §4.3 (signature + mac blanked,
+ *      hop_count and padding omitted), prepend SEMP-ENVELOPE:,
+ *      Ed25519-sign with the sender domain signing seed.
+ *   7. Compute HMAC-SHA-256 over the same canonical bytes with
+ *      K_env_mac.
+ *   8. Write both back into the envelope.
+ */
+export function compose(input) {
+    const aead = suiteBriefEnclosureAEAD(input.suite);
+    const postmarkID = new TextEncoder().encode(input.postmark.id);
+    // Step 1: brief AEAD.
+    const briefCanonical = canonicalMarshal(input.briefPlaintext);
+    const briefCT = aeadSeal(aead, input.kBrief, input.briefAEADNonce, briefCanonical, postmarkID);
+    const briefField = base64Encode(concat(input.briefAEADNonce, briefCT));
+    // Step 2: enclosure AEAD.
+    const enclosureCanonical = canonicalMarshal(input.enclosurePlaintext);
+    const enclosureCT = aeadSeal(aead, input.kEnclosure, input.enclosureAEADNonce, enclosureCanonical, postmarkID);
+    const enclosureField = base64Encode(concat(input.enclosureAEADNonce, enclosureCT));
+    // Step 3: wrap K_brief per recipient.
+    const briefRecipients = {};
+    for (const r of input.briefRecipients) {
+        const rand = input.wrapRandomness.get(r.keyId);
+        if (rand === undefined) {
+            throw new Error(`compose: missing wrap randomness for brief recipient ${r.keyId}`);
+        }
+        briefRecipients[r.keyId] = wrapWithRandomness(input.suite, r.publicKey, input.kBrief, rand);
+    }
+    // Step 4: wrap K_enclosure per recipient.
+    const enclosureRecipients = {};
+    for (const r of input.enclosureRecipients) {
+        const rand = input.wrapRandomness.get(`enclosure:${r.keyId}`)
+            ?? input.wrapRandomness.get(r.keyId);
+        if (rand === undefined) {
+            throw new Error(`compose: missing wrap randomness for enclosure recipient ${r.keyId}`);
+        }
+        enclosureRecipients[r.keyId] = wrapWithRandomness(input.suite, r.publicKey, input.kEnclosure, rand);
+    }
+    // Step 5: assemble with placeholder signature + MAC.
+    //
+    // Wire-shape rules:
+    //   postmark.extensions and seal.extensions DEFAULT to {} when
+    //     the caller doesn't pass them — these slots are always
+    //     present on the wire (some routers depend on the keys
+    //     existing as a marker even when empty).
+    //   Top-level extensions DEFAULTS to absent — the spec treats
+    //     it as truly optional.
+    const postmark = {
+        ...input.postmark,
+        extensions: input.postmark.extensions ?? {},
+    };
+    const seal = {
+        algorithm: input.suite,
+        key_id: input.sealKeyId,
+        signature: "",
+        session_mac: "",
+        brief_recipients: briefRecipients,
+        enclosure_recipients: enclosureRecipients,
+        extensions: input.sealExtensions ?? {},
+    };
+    const env = {
+        type: "SEMP_ENVELOPE",
+        version: "1.0.0",
+        postmark,
+        seal,
+        brief: briefField,
+        enclosure: enclosureField,
+    };
+    if (input.extensions !== undefined) {
+        env.extensions = input.extensions;
+    }
+    // Step 6: §4.3 canonical bytes and seal.signature.
+    const canonical = canonicalEnvelopeFor(env);
+    const signingInput = concat(new TextEncoder().encode(EnvelopePrefix), canonical);
+    const sig = ed25519Sign(input.senderDomainSigningSeed, signingInput);
+    env.seal.signature = base64Encode(sig);
+    // Step 7: session MAC over the SAME canonical bytes (signature
+    // and session_mac were both blanked, so both proofs cover the
+    // same input).
+    const mac = computeMAC(input.kEnvMAC, canonical);
+    env.seal.session_mac = base64Encode(mac);
+    return env;
+}
+/**
+ * Compute the §4.3 canonical envelope bytes — signature and
+ * session_mac blanked, hop_count and padding omitted.
+ */
+export function canonicalEnvelopeFor(envelope) {
+    return marshalWithElision(envelope, (clone) => {
+        if (!isRecord(clone)) {
+            return;
+        }
+        delete clone.padding;
+        const seal = clone.seal;
+        if (isRecord(seal)) {
+            if ("signature" in seal) {
+                seal.signature = "";
+            }
+            if ("session_mac" in seal) {
+                seal.session_mac = "";
+            }
+        }
+        const postmark = clone.postmark;
+        if (isRecord(postmark)) {
+            delete postmark.hop_count;
+        }
+    });
+}
+/**
+ * Open an envelope for a specific recipient. Inverts {@link compose}:
+ * unwraps K_brief and K_enclosure, AEAD-decrypts both fields, and
+ * returns the parsed plaintexts. Throws if the recipient slot is
+ * absent or the AEAD tag does not verify.
+ *
+ * Does NOT verify seal.signature or seal.session_mac — those are
+ * the routing-server / receiving-server checks per §7.2 and live
+ * on the server side. {@link verifySealSignature} and
+ * {@link verifySessionMAC} are the corresponding verifier helpers.
+ */
+export function openForRecipient(input) {
+    const aead = suiteBriefEnclosureAEAD(input.suite);
+    const env = input.envelope;
+    const postmarkID = new TextEncoder().encode(env.postmark.id);
+    // Unwrap K_brief.
+    const briefWrapped = env.seal.brief_recipients[input.recipientKeyId];
+    if (typeof briefWrapped !== "string") {
+        throw new Error(`open: recipient ${input.recipientKeyId} not in brief_recipients`);
+    }
+    const kBrief = sealUnwrap(input.suite, input.recipientPrivateKey, input.recipientPublicKey, briefWrapped);
+    // Brief AEAD: blob is base64(nonce || aead_ct), 12-byte nonce.
+    const briefBlob = base64Decode(env.brief);
+    if (briefBlob.length < 12) {
+        throw new Error("open: brief blob too short");
+    }
+    const briefNonce = briefBlob.slice(0, 12);
+    const briefCT = briefBlob.slice(12);
+    const briefPT = aeadOpen(aead, kBrief, briefNonce, briefCT, postmarkID);
+    const brief = JSON.parse(new TextDecoder().decode(briefPT));
+    // Unwrap K_enclosure.
+    const enclosureWrapped = env.seal.enclosure_recipients[input.recipientKeyId];
+    if (typeof enclosureWrapped !== "string") {
+        throw new Error(`open: recipient ${input.recipientKeyId} not in enclosure_recipients`);
+    }
+    const kEnclosure = sealUnwrap(input.suite, input.recipientPrivateKey, input.recipientPublicKey, enclosureWrapped);
+    // Enclosure AEAD: same wire shape.
+    const enclBlob = base64Decode(env.enclosure);
+    if (enclBlob.length < 12) {
+        throw new Error("open: enclosure blob too short");
+    }
+    const enclNonce = enclBlob.slice(0, 12);
+    const enclCT = enclBlob.slice(12);
+    const enclPT = aeadOpen(aead, kEnclosure, enclNonce, enclCT, postmarkID);
+    const enclosure = JSON.parse(new TextDecoder().decode(enclPT));
+    return { brief, enclosure };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+function base64Encode(b) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(b).toString("base64");
+    }
+    let bin = "";
+    for (let i = 0; i < b.length; i++) {
+        bin += String.fromCharCode(b[i] ?? 0);
+    }
+    return btoa(bin);
+}
+function base64Decode(s) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(s, "base64"));
+    }
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) {
+        out[i] = bin.charCodeAt(i);
+    }
+    return out;
+}
+//# sourceMappingURL=compose.js.map

package/dist/envelope/compose.js.map

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

package/dist/envelope/encode.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire serialization helpers per ENVELOPE.md §2.1 + MIME.md §2.2.
+ *
+ * `encodeEnvelope` produces the on-the-wire UTF-8 JSON. The output is
+ * suitable for transmission over any SEMP transport
+ * (`Content-Type: application/semp-envelope`) and for storage as a
+ * `.semp` file.
+ *
+ * `encodeEnvelope` does NOT produce the canonical form — use
+ * {@link "./canonical".canonicalEnvelopeBytes} for the byte stream
+ * consumed by signature and MAC computation.
+ *
+ * @module
+ */
+import type { Envelope } from "./compose.js";
+/** SEMP wire MIME type per MIME.md §2.2. */
+export declare const EnvelopeMIMEType = "application/semp-envelope";
+/** SEMP envelope file extension per MIME.md §2.2. */
+export declare const EnvelopeFileExtension = ".semp";
+/**
+ * Wire JSON serialization of `env`. UTF-8, no BOM, no trailing
+ * newline — the byte sequence is suitable for transport bodies and
+ * for direct `.semp` file content.
+ */
+export declare function encodeEnvelope(env: Envelope): Uint8Array;
+/**
+ * Alias for {@link encodeEnvelope} that names the `.semp` file
+ * use case explicitly. MIME.md §2.2 specifies one envelope per file;
+ * this helper enforces that contract by returning the same single-
+ * envelope JSON.
+ */
+export declare function encodeEnvelopeFile(env: Envelope): Uint8Array;
+/**
+ * Parse a SEMP envelope from wire bytes. Throws on malformed JSON
+ * or when the parsed value is missing the discriminator
+ * `type === "SEMP_ENVELOPE"`.
+ */
+export declare function decodeEnvelope(data: Uint8Array | string): Envelope;
+/** Decode a `.semp` file body. Mirrors {@link decodeEnvelope}. */
+export declare function decodeEnvelopeFile(data: Uint8Array | string): Envelope;
+//# sourceMappingURL=encode.d.ts.map

package/dist/envelope/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/envelope/encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,UAAU,CAGxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,UAAU,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CA2BlE;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAEtE"}

package/dist/envelope/encode.js

@@ -0,0 +1,69 @@
+/**
+ * Wire serialization helpers per ENVELOPE.md §2.1 + MIME.md §2.2.
+ *
+ * `encodeEnvelope` produces the on-the-wire UTF-8 JSON. The output is
+ * suitable for transmission over any SEMP transport
+ * (`Content-Type: application/semp-envelope`) and for storage as a
+ * `.semp` file.
+ *
+ * `encodeEnvelope` does NOT produce the canonical form — use
+ * {@link "./canonical".canonicalEnvelopeBytes} for the byte stream
+ * consumed by signature and MAC computation.
+ *
+ * @module
+ */
+/** SEMP wire MIME type per MIME.md §2.2. */
+export const EnvelopeMIMEType = "application/semp-envelope";
+/** SEMP envelope file extension per MIME.md §2.2. */
+export const EnvelopeFileExtension = ".semp";
+/**
+ * Wire JSON serialization of `env`. UTF-8, no BOM, no trailing
+ * newline — the byte sequence is suitable for transport bodies and
+ * for direct `.semp` file content.
+ */
+export function encodeEnvelope(env) {
+    // Plain JSON — NOT canonical. Used for transport, not signing.
+    return new TextEncoder().encode(JSON.stringify(env));
+}
+/**
+ * Alias for {@link encodeEnvelope} that names the `.semp` file
+ * use case explicitly. MIME.md §2.2 specifies one envelope per file;
+ * this helper enforces that contract by returning the same single-
+ * envelope JSON.
+ */
+export function encodeEnvelopeFile(env) {
+    return encodeEnvelope(env);
+}
+/**
+ * Parse a SEMP envelope from wire bytes. Throws on malformed JSON
+ * or when the parsed value is missing the discriminator
+ * `type === "SEMP_ENVELOPE"`.
+ */
+export function decodeEnvelope(data) {
+    const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+    if (text === "") {
+        throw new Error("envelope: empty input");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`envelope: parse: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed)) {
+        throw new Error("envelope: top-level value is not an object");
+    }
+    const obj = parsed;
+    if (obj.type !== "SEMP_ENVELOPE") {
+        throw new Error(`envelope: type ${JSON.stringify(obj.type)} is not SEMP_ENVELOPE`);
+    }
+    return obj;
+}
+/** Decode a `.semp` file body. Mirrors {@link decodeEnvelope}. */
+export function decodeEnvelopeFile(data) {
+    return decodeEnvelope(data);
+}
+//# sourceMappingURL=encode.js.map

package/dist/envelope/encode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.js","sourceRoot":"","sources":["../../src/envelope/encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAE5D,qDAAqD;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAE7C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa;IAC1C,+DAA+D;IAC/D,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAa;IAC9C,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAyB;IACtD,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9E,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,oBAAoB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACrB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAClE,CAAC;IACJ,CAAC;IACD,OAAO,GAA0B,CAAC;AACpC,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,kBAAkB,CAAC,IAAyB;IAC1D,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/envelope/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Envelope layer per ENVELOPE.md §2 + §4 + §6 + §7.
+ *
+ * Compose / open / verify primitives + bucket math + padding +
+ * send-time obfuscation + wire-format encode/decode + typed
+ * rejection error.
+ *
+ * @module
+ */
+export { canonicalEnvelopeBytes } from "./canonical.js";
+export { DefaultMaxEnvelopeSize, MinEnvelopeSizeBucket, selectRecipientCountBucket, selectSizeBucket, } from "./buckets.js";
+export { type ComposeInput, type Envelope, type OpenedEnvelope, type OpenInput, type PostmarkFields, type RecipientKey, canonicalEnvelopeFor, compose, openForRecipient, } from "./compose.js";
+export { EnvelopeFileExtension, EnvelopeMIMEType, decodeEnvelope, decodeEnvelopeFile, encodeEnvelope, encodeEnvelopeFile, } from "./encode.js";
+export { verifySealSignature, verifySessionMAC } from "./verify.js";
+export { type OpenedBrief, type OpenedEnclosure, type RecipientCandidate, openBriefAny, openEnclosureAny, } from "./open_any.js";
+export { type OpenAndVerifyInput, type OpenAndVerifyResult, type SenderKeyResolver, type SenderKeyResolverFunc, openAndVerify, } from "./open_verified.js";
+export { type PadConfig, Ed25519SignatureB64Len, HMACSHA256B64Len, buildPaddingValue, fillPadding, } from "./padding.js";
+export { type SendTimeDelayConfig, DefaultSendTimeDelayCeilingMs, sendTimeDelay, } from "./sendtime.js";
+export { EnvelopeRejection, isEnvelopeRejection } from "./rejection.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/envelope/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/envelope/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,oBAAoB,EACpB,OAAO,EACP,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,SAAS,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,mBAAmB,EACxB,6BAA6B,EAC7B,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/envelope/index.js

@@ -0,0 +1,20 @@
+/**
+ * Envelope layer per ENVELOPE.md §2 + §4 + §6 + §7.
+ *
+ * Compose / open / verify primitives + bucket math + padding +
+ * send-time obfuscation + wire-format encode/decode + typed
+ * rejection error.
+ *
+ * @module
+ */
+export { canonicalEnvelopeBytes } from "./canonical.js";
+export { DefaultMaxEnvelopeSize, MinEnvelopeSizeBucket, selectRecipientCountBucket, selectSizeBucket, } from "./buckets.js";
+export { canonicalEnvelopeFor, compose, openForRecipient, } from "./compose.js";
+export { EnvelopeFileExtension, EnvelopeMIMEType, decodeEnvelope, decodeEnvelopeFile, encodeEnvelope, encodeEnvelopeFile, } from "./encode.js";
+export { verifySealSignature, verifySessionMAC } from "./verify.js";
+export { openBriefAny, openEnclosureAny, } from "./open_any.js";
+export { openAndVerify, } from "./open_verified.js";
+export { Ed25519SignatureB64Len, HMACSHA256B64Len, buildPaddingValue, fillPadding, } from "./padding.js";
+export { DefaultSendTimeDelayCeilingMs, sendTimeDelay, } from "./sendtime.js";
+export { EnvelopeRejection, isEnvelopeRejection } from "./rejection.js";
+//# sourceMappingURL=index.js.map

package/dist/envelope/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/envelope/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAOL,oBAAoB,EACpB,OAAO,EACP,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAIL,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAKL,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,6BAA6B,EAC7B,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/envelope/open_any.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Multi-recipient open helpers per ENVELOPE.md §6.
+ *
+ * A recipient client may hold multiple device keys (KEY.md §10).
+ * `openBriefAny` and `openEnclosureAny` walk a list of candidate
+ * recipient private keys, attempt to unwrap each in turn, and return
+ * the result from the first matching slot.
+ *
+ * @module
+ */
+import { type Envelope, type OpenInput } from "./compose.js";
+/** One candidate recipient identity to try when opening. */
+export interface RecipientCandidate {
+    /** Recipient client key id (matches a key in seal.*_recipients). */
+    keyId: string;
+    /** 32-byte X25519 (or 2432-byte hybrid) private key. */
+    privateKey: Uint8Array;
+    /** 32-byte X25519 (or 1216-byte hybrid) public key. */
+    publicKey: Uint8Array;
+}
+/** Result of a successful multi-recipient brief open. */
+export interface OpenedBrief {
+    /** The candidate that successfully unwrapped K_brief. */
+    candidate: RecipientCandidate;
+    /** Decoded brief plaintext (parsed from canonical JSON). */
+    brief: unknown;
+}
+/** Result of a successful multi-recipient enclosure open. */
+export interface OpenedEnclosure {
+    /** The candidate that successfully unwrapped K_enclosure. */
+    candidate: RecipientCandidate;
+    /** Decoded enclosure plaintext (parsed from canonical JSON). */
+    enclosure: unknown;
+}
+/**
+ * Walk `candidates` and try each recipient identity against
+ * `env.seal.brief_recipients`. Returns the brief plaintext from the
+ * first matching slot whose AEAD tag verifies. Throws when no
+ * candidate matches a slot or every candidate's AEAD open fails.
+ */
+export declare function openBriefAny(suite: OpenInput["suite"], env: Envelope, candidates: RecipientCandidate[]): OpenedBrief;
+/**
+ * Walk `candidates` and try each against
+ * `env.seal.enclosure_recipients`. Returns the enclosure plaintext
+ * from the first matching slot whose AEAD tag verifies.
+ */
+export declare function openEnclosureAny(suite: OpenInput["suite"], env: Envelope, candidates: RecipientCandidate[]): OpenedEnclosure;
+//# sourceMappingURL=open_any.d.ts.map

package/dist/envelope/open_any.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open_any.d.ts","sourceRoot":"","sources":["../../src/envelope/open_any.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEf,MAAM,cAAc,CAAC;AAEtB,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,UAAU,EAAE,UAAU,CAAC;IACvB,uDAAuD;IACvD,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,SAAS,EAAE,kBAAkB,CAAC;IAC9B,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,SAAS,EAAE,kBAAkB,CAAC;IAC9B,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,GAAG,EAAE,QAAQ,EACb,UAAU,EAAE,kBAAkB,EAAE,GAC/B,WAAW,CAiCb;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,GAAG,EAAE,QAAQ,EACb,UAAU,EAAE,kBAAkB,EAAE,GAC/B,eAAe,CAiCjB"}

package/dist/envelope/open_any.js

@@ -0,0 +1,81 @@
+/**
+ * Multi-recipient open helpers per ENVELOPE.md §6.
+ *
+ * A recipient client may hold multiple device keys (KEY.md §10).
+ * `openBriefAny` and `openEnclosureAny` walk a list of candidate
+ * recipient private keys, attempt to unwrap each in turn, and return
+ * the result from the first matching slot.
+ *
+ * @module
+ */
+import { openForRecipient, } from "./compose.js";
+/**
+ * Walk `candidates` and try each recipient identity against
+ * `env.seal.brief_recipients`. Returns the brief plaintext from the
+ * first matching slot whose AEAD tag verifies. Throws when no
+ * candidate matches a slot or every candidate's AEAD open fails.
+ */
+export function openBriefAny(suite, env, candidates) {
+    if (candidates.length === 0) {
+        throw new Error("envelope: openBriefAny: empty candidate list");
+    }
+    const errors = [];
+    for (const c of candidates) {
+        if (env.seal.brief_recipients[c.keyId] === undefined) {
+            continue; // not a brief recipient
+        }
+        try {
+            const opened = openForRecipient({
+                suite,
+                envelope: env,
+                recipientKeyId: c.keyId,
+                recipientPrivateKey: c.privateKey,
+                recipientPublicKey: c.publicKey,
+            });
+            return { candidate: c, brief: opened.brief };
+        }
+        catch (err) {
+            errors.push(`${c.keyId}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+    }
+    if (errors.length === 0) {
+        throw new Error("envelope: openBriefAny: no candidate matches a brief recipient slot");
+    }
+    throw new Error(`envelope: openBriefAny: every candidate failed: ${errors.join("; ")}`);
+}
+/**
+ * Walk `candidates` and try each against
+ * `env.seal.enclosure_recipients`. Returns the enclosure plaintext
+ * from the first matching slot whose AEAD tag verifies.
+ */
+export function openEnclosureAny(suite, env, candidates) {
+    if (candidates.length === 0) {
+        throw new Error("envelope: openEnclosureAny: empty candidate list");
+    }
+    const errors = [];
+    for (const c of candidates) {
+        if (env.seal.enclosure_recipients[c.keyId] === undefined) {
+            continue; // not an enclosure recipient
+        }
+        try {
+            const opened = openForRecipient({
+                suite,
+                envelope: env,
+                recipientKeyId: c.keyId,
+                recipientPrivateKey: c.privateKey,
+                recipientPublicKey: c.publicKey,
+            });
+            return { candidate: c, enclosure: opened.enclosure };
+        }
+        catch (err) {
+            errors.push(`${c.keyId}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+    }
+    if (errors.length === 0) {
+        throw new Error("envelope: openEnclosureAny: no candidate matches an enclosure recipient slot");
+    }
+    throw new Error(`envelope: openEnclosureAny: every candidate failed: ${errors.join("; ")}`);
+}
+//# sourceMappingURL=open_any.js.map

package/dist/envelope/open_any.js.map

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

package/dist/envelope/open_verified.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Open + verify orchestrator per ENVELOPE.md §6 + §7.2.
+ *
+ * `openAndVerify` runs the full receipt-side check on an envelope
+ * delivered to a recipient client:
+ *
+ *   1. Resolve the sender domain's signing public key via the
+ *      caller-supplied {@link SenderKeyResolver}.
+ *   2. Verify `seal.signature` against that key.
+ *   3. Walk the supplied recipient candidates and open the brief +
+ *      enclosure for the first matching device key.
+ *
+ * `openAndVerify` does NOT run `seal.session_mac` — that is the
+ * routing-server / receiving-server check between adjacent SEMP
+ * peers; the recipient client uses {@link "./verify".verifySessionMAC}
+ * separately when it has access to the K_env_mac.
+ *
+ * @module
+ */
+import { type Envelope, type OpenInput } from "./compose.js";
+import { type RecipientCandidate } from "./open_any.js";
+/**
+ * Caller-supplied lookup for the sender domain's signing public
+ * key. Returns the 32-byte Ed25519 public key for the domain that
+ * originated `env.postmark.from_domain`, or null/throws when the
+ * key cannot be resolved.
+ */
+export interface SenderKeyResolver {
+    lookupSenderDomainPub(fromDomain: string, keyId: string): Promise<Uint8Array | null>;
+}
+/** Functional shorthand for {@link SenderKeyResolver}. */
+export type SenderKeyResolverFunc = (fromDomain: string, keyId: string) => Promise<Uint8Array | null>;
+/** Inputs to {@link openAndVerify}. */
+export interface OpenAndVerifyInput {
+    suite: OpenInput["suite"];
+    envelope: Envelope;
+    candidates: RecipientCandidate[];
+    /** Either a {@link SenderKeyResolver} or its functional form. */
+    resolver: SenderKeyResolver | SenderKeyResolverFunc;
+}
+/** Result of a successful {@link openAndVerify}. */
+export interface OpenAndVerifyResult {
+    /** Sender domain public key the signature verified under. */
+    senderDomainPub: Uint8Array;
+    /** Recipient candidate that successfully opened the slots. */
+    candidate: RecipientCandidate;
+    /** Decoded brief plaintext. */
+    brief: unknown;
+    /** Decoded enclosure plaintext. */
+    enclosure: unknown;
+}
+/**
+ * Run sender-signature verification + multi-candidate open. Returns
+ * the opened plaintexts plus the matched candidate and the resolved
+ * sender public key. Throws on missing sender key, signature
+ * mismatch, or open failure.
+ */
+export declare function openAndVerify(input: OpenAndVerifyInput): Promise<OpenAndVerifyResult>;
+//# sourceMappingURL=open_verified.d.ts.map

package/dist/envelope/open_verified.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open_verified.d.ts","sourceRoot":"","sources":["../../src/envelope/open_verified.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,kBAAkB,EAGxB,MAAM,eAAe,CAAC;AAGvB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB,CACnB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC/B;AAED,0DAA0D;AAC1D,MAAM,MAAM,qBAAqB,GAAG,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;AAEhC,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,iEAAiE;IACjE,QAAQ,EAAE,iBAAiB,GAAG,qBAAqB,CAAC;CACrD;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,eAAe,EAAE,UAAU,CAAC;IAC5B,8DAA8D;IAC9D,SAAS,EAAE,kBAAkB,CAAC;IAC9B,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CA2C9B"}