@sempdev/semp 0.4.3

package/dist/envelope/open_verified.js

@@ -0,0 +1,67 @@
+/**
+ * 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 {} from "./compose.js";
+import { openBriefAny, openEnclosureAny, } from "./open_any.js";
+import { verifySealSignature } from "./verify.js";
+/**
+ * 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 async function openAndVerify(input) {
+    const env = input.envelope;
+    const fromDomain = env.postmark.from_domain;
+    const keyId = env.seal.key_id;
+    const lookup = isResolver(input.resolver)
+        ? input.resolver.lookupSenderDomainPub.bind(input.resolver)
+        : input.resolver;
+    const pub = await lookup(fromDomain, keyId);
+    if (pub === null) {
+        throw new Error(`envelope: openAndVerify: resolver returned null for sender domain ${JSON.stringify(fromDomain)}, key_id ${JSON.stringify(keyId)}`);
+    }
+    if (!verifySealSignature(env, pub)) {
+        throw new Error("envelope: openAndVerify: seal.signature did not verify under the resolved sender domain key");
+    }
+    let brief;
+    let enclosure;
+    try {
+        brief = openBriefAny(input.suite, env, input.candidates);
+    }
+    catch (err) {
+        throw new Error(`envelope: openAndVerify: open brief failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        enclosure = openEnclosureAny(input.suite, env, input.candidates);
+    }
+    catch (err) {
+        throw new Error(`envelope: openAndVerify: open enclosure failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        senderDomainPub: pub,
+        candidate: brief.candidate,
+        brief: brief.brief,
+        enclosure: enclosure.enclosure,
+    };
+}
+function isResolver(r) {
+    return (typeof r.lookupSenderDomainPub === "function");
+}
+//# sourceMappingURL=open_verified.js.map

package/dist/envelope/open_verified.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open_verified.js","sourceRoot":"","sources":["../../src/envelope/open_verified.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAGN,MAAM,cAAc,CAAC;AACtB,OAAO,EAIL,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA0ClD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAyB;IAEzB,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC;IAC3B,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;IAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;IAC9B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC;QACvC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC3D,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;IAEnB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,qEAAqE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACnI,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IAED,IAAI,KAAkB,CAAC;IACvB,IAAI,SAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,+CAA+C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mDAAmD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACtG,CAAC;IACJ,CAAC;IAED,OAAO;QACL,eAAe,EAAE,GAAG;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,SAAS,CAAC,SAAS;KAC/B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,CAA4C;IAE5C,OAAO,CACL,OAAQ,CAAuB,CAAC,qBAAqB,KAAK,UAAU,CACrE,CAAC;AACJ,CAAC"}

package/dist/envelope/padding.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Envelope size-bucket padding per ENVELOPE.md §2.4.
+ *
+ * `fillPadding` populates `env.padding` with a base64-alphabet filler
+ * string whose length brings the serialized envelope's wire size
+ * exactly onto the bucket chosen from the configured size sequence.
+ * This is the privacy-critical primitive that prevents an on-path
+ * observer from learning the underlying envelope size.
+ *
+ * The size sequence is the default power-of-two curve starting at
+ * 4 KB by default; operators tune this via `bucketSequence` per the
+ * spec's "Operator tuning" allowance.
+ *
+ * @module
+ */
+import { type Envelope } from "./compose.js";
+/** Exact base64 length of an Ed25519 signature (64 raw bytes → 88 chars). */
+export declare const Ed25519SignatureB64Len = 88;
+/** Exact base64 length of an HMAC-SHA-256 output (32 raw bytes → 44 chars). */
+export declare const HMACSHA256B64Len = 44;
+/** Inputs to {@link fillPadding}. */
+export interface PadConfig {
+    /** Negotiated session ceiling. Zero means {@link DefaultMaxEnvelopeSize}. */
+    maxEnvelopeSize?: number;
+    /**
+     * Custom bucket sequence overriding the default power-of-two
+     * curve. Must be strictly increasing, with the first element
+     * at or above {@link MinEnvelopeSizeBucket} and the last at or
+     * below the effective ceiling. Operator tuning per §2.4.1.
+     */
+    bucketSequence?: number[];
+    /** Random source for filler bytes. Defaults to `globalThis.crypto.getRandomValues`. */
+    rand?: (n: number) => Uint8Array;
+}
+/**
+ * Populate `env.padding` so that `JSON.stringify(env)` lands on
+ * exactly the size of the chosen bucket. Safe to call before OR
+ * after `compose` populates `seal.signature` / `seal.session_mac` —
+ * if either is empty, fillPadding temporarily substitutes a
+ * fixed-length placeholder for measurement so the post-sign size
+ * is correct either way.
+ *
+ * Mutates `env` in place. Returns the chosen bucket size for
+ * caller-side assertions.
+ */
+export declare function fillPadding(env: Envelope, cfg?: PadConfig): number;
+/**
+ * Build a string of exactly `targetLen` base64-alphabet characters,
+ * drawn from a CSPRNG. The bulk is a base64 encoding of CSPRNG
+ * bytes; the final 1–3 characters (when targetLen is not reachable
+ * by `btoa` 4-character chunks) are CSPRNG-seeded alphabet
+ * characters appended for length alignment per §2.4.2.
+ */
+export declare function buildPaddingValue(targetLen: number, rand?: (n: number) => Uint8Array): string;
+//# sourceMappingURL=padding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"padding.d.ts","sourceRoot":"","sources":["../../src/envelope/padding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,KAAK,QAAQ,EACd,MAAM,cAAc,CAAC;AAOtB,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAUnC,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uFAAuF;IACvF,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,GAAE,SAAc,GAAG,MAAM,CAgDtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAwB,GAC5C,MAAM,CA0BR"}

package/dist/envelope/padding.js

@@ -0,0 +1,162 @@
+/**
+ * Envelope size-bucket padding per ENVELOPE.md §2.4.
+ *
+ * `fillPadding` populates `env.padding` with a base64-alphabet filler
+ * string whose length brings the serialized envelope's wire size
+ * exactly onto the bucket chosen from the configured size sequence.
+ * This is the privacy-critical primitive that prevents an on-path
+ * observer from learning the underlying envelope size.
+ *
+ * The size sequence is the default power-of-two curve starting at
+ * 4 KB by default; operators tune this via `bucketSequence` per the
+ * spec's "Operator tuning" allowance.
+ *
+ * @module
+ */
+import {} from "./compose.js";
+import { DefaultMaxEnvelopeSize, MinEnvelopeSizeBucket, selectSizeBucket, } from "./buckets.js";
+/** Exact base64 length of an Ed25519 signature (64 raw bytes → 88 chars). */
+export const Ed25519SignatureB64Len = 88;
+/** Exact base64 length of an HMAC-SHA-256 output (32 raw bytes → 44 chars). */
+export const HMACSHA256B64Len = 44;
+/**
+ * Pool of single base64-alphabet characters used to extend a base64
+ * filler by 1, 2, or 3 bytes when the bucket target requires
+ * non-multiple-of-4 padding length.
+ */
+const Base64AlphabetFillers = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/**
+ * Populate `env.padding` so that `JSON.stringify(env)` lands on
+ * exactly the size of the chosen bucket. Safe to call before OR
+ * after `compose` populates `seal.signature` / `seal.session_mac` —
+ * if either is empty, fillPadding temporarily substitutes a
+ * fixed-length placeholder for measurement so the post-sign size
+ * is correct either way.
+ *
+ * Mutates `env` in place. Returns the chosen bucket size for
+ * caller-side assertions.
+ */
+export function fillPadding(env, cfg = {}) {
+    const ceiling = cfg.maxEnvelopeSize ?? DefaultMaxEnvelopeSize;
+    if (cfg.bucketSequence !== undefined && cfg.bucketSequence.length > 0) {
+        validateBucketSequence(cfg.bucketSequence, ceiling);
+    }
+    const rand = cfg.rand ?? defaultRand;
+    // Substitute placeholders for empty signature / MAC so the
+    // measurement reflects the final post-sign wire size.
+    const origSig = env.seal.signature;
+    const origMac = env.seal.session_mac;
+    if (origSig === "") {
+        env.seal.signature = "A".repeat(Ed25519SignatureB64Len);
+    }
+    if (origMac === "") {
+        env.seal.session_mac = "A".repeat(HMACSHA256B64Len);
+    }
+    try {
+        env.padding = "";
+        const baselineBytes = utf8ByteLength(JSON.stringify(env));
+        const bucket = pickBucket(baselineBytes, ceiling, cfg.bucketSequence);
+        if (baselineBytes === bucket) {
+            return bucket;
+        }
+        const targetPadLen = bucket - baselineBytes;
+        if (targetPadLen < 0) {
+            throw new Error(`envelope: baseline ${baselineBytes} exceeds bucket ${bucket}`);
+        }
+        env.padding = buildPaddingValue(targetPadLen, rand);
+        // Final assertion: the envelope now serializes to exactly bucket.
+        const finalBytes = utf8ByteLength(JSON.stringify(env));
+        if (finalBytes !== bucket) {
+            throw new Error(`envelope: padding did not land on bucket ${bucket} (got ${finalBytes})`);
+        }
+        return bucket;
+    }
+    finally {
+        if (origSig === "") {
+            env.seal.signature = "";
+        }
+        if (origMac === "") {
+            env.seal.session_mac = "";
+        }
+    }
+}
+/**
+ * Build a string of exactly `targetLen` base64-alphabet characters,
+ * drawn from a CSPRNG. The bulk is a base64 encoding of CSPRNG
+ * bytes; the final 1–3 characters (when targetLen is not reachable
+ * by `btoa` 4-character chunks) are CSPRNG-seeded alphabet
+ * characters appended for length alignment per §2.4.2.
+ */
+export function buildPaddingValue(targetLen, rand = defaultRand) {
+    if (!Number.isInteger(targetLen) || targetLen < 0) {
+        throw new Error(`envelope: negative padding length ${targetLen}`);
+    }
+    if (targetLen === 0) {
+        return "";
+    }
+    // base64 emits 4 chars per 3 input bytes. Pick the largest
+    // multiple of 4 ≤ targetLen as the base64-encoded portion; the
+    // remainder (0–3 chars) is filled from the alphabet pool.
+    const baseChars = targetLen - (targetLen % 4);
+    const inputBytes = (baseChars / 4) * 3;
+    const out = [];
+    if (inputBytes > 0) {
+        const buf = rand(inputBytes);
+        out.push(base64Encode(buf));
+    }
+    const fillerCount = targetLen - baseChars;
+    if (fillerCount > 0) {
+        const seed = rand(fillerCount);
+        for (let i = 0; i < fillerCount; i++) {
+            const idx = (seed[i] ?? 0) % Base64AlphabetFillers.length;
+            out.push(Base64AlphabetFillers[idx] ?? "A");
+        }
+    }
+    return out.join("");
+}
+function pickBucket(unpaddedSize, ceiling, sequence) {
+    if (sequence === undefined || sequence.length === 0) {
+        return selectSizeBucket(unpaddedSize, ceiling);
+    }
+    for (const b of sequence) {
+        if (b >= unpaddedSize) {
+            return b;
+        }
+    }
+    return ceiling;
+}
+function validateBucketSequence(seq, ceiling) {
+    if ((seq[0] ?? 0) < MinEnvelopeSizeBucket) {
+        throw new Error(`envelope: bucket sequence first element ${seq[0]} is below protocol floor ${MinEnvelopeSizeBucket}`);
+    }
+    for (let i = 1; i < seq.length; i++) {
+        if ((seq[i] ?? 0) <= (seq[i - 1] ?? 0)) {
+            throw new Error(`envelope: bucket sequence is not strictly increasing at index ${i}`);
+        }
+    }
+    if ((seq[seq.length - 1] ?? 0) > ceiling) {
+        throw new Error(`envelope: bucket sequence last element ${seq[seq.length - 1]} exceeds max_envelope_size ${ceiling}`);
+    }
+}
+function utf8ByteLength(s) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.byteLength(s, "utf8");
+    }
+    return new TextEncoder().encode(s).length;
+}
+function defaultRand(n) {
+    const out = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(out);
+    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);
+}
+//# sourceMappingURL=padding.js.map

package/dist/envelope/padding.js.map

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

package/dist/envelope/rejection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Typed envelope-rejection error per ENVELOPE.md §9.
+ *
+ * The verify / open primitives surface structural and cryptographic
+ * failures as plain `Error` instances; consumers that need to map
+ * these onto the protocol's rejection reason codes can wrap or
+ * re-throw them as {@link EnvelopeRejection}.
+ *
+ * @module
+ */
+import type { ReasonCode } from "../reasoncodes.js";
+/** Error subtype carrying a SEMP rejection reason code. */
+export declare class EnvelopeRejection extends Error {
+    readonly name = "EnvelopeRejection";
+    readonly reasonCode: ReasonCode;
+    /** Optional operator-supplied human-readable description. */
+    readonly reasonText: string | undefined;
+    constructor(reasonCode: ReasonCode, reasonText?: string, message?: string);
+}
+/** Type guard for {@link EnvelopeRejection}. */
+export declare function isEnvelopeRejection(err: unknown): err is EnvelopeRejection;
+//# sourceMappingURL=rejection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rejection.d.ts","sourceRoot":"","sources":["../../src/envelope/rejection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,2DAA2D;AAC3D,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAU1E;AAED,gDAAgD;AAChD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAE1E"}

package/dist/envelope/rejection.js

@@ -0,0 +1,30 @@
+/**
+ * Typed envelope-rejection error per ENVELOPE.md §9.
+ *
+ * The verify / open primitives surface structural and cryptographic
+ * failures as plain `Error` instances; consumers that need to map
+ * these onto the protocol's rejection reason codes can wrap or
+ * re-throw them as {@link EnvelopeRejection}.
+ *
+ * @module
+ */
+/** Error subtype carrying a SEMP rejection reason code. */
+export class EnvelopeRejection extends Error {
+    name = "EnvelopeRejection";
+    reasonCode;
+    /** Optional operator-supplied human-readable description. */
+    reasonText;
+    constructor(reasonCode, reasonText, message) {
+        super(message ??
+            (reasonText !== undefined && reasonText !== ""
+                ? `envelope rejected: ${reasonCode} (${reasonText})`
+                : `envelope rejected: ${reasonCode}`));
+        this.reasonCode = reasonCode;
+        this.reasonText = reasonText;
+    }
+}
+/** Type guard for {@link EnvelopeRejection}. */
+export function isEnvelopeRejection(err) {
+    return err instanceof EnvelopeRejection;
+}
+//# sourceMappingURL=rejection.js.map

package/dist/envelope/rejection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejection.js","sourceRoot":"","sources":["../../src/envelope/rejection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,2DAA2D;AAC3D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACxB,IAAI,GAAG,mBAAmB,CAAC;IACpC,UAAU,CAAa;IAChC,6DAA6D;IACpD,UAAU,CAAqB;IAExC,YAAY,UAAsB,EAAE,UAAmB,EAAE,OAAgB;QACvE,KAAK,CACH,OAAO;YACL,CAAC,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE;gBAC5C,CAAC,CAAC,sBAAsB,UAAU,KAAK,UAAU,GAAG;gBACpD,CAAC,CAAC,sBAAsB,UAAU,EAAE,CAAC,CAC1C,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,gDAAgD;AAChD,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,GAAG,YAAY,iBAAiB,CAAC;AAC1C,CAAC"}

package/dist/envelope/sendtime.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Send-time obfuscation delay per CLIENT.md §3.8.
+ *
+ * `sendTimeDelay` sleeps for a uniformly random interval in
+ * `[0, ceilingMs]` before resolving, reducing the temporal
+ * resolution available to a passive network observer correlating
+ * the sender's submission with the recipient's delivery.
+ *
+ * Honors `postmark.expires`: the drawn delay is clamped so that
+ * submission cannot push past the envelope's expiry window.
+ *
+ * @module
+ */
+import type { Envelope } from "./compose.js";
+/** RECOMMENDED upper bound on the randomized delay per §3.8.1. */
+export declare const DefaultSendTimeDelayCeilingMs = 60000;
+/** Inputs to {@link sendTimeDelay}. */
+export interface SendTimeDelayConfig {
+    /** Upper bound on the delay in ms. Zero / undefined means no delay. */
+    ceilingMs?: number;
+    /**
+     * When true, skip the delay entirely. Clients flag time-sensitive
+     * envelopes (a verification code the user is reading, a reply in a
+     * live conversation, etc.) per §3.8.1.
+     */
+    timeSensitive?: boolean;
+    /** Wall-clock provider. Defaults to `() => new Date()`. */
+    nowFn?: () => Date;
+    /** Cancellation signal. Aborts the delay early when fired. */
+    signal?: AbortSignal;
+    /**
+     * Random source returning a float in `[0, 1)`. Defaults to
+     * `globalThis.crypto.getRandomValues`-derived entropy.
+     */
+    rand?: () => number;
+}
+/**
+ * Sleep for a uniformly random interval in `[0, ceilingMs]` before
+ * resolving. Returns immediately when:
+ *
+ *  - `cfg.timeSensitive === true`
+ *  - `cfg.ceilingMs` is zero / undefined / negative
+ *  - the drawn delay rounds to zero
+ *
+ * Throws when the envelope is already expired (`postmark.expires`
+ * is in the past).
+ */
+export declare function sendTimeDelay(env: Envelope, cfg?: SendTimeDelayConfig): Promise<void>;
+//# sourceMappingURL=sendtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sendtime.d.ts","sourceRoot":"","sources":["../../src/envelope/sendtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,kEAAkE;AAClE,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,QAAQ,EACb,GAAG,GAAE,mBAAwB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/envelope/sendtime.js

@@ -0,0 +1,87 @@
+/**
+ * Send-time obfuscation delay per CLIENT.md §3.8.
+ *
+ * `sendTimeDelay` sleeps for a uniformly random interval in
+ * `[0, ceilingMs]` before resolving, reducing the temporal
+ * resolution available to a passive network observer correlating
+ * the sender's submission with the recipient's delivery.
+ *
+ * Honors `postmark.expires`: the drawn delay is clamped so that
+ * submission cannot push past the envelope's expiry window.
+ *
+ * @module
+ */
+/** RECOMMENDED upper bound on the randomized delay per §3.8.1. */
+export const DefaultSendTimeDelayCeilingMs = 60_000;
+/**
+ * Sleep for a uniformly random interval in `[0, ceilingMs]` before
+ * resolving. Returns immediately when:
+ *
+ *  - `cfg.timeSensitive === true`
+ *  - `cfg.ceilingMs` is zero / undefined / negative
+ *  - the drawn delay rounds to zero
+ *
+ * Throws when the envelope is already expired (`postmark.expires`
+ * is in the past).
+ */
+export async function sendTimeDelay(env, cfg = {}) {
+    if (cfg.timeSensitive === true) {
+        return;
+    }
+    let ceiling = cfg.ceilingMs ?? 0;
+    if (ceiling <= 0) {
+        return;
+    }
+    const nowFn = cfg.nowFn ?? (() => new Date());
+    const expiresStr = env.postmark.expires;
+    if (typeof expiresStr === "string" && expiresStr !== "") {
+        const expiresMs = Date.parse(expiresStr);
+        if (Number.isNaN(expiresMs)) {
+            throw new Error(`envelope: postmark.expires ${JSON.stringify(expiresStr)} is not ISO 8601`);
+        }
+        const window = expiresMs - nowFn().getTime();
+        if (window <= 0) {
+            throw new Error(`envelope: cannot delay an already-expired envelope (expires ${expiresStr})`);
+        }
+        if (window < ceiling) {
+            ceiling = window;
+        }
+    }
+    const rand = cfg.rand ?? defaultRandFloat;
+    const r = rand();
+    if (r < 0 || r >= 1) {
+        throw new Error("envelope: send-time random source out of range");
+    }
+    const delay = Math.floor(r * ceiling);
+    if (delay <= 0) {
+        return;
+    }
+    await sleep(delay, cfg.signal);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(signal.reason ?? new Error("envelope: send-time delay aborted"));
+            return;
+        }
+        const t = setTimeout(() => {
+            if (signal !== undefined) {
+                signal.removeEventListener("abort", onAbort);
+            }
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(signal?.reason ?? new Error("envelope: send-time delay aborted"));
+        };
+        if (signal !== undefined) {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
+}
+function defaultRandFloat() {
+    const buf = new Uint32Array(1);
+    globalThis.crypto.getRandomValues(buf);
+    return (buf[0] ?? 0) / 0x1_0000_0000;
+}
+//# sourceMappingURL=sendtime.js.map

package/dist/envelope/sendtime.js.map

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

package/dist/envelope/verify.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Envelope verification primitives per ENVELOPE.md §6 + §7.2.
+ *
+ * The compose path produces `seal.signature` (Ed25519 over canonical
+ * bytes prefixed with `SEMP-ENVELOPE:`) and `seal.session_mac`
+ * (HMAC-SHA-256 over the same canonical bytes). This module exposes
+ * the corresponding verifiers as standalone primitives that callers
+ * use in receipt-side checks before opening the envelope.
+ *
+ * @module
+ */
+import { type Envelope } from "./compose.js";
+/**
+ * Verify `env.seal.signature` against `senderDomainPub`. Returns
+ * true when the Ed25519 signature over the canonical envelope bytes
+ * (prefixed with `SEMP-ENVELOPE:`) verifies. Does NOT cross-check
+ * that the supplied public key actually belongs to the
+ * `postmark.from_domain` — that lookup is the caller's responsibility.
+ */
+export declare function verifySealSignature(env: Envelope, senderDomainPub: Uint8Array): boolean;
+/**
+ * Verify `env.seal.session_mac` against `kEnvMAC`. Returns true when
+ * the HMAC-SHA-256 of the canonical envelope bytes equals the
+ * decoded MAC value. The session-MAC key is the per-session
+ * symmetric key derived from the receiving server's federation
+ * handshake; it changes on rekey.
+ */
+export declare function verifySessionMAC(env: Envelope, kEnvMAC: Uint8Array): boolean;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/envelope/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,KAAK,QAAQ,EAAwB,MAAM,cAAc,CAAC;AAKnE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,QAAQ,EACb,eAAe,EAAE,UAAU,GAC1B,OAAO,CAgBT;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAa5E"}

package/dist/envelope/verify.js

@@ -0,0 +1,90 @@
+/**
+ * Envelope verification primitives per ENVELOPE.md §6 + §7.2.
+ *
+ * The compose path produces `seal.signature` (Ed25519 over canonical
+ * bytes prefixed with `SEMP-ENVELOPE:`) and `seal.session_mac`
+ * (HMAC-SHA-256 over the same canonical bytes). This module exposes
+ * the corresponding verifiers as standalone primitives that callers
+ * use in receipt-side checks before opening the envelope.
+ *
+ * @module
+ */
+import { computeMAC } from "../crypto/index.js";
+import { verify as ed25519Verify } from "../keys/index.js";
+import { canonicalEnvelopeFor } from "./compose.js";
+/** Domain-separation prefix for the seal signature, per §4.3. */
+const EnvelopePrefix = "SEMP-ENVELOPE:";
+/**
+ * Verify `env.seal.signature` against `senderDomainPub`. Returns
+ * true when the Ed25519 signature over the canonical envelope bytes
+ * (prefixed with `SEMP-ENVELOPE:`) verifies. Does NOT cross-check
+ * that the supplied public key actually belongs to the
+ * `postmark.from_domain` — that lookup is the caller's responsibility.
+ */
+export function verifySealSignature(env, senderDomainPub) {
+    if (env.seal?.signature === undefined || env.seal.signature === "") {
+        return false;
+    }
+    let sig;
+    try {
+        sig = base64Decode(env.seal.signature);
+    }
+    catch {
+        return false;
+    }
+    const canonical = canonicalEnvelopeFor(env);
+    const signingInput = concat(new TextEncoder().encode(EnvelopePrefix), canonical);
+    return ed25519Verify(senderDomainPub, sig, signingInput);
+}
+/**
+ * Verify `env.seal.session_mac` against `kEnvMAC`. Returns true when
+ * the HMAC-SHA-256 of the canonical envelope bytes equals the
+ * decoded MAC value. The session-MAC key is the per-session
+ * symmetric key derived from the receiving server's federation
+ * handshake; it changes on rekey.
+ */
+export function verifySessionMAC(env, kEnvMAC) {
+    if (env.seal?.session_mac === undefined || env.seal.session_mac === "") {
+        return false;
+    }
+    let want;
+    try {
+        want = base64Decode(env.seal.session_mac);
+    }
+    catch {
+        return false;
+    }
+    const canonical = canonicalEnvelopeFor(env);
+    const got = computeMAC(kEnvMAC, canonical);
+    return constantTimeEqual(want, got);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    }
+    return diff === 0;
+}
+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=verify.js.map

package/dist/envelope/verify.js.map

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

package/dist/extensions/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extensions layer per EXTENSIONS.md.
+ *
+ * @module
+ */
+export { type Entry, type Layer, type Map, type RegistryEntry, KeyError, MaxKeyLength, NamespacePrefixCore, Registry, SizeError, UnsupportedError, maxBytesFor, validate, validateKey, validateSize, } from "./limits.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,GAAG,EACR,KAAK,aAAa,EAClB,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,aAAa,CAAC"}