@sempdev/semp 0.4.3

package/dist/keys/request.js

@@ -0,0 +1,130 @@
+/**
+ * SEMP_KEYS request / response per CLIENT.md §5.4 + KEY.md §4.
+ *
+ * Clients send a SEMP_KEYS request over their authenticated session
+ * to ask the home server for one or more recipient users' published
+ * keys. The home server fulfills the request from cache or by
+ * fetching from the remote domain's well-known URI / federation
+ * session and returns a SEMP_KEYS response.
+ *
+ * @module
+ */
+/** Wire-level type discriminator. */
+export const KeysRequestType = "SEMP_KEYS";
+/** Wire-level version per ENVELOPE.md §1.4. */
+export const KeysRequestVersion = "1.0.0";
+/**
+ * Construct a SEMP_KEYS request with `version` + `timestamp`
+ * pre-populated and `include_domain_keys` set to the spec default
+ * (true).
+ */
+export function newKeysRequest(id, addresses, nowFn = () => new Date()) {
+    if (id === "") {
+        throw new Error("keys: empty request id");
+    }
+    if (addresses.length === 0) {
+        throw new Error("keys: request requires at least one address");
+    }
+    return {
+        type: KeysRequestType,
+        step: "request",
+        version: KeysRequestVersion,
+        id,
+        timestamp: isoSecond(nowFn()),
+        addresses,
+        include_domain_keys: true,
+    };
+}
+/** Construct a SEMP_KEYS response echoing `requestId`. */
+export function newKeysResponse(requestId, results, nowFn = () => new Date()) {
+    if (requestId === "") {
+        throw new Error("keys: empty request id");
+    }
+    return {
+        type: KeysRequestType,
+        step: "response",
+        version: KeysRequestVersion,
+        id: requestId,
+        timestamp: isoSecond(nowFn()),
+        results,
+    };
+}
+/**
+ * Validate a SEMP_KEYS request structurally per §5.4.1. Throws on
+ * the first violation.
+ */
+export function validateKeysRequest(req) {
+    if (req.type !== KeysRequestType) {
+        throw new Error(`keys: type ${JSON.stringify(req.type)}, want ${KeysRequestType}`);
+    }
+    if (req.step !== "request") {
+        throw new Error(`keys: step ${JSON.stringify(req.step)}, want "request"`);
+    }
+    if (typeof req.version !== "string" || req.version === "") {
+        throw new Error("keys: missing version");
+    }
+    if (typeof req.id !== "string" || req.id === "") {
+        throw new Error("keys: missing id");
+    }
+    if (typeof req.timestamp !== "string" || req.timestamp === "") {
+        throw new Error("keys: missing timestamp");
+    }
+    if (Number.isNaN(Date.parse(req.timestamp))) {
+        throw new Error("keys: timestamp is not ISO 8601");
+    }
+    if (!Array.isArray(req.addresses) || req.addresses.length === 0) {
+        throw new Error("keys: addresses must be a non-empty array");
+    }
+    for (let i = 0; i < req.addresses.length; i++) {
+        if (typeof req.addresses[i] !== "string" || req.addresses[i] === "") {
+            throw new Error(`keys: addresses[${i}] missing`);
+        }
+    }
+    if (typeof req.include_domain_keys !== "boolean") {
+        throw new Error("keys: include_domain_keys must be a boolean");
+    }
+}
+/**
+ * Send a SEMP_KEYS request on the supplied stream and parse the
+ * response. The home server is expected to fulfill the request
+ * synchronously and respond on the same stream.
+ *
+ * Returns the parsed {@link KeysResponse}. Throws on transport
+ * failure, malformed JSON, response that is not a SEMP_KEYS
+ * response, or response whose `id` does not match the request.
+ */
+export async function fetchKeys(stream, req) {
+    validateKeysRequest(req);
+    await stream.send(new TextEncoder().encode(JSON.stringify(req)));
+    const respBytes = await stream.receive();
+    if (respBytes === null) {
+        throw new Error("keys: connection closed waiting for response");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(respBytes));
+    }
+    catch (err) {
+        throw new Error(`keys: response parse: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed)) {
+        throw new Error("keys: response is not a JSON object");
+    }
+    const obj = parsed;
+    if (obj.type !== KeysRequestType) {
+        throw new Error(`keys: response type ${JSON.stringify(obj.type)}, want ${KeysRequestType}`);
+    }
+    if (obj.step !== "response") {
+        throw new Error(`keys: response step ${JSON.stringify(obj.step)}, want "response"`);
+    }
+    if (obj.id !== req.id) {
+        throw new Error(`keys: response id ${JSON.stringify(obj.id)} does not match request ${JSON.stringify(req.id)}`);
+    }
+    return obj;
+}
+function isoSecond(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+//# sourceMappingURL=request.js.map

package/dist/keys/request.js.map

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

package/dist/keys/sign.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Ed25519 signature primitives for SEMP signed documents.
+ *
+ * SEMP uses Ed25519 for every signature (sender, forwarder,
+ * domain, identity, recovery, transparency-STH, etc.). Each is
+ * computed over a canonical-JSON representation prefixed with a
+ * domain-separation tag from `ENVELOPE.md` §4.3.
+ *
+ * The keypair encoding follows libsodium / @noble convention:
+ *   - secret seed: 32 bytes (the only secret material)
+ *   - public key:  32 bytes (Ed25519 point)
+ *
+ * Some legacy APIs use a 64-byte "secret key" that concatenates the
+ * seed and the public key. SEMP and this module deal exclusively
+ * with the 32-byte seed form; convert at the boundary if needed.
+ *
+ * @module
+ */
+/** Length of an Ed25519 public key (32 bytes). */
+export declare const PublicKeySize = 32;
+/** Length of an Ed25519 secret seed (32 bytes). */
+export declare const SeedSize = 32;
+/** Length of an Ed25519 signature (64 bytes). */
+export declare const SignatureSize = 64;
+/**
+ * Derive the Ed25519 public key for the given secret seed.
+ *
+ * @param seed 32-byte secret seed.
+ */
+export declare function publicKeyFromSeed(seed: Uint8Array): Uint8Array;
+/**
+ * Sign `message` with the Ed25519 secret seed. Returns a 64-byte
+ * detached signature.
+ */
+export declare function sign(seed: Uint8Array, message: Uint8Array): Uint8Array;
+/**
+ * Verify a 64-byte detached Ed25519 signature against `publicKey`
+ * over `message`. Returns true on accept, false on reject. Never
+ * throws on a malformed signature; callers see false and surface
+ * an `auth_failed` reason.
+ */
+export declare function verify(publicKey: Uint8Array, signature: Uint8Array, message: Uint8Array): boolean;
+/**
+ * Compute the SEMP key fingerprint per `KEY.md` §3 — SHA-256 of
+ * the raw 32-byte public key, lowercase-hex encoded. Used as the
+ * `key_id` field everywhere keys are referenced.
+ */
+export declare function fingerprint(publicKey: Uint8Array): string;
+//# sourceMappingURL=sign.d.ts.map

package/dist/keys/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/keys/sign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,kDAAkD;AAClD,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,mDAAmD;AACnD,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,iDAAiD;AACjD,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAG9D;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,UAAU,CAGtE;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,GAClB,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAQzD"}

package/dist/keys/sign.js

@@ -0,0 +1,80 @@
+/**
+ * Ed25519 signature primitives for SEMP signed documents.
+ *
+ * SEMP uses Ed25519 for every signature (sender, forwarder,
+ * domain, identity, recovery, transparency-STH, etc.). Each is
+ * computed over a canonical-JSON representation prefixed with a
+ * domain-separation tag from `ENVELOPE.md` §4.3.
+ *
+ * The keypair encoding follows libsodium / @noble convention:
+ *   - secret seed: 32 bytes (the only secret material)
+ *   - public key:  32 bytes (Ed25519 point)
+ *
+ * Some legacy APIs use a 64-byte "secret key" that concatenates the
+ * seed and the public key. SEMP and this module deal exclusively
+ * with the 32-byte seed form; convert at the boundary if needed.
+ *
+ * @module
+ */
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+/** Length of an Ed25519 public key (32 bytes). */
+export const PublicKeySize = 32;
+/** Length of an Ed25519 secret seed (32 bytes). */
+export const SeedSize = 32;
+/** Length of an Ed25519 signature (64 bytes). */
+export const SignatureSize = 64;
+/**
+ * Derive the Ed25519 public key for the given secret seed.
+ *
+ * @param seed 32-byte secret seed.
+ */
+export function publicKeyFromSeed(seed) {
+    expectLength("seed", seed, SeedSize);
+    return ed25519.getPublicKey(seed);
+}
+/**
+ * Sign `message` with the Ed25519 secret seed. Returns a 64-byte
+ * detached signature.
+ */
+export function sign(seed, message) {
+    expectLength("seed", seed, SeedSize);
+    return ed25519.sign(message, seed);
+}
+/**
+ * Verify a 64-byte detached Ed25519 signature against `publicKey`
+ * over `message`. Returns true on accept, false on reject. Never
+ * throws on a malformed signature; callers see false and surface
+ * an `auth_failed` reason.
+ */
+export function verify(publicKey, signature, message) {
+    if (publicKey.length !== PublicKeySize || signature.length !== SignatureSize) {
+        return false;
+    }
+    try {
+        return ed25519.verify(signature, message, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compute the SEMP key fingerprint per `KEY.md` §3 — SHA-256 of
+ * the raw 32-byte public key, lowercase-hex encoded. Used as the
+ * `key_id` field everywhere keys are referenced.
+ */
+export function fingerprint(publicKey) {
+    expectLength("publicKey", publicKey, PublicKeySize);
+    const sum = sha256(publicKey);
+    let s = "";
+    for (let i = 0; i < sum.length; i++) {
+        s += (sum[i] ?? 0).toString(16).padStart(2, "0");
+    }
+    return s;
+}
+function expectLength(name, b, want) {
+    if (b.length !== want) {
+        throw new Error(`keys: ${name} length ${b.length}, want ${want}`);
+    }
+}
+//# sourceMappingURL=sign.js.map

package/dist/keys/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../../src/keys/sign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,kDAAkD;AAClD,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,mDAAmD;AACnD,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAC3B,iDAAiD;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAgB;IAChD,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,IAAgB,EAAE,OAAmB;IACxD,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CACpB,SAAqB,EACrB,SAAqB,EACrB,OAAmB;IAEnB,IAAI,SAAS,CAAC,MAAM,KAAK,aAAa,IAAI,SAAS,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,SAAqB;IAC/C,YAAY,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;IACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,CAAa,EAAE,IAAY;IAC7D,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,WAAW,CAAC,CAAC,MAAM,UAAU,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/dist/keys/signed.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Signed-document compose helpers.
+ *
+ * Every Ed25519-signed SEMP document — closure request, configuration
+ * update, user policy, migration record, sender-signature enclosure,
+ * delivery receipt, transparency STH, recovery manifest, recovery
+ * share, handshake response/accepted/rejected — follows the same
+ * shape: build the document with the signature value blanked,
+ * canonicalize per ENVELOPE.md §4.3, prepend a domain-separation
+ * prefix, sign with Ed25519, write the signature back into the
+ * document.
+ *
+ * `signSignedDoc` runs that flow on a deep copy of the input and
+ * returns both the populated document AND the bare base64 signature.
+ *
+ * @module
+ */
+/** Inputs to a signed-document compose. */
+export interface SignSignedDocSpec {
+    /**
+     * The pre-sign document. Must contain the signature path with the
+     * value field present (any string content; will be blanked before
+     * canonicalization).
+     */
+    preSignJSON: Record<string, unknown>;
+    /** 32-byte Ed25519 secret seed. */
+    seed: Uint8Array;
+    /** Dotted path to the signature value (e.g. "signature.value"). */
+    signaturePath: string;
+    /** Domain-separation prefix from ENVELOPE.md §4.3. */
+    prefix: string;
+}
+/** Result of a signed-document compose. */
+export interface SignSignedDocResult {
+    /** Deep copy of preSignJSON with the signature value populated. */
+    signedJSON: Record<string, unknown>;
+    /** Canonical bytes that were signed (with the value blanked). */
+    canonicalBlanked: Uint8Array;
+    /** Base64-encoded Ed25519 signature. */
+    signatureB64: string;
+}
+/**
+ * Compose a signed document. Deep-clones the input, blanks the
+ * signature value field, canonicalizes, prepends the prefix,
+ * Ed25519-signs the result with `seed`, and writes the signature
+ * back into the cloned document at the same path.
+ */
+export declare function signSignedDoc(spec: SignSignedDocSpec): SignSignedDocResult;
+/** Inputs to a signed-document verify. */
+export interface VerifySignedDocSpec {
+    /** The signed document AS RECEIVED, with the signature populated. */
+    signedJSON: Record<string, unknown>;
+    /** 32-byte Ed25519 public key. */
+    publicKey: Uint8Array;
+    /** Dotted path to the signature value (e.g. "signature.value"). */
+    signaturePath: string;
+    /** Domain-separation prefix from ENVELOPE.md §4.3. */
+    prefix: string;
+}
+/** Result of a signed-document verify. */
+export interface VerifySignedDocResult {
+    /** True when the signature verifies under `publicKey`. */
+    ok: boolean;
+    /** Canonical bytes the signature was checked against. */
+    canonicalBlanked: Uint8Array;
+}
+/**
+ * Verify a single signed document. Deep-clones the input, captures
+ * the base64 signature at `signaturePath`, blanks that path,
+ * canonicalizes per ENVELOPE.md §4.3, prepends `prefix`, and
+ * Ed25519-verifies.
+ *
+ * Throws if the document is structurally malformed (path missing,
+ * signature not a string, signature not valid base64). A successful
+ * parse with a bad signature returns `{ ok: false, canonicalBlanked }`
+ * — the canonical bytes are returned so callers can cross-check
+ * pinned `intermediates.canonical_with_blanked_signature_utf8`.
+ */
+export declare function verifySignedDoc(spec: VerifySignedDocSpec): VerifySignedDocResult;
+//# sourceMappingURL=signed.d.ts.map

package/dist/keys/signed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed.d.ts","sourceRoot":"","sources":["../../src/keys/signed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,mCAAmC;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,iEAAiE;IACjE,gBAAgB,EAAE,UAAU,CAAC;IAC7B,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAS1E;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,kCAAkC;IAClC,SAAS,EAAE,UAAU,CAAC;IACtB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAC;IACZ,yDAAyD;IACzD,gBAAgB,EAAE,UAAU,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAQhF"}

package/dist/keys/signed.js

@@ -0,0 +1,138 @@
+/**
+ * Signed-document compose helpers.
+ *
+ * Every Ed25519-signed SEMP document — closure request, configuration
+ * update, user policy, migration record, sender-signature enclosure,
+ * delivery receipt, transparency STH, recovery manifest, recovery
+ * share, handshake response/accepted/rejected — follows the same
+ * shape: build the document with the signature value blanked,
+ * canonicalize per ENVELOPE.md §4.3, prepend a domain-separation
+ * prefix, sign with Ed25519, write the signature back into the
+ * document.
+ *
+ * `signSignedDoc` runs that flow on a deep copy of the input and
+ * returns both the populated document AND the bare base64 signature.
+ *
+ * @module
+ */
+import { marshal as canonicalMarshal } from "../canonical/index.js";
+import { sign, verify } from "./sign.js";
+/**
+ * Compose a signed document. Deep-clones the input, blanks the
+ * signature value field, canonicalizes, prepends the prefix,
+ * Ed25519-signs the result with `seed`, and writes the signature
+ * back into the cloned document at the same path.
+ */
+export function signSignedDoc(spec) {
+    const clone = deepCloneJSON(spec.preSignJSON);
+    setPath(clone, spec.signaturePath, "");
+    const blanked = canonicalMarshal(clone);
+    const signingInput = concat(new TextEncoder().encode(spec.prefix), blanked);
+    const sig = sign(spec.seed, signingInput);
+    const sigB64 = base64Encode(sig);
+    setPath(clone, spec.signaturePath, sigB64);
+    return { signedJSON: clone, canonicalBlanked: blanked, signatureB64: sigB64 };
+}
+/**
+ * Verify a single signed document. Deep-clones the input, captures
+ * the base64 signature at `signaturePath`, blanks that path,
+ * canonicalizes per ENVELOPE.md §4.3, prepends `prefix`, and
+ * Ed25519-verifies.
+ *
+ * Throws if the document is structurally malformed (path missing,
+ * signature not a string, signature not valid base64). A successful
+ * parse with a bad signature returns `{ ok: false, canonicalBlanked }`
+ * — the canonical bytes are returned so callers can cross-check
+ * pinned `intermediates.canonical_with_blanked_signature_utf8`.
+ */
+export function verifySignedDoc(spec) {
+    const clone = deepCloneJSON(spec.signedJSON);
+    const sigB64 = pluckAndBlankPath(clone, spec.signaturePath);
+    const sig = base64Decode(sigB64);
+    const blanked = canonicalMarshal(clone);
+    const signingInput = concat(new TextEncoder().encode(spec.prefix), blanked);
+    const ok = verify(spec.publicKey, sig, signingInput);
+    return { ok, canonicalBlanked: blanked };
+}
+/**
+ * Walk a dotted path, capture the leaf string, and replace it with
+ * "" in place. Throws if the path is malformed or the leaf is not a
+ * string. The captured string is returned (typically the base64
+ * signature value).
+ */
+function pluckAndBlankPath(m, path) {
+    const parts = path.split(".");
+    let cur = m;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (key === undefined || key === "") {
+            throw new Error(`verifySignedDoc: empty path segment in ${path}`);
+        }
+        const next = cur[key];
+        if (typeof next !== "object" || next === null || Array.isArray(next)) {
+            throw new Error(`verifySignedDoc: path ${path}: segment ${key} is not an object`);
+        }
+        cur = next;
+    }
+    const leaf = parts[parts.length - 1];
+    if (leaf === undefined || leaf === "") {
+        throw new Error(`verifySignedDoc: path ${path} is empty`);
+    }
+    const value = cur[leaf];
+    if (typeof value !== "string") {
+        throw new Error(`verifySignedDoc: path ${path}: leaf is not a string`);
+    }
+    cur[leaf] = "";
+    return value;
+}
+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;
+}
+function setPath(m, path, value) {
+    const parts = path.split(".");
+    let cur = m;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (key === undefined) {
+            throw new Error(`signSignedDoc: empty path segment in ${path}`);
+        }
+        const next = cur[key];
+        if (typeof next !== "object" || next === null || Array.isArray(next)) {
+            throw new Error(`signSignedDoc: path ${path}: segment ${key} is not an object`);
+        }
+        cur = next;
+    }
+    const leaf = parts[parts.length - 1];
+    if (leaf === undefined) {
+        throw new Error(`signSignedDoc: path ${path} is empty`);
+    }
+    cur[leaf] = value;
+}
+function deepCloneJSON(v) {
+    return JSON.parse(JSON.stringify(v));
+}
+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=signed.js.map

package/dist/keys/signed.js.map

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

package/dist/keys/store.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Persistence interfaces and reference in-memory implementation for
+ * SEMP key records per KEY.md §4 / §8 / §9.
+ *
+ * The `KeyStore` interface is the layer-1 contract: it holds public
+ * key records (domain + user) and revocation state. `PrivateKeyStore`
+ * adds access to the user's own private key material in
+ * encrypted-at-rest form per KEY.md §9.1.
+ *
+ * Server implementations and client implementations have different
+ * storage needs but expose the same interfaces so handshake,
+ * envelope, and delivery code can be written once.
+ *
+ * The reference {@link InMemoryKeyStore} is intended for tests,
+ * single-process demos, and reference-implementation builds. It is
+ * NOT a production storage layer:
+ *
+ *   - Private keys are held in memory in plaintext (no encryption at
+ *     rest, no KDF, no hardware backing). This violates KEY.md §9.1.
+ *   - There is no persistence: process restart loses everything.
+ *
+ * @module
+ */
+import type { DeviceCertificate } from "./device_certificate.js";
+import type { Revocation } from "./key_revocation.js";
+/** Key role per KEY.md §1.1. */
+export type KeyType = "domain" | "identity" | "encryption" | "device";
+/** A single signature entry on a {@link KeyStoreRecord} per KEY.md §5. */
+export interface KeyStoreSignature {
+    signer: string;
+    key_id: string;
+    /** Base64 signature bytes. */
+    value: string;
+    /** ISO 8601 UTC. */
+    timestamp: string;
+    /** Optional informational tag attached by web-of-trust signers. */
+    trust_level?: string;
+}
+/**
+ * A single key record as it appears in a SEMP_KEYS response (KEY.md
+ * §4.3, §4.4) or in a domain key publication (KEY.md §2.3).
+ */
+export interface KeyStoreRecord {
+    /** Address (for user keys); empty for domain keys. */
+    address?: string;
+    key_type: KeyType;
+    algorithm: string;
+    /** Base64 public key. */
+    public_key: string;
+    /** Lowercase-hex SHA-256 fingerprint. */
+    key_id: string;
+    /** ISO 8601 UTC. */
+    created: string;
+    /**
+     * ISO 8601 UTC after which the key SHOULD NOT be used for new
+     * operations. Past-expiry keys remain valid for decrypting
+     * historical envelopes. Empty / absent for non-expiring keys.
+     */
+    expires?: string;
+    /** Optional set of signatures attached to the record. */
+    signatures?: KeyStoreSignature[];
+    /** Non-null iff the key has been revoked per KEY.md §8. */
+    revocation?: Revocation;
+}
+/**
+ * Persistence interface for SEMP key material. Concrete
+ * implementations live in product code; the layer-1 library ships
+ * the interface plus {@link InMemoryKeyStore}.
+ */
+export interface KeyStore {
+    /** Look up the current domain key for `domain`, or null. */
+    lookupDomainKey(domain: string): KeyStoreRecord | null;
+    /**
+     * Look up all current key records for `address`, optionally
+     * filtered by `keyTypes`. Empty / undefined `keyTypes` means "all
+     * known types".
+     */
+    lookupUserKeys(address: string, keyTypes?: KeyType[]): KeyStoreRecord[];
+    /**
+     * Persist a fetched key record. Implementations SHOULD respect the
+     * record's `expires` timestamp when caching.
+     */
+    putRecord(rec: KeyStoreRecord): void;
+    /**
+     * Record a revocation. Subsequent {@link lookupUserKeys} /
+     * {@link lookupDomainKey} calls MUST surface the revocation in the
+     * returned record per KEY.md §8.
+     */
+    putRevocation(keyId: string, rev: Revocation): void;
+    /**
+     * Look up a scoped device certificate by its delegated device's
+     * key fingerprint. Returns null when the device is full-access
+     * (no certificate is on file).
+     */
+    lookupDeviceCertificate(deviceKeyId: string): DeviceCertificate | null;
+    /** Persist a delegated device certificate. */
+    putDeviceCertificate(cert: DeviceCertificate): void;
+}
+/**
+ * Extension that adds access to the user's own private keys. Only
+ * client implementations need this; server implementations never
+ * hold user private keys (KEY.md §9.1).
+ */
+export interface PrivateKeyStore extends KeyStore {
+    /**
+     * Decrypted private key material for `keyId`. Implementations are
+     * responsible for prompting the user for unlock credentials when
+     * required. Throws when no key is found.
+     */
+    loadPrivateKey(keyId: string): Uint8Array;
+    /**
+     * Persist encrypted private key material for `keyId`. Production
+     * implementations MUST encrypt at rest using a KDF such as Argon2id
+     * (KEY.md §9.2).
+     */
+    storePrivateKey(keyId: string, privateKey: Uint8Array): void;
+}
+/**
+ * Reference in-memory {@link KeyStore} + {@link PrivateKeyStore}.
+ * Tests, demos, and the reference build only.
+ */
+export declare class InMemoryKeyStore implements PrivateKeyStore {
+    private domainKeys;
+    private userKeys;
+    private privateKeys;
+    private deviceCerts;
+    /** Persist a domain record under `domain`. */
+    putDomainRecord(domain: string, rec: KeyStoreRecord): void;
+    lookupDomainKey(domain: string): KeyStoreRecord | null;
+    lookupUserKeys(address: string, keyTypes?: KeyType[]): KeyStoreRecord[];
+    putRecord(rec: KeyStoreRecord): void;
+    putRevocation(keyId: string, rev: Revocation): void;
+    lookupDeviceCertificate(deviceKeyId: string): DeviceCertificate | null;
+    putDeviceCertificate(cert: DeviceCertificate): void;
+    loadPrivateKey(keyId: string): Uint8Array;
+    storePrivateKey(keyId: string, privateKey: Uint8Array): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/keys/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/keys/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,gCAAgC;AAChC,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEtE,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACjC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,4DAA4D;IAC5D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IACvD;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IACxE;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACpD;;;;OAIG;IACH,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAAC;IACvE,8CAA8C;IAC9C,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CAC9D;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IACtD,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,WAAW,CAAwC;IAE3D,8CAA8C;IAC9C,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAI1D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAItD,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE;IASvE,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAkBpC,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI;IAenD,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAItE,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAWnD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAQzC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;CAM7D"}