@sempdev/semp 0.4.3

package/dist/discovery/resolver.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Discovery resolver — well-known URI fetch + parse, plus the
+ * higher-level "resolve a server" orchestrator that produces the
+ * `serverDomainPub` a {@link "../handshake/driver".runClient} call
+ * needs.
+ *
+ * The resolver is fetch-injectable so tests can stub the HTTPS
+ * round-trips; production callers omit the `fetchImpl` option and
+ * the resolver uses Node 22+'s global `fetch`.
+ *
+ * The DNS SRV / TXT lookup leg of §5.1 is intentionally not
+ * implemented in this module — it requires `node:dns/promises` and
+ * does not cleanly tree-shake into a browser bundle. Callers that
+ * need DNS-first discovery wire it in front of {@link resolveServer}
+ * and pass an explicit `host` / well-known URL.
+ *
+ * @module
+ */
+import { type Configuration } from "./configuration.js";
+import { type DomainKeys, type KeyBlock, decodeKeyBlockPublic, verifyDomainKeyFingerprint } from "./domain_keys.js";
+/**
+ * Minimal subset of the WHATWG fetch surface this module depends on.
+ * Both Node 22+ and browsers ship `fetch` matching this shape. Tests
+ * pass a fake to drive deterministic responses.
+ */
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+/** Options shared by every fetch in this module. */
+export interface FetchOptions {
+    /** Override the fetch implementation. Defaults to `globalThis.fetch`. */
+    fetchImpl?: FetchLike;
+    /** Optional cancellation signal. */
+    signal?: AbortSignal;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 10 seconds —
+     * matches semp-go's `FetchConfiguration` default.
+     */
+    timeoutMs?: number;
+}
+/** Build the canonical well-known URL for a given hostname. */
+export declare function wellKnownUrl(host: string): string;
+/**
+ * GET the well-known configuration document and return it parsed.
+ * Throws on transport failure, non-200 status, oversized body, or
+ * structural parse failure.
+ *
+ * The URL's scheme is NOT enforced — production callers must pass an
+ * `https://` URL, but tests need to point at a local httptest-style
+ * server so this layer stays permissive.
+ */
+export declare function fetchConfiguration(url: string, opts?: FetchOptions): Promise<Configuration>;
+/**
+ * GET the domain-keys document at the URL advertised as
+ * `endpoints.domain_keys` in a server's configuration. Returns the
+ * parsed document and the cross-checked signing-key public bytes.
+ *
+ * Throws if the fingerprint cross-check fails — a peer that trusts
+ * the publication channel still MUST confirm `key_id` is the SHA-256
+ * fingerprint of `public_key`, otherwise a misconfiguration could
+ * swap in a key whose fingerprint doesn't match the one the peer
+ * cached.
+ */
+export declare function fetchDomainKeys(url: string, opts?: FetchOptions): Promise<{
+    domainKeys: DomainKeys;
+    signingPub: Uint8Array;
+    encryptionPub: Uint8Array;
+}>;
+/** Result of {@link resolveServer}. */
+export interface ResolvedServer {
+    /** The full configuration document. */
+    configuration: Configuration;
+    /** Parsed domain-keys document. */
+    domainKeys: DomainKeys;
+    /** 32-byte Ed25519 domain signing public key. */
+    signingPub: Uint8Array;
+    /** Lowercase-hex SHA-256 fingerprint of `signingPub`. */
+    signingKeyId: string;
+    /** 32-byte X25519 domain encryption public key. */
+    encryptionPub: Uint8Array;
+    /** Lowercase-hex SHA-256 fingerprint of `encryptionPub`. */
+    encryptionKeyId: string;
+}
+/** Inputs to {@link resolveServer}. */
+export interface ResolveServerOptions extends FetchOptions {
+    /**
+     * Override the configuration URL. When omitted, the resolver uses
+     * `https://<domain>/.well-known/semp/configuration` per §3 / §5.5.
+     * Callers that have already done DNS SRV discovery pass the SRV
+     * target host instead.
+     */
+    configurationUrl?: string;
+}
+/**
+ * High-level resolver: fetch the configuration, then fetch the
+ * domain-keys at `endpoints.domain_keys`, then return the structured
+ * result. The `signingPub` field is what
+ * {@link "../handshake/driver".runClient} needs as its
+ * `serverDomainPub` config.
+ */
+export declare function resolveServer(domain: string, opts?: ResolveServerOptions): Promise<ResolvedServer>;
+export { decodeKeyBlockPublic, verifyDomainKeyFingerprint };
+export type { Configuration, DomainKeys, KeyBlock };
+//# sourceMappingURL=resolver.d.ts.map

package/dist/discovery/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/discovery/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,QAAQ,EAEb,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC/E,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,aAAa,CAAC,CAWxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,UAAU,CAAA;CAAE,CAAC,CA4BxF;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,aAAa,EAAE,aAAa,CAAC;IAC7B,mCAAmC;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,iDAAiD;IACjD,UAAU,EAAE,UAAU,CAAC;IACvB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,aAAa,EAAE,UAAU,CAAC;IAC1B,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAwBzB;AAsFD,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC"}

package/dist/discovery/resolver.js

@@ -0,0 +1,176 @@
+/**
+ * Discovery resolver — well-known URI fetch + parse, plus the
+ * higher-level "resolve a server" orchestrator that produces the
+ * `serverDomainPub` a {@link "../handshake/driver".runClient} call
+ * needs.
+ *
+ * The resolver is fetch-injectable so tests can stub the HTTPS
+ * round-trips; production callers omit the `fetchImpl` option and
+ * the resolver uses Node 22+'s global `fetch`.
+ *
+ * The DNS SRV / TXT lookup leg of §5.1 is intentionally not
+ * implemented in this module — it requires `node:dns/promises` and
+ * does not cleanly tree-shake into a browser bundle. Callers that
+ * need DNS-first discovery wire it in front of {@link resolveServer}
+ * and pass an explicit `host` / well-known URL.
+ *
+ * @module
+ */
+import { WellKnownMaxBytes, WellKnownPath, parseConfiguration, } from "./configuration.js";
+import { DomainKeysMaxBytes, decodeKeyBlockPublic, parseDomainKeys, verifyDomainKeyFingerprint, } from "./domain_keys.js";
+/** Build the canonical well-known URL for a given hostname. */
+export function wellKnownUrl(host) {
+    if (host === "") {
+        throw new Error("discovery: empty host");
+    }
+    return `https://${host}${WellKnownPath}`;
+}
+/**
+ * GET the well-known configuration document and return it parsed.
+ * Throws on transport failure, non-200 status, oversized body, or
+ * structural parse failure.
+ *
+ * The URL's scheme is NOT enforced — production callers must pass an
+ * `https://` URL, but tests need to point at a local httptest-style
+ * server so this layer stays permissive.
+ */
+export async function fetchConfiguration(url, opts = {}) {
+    const body = await fetchTextBounded(url, WellKnownMaxBytes, opts);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (err) {
+        throw new Error(`discovery: configuration parse: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return parseConfiguration(parsed);
+}
+/**
+ * GET the domain-keys document at the URL advertised as
+ * `endpoints.domain_keys` in a server's configuration. Returns the
+ * parsed document and the cross-checked signing-key public bytes.
+ *
+ * Throws if the fingerprint cross-check fails — a peer that trusts
+ * the publication channel still MUST confirm `key_id` is the SHA-256
+ * fingerprint of `public_key`, otherwise a misconfiguration could
+ * swap in a key whose fingerprint doesn't match the one the peer
+ * cached.
+ */
+export async function fetchDomainKeys(url, opts = {}) {
+    const body = await fetchTextBounded(url, DomainKeysMaxBytes, opts);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (err) {
+        throw new Error(`discovery: domain_keys parse: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const domainKeys = parseDomainKeys(parsed);
+    if (!verifyDomainKeyFingerprint(domainKeys.signing_key)) {
+        throw new Error("discovery: domain_keys.signing_key.key_id does not match SHA-256(public_key)");
+    }
+    if (!verifyDomainKeyFingerprint(domainKeys.encryption_key)) {
+        throw new Error("discovery: domain_keys.encryption_key.key_id does not match SHA-256(public_key)");
+    }
+    return {
+        domainKeys,
+        signingPub: decodeKeyBlockPublic(domainKeys.signing_key),
+        encryptionPub: decodeKeyBlockPublic(domainKeys.encryption_key),
+    };
+}
+/**
+ * High-level resolver: fetch the configuration, then fetch the
+ * domain-keys at `endpoints.domain_keys`, then return the structured
+ * result. The `signingPub` field is what
+ * {@link "../handshake/driver".runClient} needs as its
+ * `serverDomainPub` config.
+ */
+export async function resolveServer(domain, opts = {}) {
+    if (domain === "") {
+        throw new Error("discovery: empty domain");
+    }
+    const configUrl = opts.configurationUrl ?? wellKnownUrl(domain);
+    const configuration = await fetchConfiguration(configUrl, opts);
+    const domainKeysUrl = configuration.endpoints.domain_keys;
+    if (typeof domainKeysUrl !== "string" || domainKeysUrl === "") {
+        throw new Error("discovery: configuration missing endpoints.domain_keys");
+    }
+    const { domainKeys, signingPub, encryptionPub } = await fetchDomainKeys(domainKeysUrl, opts);
+    return {
+        configuration,
+        domainKeys,
+        signingPub,
+        signingKeyId: domainKeys.signing_key.key_id,
+        encryptionPub,
+        encryptionKeyId: domainKeys.encryption_key.key_id,
+    };
+}
+// ---------------------------------------------------------------------------
+// HTTP plumbing
+async function fetchTextBounded(url, maxBytes, opts) {
+    if (url === "") {
+        throw new Error("discovery: empty URL");
+    }
+    const fetchImpl = opts.fetchImpl ?? defaultFetch();
+    // Compose a timeout-aware abort signal. The runtime supports
+    // AbortSignal.timeout when present; otherwise we wire it manually.
+    const externalSignal = opts.signal;
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+    const externalListener = () => timeoutController.abort();
+    if (externalSignal !== undefined) {
+        if (externalSignal.aborted) {
+            timeoutController.abort();
+        }
+        else {
+            externalSignal.addEventListener("abort", externalListener, { once: true });
+        }
+    }
+    let resp;
+    try {
+        resp = await fetchImpl(url, {
+            method: "GET",
+            headers: { Accept: "application/json" },
+            signal: timeoutController.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        if (externalSignal !== undefined) {
+            externalSignal.removeEventListener("abort", externalListener);
+        }
+    }
+    if (!resp.ok) {
+        throw new Error(`discovery: GET ${url} returned ${resp.status}`);
+    }
+    // Permissive content-type check — some servers return
+    // application/octet-stream for .json paths. We require JSON in the
+    // body parse, not in the header.
+    const ct = resp.headers.get("content-type") ?? "";
+    if (ct !== "" &&
+        !ct.toLowerCase().includes("json") &&
+        !ct.toLowerCase().includes("octet-stream")) {
+        throw new Error(`discovery: GET ${url}: unexpected content-type ${ct}`);
+    }
+    const body = await resp.text();
+    // Use UTF-8 byte length; JS strings are UTF-16 internally but the
+    // wire-side cap is in bytes. Buffer.byteLength is constant-time.
+    const byteLen = typeof Buffer !== "undefined"
+        ? Buffer.byteLength(body, "utf8")
+        : new TextEncoder().encode(body).length;
+    if (byteLen > maxBytes) {
+        throw new Error(`discovery: GET ${url}: body exceeds ${maxBytes} bytes (got ${byteLen})`);
+    }
+    return body;
+}
+function defaultFetch() {
+    const f = globalThis.fetch;
+    if (f === undefined) {
+        throw new Error("discovery: globalThis.fetch is undefined. Pass a fetchImpl option, or run on Node 22+ / a browser.");
+    }
+    return f;
+}
+// Re-export helpers for callers that prefer the lower-level pieces.
+export { decodeKeyBlockPublic, verifyDomainKeyFingerprint };
+//# sourceMappingURL=resolver.js.map

package/dist/discovery/resolver.js.map

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

package/dist/discovery/txt.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DNS TXT capability-record parsing per DISCOVERY.md §8.1.
+ *
+ * The TXT record advertises a domain's SEMP capabilities under
+ * semicolon-separated `key=value` pairs:
+ *
+ * ```
+ * v=semp1;pq=ready;c=ws,h2,quic;f=groups,threads,reactions
+ * ```
+ *
+ * Known keys:
+ *   - `v`  string  protocol version
+ *   - `pq` string  PQ readiness signal
+ *   - `c`  list    comma-separated transport identifiers
+ *   - `f`  list    comma-separated optional features
+ *
+ * Unknown keys MUST be ignored, not rejected — DNS TXT records are
+ * a public surface and an upgrading peer might add new keys before
+ * a downgrading peer learns about them.
+ *
+ * @module
+ */
+/** Parsed shape of a `_semp.<domain>` TXT record. */
+export interface TXTCapabilities {
+    v?: string;
+    pq?: string;
+    c?: string[];
+    f?: string[];
+    /** Keys present in the record but not recognized by this parser. */
+    _ignored_unknown: string[];
+}
+/**
+ * Parse a TXT capability record. Unknown keys are collected into
+ * `_ignored_unknown` rather than rejected. Empty segments and
+ * malformed `k=v` pairs are silently dropped (DISCOVERY.md §8.1
+ * treats DNS TXT as best-effort).
+ */
+export declare function parseTXTCapabilities(record: string): TXTCapabilities;
+//# sourceMappingURL=txt.d.ts.map

package/dist/discovery/txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txt.d.ts","sourceRoot":"","sources":["../../src/discovery/txt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IACb,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAmCpE"}

package/dist/discovery/txt.js

@@ -0,0 +1,71 @@
+/**
+ * DNS TXT capability-record parsing per DISCOVERY.md §8.1.
+ *
+ * The TXT record advertises a domain's SEMP capabilities under
+ * semicolon-separated `key=value` pairs:
+ *
+ * ```
+ * v=semp1;pq=ready;c=ws,h2,quic;f=groups,threads,reactions
+ * ```
+ *
+ * Known keys:
+ *   - `v`  string  protocol version
+ *   - `pq` string  PQ readiness signal
+ *   - `c`  list    comma-separated transport identifiers
+ *   - `f`  list    comma-separated optional features
+ *
+ * Unknown keys MUST be ignored, not rejected — DNS TXT records are
+ * a public surface and an upgrading peer might add new keys before
+ * a downgrading peer learns about them.
+ *
+ * @module
+ */
+/**
+ * Parse a TXT capability record. Unknown keys are collected into
+ * `_ignored_unknown` rather than rejected. Empty segments and
+ * malformed `k=v` pairs are silently dropped (DISCOVERY.md §8.1
+ * treats DNS TXT as best-effort).
+ */
+export function parseTXTCapabilities(record) {
+    const out = { _ignored_unknown: [] };
+    if (record.length === 0) {
+        return out;
+    }
+    for (const segment of record.split(";")) {
+        const trimmed = segment.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        const eq = trimmed.indexOf("=");
+        if (eq < 1) {
+            continue;
+        }
+        const key = trimmed.slice(0, eq);
+        const value = trimmed.slice(eq + 1);
+        switch (key) {
+            case "v":
+                out.v = value;
+                break;
+            case "pq":
+                out.pq = value;
+                break;
+            case "c":
+                out.c = splitCSV(value);
+                break;
+            case "f":
+                out.f = splitCSV(value);
+                break;
+            default:
+                out._ignored_unknown.push(key);
+                break;
+        }
+    }
+    return out;
+}
+function splitCSV(s) {
+    if (s.length === 0) {
+        return [];
+    }
+    return s.split(",").map((x) => x.trim()).filter((x) => x.length > 0);
+}
+//# sourceMappingURL=txt.js.map

package/dist/discovery/txt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"txt.js","sourceRoot":"","sources":["../../src/discovery/txt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,GAAG,GAAoB,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,SAAS;QACX,CAAC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACpC,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,GAAG;gBACN,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;gBACd,MAAM;YACR,KAAK,IAAI;gBACP,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC;gBACf,MAAM;YACR,KAAK,GAAG;gBACN,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;gBACxB,MAAM;YACR,KAAK,GAAG;gBACN,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;gBACxB,MAAM;YACR;gBACE,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC/B,MAAM;QACV,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS;IACzB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC"}

package/dist/enclosure/forwarding.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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
+ */
+/** A keyref for a sender identity (`{algorithm, key_id, value}` style). */
+interface IdentitySigBlock {
+    algorithm: "ed25519";
+    key_id: string;
+    value: string;
+}
+/** Inner sender's enclosure plaintext (the original message body). */
+export interface InnerEnclosurePlaintext {
+    subject: string;
+    content_type: string;
+    body: Record<string, string>;
+    attachments?: unknown[];
+    extensions?: Record<string, unknown>;
+    /** Set to null for an inner (un-forwarded) enclosure. */
+    forwarded_from?: null;
+}
+/** Outer enclosure plaintext (forwarder's own added content). */
+export interface OuterEnclosurePlaintext {
+    subject: string;
+    content_type: string;
+    body: Record<string, string>;
+    attachments?: unknown[];
+    extensions?: Record<string, unknown>;
+}
+/** Reference to the original envelope's seal + postmark. */
+export interface OriginalEnvelopeRef {
+    /** seal.algorithm + seal.key_id of the original envelope. */
+    original_seal: {
+        algorithm: string;
+        key_id: string;
+    };
+    /** Pinned postmark fields from the original envelope. */
+    original_postmark: {
+        id: string;
+        from_domain: string;
+        to_domain: string;
+        expires: string;
+        session_id: string;
+    };
+    /** Original sender address (`alice@a.example`). */
+    original_sender_address: string;
+}
+/** Inputs to {@link composeForwarded}. */
+export interface ComposeForwardedInput {
+    /** Inner sender's 32-byte Ed25519 secret seed. */
+    innerSenderSeed: Uint8Array;
+    /** Inner sender's identity key_id. */
+    innerSenderKeyId: string;
+    /** Inner enclosure plaintext (no sender_signature yet). */
+    innerEnclosurePlaintext: InnerEnclosurePlaintext;
+    /** Forwarder's 32-byte Ed25519 secret seed (used twice: for the
+     * forwarder_attestation AND for the outer sender_signature). */
+    forwarderSeed: Uint8Array;
+    /** Forwarder's identity key_id. */
+    forwarderKeyId: string;
+    /** Outer enclosure plaintext (no sender_signature yet). */
+    outerEnclosurePlaintext: OuterEnclosurePlaintext;
+    /** Pinned reference to the original envelope. */
+    originalEnvelope: OriginalEnvelopeRef;
+    /** ISO 8601 timestamp when the forwarder received the original. */
+    receivedAt: string;
+}
+/** Fully-signed outer enclosure, ready to wrap as an envelope payload. */
+export interface SignedForwardedEnclosure {
+    subject: string;
+    content_type: string;
+    body: Record<string, string>;
+    attachments: unknown[];
+    forwarded_from: {
+        original_enclosure_plaintext: InnerEnclosurePlaintext & {
+            sender_signature: IdentitySigBlock;
+        };
+        original_seal: OriginalEnvelopeRef["original_seal"];
+        original_postmark: OriginalEnvelopeRef["original_postmark"];
+        original_sender_address: string;
+        received_at: string;
+        forwarder_attestation: IdentitySigBlock;
+    };
+    extensions: Record<string, unknown>;
+    sender_signature: IdentitySigBlock;
+}
+/**
+ * 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 declare function composeForwarded(input: ComposeForwardedInput): SignedForwardedEnclosure;
+export {};
+//# sourceMappingURL=forwarding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forwarding.d.ts","sourceRoot":"","sources":["../../src/enclosure/forwarding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,2EAA2E;AAC3E,UAAU,gBAAgB;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,yDAAyD;IACzD,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,aAAa,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,yDAAyD;IACzD,iBAAiB,EAAE;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,mDAAmD;IACnD,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,eAAe,EAAE,UAAU,CAAC;IAC5B,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,uBAAuB,EAAE,uBAAuB,CAAC;IAEjD;oEACgE;IAChE,aAAa,EAAE,UAAU,CAAC;IAC1B,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,uBAAuB,EAAE,uBAAuB,CAAC;IAEjD,iDAAiD;IACjD,gBAAgB,EAAE,mBAAmB,CAAC;IACtC,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,EAAE,OAAO,EAAE,CAAC;IACvB,cAAc,EAAE;QACd,4BAA4B,EAAE,uBAAuB,GAAG;YACtD,gBAAgB,EAAE,gBAAgB,CAAC;SACpC,CAAC;QACF,aAAa,EAAE,mBAAmB,CAAC,eAAe,CAAC,CAAC;QACpD,iBAAiB,EAAE,mBAAmB,CAAC,mBAAmB,CAAC,CAAC;QAC5D,uBAAuB,EAAE,MAAM,CAAC;QAChC,WAAW,EAAE,MAAM,CAAC;QACpB,qBAAqB,EAAE,gBAAgB,CAAC;KACzC,CAAC;IACF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,wBAAwB,CAmFvF"}