@sempdev/semp 0.4.3

package/dist/reasoncodes.js

@@ -0,0 +1,80 @@
+/**
+ * Reason-code registry per VECTORS.md §8 / HANDSHAKE.md §4.1 /
+ * ENVELOPE.md §9.3 / ERRORS.md.
+ *
+ * @module
+ */
+/** The full set of recognized ReasonCode values. */
+export const KnownReasonCodes = new Set([
+    "blocked",
+    "auth_failed",
+    "policy_forbidden",
+    "handshake_expired",
+    "handshake_invalid",
+    "no_session",
+    "rate_limited",
+    "challenge",
+    "challenge_failed",
+    "challenge_invalid",
+    "server_at_capacity",
+    "resumption_failed",
+    "version_unsupported",
+    "seal_invalid",
+    "session_mac_invalid",
+    "envelope_expired",
+    "envelope_size_exceeded",
+    "extension_unsupported",
+    "extension_size_exceeded",
+    "scope_exceeded",
+    "scope_invalid",
+    "certificate_expired",
+    "server_unavailable",
+    "session_expired",
+    "rekey_unsupported",
+    "policy_kind_unsupported",
+    "policy_op_invalid",
+    "policy_version_stale",
+]);
+/** Type guard: is this string one of the recognized codes? */
+export function isKnownReasonCode(code) {
+    return KnownReasonCodes.has(code);
+}
+/**
+ * Reports whether automated retry is appropriate for this reason.
+ *
+ * Recoverable codes signal a transient or transport condition the
+ * sender SHOULD retry after a back-off, OR a state-staleness
+ * condition (handshake_expired, no_session, policy_version_stale)
+ * the sender resolves with a fresh handshake / refresh and a single
+ * retry. Non-recoverable codes signal a permanent condition (blocked,
+ * auth_failed, policy_forbidden, scope_invalid, etc.) where the
+ * sender MUST NOT retry without operator intervention.
+ *
+ * Notes on edge cases:
+ *
+ *   - `session_expired` and `rekey_unsupported` are NOT recoverable
+ *     here because they require a fresh handshake rather than an
+ *     automated retry on the rekey path.
+ *   - `challenge_invalid`, `version_unsupported`, `resumption_failed`,
+ *     `envelope_size_exceeded`, `scope_invalid`, and
+ *     `certificate_expired` are non-recoverable per ERRORS.md.
+ *
+ * Mirrors semp-go's `ReasonCode.Recoverable()` byte-for-byte; the
+ * vectors at `vectors/v1.0.0/rejection-codes.json` cross-check both.
+ */
+export function isRecoverable(code) {
+    switch (code) {
+        case "handshake_expired":
+        case "handshake_invalid":
+        case "no_session":
+        case "rate_limited":
+        case "challenge":
+        case "challenge_failed":
+        case "server_at_capacity":
+        case "policy_version_stale":
+            return true;
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=reasoncodes.js.map

package/dist/reasoncodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoncodes.js","sourceRoot":"","sources":["../src/reasoncodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,oDAAoD;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAa;IACvE,SAAS;IACT,aAAa;IACb,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,YAAY;IACZ,cAAc;IACd,WAAW;IACX,kBAAkB;IAClB,mBAAmB;IACnB,oBAAoB;IACpB,mBAAmB;IACnB,qBAAqB;IACrB,cAAc;IACd,qBAAqB;IACrB,kBAAkB;IAClB,wBAAwB;IACxB,uBAAuB;IACvB,yBAAyB;IACzB,gBAAgB;IAChB,eAAe;IACf,qBAAqB;IACrB,oBAAoB;IACpB,iBAAiB;IACjB,mBAAmB;IACnB,yBAAyB;IACzB,mBAAmB;IACnB,sBAAsB;CACvB,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAgB;IAC5C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,mBAAmB,CAAC;QACzB,KAAK,mBAAmB,CAAC;QACzB,KAAK,YAAY,CAAC;QAClB,KAAK,cAAc,CAAC;QACpB,KAAK,WAAW,CAAC;QACjB,KAAK,kBAAkB,CAAC;QACxB,KAAK,oBAAoB,CAAC;QAC1B,KAAK,sBAAsB;YACzB,OAAO,IAAI,CAAC;QACd;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/recovery/bundle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SEMP_BACKUP_BUNDLE sign / verify primitives per RECOVERY.md §2.
+ *
+ * Covers the wire shape and identity-key signature over the bundle.
+ * Payload encryption (Argon2id-derived key + XChaCha20-Poly1305) is
+ * the next layer up; this module ships the record-level primitives
+ * the higher-level flow plugs into.
+ *
+ * @module
+ */
+import { type BackupBundle } from "./types.js";
+/**
+ * Sign `b.signature` with the user's currently active identity
+ * private key per §2.4.
+ */
+export declare function signBundle(b: BackupBundle, identityPriv: Uint8Array, identityKeyId: string): string;
+/** Verify `b.signature` against `identityPub`. */
+export declare function verifyBundle(b: BackupBundle, identityPub: Uint8Array): boolean;
+/**
+ * Structural validation per §2.1 + §2.5. Throws on the first
+ * violation. Enforces:
+ *
+ *  - Required string fields present.
+ *  - `kdf.algorithm === "argon2id"` (the only KDF currently spec'd).
+ *  - Argon2id parameter floors: memory_kb >= 65536, iterations >= 2,
+ *    parallelism >= 1, salt >= 16 bytes (after base64 decode).
+ *  - `payload_algorithm === "xchacha20-poly1305"`.
+ *  - `signature.{algorithm,key_id,value}` present (value optional
+ *    when `skipSignatureCheck`).
+ */
+export declare function validateBundle(b: BackupBundle, opts?: {
+    skipSignatureCheck?: boolean;
+}): void;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/recovery/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/recovery/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EACL,KAAK,YAAY,EAQlB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,YAAY,EACf,YAAY,EAAE,UAAU,EACxB,aAAa,EAAE,MAAM,GACpB,MAAM,CAgBR;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAC1B,CAAC,EAAE,YAAY,EACf,WAAW,EAAE,UAAU,GACtB,OAAO,CAYT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,YAAY,EACf,IAAI,GAAE;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,IAAI,CAgGN"}

package/dist/recovery/bundle.js

@@ -0,0 +1,144 @@
+/**
+ * SEMP_BACKUP_BUNDLE sign / verify primitives per RECOVERY.md §2.
+ *
+ * Covers the wire shape and identity-key signature over the bundle.
+ * Payload encryption (Argon2id-derived key + XChaCha20-Poly1305) is
+ * the next layer up; this module ships the record-level primitives
+ * the higher-level flow plugs into.
+ *
+ * @module
+ */
+import { signSignedDoc, verifySignedDoc } from "../keys/index.js";
+import { KDFAlgorithmArgon2id, MinKDFIterations, MinKDFMemoryKB, MinKDFParallelism, MinKDFSaltBytes, RecoveryBundlePrefix, SignatureAlgorithmEd25519, } from "./types.js";
+/**
+ * Sign `b.signature` with the user's currently active identity
+ * private key per §2.4.
+ */
+export function signBundle(b, identityPriv, identityKeyId) {
+    if (identityKeyId === "") {
+        throw new Error("recovery: empty identity key_id");
+    }
+    validateBundle(b, { skipSignatureCheck: true });
+    b.signature.algorithm = SignatureAlgorithmEd25519;
+    b.signature.key_id = identityKeyId;
+    b.signature.value = "";
+    const { signedJSON, signatureB64 } = signSignedDoc({
+        preSignJSON: b,
+        seed: identityPriv,
+        signaturePath: "signature.value",
+        prefix: RecoveryBundlePrefix,
+    });
+    b.signature.value = signedJSON.signature.value;
+    return signatureB64;
+}
+/** Verify `b.signature` against `identityPub`. */
+export function verifyBundle(b, identityPub) {
+    validateBundle(b);
+    if (b.signature.value === "") {
+        return false;
+    }
+    const { ok } = verifySignedDoc({
+        signedJSON: b,
+        publicKey: identityPub,
+        signaturePath: "signature.value",
+        prefix: RecoveryBundlePrefix,
+    });
+    return ok;
+}
+/**
+ * Structural validation per §2.1 + §2.5. Throws on the first
+ * violation. Enforces:
+ *
+ *  - Required string fields present.
+ *  - `kdf.algorithm === "argon2id"` (the only KDF currently spec'd).
+ *  - Argon2id parameter floors: memory_kb >= 65536, iterations >= 2,
+ *    parallelism >= 1, salt >= 16 bytes (after base64 decode).
+ *  - `payload_algorithm === "xchacha20-poly1305"`.
+ *  - `signature.{algorithm,key_id,value}` present (value optional
+ *    when `skipSignatureCheck`).
+ */
+export function validateBundle(b, opts = {}) {
+    if (b.type !== "SEMP_BACKUP_BUNDLE") {
+        throw new Error(`recovery: bundle type ${JSON.stringify(b.type)}, want SEMP_BACKUP_BUNDLE`);
+    }
+    for (const f of [
+        "version",
+        "user_id",
+        "bundle_id",
+        "created_at",
+        "payload_algorithm",
+        "payload_nonce",
+        "encrypted_payload",
+    ]) {
+        if (typeof b[f] !== "string" || b[f] === "") {
+            throw new Error(`recovery: bundle missing ${f}`);
+        }
+    }
+    if (Number.isNaN(Date.parse(b.created_at))) {
+        throw new Error("recovery: bundle created_at is not ISO 8601");
+    }
+    if (b.payload_algorithm !== "xchacha20-poly1305") {
+        throw new Error(`recovery: bundle payload_algorithm ${JSON.stringify(b.payload_algorithm)}, want xchacha20-poly1305`);
+    }
+    if (b.kdf === undefined || b.kdf === null) {
+        throw new Error("recovery: bundle missing kdf");
+    }
+    if (b.kdf.algorithm !== KDFAlgorithmArgon2id) {
+        throw new Error(`recovery: bundle kdf.algorithm ${JSON.stringify(b.kdf.algorithm)}, want ${KDFAlgorithmArgon2id}`);
+    }
+    if (typeof b.kdf.salt !== "string" || b.kdf.salt === "") {
+        throw new Error("recovery: bundle kdf.salt missing");
+    }
+    // Decode the salt to enforce the 16-byte floor.
+    const saltBytes = base64Decode(b.kdf.salt);
+    if (saltBytes.length < MinKDFSaltBytes) {
+        throw new Error(`recovery: bundle kdf.salt ${saltBytes.length} bytes below minimum ${MinKDFSaltBytes}`);
+    }
+    if (!Number.isInteger(b.kdf.memory_kb) ||
+        b.kdf.memory_kb < MinKDFMemoryKB) {
+        throw new Error(`recovery: bundle kdf.memory_kb ${b.kdf.memory_kb} below minimum ${MinKDFMemoryKB}`);
+    }
+    if (!Number.isInteger(b.kdf.iterations) ||
+        b.kdf.iterations < MinKDFIterations) {
+        throw new Error(`recovery: bundle kdf.iterations ${b.kdf.iterations} below minimum ${MinKDFIterations}`);
+    }
+    if (!Number.isInteger(b.kdf.parallelism) ||
+        b.kdf.parallelism < MinKDFParallelism) {
+        throw new Error(`recovery: bundle kdf.parallelism ${b.kdf.parallelism} below minimum ${MinKDFParallelism}`);
+    }
+    if (b.recovery_verify_pk === undefined ||
+        typeof b.recovery_verify_pk?.public_key !== "string" ||
+        b.recovery_verify_pk.public_key === "") {
+        throw new Error("recovery: bundle recovery_verify_pk.public_key missing");
+    }
+    if (typeof b.recovery_verify_pk.algorithm !== "string" || b.recovery_verify_pk.algorithm === "") {
+        throw new Error("recovery: bundle recovery_verify_pk.algorithm missing");
+    }
+    if (b.supersedes !== null && (typeof b.supersedes !== "string" || b.supersedes === "")) {
+        throw new Error("recovery: bundle supersedes must be a non-empty string or null");
+    }
+    if (typeof b.signature?.algorithm !== "string") {
+        throw new Error("recovery: bundle signature.algorithm missing");
+    }
+    if (typeof b.signature?.key_id !== "string") {
+        throw new Error("recovery: bundle signature.key_id missing");
+    }
+    if (typeof b.signature?.value !== "string") {
+        throw new Error("recovery: bundle signature.value must be a string");
+    }
+    if (!opts.skipSignatureCheck && b.signature.value === "") {
+        throw new Error("recovery: bundle is unsigned");
+    }
+}
+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=bundle.js.map

package/dist/recovery/bundle.js.map

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

package/dist/recovery/bundle_crypto.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Bundle-payload encryption + recovery key derivation per
+ * RECOVERY.md §2.5 + §3.2 + §3.3.
+ *
+ *   - {@link normalizeRecoverySecret}: NFKC for passphrases /
+ *     lower+space-join for recovery codes per §3.2.
+ *   - {@link deriveBundleKey}: Argon2id over the normalized secret
+ *     yields the 32-byte K_bundle per §2.5.
+ *   - {@link deriveRecoverySignKey}: HKDF-Expand(K_bundle, ...) →
+ *     Ed25519 (recovery_sign_sk, recovery_verify_pk) per §3.3.
+ *   - {@link encryptBundlePayload} / {@link decryptBundlePayload}:
+ *     XChaCha20-Poly1305 per §2.5.
+ *
+ * @module
+ */
+import { type BundleKDF } from "./types.js";
+/** Recovery secret encoding per §3.1. */
+export type SecretForm = "passphrase" | "recovery_code";
+/** Hard minimum on a passphrase secret's UTF-8 byte length per §3.1. */
+export declare const MinPassphraseBytes = 12;
+/** HKDF info string for the recovery signing-key seed per §3.3. */
+export declare const RecoverySignKeyInfo = "SEMP-RECOVERY-SIGN-KEY-v1";
+/**
+ * Return the UTF-8 byte representation of `raw` after applying the
+ * §3.2 normalization rules for `form`:
+ *
+ *  - `passphrase`: NFKC, trimmed of leading/trailing whitespace.
+ *  - `recovery_code`: split on whitespace, lowercase each token,
+ *    join with single ASCII space.
+ */
+export declare function normalizeRecoverySecret(form: SecretForm, raw: string): Uint8Array;
+/**
+ * Run Argon2id over `secretBytes` with the parameters in `kdf` and
+ * return the 32-byte K_bundle per §2.5. Validates that `kdf` meets
+ * the §2.5 minima before computing.
+ */
+export declare function deriveBundleKey(secretBytes: Uint8Array, kdf: BundleKDF): Uint8Array;
+/**
+ * Derive the (recovery_sign_seed, recovery_verify_pk) Ed25519 key
+ * pair per §3.3:
+ *
+ *   seed = HKDF-Expand(K_bundle, "SEMP-RECOVERY-SIGN-KEY-v1", 32)
+ *
+ * Returns the 32-byte Ed25519 seed (used directly as the secret
+ * key per @noble/curves) and the corresponding 32-byte public key.
+ */
+export declare function deriveRecoverySignKey(bundleKey: Uint8Array): {
+    signSeed: Uint8Array;
+    verifyPub: Uint8Array;
+};
+/**
+ * XChaCha20-Poly1305-encrypt the JSON-encoded `payload` under
+ * `bundleKey` with a 24-byte `nonce`. AAD is empty per §2.5.
+ *
+ * Returns the ciphertext (with the 16-byte AEAD tag appended).
+ */
+export declare function encryptBundlePayload(bundleKey: Uint8Array, nonce: Uint8Array, payload: unknown): Uint8Array;
+/** Reverse {@link encryptBundlePayload}. */
+export declare function decryptBundlePayload<T = unknown>(bundleKey: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array): T;
+//# sourceMappingURL=bundle_crypto.d.ts.map

package/dist/recovery/bundle_crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle_crypto.d.ts","sourceRoot":"","sources":["../../src/recovery/bundle_crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,OAAO,EACL,KAAK,SAAS,EAMf,MAAM,YAAY,CAAC;AAEpB,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,eAAe,CAAC;AAExD,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,GACV,UAAU,CAuBZ;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,UAAU,EACvB,GAAG,EAAE,SAAS,GACb,UAAU,CAiBZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,UAAU,GAAG;IAC5D,QAAQ,EAAE,UAAU,CAAC;IACrB,SAAS,EAAE,UAAU,CAAC;CACvB,CAQA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,UAAU,EACrB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,OAAO,GACf,UAAU,CAWZ;AAED,4CAA4C;AAC5C,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAC9C,SAAS,EAAE,UAAU,EACrB,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,UAAU,GACrB,CAAC,CAWH"}

package/dist/recovery/bundle_crypto.js

@@ -0,0 +1,179 @@
+/**
+ * Bundle-payload encryption + recovery key derivation per
+ * RECOVERY.md §2.5 + §3.2 + §3.3.
+ *
+ *   - {@link normalizeRecoverySecret}: NFKC for passphrases /
+ *     lower+space-join for recovery codes per §3.2.
+ *   - {@link deriveBundleKey}: Argon2id over the normalized secret
+ *     yields the 32-byte K_bundle per §2.5.
+ *   - {@link deriveRecoverySignKey}: HKDF-Expand(K_bundle, ...) →
+ *     Ed25519 (recovery_sign_sk, recovery_verify_pk) per §3.3.
+ *   - {@link encryptBundlePayload} / {@link decryptBundlePayload}:
+ *     XChaCha20-Poly1305 per §2.5.
+ *
+ * @module
+ */
+import { argon2id } from "@noble/hashes/argon2.js";
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { publicKeyFromSeed } from "../keys/index.js";
+import { KDFAlgorithmArgon2id, MinKDFIterations, MinKDFMemoryKB, MinKDFParallelism, MinKDFSaltBytes, } from "./types.js";
+/** Hard minimum on a passphrase secret's UTF-8 byte length per §3.1. */
+export const MinPassphraseBytes = 12;
+/** HKDF info string for the recovery signing-key seed per §3.3. */
+export const RecoverySignKeyInfo = "SEMP-RECOVERY-SIGN-KEY-v1";
+/**
+ * Return the UTF-8 byte representation of `raw` after applying the
+ * §3.2 normalization rules for `form`:
+ *
+ *  - `passphrase`: NFKC, trimmed of leading/trailing whitespace.
+ *  - `recovery_code`: split on whitespace, lowercase each token,
+ *    join with single ASCII space.
+ */
+export function normalizeRecoverySecret(form, raw) {
+    switch (form) {
+        case "passphrase": {
+            const s = raw.normalize("NFKC").trim();
+            const bytes = new TextEncoder().encode(s);
+            if (bytes.length < MinPassphraseBytes) {
+                throw new Error(`recovery: passphrase length ${bytes.length} below ${MinPassphraseBytes}-byte minimum`);
+            }
+            return bytes;
+        }
+        case "recovery_code": {
+            const fields = raw.trim().split(/\s+/).filter((s) => s !== "");
+            if (fields.length === 0) {
+                throw new Error("recovery: recovery code is empty");
+            }
+            const joined = fields.map((w) => w.toLowerCase()).join(" ");
+            return new TextEncoder().encode(joined);
+        }
+        default:
+            throw new Error(`recovery: unsupported secret form ${JSON.stringify(form)}`);
+    }
+}
+/**
+ * Run Argon2id over `secretBytes` with the parameters in `kdf` and
+ * return the 32-byte K_bundle per §2.5. Validates that `kdf` meets
+ * the §2.5 minima before computing.
+ */
+export function deriveBundleKey(secretBytes, kdf) {
+    if (secretBytes.length === 0) {
+        throw new Error("recovery: empty recovery secret bytes");
+    }
+    validateKDFParams(kdf);
+    const salt = base64Decode(kdf.salt);
+    if (salt.length < MinKDFSaltBytes) {
+        throw new Error(`recovery: kdf salt length ${salt.length} below ${MinKDFSaltBytes}-byte minimum`);
+    }
+    return argon2id(secretBytes, salt, {
+        t: kdf.iterations,
+        m: kdf.memory_kb,
+        p: kdf.parallelism,
+        dkLen: 32,
+    });
+}
+/**
+ * Derive the (recovery_sign_seed, recovery_verify_pk) Ed25519 key
+ * pair per §3.3:
+ *
+ *   seed = HKDF-Expand(K_bundle, "SEMP-RECOVERY-SIGN-KEY-v1", 32)
+ *
+ * Returns the 32-byte Ed25519 seed (used directly as the secret
+ * key per @noble/curves) and the corresponding 32-byte public key.
+ */
+export function deriveRecoverySignKey(bundleKey) {
+    if (bundleKey.length === 0) {
+        throw new Error("recovery: empty bundle key");
+    }
+    const info = new TextEncoder().encode(RecoverySignKeyInfo);
+    const seed = hkdfExpandSHA512(bundleKey, info, 32);
+    const verifyPub = publicKeyFromSeed(seed);
+    return { signSeed: seed, verifyPub };
+}
+/**
+ * XChaCha20-Poly1305-encrypt the JSON-encoded `payload` under
+ * `bundleKey` with a 24-byte `nonce`. AAD is empty per §2.5.
+ *
+ * Returns the ciphertext (with the 16-byte AEAD tag appended).
+ */
+export function encryptBundlePayload(bundleKey, nonce, payload) {
+    if (bundleKey.length !== 32) {
+        throw new Error(`recovery: bundle key length ${bundleKey.length}, want 32`);
+    }
+    if (nonce.length !== 24) {
+        throw new Error(`recovery: payload nonce length ${nonce.length}, want 24`);
+    }
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    return xchacha20poly1305(bundleKey, nonce).encrypt(plaintext);
+}
+/** Reverse {@link encryptBundlePayload}. */
+export function decryptBundlePayload(bundleKey, nonce, ciphertext) {
+    if (bundleKey.length !== 32) {
+        throw new Error(`recovery: bundle key length ${bundleKey.length}, want 32`);
+    }
+    if (nonce.length !== 24) {
+        throw new Error(`recovery: payload nonce length ${nonce.length}, want 24`);
+    }
+    const plaintext = xchacha20poly1305(bundleKey, nonce).decrypt(ciphertext);
+    return JSON.parse(new TextDecoder().decode(plaintext));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+function validateKDFParams(kdf) {
+    if (kdf.algorithm !== KDFAlgorithmArgon2id) {
+        throw new Error(`recovery: kdf.algorithm ${JSON.stringify(kdf.algorithm)}, want ${KDFAlgorithmArgon2id}`);
+    }
+    if (typeof kdf.salt !== "string" || kdf.salt === "") {
+        throw new Error("recovery: kdf.salt missing");
+    }
+    if (!Number.isInteger(kdf.memory_kb) || kdf.memory_kb < MinKDFMemoryKB) {
+        throw new Error(`recovery: kdf.memory_kb ${kdf.memory_kb} below ${MinKDFMemoryKB} minimum`);
+    }
+    if (!Number.isInteger(kdf.iterations) || kdf.iterations < MinKDFIterations) {
+        throw new Error(`recovery: kdf.iterations ${kdf.iterations} below ${MinKDFIterations} minimum`);
+    }
+    if (!Number.isInteger(kdf.parallelism) ||
+        kdf.parallelism < MinKDFParallelism) {
+        throw new Error(`recovery: kdf.parallelism ${kdf.parallelism} below ${MinKDFParallelism} minimum`);
+    }
+}
+/**
+ * RFC 5869 HKDF-Expand with HMAC-SHA-512. Permits PRK shorter than
+ * HashLen (§3.3 passes 32-byte K_bundle as the PRK).
+ */
+function hkdfExpandSHA512(prk, info, length) {
+    const hashLen = 64;
+    const N = Math.ceil(length / hashLen);
+    if (N > 255) {
+        throw new Error("recovery: HKDF-Expand requested length too large");
+    }
+    let prev = new Uint8Array(0);
+    const out = new Uint8Array(length);
+    let written = 0;
+    for (let i = 1; i <= N; i++) {
+        const buf = new Uint8Array(prev.length + info.length + 1);
+        buf.set(prev, 0);
+        buf.set(info, prev.length);
+        buf[prev.length + info.length] = i;
+        const t = hmac(sha512, prk, buf);
+        const take = Math.min(hashLen, length - written);
+        out.set(t.slice(0, take), written);
+        written += take;
+        prev = t;
+    }
+    return out;
+}
+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=bundle_crypto.js.map

package/dist/recovery/bundle_crypto.js.map

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

package/dist/recovery/bundle_store.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Backup-bundle persistence per RECOVERY.md §2.6.
+ *
+ * The home server retains the user's most recent bundle plus the
+ * recent superseded chain (so a client recovering after a long
+ * offline period can fetch the bundle that matches whichever
+ * recovery secret the user remembers). Pruning honors the §2.6
+ * floor of 30 days for superseded entries.
+ *
+ * @module
+ */
+import type { BackupBundle } from "./types.js";
+/**
+ * Spec-mandated retention floor for superseded bundles per §2.6:
+ * at least 30 days. Operators MAY use a larger value; smaller
+ * values are clamped up by {@link InMemoryBundleStore.pruneSuperseded}.
+ */
+export declare const MinSupersededRetentionMs: number;
+/** Persistence interface for backup bundles. */
+export interface BundleStore {
+    /**
+     * Replace the current bundle for `userId`. The previous current
+     * bundle (if any) becomes superseded as of `supersededAt`.
+     * Throws when the new bundle's `supersedes` field doesn't point
+     * at the existing current bundle's id (or when the existing
+     * record's user_id doesn't match).
+     */
+    putCurrent(userId: string, bundle: BackupBundle, supersededAt: Date): Promise<void>;
+    /** Fetch the current bundle for `userId`, or null when none. */
+    getCurrent(userId: string): Promise<BackupBundle | null>;
+    /**
+     * Return every bundle (current + superseded) for `userId` in
+     * descending order by created_at. Empty list when no bundles.
+     */
+    history(userId: string): Promise<BackupBundle[]>;
+    /** Remove every bundle for `userId`. */
+    deleteAll(userId: string): Promise<void>;
+    /**
+     * Drop superseded bundles whose `supersededAt` is older than
+     * `now - retainForMs`. Values smaller than
+     * {@link MinSupersededRetentionMs} are clamped up. Returns the
+     * number pruned.
+     */
+    pruneSuperseded(retainForMs: number, now?: Date): Promise<number>;
+}
+/** Reference {@link BundleStore}. Single-process only. */
+export declare class InMemoryBundleStore implements BundleStore {
+    private readonly byUser;
+    private readonly nowFn;
+    constructor(nowFn?: () => Date);
+    putCurrent(userId: string, bundle: BackupBundle, supersededAt: Date): Promise<void>;
+    getCurrent(userId: string): Promise<BackupBundle | null>;
+    history(userId: string): Promise<BackupBundle[]>;
+    deleteAll(userId: string): Promise<void>;
+    pruneSuperseded(retainForMs: number, now?: Date): Promise<number>;
+}
+//# sourceMappingURL=bundle_store.d.ts.map

package/dist/recovery/bundle_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle_store.d.ts","sourceRoot":"","sources":["../../src/recovery/bundle_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAQjE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,IAAI,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,gEAAgE;IAChE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAEzD;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEjD,wCAAwC;IACxC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED,0DAA0D;AAC1D,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAEvB,KAAK,GAAE,MAAM,IAAuB;IAI1C,UAAU,CACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,IAAI,GACjB,OAAO,CAAC,IAAI,CAAC;IA8BV,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IASxD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAWhD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,MAAM,CAAC;CA6BnB"}