@sempdev/semp 0.4.3

package/dist/enclosure/forwarding.js

@@ -0,0 +1,119 @@
+/**
+ * Forwarding compose per ENVELOPE.md §6.6.
+ *
+ * A forwarded enclosure carries three signatures, layered:
+ *
+ *   1. The ORIGINAL sender's `sender_signature` over their inner
+ *      enclosure (subject, content_type, body, attachments,
+ *      extensions). Prefix: `SEMP-ENCLOSURE-SENDER:`.
+ *      Signed scope: the `original_enclosure_plaintext` subtree.
+ *
+ *   2. The FORWARDER's `forwarder_attestation` over the
+ *      `forwarded_from` block — the inner sender_signature is
+ *      already populated by step 1, so this signs over canonical
+ *      bytes that include it. Prefix: `SEMP-FORWARDER-ATTESTATION:`.
+ *      Signed scope: the entire `forwarded_from` subtree.
+ *
+ *   3. The FORWARDER acting as outer sender: `sender_signature`
+ *      over the outer enclosure. Prefix: `SEMP-ENCLOSURE-SENDER:`.
+ *      Signed scope: the entire outer enclosure object.
+ *
+ * The verify path (handlers-wave4.ts) walks these three steps in
+ * reverse to verify.
+ *
+ * @module
+ */
+import { fingerprint, publicKeyFromSeed, signSignedDoc } from "../keys/index.js";
+/**
+ * Compose a 3-signature forwarded enclosure. Returns the
+ * fully-signed object whose canonical bytes match the spec.
+ *
+ * Step 1: sign the inner enclosure with the original sender's
+ *   identity key. The signed inner becomes
+ *   `forwarded_from.original_enclosure_plaintext`.
+ *
+ * Step 2: assemble the `forwarded_from` block with the signed
+ *   inner, original_seal/postmark/address, received_at, and a
+ *   `forwarder_attestation` placeholder. Sign the block with the
+ *   forwarder's identity key under the
+ *   SEMP-FORWARDER-ATTESTATION: prefix.
+ *
+ * Step 3: assemble the outer enclosure with the signed
+ *   forwarded_from block and a `sender_signature` placeholder.
+ *   Sign with the forwarder's identity key under the
+ *   SEMP-ENCLOSURE-SENDER: prefix.
+ */
+export function composeForwarded(input) {
+    // Step 1: sign the inner enclosure as the original sender.
+    const innerPreSign = {
+        subject: input.innerEnclosurePlaintext.subject,
+        content_type: input.innerEnclosurePlaintext.content_type,
+        body: input.innerEnclosurePlaintext.body,
+        attachments: input.innerEnclosurePlaintext.attachments ?? [],
+        forwarded_from: input.innerEnclosurePlaintext.forwarded_from ?? null,
+        extensions: input.innerEnclosurePlaintext.extensions ?? {},
+        sender_signature: {
+            algorithm: "ed25519",
+            key_id: input.innerSenderKeyId,
+            value: "",
+        },
+    };
+    const innerSigned = signSignedDoc({
+        preSignJSON: innerPreSign,
+        seed: input.innerSenderSeed,
+        signaturePath: "sender_signature.value",
+        prefix: "SEMP-ENCLOSURE-SENDER:",
+    });
+    // Cross-check: the inner key_id MUST match the forwarder-claimed
+    // key. Fingerprint mismatches surface here, not at the verify
+    // layer.
+    const innerKeyIdActual = fingerprint(publicKeyFromSeed(input.innerSenderSeed));
+    if (innerKeyIdActual !== input.innerSenderKeyId) {
+        throw new Error(`composeForwarded: innerSenderKeyId ${input.innerSenderKeyId} does not match seed-derived ${innerKeyIdActual}`);
+    }
+    // Step 2: forwarder_attestation over forwarded_from.
+    const forwardedFromPreSign = {
+        original_enclosure_plaintext: innerSigned.signedJSON,
+        original_seal: input.originalEnvelope.original_seal,
+        original_postmark: input.originalEnvelope.original_postmark,
+        original_sender_address: input.originalEnvelope.original_sender_address,
+        received_at: input.receivedAt,
+        forwarder_attestation: {
+            algorithm: "ed25519",
+            key_id: input.forwarderKeyId,
+            value: "",
+        },
+    };
+    const fromSigned = signSignedDoc({
+        preSignJSON: forwardedFromPreSign,
+        seed: input.forwarderSeed,
+        signaturePath: "forwarder_attestation.value",
+        prefix: "SEMP-FORWARDER-ATTESTATION:",
+    });
+    const forwarderKeyIdActual = fingerprint(publicKeyFromSeed(input.forwarderSeed));
+    if (forwarderKeyIdActual !== input.forwarderKeyId) {
+        throw new Error(`composeForwarded: forwarderKeyId ${input.forwarderKeyId} does not match seed-derived ${forwarderKeyIdActual}`);
+    }
+    // Step 3: outer sender_signature.
+    const outerPreSign = {
+        subject: input.outerEnclosurePlaintext.subject,
+        content_type: input.outerEnclosurePlaintext.content_type,
+        body: input.outerEnclosurePlaintext.body,
+        attachments: input.outerEnclosurePlaintext.attachments ?? [],
+        forwarded_from: fromSigned.signedJSON,
+        extensions: input.outerEnclosurePlaintext.extensions ?? {},
+        sender_signature: {
+            algorithm: "ed25519",
+            key_id: input.forwarderKeyId,
+            value: "",
+        },
+    };
+    const outerSigned = signSignedDoc({
+        preSignJSON: outerPreSign,
+        seed: input.forwarderSeed,
+        signaturePath: "sender_signature.value",
+        prefix: "SEMP-ENCLOSURE-SENDER:",
+    });
+    return outerSigned.signedJSON;
+}
+//# sourceMappingURL=forwarding.js.map

package/dist/enclosure/forwarding.js.map

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

package/dist/enclosure/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Enclosure-layer compose helpers per ENVELOPE.md §6.
+ *
+ * Today: forwarding (3-signature chain). Future: large-attachment
+ * enclosure pre-encryption helpers, sender-signature compose
+ * convenience wrappers.
+ *
+ * @module
+ */
+export { type ComposeForwardedInput, type InnerEnclosurePlaintext, type OriginalEnvelopeRef, type OuterEnclosurePlaintext, type SignedForwardedEnclosure, composeForwarded, } from "./forwarding.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/enclosure/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/enclosure/index.js

@@ -0,0 +1,11 @@
+/**
+ * Enclosure-layer compose helpers per ENVELOPE.md §6.
+ *
+ * Today: forwarding (3-signature chain). Future: large-attachment
+ * enclosure pre-encryption helpers, sender-signature compose
+ * convenience wrappers.
+ *
+ * @module
+ */
+export { composeForwarded, } from "./forwarding.js";
+//# sourceMappingURL=index.js.map

package/dist/enclosure/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/enclosure/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAML,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/envelope/buckets.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Envelope size and recipient-count bucket math per ENVELOPE.md
+ * §2.4.1 (size) and §4.4.2 (recipient count).
+ *
+ * @module
+ */
+/**
+ * Smallest envelope size bucket (the protocol floor). Every
+ * envelope, including the smallest plaintext-only message, occupies
+ * at least 4 KB on the wire.
+ */
+export declare const MinEnvelopeSizeBucket = 4096;
+/**
+ * Default ceiling on envelope size. A deployment may configure a
+ * smaller `max_envelope_size` via the negotiated session limit; this
+ * is the protocol-default fallback.
+ */
+export declare const DefaultMaxEnvelopeSize: number;
+/**
+ * Select the size bucket for an unpadded envelope of the given byte
+ * size per the default power-of-two curve (4096, 8192, 16384, ...).
+ *
+ * Throws on negative input or input that exceeds the ceiling — over-
+ * limit envelopes MUST be recomposed; padding is not a remedy for
+ * over-limit content.
+ */
+export declare function selectSizeBucket(unpaddedSize: number, maxEnvelopeSize?: number): number;
+/**
+ * Select the recipient-count bucket per §4.4.2. The floor is 2
+ * unless `realRecipients === 1` AND `singleDomainNotGroup` is true,
+ * in which case the floor relaxes to 1 (a single-domain non-group
+ * send reveals only the obvious cardinality and gains no
+ * obfuscation from padding to 2). Real counts above 1024 force
+ * recomposition into multiple envelopes — the runner returns a
+ * sentinel of -1 in that case so callers can detect it.
+ */
+export declare function selectRecipientCountBucket(realRecipients: number, singleDomainNotGroup: boolean): number;
+//# sourceMappingURL=buckets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buckets.d.ts","sourceRoot":"","sources":["../../src/envelope/buckets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAsBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,oBAAoB,EAAE,OAAO,GAC5B,MAAM,CAeR"}

package/dist/envelope/buckets.js

@@ -0,0 +1,73 @@
+/**
+ * Envelope size and recipient-count bucket math per ENVELOPE.md
+ * §2.4.1 (size) and §4.4.2 (recipient count).
+ *
+ * @module
+ */
+/**
+ * Smallest envelope size bucket (the protocol floor). Every
+ * envelope, including the smallest plaintext-only message, occupies
+ * at least 4 KB on the wire.
+ */
+export const MinEnvelopeSizeBucket = 4096;
+/**
+ * Default ceiling on envelope size. A deployment may configure a
+ * smaller `max_envelope_size` via the negotiated session limit; this
+ * is the protocol-default fallback.
+ */
+export const DefaultMaxEnvelopeSize = 25 * 1024 * 1024;
+/**
+ * Select the size bucket for an unpadded envelope of the given byte
+ * size per the default power-of-two curve (4096, 8192, 16384, ...).
+ *
+ * Throws on negative input or input that exceeds the ceiling — over-
+ * limit envelopes MUST be recomposed; padding is not a remedy for
+ * over-limit content.
+ */
+export function selectSizeBucket(unpaddedSize, maxEnvelopeSize) {
+    if (!Number.isInteger(unpaddedSize) || unpaddedSize < 0) {
+        throw new Error(`envelope: invalid unpadded size ${unpaddedSize}`);
+    }
+    const ceiling = maxEnvelopeSize ?? DefaultMaxEnvelopeSize;
+    if (ceiling <= 0) {
+        throw new Error(`envelope: non-positive ceiling ${ceiling}`);
+    }
+    if (unpaddedSize > ceiling) {
+        throw new Error(`envelope: unpadded size ${unpaddedSize} exceeds max_envelope_size ${ceiling}`);
+    }
+    let bucket = MinEnvelopeSizeBucket;
+    while (bucket < unpaddedSize) {
+        const next = bucket * 2;
+        if (next > ceiling) {
+            return ceiling;
+        }
+        bucket = next;
+    }
+    return bucket;
+}
+/**
+ * Select the recipient-count bucket per §4.4.2. The floor is 2
+ * unless `realRecipients === 1` AND `singleDomainNotGroup` is true,
+ * in which case the floor relaxes to 1 (a single-domain non-group
+ * send reveals only the obvious cardinality and gains no
+ * obfuscation from padding to 2). Real counts above 1024 force
+ * recomposition into multiple envelopes — the runner returns a
+ * sentinel of -1 in that case so callers can detect it.
+ */
+export function selectRecipientCountBucket(realRecipients, singleDomainNotGroup) {
+    if (!Number.isInteger(realRecipients) || realRecipients < 0) {
+        throw new Error(`envelope: invalid recipient count ${realRecipients}`);
+    }
+    if (realRecipients === 1 && singleDomainNotGroup) {
+        return 1;
+    }
+    if (realRecipients > 1024) {
+        return -1; // recomposition required
+    }
+    let bucket = 2;
+    while (bucket < realRecipients) {
+        bucket *= 2;
+    }
+    return bucket;
+}
+//# sourceMappingURL=buckets.js.map

package/dist/envelope/buckets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buckets.js","sourceRoot":"","sources":["../../src/envelope/buckets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAAoB,EACpB,eAAwB;IAExB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,mCAAmC,YAAY,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,OAAO,GAAG,eAAe,IAAI,sBAAsB,CAAC;IAC1D,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,kCAAkC,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,YAAY,GAAG,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,2BAA2B,YAAY,8BAA8B,OAAO,EAAE,CAC/E,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,qBAAqB,CAAC;IACnC,OAAO,MAAM,GAAG,YAAY,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC;QACxB,IAAI,IAAI,GAAG,OAAO,EAAE,CAAC;YACnB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACxC,cAAsB,EACtB,oBAA6B;IAE7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,qCAAqC,cAAc,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,cAAc,KAAK,CAAC,IAAI,oBAAoB,EAAE,CAAC;QACjD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,cAAc,GAAG,IAAI,EAAE,CAAC;QAC1B,OAAO,CAAC,CAAC,CAAC,CAAC,yBAAyB;IACtC,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,MAAM,GAAG,cAAc,EAAE,CAAC;QAC/B,MAAM,IAAI,CAAC,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/envelope/canonical.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Envelope-specific canonicalization per ENVELOPE.md §4.3.
+ *
+ * On top of the generic canonical-JSON rules ({@link
+ * "../canonical/marshal"}), envelope canonicalization applies four
+ * specific elisions:
+ *
+ *   - `seal.signature` is set to ""
+ *   - `seal.session_mac` is set to ""
+ *   - `postmark.hop_count` is omitted entirely
+ *   - `padding` is omitted entirely
+ *
+ * These rules apply identically to the input of seal.signature
+ * (Ed25519) and seal.session_mac (HMAC-SHA-256); both proofs cover
+ * exactly the same byte stream so neither depends on the value of
+ * the other.
+ *
+ * @module
+ */
+/**
+ * Compute the §4.3 canonical bytes from any envelope-shaped value.
+ * The input is treated as opaque JSON: navigate to `seal.*` and
+ * `postmark.*` if they exist, blank/omit the relevant fields, and
+ * canonicalize. Inputs without those keys are returned with the
+ * generic canonicalization only.
+ */
+export declare function canonicalEnvelopeBytes(envelope: unknown): Uint8Array;
+//# sourceMappingURL=canonical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/envelope/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAEpE"}

package/dist/envelope/canonical.js

@@ -0,0 +1,54 @@
+/**
+ * Envelope-specific canonicalization per ENVELOPE.md §4.3.
+ *
+ * On top of the generic canonical-JSON rules ({@link
+ * "../canonical/marshal"}), envelope canonicalization applies four
+ * specific elisions:
+ *
+ *   - `seal.signature` is set to ""
+ *   - `seal.session_mac` is set to ""
+ *   - `postmark.hop_count` is omitted entirely
+ *   - `padding` is omitted entirely
+ *
+ * These rules apply identically to the input of seal.signature
+ * (Ed25519) and seal.session_mac (HMAC-SHA-256); both proofs cover
+ * exactly the same byte stream so neither depends on the value of
+ * the other.
+ *
+ * @module
+ */
+import { marshalWithElision } from "../canonical/index.js";
+/**
+ * Compute the §4.3 canonical bytes from any envelope-shaped value.
+ * The input is treated as opaque JSON: navigate to `seal.*` and
+ * `postmark.*` if they exist, blank/omit the relevant fields, and
+ * canonicalize. Inputs without those keys are returned with the
+ * generic canonicalization only.
+ */
+export function canonicalEnvelopeBytes(envelope) {
+    return marshalWithElision(envelope, envelopeElider);
+}
+function envelopeElider(v) {
+    if (!isRecord(v)) {
+        return;
+    }
+    // Top-level: drop `padding` if present.
+    delete v.padding;
+    const seal = v.seal;
+    if (isRecord(seal)) {
+        if ("signature" in seal) {
+            seal.signature = "";
+        }
+        if ("session_mac" in seal) {
+            seal.session_mac = "";
+        }
+    }
+    const postmark = v.postmark;
+    if (isRecord(postmark)) {
+        delete postmark.hop_count;
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/envelope/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/envelope/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAiB;IACtD,OAAO,kBAAkB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,cAAc,CAAC,CAAU;IAChC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IACD,wCAAwC;IACxC,OAAO,CAAC,CAAC,OAAO,CAAC;IAEjB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;IACpB,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,aAAa,IAAI,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC5B,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,QAAQ,CAAC,SAAS,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/envelope/compose.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 { type Suite, type WrapRandomness } from "../seal/index.js";
+/**
+ * Postmark fields populated at compose time. `hop_count` is set by
+ * relays in transit and is excluded from canonical bytes; it's
+ * not on the compose surface.
+ */
+export interface PostmarkFields {
+    id: string;
+    session_id: string;
+    from_domain: string;
+    to_domain: string;
+    /** ISO 8601 timestamp string. */
+    expires: string;
+    extensions?: Record<string, unknown>;
+}
+/** One recipient slot in the seal. */
+export interface RecipientKey {
+    /** SEMP fingerprint (lowercase hex of SHA-256(public_key)). */
+    keyId: string;
+    /** Recipient public key bytes (X25519 32B or hybrid 1216B per suite). */
+    publicKey: Uint8Array;
+}
+/**
+ * Inputs to envelope compose. All fields are required so the result
+ * is byte-deterministic given the inputs.
+ */
+export interface ComposeInput {
+    /** Algorithm suite. */
+    suite: Suite;
+    /** Sender domain signing key id (lowercase-hex SHA-256 fingerprint). */
+    sealKeyId: string;
+    /** 32-byte Ed25519 secret seed for the sender domain signing key. */
+    senderDomainSigningSeed: Uint8Array;
+    /** Postmark fields. */
+    postmark: PostmarkFields;
+    /** Brief payload (will be canonicalized, then AEAD-sealed). */
+    briefPlaintext: unknown;
+    /** Enclosure payload (already-signed enclosure; will be canonicalized + AEAD-sealed). */
+    enclosurePlaintext: unknown;
+    /** Per-recipient keys for the brief slot (server + clients). */
+    briefRecipients: RecipientKey[];
+    /** Per-recipient keys for the enclosure slot (clients only). */
+    enclosureRecipients: RecipientKey[];
+    /** 32-byte symmetric key wrapped to every brief recipient. */
+    kBrief: Uint8Array;
+    /** 32-byte symmetric key wrapped to every enclosure recipient. */
+    kEnclosure: Uint8Array;
+    /** Envelope MAC key derived from the session. */
+    kEnvMAC: Uint8Array;
+    /** AEAD nonce for the brief seal call (12 bytes for both suites). */
+    briefAEADNonce: Uint8Array;
+    /** AEAD nonce for the enclosure seal call (12 bytes for both suites). */
+    enclosureAEADNonce: Uint8Array;
+    /**
+     * Per-recipient wrap randomness. Keyed by keyId. Each entry must
+     * carry the X25519 ephemeral private key; the PQ suite also
+     * requires kyberEncapsRandomnessM. The runner pins these per
+     * vector; production callers either generate them fresh or
+     * forward them from a higher layer.
+     */
+    wrapRandomness: ReadonlyMap<string, WrapRandomness>;
+    /** Top-level extensions object (default: {}). */
+    extensions?: Record<string, unknown>;
+    /** Seal-layer extensions (default: {}). */
+    sealExtensions?: Record<string, unknown>;
+}
+/** Wire envelope returned by {@link compose}. */
+export interface Envelope {
+    type: "SEMP_ENVELOPE";
+    version: "1.0.0";
+    postmark: PostmarkFields;
+    seal: {
+        algorithm: string;
+        key_id: string;
+        signature: string;
+        session_mac: string;
+        brief_recipients: Record<string, string>;
+        enclosure_recipients: Record<string, string>;
+        extensions?: Record<string, unknown>;
+    };
+    brief: string;
+    enclosure: string;
+    /** Optional opaque base64-alphabet filler for size-bucket padding (§2.4). */
+    padding?: string;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * 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 declare function compose(input: ComposeInput): Envelope;
+/**
+ * Compute the §4.3 canonical envelope bytes — signature and
+ * session_mac blanked, hop_count and padding omitted.
+ */
+export declare function canonicalEnvelopeFor(envelope: unknown): Uint8Array;
+/**
+ * Inputs to {@link openForRecipient}. Targets one recipient client;
+ * for the multi-recipient case the caller iterates over the slot
+ * map and tries each client priv until one succeeds.
+ */
+export interface OpenInput {
+    suite: Suite;
+    envelope: Envelope;
+    /** Recipient client key id (matches a key in seal.*_recipients). */
+    recipientKeyId: string;
+    /** Recipient client private key (32B X25519 or 2432B hybrid). */
+    recipientPrivateKey: Uint8Array;
+    /** Recipient client public key (32B X25519 or 1216B hybrid). */
+    recipientPublicKey: Uint8Array;
+}
+/** Output of a successful open: recovered brief + enclosure plaintexts. */
+export interface OpenedEnvelope {
+    /** Decoded brief (parsed from canonical JSON). */
+    brief: unknown;
+    /** Decoded enclosure (parsed from canonical JSON). */
+    enclosure: unknown;
+}
+/**
+ * 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 declare function openForRecipient(input: OpenInput): OpenedEnvelope;
+//# sourceMappingURL=compose.d.ts.map

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

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