@sempdev/semp 0.4.3

package/dist/delivery/disposition.js

@@ -0,0 +1,105 @@
+/**
+ * Delivery disposition data per DELIVERY.md §3.2 + CLIENT.md §4.5.7.
+ *
+ * The `delivery-disposition` sync kind is the control signal a
+ * staged device emits to tell the home server whether a held
+ * envelope should advance to the next stage or be suppressed.
+ *
+ * @module
+ */
+/** The literal `kind` string identifying a delivery-disposition sync marker. */
+export const DispositionKind = "delivery-disposition";
+/** Recommended reason tags per CLIENT.md §4.5.7. Operators MAY define more. */
+export const DispositionReasonSpam = "spam";
+export const DispositionReasonAccepted = "accepted";
+export const DispositionReasonPolicy = "policy";
+export const DispositionReasonOther = "other";
+/**
+ * Validate `d` is structurally well-formed per CLIENT.md §4.5.7.
+ * Does NOT verify authentication; the home server verifies §3.2.5
+ * (session belongs to `device_id`) at receipt.
+ */
+export function validateDisposition(d) {
+    if (d === undefined || d === null) {
+        throw new Error("delivery: nil disposition");
+    }
+    if (d.kind !== DispositionKind) {
+        throw new Error(`delivery: disposition kind ${JSON.stringify(d.kind)}, want ${JSON.stringify(DispositionKind)}`);
+    }
+    if (d.source_envelope_id === "") {
+        throw new Error("delivery: disposition missing source_envelope_id");
+    }
+    if (d.device_id === "") {
+        throw new Error("delivery: disposition missing device_id");
+    }
+    if (d.disposition === undefined || d.disposition === "") {
+        throw new Error("delivery: disposition missing decision");
+    }
+    if (d.disposition !== "advance" && d.disposition !== "suppress") {
+        throw new Error(`delivery: disposition decision ${JSON.stringify(d.disposition)} is not a valid value`);
+    }
+}
+/**
+ * Apply the §3.2.3 conservative aggregation rule across the
+ * dispositions collected at one stage:
+ *
+ *   - If any disposition is `suppress`, return `"suppress"`.
+ *   - Otherwise return `"advance"` (covers "any advance" and "no
+ *     dispositions at all" via §3.2.4 fail-open on timeout).
+ *
+ * Does NOT itself enforce the §3.2.5 authentication rules; the
+ * caller filters out late or off-stage dispositions before
+ * aggregating.
+ */
+export function aggregateDispositions(ds) {
+    for (const d of ds) {
+        if (d.disposition === "suppress") {
+            return "suppress";
+        }
+    }
+    return "advance";
+}
+/**
+ * Recommended stage timeout per DELIVERY.md §3.2.2. Operators MAY
+ * configure longer windows.
+ */
+export const DefaultStageTimeoutMs = 30_000;
+/**
+ * Whether the wait at the current stage MUST terminate per §3.2.2.
+ * Either every device at the stage has emitted a disposition, or
+ * the deadline has passed.
+ *
+ * Does NOT return the outcome; the caller follows up with
+ * {@link aggregateDispositions} to compute that.
+ *
+ * @param stage - the current stage record
+ * @param now - current wall-clock
+ * @param deadline - ISO 8601 UTC string; empty means "no deadline"
+ */
+export function isStageComplete(stage, now, deadline) {
+    if (stage === undefined || stage === null) {
+        return true;
+    }
+    if (stage.pending_device_ids.length === 0) {
+        return true;
+    }
+    if (deadline !== "") {
+        const ms = Date.parse(deadline);
+        if (!Number.isNaN(ms) && now.getTime() >= ms) {
+            return true;
+        }
+    }
+    // All pending devices have emitted? Build a set of devices
+    // already represented in `dispositions` and check.
+    const seen = new Set();
+    for (const d of stage.dispositions) {
+        seen.add(d.device_id);
+    }
+    for (const id of stage.pending_device_ids) {
+        if (!seen.has(id)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=disposition.js.map

package/dist/delivery/disposition.js.map

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

package/dist/delivery/fetch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SEMP_FETCH wire shapes — the demo-only client → home-server inbox
+ * pull protocol per CLIENT.md §3.
+ *
+ * HANDSHAKE.md §4.6 explicitly leaves the client wakeup mechanism
+ * outside the scope of the spec: "How a server notifies a client
+ * that incoming messages are waiting is outside the scope of this
+ * specification. Implementations MAY use persistent WebSocket
+ * connections, long polling, or platform notification services such
+ * as APNs or FCM."
+ *
+ * `SEMP_FETCH` is the simplest possible such mechanism: the client,
+ * after completing the handshake, sends a single `SEMP_FETCH`
+ * request and the server responds with the contents of the client's
+ * inbox. It is fit for demo and test purposes only; a real
+ * deployment would use a long-lived notification stream or platform
+ * push.
+ *
+ * @module
+ */
+/** Wire-level type discriminator. */
+export declare const FetchType = "SEMP_FETCH";
+/** Schema version. */
+export declare const FetchVersion = "1.0.0";
+/** Discriminator for which fetch message variant this is. */
+export type FetchStep = "request" | "response";
+/** Sent by the client to pull every waiting envelope from the inbox. */
+export interface FetchRequest {
+    type: typeof FetchType;
+    step: "request";
+    version: string;
+}
+/** Construct a {@link FetchRequest} with the protocol version pre-populated. */
+export declare function newFetchRequest(): FetchRequest;
+/**
+ * Server's response carrying the envelopes being delivered. Each
+ * element of `envelopes` is the base64-encoded canonical JSON of a
+ * single SEMP envelope (the same bytes the sender produced; the
+ * recipient runs `decodeEnvelope` and `openBriefAny` /
+ * `openEnclosureAny` on each).
+ *
+ * `drained` reports whether the server returned every envelope it
+ * had queued for the recipient. The demo server always sets this to
+ * `true` because the inbox is unbounded; production implementations
+ * might paginate and set `drained === false`.
+ */
+export interface FetchResponse {
+    type: typeof FetchType;
+    step: "response";
+    version: string;
+    /** Base64-encoded envelope payloads. */
+    envelopes: string[];
+    drained: boolean;
+    /** ISO 8601 UTC. */
+    timestamp: string;
+}
+/** Construct a fully-populated {@link FetchResponse}. */
+export declare function newFetchResponse(envelopesB64: string[], nowFn?: () => Date): FetchResponse;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/delivery/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/delivery/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qCAAqC;AACrC,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC,sBAAsB;AACtB,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE/C,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,SAAS,CAAC;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gFAAgF;AAChF,wBAAgB,eAAe,IAAI,YAAY,CAM9C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,SAAS,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EAAE,EACtB,KAAK,GAAE,MAAM,IAAuB,GACnC,aAAa,CASf"}

package/dist/delivery/fetch.js

@@ -0,0 +1,47 @@
+/**
+ * SEMP_FETCH wire shapes — the demo-only client → home-server inbox
+ * pull protocol per CLIENT.md §3.
+ *
+ * HANDSHAKE.md §4.6 explicitly leaves the client wakeup mechanism
+ * outside the scope of the spec: "How a server notifies a client
+ * that incoming messages are waiting is outside the scope of this
+ * specification. Implementations MAY use persistent WebSocket
+ * connections, long polling, or platform notification services such
+ * as APNs or FCM."
+ *
+ * `SEMP_FETCH` is the simplest possible such mechanism: the client,
+ * after completing the handshake, sends a single `SEMP_FETCH`
+ * request and the server responds with the contents of the client's
+ * inbox. It is fit for demo and test purposes only; a real
+ * deployment would use a long-lived notification stream or platform
+ * push.
+ *
+ * @module
+ */
+/** Wire-level type discriminator. */
+export const FetchType = "SEMP_FETCH";
+/** Schema version. */
+export const FetchVersion = "1.0.0";
+/** Construct a {@link FetchRequest} with the protocol version pre-populated. */
+export function newFetchRequest() {
+    return {
+        type: FetchType,
+        step: "request",
+        version: FetchVersion,
+    };
+}
+/** Construct a fully-populated {@link FetchResponse}. */
+export function newFetchResponse(envelopesB64, nowFn = () => new Date()) {
+    return {
+        type: FetchType,
+        step: "response",
+        version: FetchVersion,
+        envelopes: envelopesB64,
+        drained: true,
+        timestamp: isoSecond(nowFn()),
+    };
+}
+function isoSecond(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+//# sourceMappingURL=fetch.js.map

package/dist/delivery/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/delivery/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qCAAqC;AACrC,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;AAEtC,sBAAsB;AACtB,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAYpC,gFAAgF;AAChF,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,YAAY;KACtB,CAAC;AACJ,CAAC;AAyBD,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAC9B,YAAsB,EACtB,QAAoB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAEpC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,YAAY;QACrB,SAAS,EAAE,YAAY;QACvB,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,CAAO;IACxB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACnD,CAAC"}

package/dist/delivery/forwarder.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Federation forwarder per DELIVERY.md §5 and HANDSHAKE.md §5.
+ *
+ * Establishes and caches federation sessions to remote peers and
+ * forwards envelopes across them. Each `(localDomain, peerDomain)`
+ * pair gets at most one live session at a time; the forwarder
+ * re-runs the federation handshake if the cached session has
+ * expired or been torn down.
+ *
+ * On forward, the forwarder:
+ *
+ *   1. Updates `postmark.session_id` to reference the federation
+ *      session id (so the peer's receive pipeline matches).
+ *   2. Re-signs the envelope with the local domain key and
+ *      recomputes `seal.session_mac` under the federation
+ *      session's `K_env_mac`.
+ *   3. Sends the encoded envelope over the federation transport.
+ *   4. Returns the peer's parsed {@link SubmissionResponse}.
+ *
+ * The original sender's domain proof of provenance does NOT need
+ * to be preserved separately — in the SEMP architecture the
+ * sender's home server and the federation initiator are the SAME
+ * server, so re-signing with the local domain key is functionally
+ * identical to "the sender's domain signed this envelope".
+ *
+ * @module
+ */
+import { type Envelope } from "../envelope/index.js";
+import { type Capabilities, type FederationPolicy } from "../handshake/index.js";
+import type { Transport } from "../transport/index.js";
+import type { SubmissionResponse } from "./submission.js";
+/** Per-peer routing information. */
+export interface PeerConfig {
+    /** Peer's domain (e.g. `"b.example"`). */
+    domain: string;
+    /**
+     * Federation endpoint URL (e.g. `"ws://127.0.0.1:18082/v1/federate"`).
+     * The forwarder passes this verbatim to {@link Dialer}.
+     */
+    endpoint: string;
+    /**
+     * Peer's long-term Ed25519 signing public key. Used by the
+     * federation Initiator to verify the peer's response / accepted
+     * messages.
+     */
+    domainSigningPub: Uint8Array;
+}
+/** Domain → {@link PeerConfig} map. */
+export declare class PeerRegistry {
+    private readonly peers;
+    put(cfg: PeerConfig): void;
+    lookup(domain: string): PeerConfig | null;
+}
+/** Opens a transport to a peer's federation endpoint. */
+export type Dialer = (endpoint: string) => Promise<Transport>;
+/** Inputs to {@link Forwarder}. */
+export interface ForwarderConfig {
+    /** Local server's domain. */
+    localDomain: string;
+    /** Stable id of the local server instance. */
+    localServerID: string;
+    /** Local 32-byte Ed25519 secret seed. */
+    localDomainSeed: Uint8Array;
+    /** Static peer registry. */
+    peers: PeerRegistry;
+    /** Transport dialer. */
+    dial: Dialer;
+    /**
+     * Capabilities advertised on outbound federation handshakes.
+     * Defaults to `{ encryption_algorithms: ["x25519-chacha20-poly1305"], extensions: [] }`.
+     */
+    capabilities?: Capabilities;
+    /** Policy hook. Defaults to `acceptAllPolicies`. */
+    policyAcceptor?: (policy: FederationPolicy) => string | null;
+}
+/**
+ * Federation forwarder.
+ *
+ * `forward()` is concurrency-safe: per-peer wire access is
+ * serialized by a software lock so concurrent calls don't
+ * interleave on the same stream. Use {@link Forwarder.close} on
+ * shutdown to tear down every cached session.
+ */
+export declare class Forwarder {
+    private readonly cfg;
+    private readonly sessions;
+    private readonly connecting;
+    constructor(cfg: ForwarderConfig);
+    /**
+     * Re-bind `seal.session_mac` under the federation session's
+     * `K_env_mac` and ship `env` across the cached session for
+     * `peerDomain`. Returns the peer's parsed submission response.
+     *
+     * Opens a federation session lazily on first call per peer.
+     */
+    forward(peerDomain: string, env: Envelope): Promise<SubmissionResponse>;
+    /** Tear down every cached session. Call on shutdown. */
+    close(): Promise<void>;
+    /** Diagnostic: peer domains with a live cached session. */
+    cachedPeers(): string[];
+    private getSession;
+    private openSession;
+    private forwardOnSession;
+    private dropSession;
+}
+//# sourceMappingURL=forwarder.d.ts.map

package/dist/delivery/forwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder.d.ts","sourceRoot":"","sources":["../../src/delivery/forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,EACL,KAAK,QAAQ,EAGd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,gBAAgB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK1D,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,EAAE,UAAU,CAAC;CAC9B;AAED,uCAAuC;AACvC,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAO1B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;CAG1C;AAED,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;AAE9D,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,eAAe,EAAE,UAAU,CAAC;IAC5B,4BAA4B;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,oDAAoD;IACpD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9D;AASD;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6C;gBAE5D,GAAG,EAAE,eAAe;IAahC;;;;;;OAMG;IACG,OAAO,CACX,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,kBAAkB,CAAC;IAgB9B,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,2DAA2D;IAC3D,WAAW,IAAI,MAAM,EAAE;YAMT,UAAU;YAkBV,WAAW;YAyDX,gBAAgB;IAqD9B,OAAO,CAAC,WAAW;CAUpB"}

package/dist/delivery/forwarder.js

@@ -0,0 +1,251 @@
+/**
+ * Federation forwarder per DELIVERY.md §5 and HANDSHAKE.md §5.
+ *
+ * Establishes and caches federation sessions to remote peers and
+ * forwards envelopes across them. Each `(localDomain, peerDomain)`
+ * pair gets at most one live session at a time; the forwarder
+ * re-runs the federation handshake if the cached session has
+ * expired or been torn down.
+ *
+ * On forward, the forwarder:
+ *
+ *   1. Updates `postmark.session_id` to reference the federation
+ *      session id (so the peer's receive pipeline matches).
+ *   2. Re-signs the envelope with the local domain key and
+ *      recomputes `seal.session_mac` under the federation
+ *      session's `K_env_mac`.
+ *   3. Sends the encoded envelope over the federation transport.
+ *   4. Returns the peer's parsed {@link SubmissionResponse}.
+ *
+ * The original sender's domain proof of provenance does NOT need
+ * to be preserved separately — in the SEMP architecture the
+ * sender's home server and the federation initiator are the SAME
+ * server, so re-signing with the local domain key is functionally
+ * identical to "the sender's domain signed this envelope".
+ *
+ * @module
+ */
+import { marshal as canonicalMarshal } from "../canonical/index.js";
+import { computeMAC } from "../crypto/index.js";
+import { canonicalEnvelopeFor, encodeEnvelope, } from "../envelope/index.js";
+import { sign as ed25519Sign } from "../keys/index.js";
+import { FederationInitiator, } from "../handshake/index.js";
+/** Domain-separation prefix for the seal signature, per §4.3. */
+const EnvelopePrefix = "SEMP-ENVELOPE:";
+/** Domain → {@link PeerConfig} map. */
+export class PeerRegistry {
+    peers = new Map();
+    put(cfg) {
+        if (cfg.domain === "") {
+            throw new Error("delivery: PeerConfig missing domain");
+        }
+        this.peers.set(cfg.domain, { ...cfg });
+    }
+    lookup(domain) {
+        return this.peers.get(domain) ?? null;
+    }
+}
+/**
+ * Federation forwarder.
+ *
+ * `forward()` is concurrency-safe: per-peer wire access is
+ * serialized by a software lock so concurrent calls don't
+ * interleave on the same stream. Use {@link Forwarder.close} on
+ * shutdown to tear down every cached session.
+ */
+export class Forwarder {
+    cfg;
+    sessions = new Map();
+    connecting = new Map();
+    constructor(cfg) {
+        if (cfg.localDomain === "") {
+            throw new Error("delivery: forwarder empty localDomain");
+        }
+        if (cfg.localServerID === "") {
+            throw new Error("delivery: forwarder empty localServerID");
+        }
+        if (cfg.localDomainSeed.length === 0) {
+            throw new Error("delivery: forwarder empty localDomainSeed");
+        }
+        this.cfg = cfg;
+    }
+    /**
+     * Re-bind `seal.session_mac` under the federation session's
+     * `K_env_mac` and ship `env` across the cached session for
+     * `peerDomain`. Returns the peer's parsed submission response.
+     *
+     * Opens a federation session lazily on first call per peer.
+     */
+    async forward(peerDomain, env) {
+        const cfg = this.cfg.peers.lookup(peerDomain);
+        if (cfg === null) {
+            throw new Error(`delivery: forwarder: unknown peer ${peerDomain}`);
+        }
+        const fs = await this.getSession(cfg);
+        try {
+            return await this.forwardOnSession(fs, env);
+        }
+        catch (err) {
+            // Drop the session on transport-layer failure; next call
+            // re-handshakes.
+            this.dropSession(peerDomain);
+            throw err;
+        }
+    }
+    /** Tear down every cached session. Call on shutdown. */
+    async close() {
+        const sessions = Array.from(this.sessions.values());
+        this.sessions.clear();
+        for (const fs of sessions) {
+            try {
+                await fs.transport.close();
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    /** Diagnostic: peer domains with a live cached session. */
+    cachedPeers() {
+        return Array.from(this.sessions.keys()).sort();
+    }
+    // ---------------------------------------------------------------------------
+    async getSession(cfg) {
+        const cached = this.sessions.get(cfg.domain);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Coalesce concurrent connects so we don't open two sessions to
+        // the same peer in parallel.
+        const inflight = this.connecting.get(cfg.domain);
+        if (inflight !== undefined) {
+            return inflight;
+        }
+        const p = this.openSession(cfg).finally(() => {
+            this.connecting.delete(cfg.domain);
+        });
+        this.connecting.set(cfg.domain, p);
+        return p;
+    }
+    async openSession(cfg) {
+        const transport = await this.cfg.dial(cfg.endpoint);
+        const initiator = new FederationInitiator({
+            suite: "x25519-chacha20-poly1305",
+            capabilities: this.cfg.capabilities ?? {
+                encryption_algorithms: ["x25519-chacha20-poly1305"],
+                extensions: [],
+            },
+            localDomain: this.cfg.localDomain,
+            localServerID: this.cfg.localServerID,
+            localDomainSeed: this.cfg.localDomainSeed,
+            peerDomainPubLookup: (d) => {
+                if (d !== cfg.domain) {
+                    throw new Error(`forwarder: peer domain pub lookup for unknown domain ${d}`);
+                }
+                return cfg.domainSigningPub;
+            },
+            peerDomain: cfg.domain,
+            domainProof: { method: "test-trust", data: this.cfg.localDomain },
+            ...(this.cfg.policyAcceptor !== undefined
+                ? { policyAcceptor: this.cfg.policyAcceptor }
+                : {}),
+        });
+        try {
+            const initBytes = initiator.init();
+            await transport.send(initBytes);
+            const respBytes = await transport.receive();
+            if (respBytes === null) {
+                throw new Error("forwarder: connection closed waiting for response");
+            }
+            const confirmBytes = initiator.onResponse(respBytes);
+            await transport.send(confirmBytes);
+            const acceptedBytes = await transport.receive();
+            if (acceptedBytes === null) {
+                throw new Error("forwarder: connection closed waiting for accepted");
+            }
+            initiator.onAccepted(acceptedBytes);
+            const session = initiator.session();
+            const fs = {
+                transport,
+                session,
+                wireMu: { locked: false },
+            };
+            this.sessions.set(cfg.domain, fs);
+            return fs;
+        }
+        catch (err) {
+            try {
+                await transport.close();
+            }
+            catch {
+                // already closed
+            }
+            throw err;
+        }
+    }
+    async forwardOnSession(fs, env) {
+        // Serialize wire access — JS run-to-completion makes this a soft
+        // latch sufficient for the single-thread model.
+        while (fs.wireMu.locked) {
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        fs.wireMu.locked = true;
+        try {
+            // Update postmark.session_id so the peer's pipeline matches.
+            env.postmark.session_id = fs.session.sessionId;
+            // Re-sign with our local domain key + re-MAC under federation
+            // K_env_mac. Both proofs cover the SAME canonical bytes (with
+            // signature + mac blanked).
+            env.seal.signature = "";
+            env.seal.session_mac = "";
+            const canonical = canonicalEnvelopeFor(env);
+            const signingInput = concat(new TextEncoder().encode(EnvelopePrefix), canonical);
+            env.seal.signature = base64Encode(ed25519Sign(this.cfg.localDomainSeed, signingInput));
+            env.seal.session_mac = base64Encode(computeMAC(fs.session.keys.envMAC, canonical));
+            const wire = encodeEnvelope(env);
+            await fs.transport.send(wire);
+            const respBytes = await fs.transport.receive();
+            if (respBytes === null) {
+                throw new Error("forwarder: connection closed waiting for federation response");
+            }
+            const parsed = JSON.parse(new TextDecoder().decode(respBytes));
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                Array.isArray(parsed)) {
+                throw new Error("forwarder: federation response is not a JSON object");
+            }
+            return parsed;
+        }
+        finally {
+            fs.wireMu.locked = false;
+        }
+    }
+    dropSession(peerDomain) {
+        const fs = this.sessions.get(peerDomain);
+        if (fs === undefined) {
+            return;
+        }
+        this.sessions.delete(peerDomain);
+        fs.transport.close().catch(() => {
+            // best-effort
+        });
+    }
+}
+void canonicalMarshal;
+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);
+}
+//# sourceMappingURL=forwarder.js.map

package/dist/delivery/forwarder.js.map

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

package/dist/delivery/inbox.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reference per-user envelope inbox — minimal in-memory FIFO.
+ *
+ * Intended for in-process tests, embedded servers, and the
+ * reference {@link "./fetch".FetchResponse} producer. NOT a
+ * production storage layer:
+ *
+ *   - No persistence: process restart loses all queued envelopes.
+ *   - No fairness controls, no per-address access control, no
+ *     retention rules.
+ *   - Concurrency boundary is single-process; multi-writer use is
+ *     safe under the JavaScript run-to-completion model but not
+ *     across worker threads.
+ *
+ * Production deployments MUST back this with a durable store,
+ * retention rules, fairness controls, and per-address access
+ * control — none of which are present here.
+ *
+ * @module
+ */
+/** Default maximum per-address queue depth. */
+export declare const DefaultMaxQueueDepth = 10000;
+/** Reference in-memory inbox keyed by canonical user@domain string. */
+export declare class Inbox {
+    private readonly queues;
+    private readonly maxDepth;
+    constructor(maxDepth?: number);
+    /**
+     * Append `payload` to the queue for `address`. If the queue is at
+     * its maximum depth, the oldest entry is dropped to make room.
+     */
+    store(address: string, payload: Uint8Array): void;
+    /**
+     * Return every queued envelope for `address` and clear the queue.
+     * Returns an empty array when the address has no waiting
+     * envelopes.
+     */
+    drain(address: string): Uint8Array[];
+    /** Number of waiting envelopes for `address`. */
+    pending(address: string): number;
+}
+//# sourceMappingURL=inbox.d.ts.map

package/dist/delivery/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/delivery/inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,uEAAuE;AACvE,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,GAAE,MAA6B;IAQnD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAejD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAMpC,iDAAiD;IACjD,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAGjC"}