@sempdev/semp 0.4.3

package/dist/delivery/pipeline.js

@@ -0,0 +1,356 @@
+/**
+ * Receive-side delivery pipeline per DELIVERY.md §2.
+ *
+ * Runs the fixed nine-step sequence every envelope passes through
+ * before a delivery decision is made:
+ *
+ *  1. Verify `seal.signature`            → `seal_invalid`
+ *  2. Check `postmark.expires`           → `envelope_expired`
+ *  3. Check `postmark.session_id`        → `no_session` / `handshake_invalid`
+ *  4. Verify `seal.session_mac`          → `session_mac_invalid`
+ *  5. Check domain / server policy       → `rejected` or `silent`
+ *  6. Decrypt `K_brief` from `seal.brief_recipients`
+ *  7. Decrypt `envelope.brief`
+ *  8. Check user policy (block list)     → `rejected` or `silent`
+ *  9. Deliver to client                  → `delivered`
+ *
+ * Each step is a private method so operators can wrap or override
+ * individual stages without rewriting orchestration. The exported
+ * {@link Pipeline.process} runs all steps in order and short-circuits
+ * on the first failure.
+ *
+ * @module
+ */
+import { aeadOpen } from "../crypto/index.js";
+import { encodeEnvelope, verifySealSignature, verifySessionMAC, } from "../envelope/index.js";
+import { unwrap as sealUnwrap } from "../seal/index.js";
+import { matchBlockList } from "./blocklist.js";
+/**
+ * Receive-side delivery pipeline. Single-process, callable across
+ * many envelopes. Concurrency is the caller's responsibility — each
+ * `process()` call is independent and stateless beyond the
+ * configured hooks.
+ */
+export class Pipeline {
+    cfg;
+    constructor(cfg) {
+        if (cfg.isLocal === undefined) {
+            throw new Error("delivery: pipeline missing isLocal classifier");
+        }
+        if (cfg.briefRecipients.length === 0) {
+            throw new Error("delivery: pipeline missing briefRecipients");
+        }
+        this.cfg = cfg;
+    }
+    /** Run the full pipeline against `env`. */
+    async process(env) {
+        const result = {
+            envelopeId: env.postmark.id,
+            results: [],
+        };
+        // Step 1.
+        if (this.cfg.skipSignatureCheck !== true) {
+            const rej1 = await this.verifySignature(env);
+            if (rej1 !== null) {
+                result.rejection = rej1;
+                this.log(`step1 reject: ${rej1.reasonCode}`);
+                return result;
+            }
+        }
+        // Step 2.
+        if (this.cfg.skipExpiryCheck !== true) {
+            const rej2 = this.checkExpiry(env);
+            if (rej2 !== null) {
+                result.rejection = rej2;
+                this.log(`step2 reject: ${rej2.reasonCode}`);
+                return result;
+            }
+        }
+        // Step 3.
+        if (this.cfg.skipSessionIDCheck !== true) {
+            const rej3 = await this.checkSessionId(env);
+            if (rej3 !== null) {
+                result.rejection = rej3;
+                this.log(`step3 reject: ${rej3.reasonCode}`);
+                return result;
+            }
+        }
+        // Step 4.
+        if (this.cfg.skipSessionMACCheck !== true) {
+            const rej4 = this.checkSessionMac(env);
+            if (rej4 !== null) {
+                result.rejection = rej4;
+                this.log(`step4 reject: ${rej4.reasonCode}`);
+                return result;
+            }
+        }
+        // Step 5.
+        const rej5 = this.checkDomainPolicy(env);
+        if (rej5 !== null) {
+            result.rejection = rej5;
+            this.log(`step5 reject: ${rej5.reasonCode}`);
+            return result;
+        }
+        // Steps 6 + 7: home-server brief-only open. We don't need
+        // K_enclosure here — only the recipient client does. Walk the
+        // configured candidates and try each against
+        // env.seal.brief_recipients.
+        let brief;
+        try {
+            brief = openBriefOnly(env, this.cfg.briefRecipients);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            result.rejection = { reasonCode: "seal_invalid", reason };
+            this.log(`step6/7 reject: ${reason}`);
+            return result;
+        }
+        if (!Array.isArray(brief.to)) {
+            result.rejection = {
+                reasonCode: "brief_invalid",
+                reason: "brief.to is missing or not an array",
+            };
+            return result;
+        }
+        result.brief = brief;
+        // Steps 8 + 9.
+        const wire = encodeEnvelope(env);
+        const recipients = [...brief.to, ...(brief.cc ?? [])];
+        for (const recipient of recipients) {
+            result.results.push(await this.deliverOne(env, brief, recipient, wire));
+        }
+        return result;
+    }
+    // --- Step implementations -----------------------------------------------
+    async verifySignature(env) {
+        if (this.cfg.domainKeys === undefined) {
+            return {
+                reasonCode: "seal_invalid",
+                reason: "pipeline missing domainKeys lookup; cannot verify seal.signature",
+            };
+        }
+        const pub = await this.cfg.domainKeys(env.postmark.from_domain);
+        if (pub === null || pub.length === 0) {
+            return {
+                reasonCode: "seal_invalid",
+                reason: `no domain key on file for ${env.postmark.from_domain}`,
+            };
+        }
+        let ok = false;
+        try {
+            ok = verifySealSignature(env, pub);
+        }
+        catch (err) {
+            return {
+                reasonCode: "seal_invalid",
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
+        if (!ok) {
+            return {
+                reasonCode: "seal_invalid",
+                reason: "seal.signature did not verify",
+            };
+        }
+        return null;
+    }
+    checkExpiry(env) {
+        if (env.postmark.expires === undefined || env.postmark.expires === "") {
+            return null;
+        }
+        const expiryMs = Date.parse(env.postmark.expires);
+        if (Number.isNaN(expiryMs)) {
+            return {
+                reasonCode: "envelope_expired",
+                reason: `postmark.expires ${env.postmark.expires} is not ISO 8601`,
+            };
+        }
+        const nowMs = (this.cfg.now ?? (() => new Date()))().getTime();
+        const tolerance = this.cfg.clockSkewMs ?? 15 * 60 * 1_000;
+        if (nowMs - expiryMs > tolerance) {
+            return {
+                reasonCode: "envelope_expired",
+                reason: `postmark.expires ${env.postmark.expires} is outside the clock-skew tolerance`,
+            };
+        }
+        return null;
+    }
+    async checkSessionId(env) {
+        if (env.postmark.session_id.trim() === "") {
+            return {
+                reasonCode: "no_session",
+                reason: "postmark.session_id is empty",
+            };
+        }
+        if (this.cfg.sessionRetired === undefined) {
+            return null;
+        }
+        let retired = false;
+        try {
+            retired = await this.cfg.sessionRetired(env.postmark.session_id);
+        }
+        catch (err) {
+            // Lookup failures fail open; log and continue.
+            this.log(`session retired lookup error for ${env.postmark.session_id}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        if (retired) {
+            return {
+                reasonCode: "handshake_invalid",
+                reason: `session_id ${env.postmark.session_id} is retired`,
+            };
+        }
+        return null;
+    }
+    checkSessionMac(env) {
+        if (this.cfg.envMAC === undefined) {
+            return {
+                reasonCode: "session_mac_invalid",
+                reason: "pipeline missing envMAC source; cannot verify seal.session_mac",
+            };
+        }
+        const mac = this.cfg.envMAC();
+        if (mac.length === 0) {
+            return {
+                reasonCode: "session_mac_invalid",
+                reason: "empty K_env_mac; cannot verify seal.session_mac",
+            };
+        }
+        let ok = false;
+        try {
+            ok = verifySessionMAC(env, mac);
+        }
+        catch (err) {
+            return {
+                reasonCode: "session_mac_invalid",
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
+        if (!ok) {
+            return {
+                reasonCode: "session_mac_invalid",
+                reason: "seal.session_mac did not verify",
+            };
+        }
+        return null;
+    }
+    checkDomainPolicy(env) {
+        if (this.cfg.domainPolicy === undefined) {
+            return null;
+        }
+        const verdict = this.cfg.domainPolicy(env.postmark.from_domain, "");
+        if (verdict.ack === "delivered") {
+            return null;
+        }
+        return {
+            reasonCode: verdict.reasonCode,
+            reason: verdict.reason ?? "domain policy rejected envelope",
+            silent: verdict.ack === "silent",
+        };
+    }
+    async deliverOne(env, brief, recipient, wire) {
+        if (!this.cfg.isLocal(recipient)) {
+            return {
+                recipient,
+                status: "rejected",
+                reason_code: "recipient_not_found",
+                reason: "recipient is not local; caller forwards via federation",
+            };
+        }
+        // Step 8a: optional pre-block-list per-recipient gate.
+        if (this.cfg.recipientPolicy !== undefined) {
+            const gate = this.cfg.recipientPolicy(recipient);
+            if (gate.ack !== "delivered") {
+                return {
+                    recipient,
+                    status: gate.ack,
+                    reason_code: gate.reasonCode,
+                    ...(gate.reason !== undefined ? { reason: gate.reason } : {}),
+                };
+            }
+        }
+        // Step 8b: user block list.
+        if (this.cfg.blockList !== undefined) {
+            const sender = brief.from !== undefined
+                ? { address: brief.from, domain: brief.from.split("@")[1] ?? "" }
+                : { address: "", domain: env.postmark.from_domain };
+            const list = await this.cfg.blockList.lookup(recipient);
+            const matched = matchBlockList(list, sender);
+            if (matched !== null) {
+                return {
+                    recipient,
+                    status: matched.acknowledgment,
+                    reason_code: "blocked_recipient",
+                    ...(matched.reason !== undefined ? { reason: matched.reason } : {}),
+                };
+            }
+        }
+        // Step 9: inbox.
+        if (this.cfg.inbox !== undefined) {
+            this.cfg.inbox.store(recipient, wire);
+        }
+        return {
+            recipient,
+            status: "delivered",
+        };
+    }
+    log(line) {
+        if (this.cfg.logger !== undefined) {
+            this.cfg.logger(`pipeline ${line}`);
+        }
+    }
+}
+/**
+ * Home-server brief-only open: walk `candidates`, find the first
+ * whose `keyId` is in `env.seal.brief_recipients`, unwrap K_brief
+ * with that candidate's X25519 keypair, AEAD-open the brief blob,
+ * and return the decoded JSON. Throws if no candidate matches or
+ * decryption fails.
+ *
+ * Distinct from {@link "../envelope".openForRecipient}, which
+ * additionally requires the candidate to be an enclosure recipient.
+ * The home server only ever receives K_brief, never K_enclosure.
+ */
+function openBriefOnly(env, candidates) {
+    if (candidates.length === 0) {
+        throw new Error("envelope: openBriefOnly: empty candidate list");
+    }
+    const errors = [];
+    for (const c of candidates) {
+        const wrapped = env.seal.brief_recipients[c.keyId];
+        if (typeof wrapped !== "string") {
+            continue;
+        }
+        try {
+            const kBrief = sealUnwrap("x25519-chacha20-poly1305", c.privateKey, c.publicKey, wrapped);
+            const briefBlob = base64Decode(env.brief);
+            if (briefBlob.length < 12) {
+                throw new Error("brief blob too short");
+            }
+            const briefNonce = briefBlob.slice(0, 12);
+            const briefCT = briefBlob.slice(12);
+            const aad = new TextEncoder().encode(env.postmark.id);
+            const briefPT = aeadOpen("chacha20-poly1305", kBrief, briefNonce, briefCT, aad);
+            return JSON.parse(new TextDecoder().decode(briefPT));
+        }
+        catch (err) {
+            errors.push(`${c.keyId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (errors.length === 0) {
+        throw new Error("envelope: openBriefOnly: no candidate matches a brief recipient slot");
+    }
+    throw new Error(`envelope: openBriefOnly: every candidate failed: ${errors.join("; ")}`);
+}
+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=pipeline.js.map

package/dist/delivery/pipeline.js.map

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

package/dist/delivery/policy_state.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-user authoritative policy view per DELIVERY.md §7.2.
+ *
+ * `applyPolicyMessage` takes a verified {@link UserPolicyMessage} and
+ * either applies every operation atomically (advancing
+ * `policy_version`) or rejects the whole message without mutating
+ * state. Atomicity is the §7.2 guarantee: a single unrecognized kind
+ * rejects the whole message; unrelated operations in the same
+ * message MUST NOT be applied.
+ *
+ * Apply does NOT verify the signature on the message — callers MUST
+ * run {@link verifyUserPolicyMessage} before invoking
+ * {@link PolicyState.apply}.
+ *
+ * @module
+ */
+import { type UserPolicyMessage } from "./user_policy.js";
+/** §7.3 default rule kinds for v1.0.0. */
+export declare function defaultPolicyKinds(): string[];
+/** Reason codes for policy apply failures (mirror ERRORS.md §5). */
+export type PolicyApplyReasonCode = "policy_kind_unsupported" | "policy_op_invalid" | "policy_version_stale";
+/** Typed error wrapping a structured policy rejection. */
+export declare class PolicyApplyError extends Error {
+    readonly code: PolicyApplyReasonCode;
+    readonly details: {
+        kind?: string;
+        opIndex?: number;
+        submittedVersion?: number;
+        currentVersion?: number;
+        detail?: string;
+    };
+    readonly name = "PolicyApplyError";
+    constructor(code: PolicyApplyReasonCode, details?: {
+        kind?: string;
+        opIndex?: number;
+        submittedVersion?: number;
+        currentVersion?: number;
+        detail?: string;
+    });
+}
+/**
+ * Snapshot of a {@link PolicyState} at one point in time. Used for
+ * propagation to other devices on next connection per §7.2 and for
+ * persistence checkpointing.
+ */
+export interface PolicySnapshot {
+    user_id: string;
+    policy_version: number;
+    /** ISO 8601 UTC timestamp of the most recent applied message. */
+    last_timestamp: string;
+    /** Per-kind list-shaped entries, keyed by kind, then by entry_id. */
+    list_entries: Record<string, Record<string, unknown>>;
+    /** Per-kind singleton entries (e.g. semp.dev/first_contact). */
+    singletons: Record<string, unknown>;
+}
+/**
+ * Per-user policy state. Concurrency-safe within a single JS event
+ * loop (no async mutation between read-modify-write).
+ *
+ * Does NOT enforce DELIVERY.md §7.5 encrypted-at-rest storage —
+ * that is the persistence layer's responsibility.
+ */
+export declare class PolicyState {
+    private readonly userIdValue;
+    private readonly supportedKinds;
+    private policyVersionValue;
+    private lastTimestampValue;
+    private readonly listEntriesMap;
+    private readonly singletonsMap;
+    /**
+     * @param userId - the account this state belongs to
+     * @param kinds - rule kinds to register; defaults to {@link defaultPolicyKinds}
+     */
+    constructor(userId: string, kinds?: string[]);
+    /** Account this state belongs to. */
+    userId(): string;
+    /** Current policy_version per §7.2. Zero before any message has been applied. */
+    currentVersion(): number;
+    /** Timestamp of the most recently applied message; `""` before any apply. */
+    lastTimestamp(): string;
+    /** Whether `kind` is registered for this state. */
+    supportsKind(kind: string): boolean;
+    /** Registered kinds, lexically sorted. */
+    registeredKinds(): string[];
+    /**
+     * Apply `m` atomically per §7.2. On success advances
+     * `policy_version` and applies every operation. On any per-message
+     * failure throws a {@link PolicyApplyError} with structured
+     * details and leaves state unchanged.
+     *
+     * Caller MUST have run {@link verifyUserPolicyMessage} first.
+     */
+    apply(m: UserPolicyMessage): void;
+    private applyOp;
+    /** Deep copy of the entries currently held for `kind`, keyed by entry id. */
+    listEntries(kind: string): Record<string, unknown>;
+    /**
+     * Copy of the current singleton entry for `kind`, or `undefined`
+     * if none has been set.
+     */
+    singleton(kind: string): unknown;
+    /** Deep copy of all state for propagation / persistence. */
+    snapshot(): PolicySnapshot;
+}
+//# sourceMappingURL=policy_state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy_state.d.ts","sourceRoot":"","sources":["../../src/delivery/policy_state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAKvB,MAAM,kBAAkB,CAAC;AAE1B,0CAA0C;AAC1C,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED,oEAAoE;AACpE,MAAM,MAAM,qBAAqB,GAC7B,yBAAyB,GACzB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B,0DAA0D;AAC1D,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,IAAI,EAAE,qBAAqB;aAC3B,OAAO,EAAE;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IATH,SAAkB,IAAI,sBAAsB;gBAE1B,IAAI,EAAE,qBAAqB,EAC3B,OAAO,GAAE;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;CAIT;AAkBD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAE7C,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,kBAAkB,CAAM;IAEhC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2C;IAC1E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAE5D;;;OAGG;gBACS,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE;IAe5C,qCAAqC;IACrC,MAAM,IAAI,MAAM;IAIhB,iFAAiF;IACjF,cAAc,IAAI,MAAM;IAIxB,6EAA6E;IAC7E,aAAa,IAAI,MAAM;IAIvB,mDAAmD;IACnD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInC,0CAA0C;IAC1C,eAAe,IAAI,MAAM,EAAE;IAI3B;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI;IA8DjC,OAAO,CAAC,OAAO;IA8Bf,6EAA6E;IAC7E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYlD;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAOhC,4DAA4D;IAC5D,QAAQ,IAAI,cAAc;CAqB3B"}