@forthtilliath/backup-crypto 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forthtilliath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @forthtilliath/backup-crypto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Encrypt an app's backup (typically a JSON export) with a random app-generated key — no password for the user to pick or remember. Pure TypeScript on top of audited libraries ([`@noble/ciphers`](https://github.com/paulmillr/noble-ciphers), [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), [`@scure/base`](https://github.com/paulmillr/scure-base)): no native module, runs in React Native, browsers and Node.
+
+Used by [`@forthtilliath/expo-backup`](../expo-backup#readme), which stores the keys (secure store + private Google Drive copy). Use this package directly only for another platform (e.g. a web app reading the same backups).
+
+## Install
+
+```bash
+npm install @forthtilliath/backup-crypto
+```
+
+## Format
+
+An encrypted backup is still JSON — file pickers filtering on `application/json` keep working — but only its header is readable:
+
+```json
+{
+  "format": "forthtilliath.encrypted-backup",
+  "version": 1,
+  "app": "glucodose",
+  "keyId": "3f9c0a1b2c3d4e5f",
+  "cipher": "xchacha20-poly1305",
+  "nonce": "…",
+  "ciphertext": "…"
+}
+```
+
+- **XChaCha20-Poly1305** with a 256-bit key and a fresh random 192-bit nonce per backup: safe to encrypt every backup with the same key.
+- The header (format, version, app, keyId, cipher) is authenticated: editing it makes decryption fail instead of being trusted.
+- `keyId` is a domain-separated hash of the key (not the key): it says which key of a keyring to use.
+
+## Usage
+
+```ts
+import {
+  decryptBackupWithKeyring,
+  emptyKeyring,
+  encryptBackup,
+  ensureCurrentKey,
+  formatRecoveryCode,
+  getCurrentKey,
+  isEncryptedBackup,
+  parseRecoveryCode,
+} from "@forthtilliath/backup-crypto";
+
+let keyring = ensureCurrentKey(emptyKeyring); // generates a key
+const key = getCurrentKey(keyring)!.key;
+
+const file = encryptBackup(JSON.stringify(data), key, { app: "glucodose" });
+isEncryptedBackup(file); // true
+const json = decryptBackupWithKeyring(file, keyring);
+
+// Human-friendly form of the key, to write down: 55 Crockford base32 chars
+// with a checksum, e.g. "7K3QD-…". Tolerates case, spaces and I/L/O typos.
+const code = formatRecoveryCode(key);
+parseRecoveryCode(code); // the key again
+```
+
+### Keyrings
+
+A keyring keeps every key an app ever encrypted with, so files written before a key change (other phone, reinstall) stay readable; new backups use `currentId`. All helpers are immutable:
+
+| Function                                          |                                                       |
+| ------------------------------------------------- | ----------------------------------------------------- |
+| `ensureCurrentKey(keyring, randomBytes?)`         | Adds a current key if there's none                    |
+| `addKeyToKeyring(keyring, key, { makeCurrent? })` | Adds a key (current if the keyring had none)          |
+| `mergeKeyrings(preferred, other)`                 | Union; `preferred`'s current key wins                 |
+| `sameKeyring(a, b)`                               | Nothing to save or upload                             |
+| `serializeKeyring` / `parseKeyring`               | JSON form (contains the raw keys — store it securely) |
+
+### API reference
+
+All functions are pure (no I/O); the keyring helpers return new objects.
+
+| Export                                                                  | Module         |                                                                                               |
+| ----------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
+| `generateBackupKey(randomBytes?)`                                       | `backupKey`    | A new random 256-bit key (`BACKUP_KEY_LENGTH` = 32 bytes)                                     |
+| `getBackupKeyId(key)`                                                   | `backupKey`    | Short non-secret id (16 hex chars) of a key, stored in each envelope                          |
+| `encodeBackupKey(key)` / `decodeBackupKey(text)`                        | `backupKey`    | Base64 form of a key, for storage; decoding throws `corrupted` for anything but a 256-bit key |
+| `defaultRandomBytes(length)`                                            | `backupKey`    | `crypto.getRandomValues`, or throws `no-random-source`                                        |
+| `encryptBackup(text, key, { app?, randomBytes? })`                      | `envelope`     | The JSON envelope to write as is                                                              |
+| `decryptBackup(content, key)`                                           | `envelope`     | Plaintext; throws `unknown-key` or `corrupted`                                                |
+| `isEncryptedBackup(content)`                                            | `envelope`     | Whether a file is an envelope (of any version)                                                |
+| `readEncryptedBackup(content)`                                          | `envelope`     | Validated header (`app`, `keyId`, `version`…) without decrypting                              |
+| `ENCRYPTED_BACKUP_FORMAT` / `ENCRYPTED_BACKUP_VERSION`                  | `envelope`     | `format` field of an envelope / version this package writes                                   |
+| `emptyKeyring`, `getCurrentKey(keyring)`, `findKeyringKey(keyring, id)` | `keyring`      | Keyring basics                                                                                |
+| `decryptBackupWithKeyring(content, keyring)`                            | `keyring`      | Decrypts with whichever key wrote the file                                                    |
+| `BACKUP_KEYRING_FORMAT`                                                 | `keyring`      | `format` field of a serialized keyring                                                        |
+| `formatRecoveryCode(key)` / `parseRecoveryCode(code)`                   | `recoveryCode` | Human-friendly form of a key, with a checksum                                                 |
+
+Everything is exported from the package root; each module is also importable on its own (`@forthtilliath/backup-crypto/keyring`…).
+
+### Errors
+
+Everything throws a `BackupCryptoError` with a `code`: `not-encrypted`, `unsupported-version`, `unknown-key` (ask for the recovery code of the device that wrote it), `corrupted` (truncated or tampered with), `invalid-recovery-code` (typo), `no-random-source`.
+
+### Randomness
+
+Keys and nonces come from `crypto.getRandomValues`, or the `randomBytes` option — pass `expo-crypto`'s `getRandomBytes` in React Native. There's no `Math.random` fallback: without a secure source, encryption throws `no-random-source`.

package/dist/backupKey.d.ts

@@ -0,0 +1,33 @@
+/** Length in bytes of a backup key (XChaCha20-Poly1305 uses 256-bit keys). */
+export declare const BACKUP_KEY_LENGTH = 32;
+/** Fills a new array with `length` cryptographically secure random bytes. */
+export type RandomBytes = (length: number) => Uint8Array;
+/**
+ * The random source used when no `randomBytes` option is given:
+ * `crypto.getRandomValues` (browsers, Node, React Native with `expo-crypto`'s
+ * polyfill). Throws rather than ever falling back to `Math.random`.
+ */
+export declare function defaultRandomBytes(length: number): Uint8Array;
+/**
+ * Generates a new random 256-bit backup key.
+ *
+ * @param randomBytes - Source of randomness. Defaults to
+ *   `crypto.getRandomValues`; pass
+ *   expo-crypto's `getRandomBytes` where the global is missing.
+ * @returns The 32-byte key. Keep it secret (secure store, private cloud file).
+ */
+export declare function generateBackupKey(randomBytes?: RandomBytes): Uint8Array;
+/**
+ * A short, stable, non-secret identifier of a key (16 hex chars), stored next
+ * to each encrypted backup so the right key can be picked from a keyring.
+ * Domain-separated hash: it reveals nothing usable about the key itself.
+ */
+export declare function getBackupKeyId(key: Uint8Array): string;
+/** Base64 form of a key, for storage (secure store, keyring file). */
+export declare function encodeBackupKey(key: Uint8Array): string;
+/**
+ * Reverse of {@link encodeBackupKey}. Throws `corrupted` on anything else than
+ * a 256-bit key.
+ */
+export declare function decodeBackupKey(encoded: string): Uint8Array;
+//# sourceMappingURL=backupKey.d.ts.map

package/dist/backupKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backupKey.d.ts","sourceRoot":"","sources":["../src/backupKey.ts"],"names":[],"mappings":"AAMA,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;AAIzD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,GAAE,WAAgC,GAC5C,UAAU,CASZ;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAKtD;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAW3D"}

package/dist/backupKey.js

@@ -0,0 +1,66 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { utf8ToBytes } from "@noble/hashes/utils.js";
+import { base64, hex } from "@scure/base";
+import { BackupCryptoError } from "./errors.js";
+/** Length in bytes of a backup key (XChaCha20-Poly1305 uses 256-bit keys). */
+export const BACKUP_KEY_LENGTH = 32;
+const KEY_ID_DOMAIN = utf8ToBytes("forthtilliath.backup-key-id");
+/**
+ * The random source used when no `randomBytes` option is given:
+ * `crypto.getRandomValues` (browsers, Node, React Native with `expo-crypto`'s
+ * polyfill). Throws rather than ever falling back to `Math.random`.
+ */
+export function defaultRandomBytes(length) {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues !== "function") {
+        throw new BackupCryptoError("no-random-source", "No secure random source: pass a `randomBytes` option (e.g. expo-crypto's getRandomBytes).");
+    }
+    return webCrypto.getRandomValues(new Uint8Array(length));
+}
+/**
+ * Generates a new random 256-bit backup key.
+ *
+ * @param randomBytes - Source of randomness. Defaults to
+ *   `crypto.getRandomValues`; pass
+ *   expo-crypto's `getRandomBytes` where the global is missing.
+ * @returns The 32-byte key. Keep it secret (secure store, private cloud file).
+ */
+export function generateBackupKey(randomBytes = defaultRandomBytes) {
+    const key = randomBytes(BACKUP_KEY_LENGTH);
+    if (key.length !== BACKUP_KEY_LENGTH) {
+        throw new BackupCryptoError("no-random-source", `randomBytes returned ${key.length} bytes instead of ${BACKUP_KEY_LENGTH}.`);
+    }
+    return key;
+}
+/**
+ * A short, stable, non-secret identifier of a key (16 hex chars), stored next
+ * to each encrypted backup so the right key can be picked from a keyring.
+ * Domain-separated hash: it reveals nothing usable about the key itself.
+ */
+export function getBackupKeyId(key) {
+    const input = new Uint8Array(KEY_ID_DOMAIN.length + key.length);
+    input.set(KEY_ID_DOMAIN);
+    input.set(key, KEY_ID_DOMAIN.length);
+    return hex.encode(sha256(input).subarray(0, 8));
+}
+/** Base64 form of a key, for storage (secure store, keyring file). */
+export function encodeBackupKey(key) {
+    return base64.encode(key);
+}
+/**
+ * Reverse of {@link encodeBackupKey}. Throws `corrupted` on anything else than
+ * a 256-bit key.
+ */
+export function decodeBackupKey(encoded) {
+    let key;
+    try {
+        key = base64.decode(encoded);
+    }
+    catch {
+        throw new BackupCryptoError("corrupted", "Invalid backup key encoding.");
+    }
+    if (key.length !== BACKUP_KEY_LENGTH) {
+        throw new BackupCryptoError("corrupted", "Invalid backup key length.");
+    }
+    return key;
+}

package/dist/envelope.d.ts

@@ -0,0 +1,72 @@
+import { type RandomBytes } from "./backupKey.js";
+/**
+ * Value of the `format` field that marks a file as an encrypted backup
+ * envelope.
+ */
+export declare const ENCRYPTED_BACKUP_FORMAT = "forthtilliath.encrypted-backup";
+/**
+ * Envelope version this package writes; a higher one is refused as
+ * `unsupported-version`.
+ */
+export declare const ENCRYPTED_BACKUP_VERSION = 1;
+declare const CIPHER = "xchacha20-poly1305";
+/**
+ * What an encrypted backup file contains. Still JSON (so pickers filtering on
+ * `application/json` keep working), but only the header is readable: the
+ * app's data is in `ciphertext`.
+ */
+export interface EncryptedBackupEnvelope {
+    /** Always {@link ENCRYPTED_BACKUP_FORMAT}. */
+    format: typeof ENCRYPTED_BACKUP_FORMAT;
+    /**
+     * Envelope version, {@link ENCRYPTED_BACKUP_VERSION} when written by this
+     * package.
+     */
+    version: number;
+    /** Free label of the app that wrote it — authenticated, not secret. */
+    app: string;
+    /** {@link getBackupKeyId} of the key it was encrypted with. */
+    keyId: string;
+    /** The algorithm, always `"xchacha20-poly1305"`. */
+    cipher: typeof CIPHER;
+    /** The random 24-byte nonce, base64-encoded. */
+    nonce: string;
+    /**
+     * The encrypted backup followed by its 16-byte authentication tag,
+     * base64-encoded.
+     */
+    ciphertext: string;
+}
+/** Options of {@link encryptBackup}. */
+export interface EncryptBackupOptions {
+    /** Stored in clear and authenticated, e.g. `"glucodose"`. */
+    app?: string;
+    /**
+     * Source of the nonce. Defaults to the platform's secure generator
+     * (`crypto.getRandomValues`); override it only in tests, for a deterministic
+     * output.
+     */
+    randomBytes?: RandomBytes;
+}
+/**
+ * Encrypts a backup's text (typically the app's JSON export) with
+ * XChaCha20-Poly1305 and a fresh random 192-bit nonce — safe to reuse the
+ * same key for every backup. Returns the JSON envelope to write as is.
+ */
+export declare function encryptBackup(plaintext: string, key: Uint8Array, { app, randomBytes }?: EncryptBackupOptions): string;
+/** Whether `content` is an encrypted backup envelope (of any version). */
+export declare function isEncryptedBackup(content: string): boolean;
+/**
+ * Validates and returns an encrypted backup's header. Throws
+ * `not-encrypted` for anything that isn't an envelope, `unsupported-version`
+ * for a newer one, `corrupted` for a malformed one.
+ */
+export declare function readEncryptedBackup(content: string): EncryptedBackupEnvelope;
+/**
+ * Decrypts an envelope written by {@link encryptBackup}. Throws `unknown-key`
+ * when `key` isn't the one it was encrypted with, `corrupted` when the file
+ * was truncated or tampered with.
+ */
+export declare function decryptBackup(content: string, key: Uint8Array): string;
+export {};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAGxB;;;GAGG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AACxE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,QAAA,MAAM,MAAM,uBAAuB,CAAC;AAGpC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AA2BD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,UAAU,EACf,EAAE,GAAQ,EAAE,WAAgC,EAAE,GAAE,oBAAyB,GACxE,MAAM,CAwBR;AAcD,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,CA8B5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAqBtE"}

package/dist/envelope.js

@@ -0,0 +1,128 @@
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
+import { base64 } from "@scure/base";
+import { BACKUP_KEY_LENGTH, defaultRandomBytes, getBackupKeyId, } from "./backupKey.js";
+import { BackupCryptoError } from "./errors.js";
+/**
+ * Value of the `format` field that marks a file as an encrypted backup
+ * envelope.
+ */
+export const ENCRYPTED_BACKUP_FORMAT = "forthtilliath.encrypted-backup";
+/**
+ * Envelope version this package writes; a higher one is refused as
+ * `unsupported-version`.
+ */
+export const ENCRYPTED_BACKUP_VERSION = 1;
+const CIPHER = "xchacha20-poly1305";
+const NONCE_LENGTH = 24;
+// The header is bound to the ciphertext as associated data: editing the
+// app/keyId/version of a file makes decryption fail instead of being trusted.
+function associatedData(envelope) {
+    return utf8ToBytes(JSON.stringify([
+        envelope.format,
+        envelope.version,
+        envelope.app,
+        envelope.keyId,
+        envelope.cipher,
+    ]));
+}
+function assertKey(key) {
+    if (key.length !== BACKUP_KEY_LENGTH) {
+        throw new BackupCryptoError("corrupted", "Invalid backup key length.");
+    }
+}
+/**
+ * Encrypts a backup's text (typically the app's JSON export) with
+ * XChaCha20-Poly1305 and a fresh random 192-bit nonce — safe to reuse the
+ * same key for every backup. Returns the JSON envelope to write as is.
+ */
+export function encryptBackup(plaintext, key, { app = "", randomBytes = defaultRandomBytes } = {}) {
+    assertKey(key);
+    const nonce = randomBytes(NONCE_LENGTH);
+    if (nonce.length !== NONCE_LENGTH) {
+        throw new BackupCryptoError("no-random-source");
+    }
+    const header = {
+        format: ENCRYPTED_BACKUP_FORMAT,
+        version: ENCRYPTED_BACKUP_VERSION,
+        app,
+        keyId: getBackupKeyId(key),
+        cipher: CIPHER,
+    };
+    const ciphertext = xchacha20poly1305(key, nonce, associatedData(header)).encrypt(utf8ToBytes(plaintext));
+    const envelope = {
+        ...header,
+        nonce: base64.encode(nonce),
+        ciphertext: base64.encode(ciphertext),
+    };
+    return JSON.stringify(envelope);
+}
+function tryParseJson(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Whether `content` is an encrypted backup envelope (of any version). */
+export function isEncryptedBackup(content) {
+    const parsed = tryParseJson(content);
+    return isRecord(parsed) && parsed.format === ENCRYPTED_BACKUP_FORMAT;
+}
+/**
+ * Validates and returns an encrypted backup's header. Throws
+ * `not-encrypted` for anything that isn't an envelope, `unsupported-version`
+ * for a newer one, `corrupted` for a malformed one.
+ */
+export function readEncryptedBackup(content) {
+    const parsed = tryParseJson(content);
+    if (!isRecord(parsed) || parsed.format !== ENCRYPTED_BACKUP_FORMAT) {
+        throw new BackupCryptoError("not-encrypted");
+    }
+    if (typeof parsed.version !== "number" ||
+        parsed.version > ENCRYPTED_BACKUP_VERSION) {
+        throw new BackupCryptoError("unsupported-version");
+    }
+    const { app, keyId, cipher, nonce, ciphertext } = parsed;
+    if (typeof app !== "string" ||
+        typeof keyId !== "string" ||
+        cipher !== CIPHER ||
+        typeof nonce !== "string" ||
+        typeof ciphertext !== "string") {
+        throw new BackupCryptoError("corrupted", "Malformed encrypted backup.");
+    }
+    return {
+        format: ENCRYPTED_BACKUP_FORMAT,
+        version: parsed.version,
+        app,
+        keyId,
+        cipher,
+        nonce,
+        ciphertext,
+    };
+}
+/**
+ * Decrypts an envelope written by {@link encryptBackup}. Throws `unknown-key`
+ * when `key` isn't the one it was encrypted with, `corrupted` when the file
+ * was truncated or tampered with.
+ */
+export function decryptBackup(content, key) {
+    assertKey(key);
+    const envelope = readEncryptedBackup(content);
+    if (envelope.keyId !== getBackupKeyId(key)) {
+        throw new BackupCryptoError("unknown-key");
+    }
+    try {
+        const nonce = base64.decode(envelope.nonce);
+        const ciphertext = base64.decode(envelope.ciphertext);
+        const plaintext = xchacha20poly1305(key, nonce, associatedData(envelope)).decrypt(ciphertext);
+        return bytesToUtf8(plaintext);
+    }
+    catch {
+        throw new BackupCryptoError("corrupted", "Encrypted backup failed authentication.");
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Why a backup couldn't be encrypted or decrypted:
+ * - `not-encrypted`: the content isn't an encrypted backup at all (e.g. a
+ *   plain JSON export) — callers usually fall back to reading it as is.
+ * - `unsupported-version`: written by a newer version of this package.
+ * - `unknown-key`: encrypted with a key that isn't in the keyring — ask for
+ *   the recovery code of the device that wrote it.
+ * - `corrupted`: malformed, truncated or tampered with (authentication failed).
+ * - `invalid-recovery-code`: a typo in a recovery code (checksum mismatch).
+ * - `no-random-source`: no `crypto.getRandomValues` and no `randomBytes`
+ *   option — never encrypt with a weak random source instead.
+ */
+export type BackupCryptoErrorCode = "not-encrypted" | "unsupported-version" | "unknown-key" | "corrupted" | "invalid-recovery-code" | "no-random-source";
+/**
+ * The only error this package throws: `code` says what went wrong (see {@link
+ * BackupCryptoErrorCode}), so the app can show the right message — e.g. ask for
+ * the recovery key on `unknown-key`.
+ */
+export declare class BackupCryptoError extends Error {
+    readonly code: BackupCryptoErrorCode;
+    constructor(code: BackupCryptoErrorCode, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAC7B,eAAe,GACf,qBAAqB,GACrB,aAAa,GACb,WAAW,GACX,uBAAuB,GACvB,kBAAkB,CAAC;AAEvB;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;gBAEzB,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,MAAM;CAK1D"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/**
+ * The only error this package throws: `code` says what went wrong (see {@link
+ * BackupCryptoErrorCode}), so the app can show the right message — e.g. ask for
+ * the recovery key on `unknown-key`.
+ */
+export class BackupCryptoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = "BackupCryptoError";
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./backupKey.js";
+export * from "./envelope.js";
+export * from "./errors.js";
+export * from "./keyring.js";
+export * from "./recoveryCode.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./backupKey.js";
+export * from "./envelope.js";
+export * from "./errors.js";
+export * from "./keyring.js";
+export * from "./recoveryCode.js";

package/dist/keyring.d.ts

@@ -0,0 +1,87 @@
+import { type RandomBytes } from "./backupKey.js";
+/**
+ * Value of the `format` field of a serialized keyring (see {@link
+ * serializeKeyring}).
+ */
+export declare const BACKUP_KEYRING_FORMAT = "forthtilliath.backup-keyring";
+/** One key of a keyring. */
+export interface BackupKeyringEntry {
+    /**
+     * {@link getBackupKeyId} of `key`: short, non-secret, stored in every
+     * envelope it encrypts.
+     */
+    id: string;
+    /**
+     * The raw 32-byte key. Secret: keep it in a secure store or a private cloud
+     * file.
+     */
+    key: Uint8Array;
+    /** Epoch ms. */
+    createdAt: number;
+}
+/**
+ * Every key an app has encrypted backups with, so a file written before a
+ * key change (another phone, a reinstall…) stays readable. New backups always
+ * use `currentId`. Immutable: every helper returns a new keyring.
+ */
+export interface BackupKeyring {
+    /**
+     * Id of the key new backups are encrypted with, `null` while the keyring is
+     * empty.
+     */
+    currentId: string | null;
+    /**
+     * Every key known on this device — older ones are kept to decrypt older
+     * backups.
+     */
+    keys: readonly BackupKeyringEntry[];
+}
+/**
+ * A keyring with no key, the starting point before {@link ensureCurrentKey}.
+ */
+export declare const emptyKeyring: BackupKeyring;
+/**
+ * Looks a key up by id.
+ * @param keyring - The keyring to search.
+ * @param id - A key id, e.g. an envelope's `keyId`.
+ * @returns The entry, or `undefined` when this keyring doesn't have it.
+ */
+export declare function findKeyringKey(keyring: BackupKeyring, id: string): BackupKeyringEntry | undefined;
+/**
+ * Returns the key new backups should be encrypted with.
+ * @param keyring - The keyring.
+ * @returns The current entry, or `undefined` when the keyring has none.
+ */
+export declare function getCurrentKey(keyring: BackupKeyring): BackupKeyringEntry | undefined;
+/**
+ * Adds `key` (a no-op if already there). It becomes the current key when
+ * `makeCurrent` is set or when the keyring had none.
+ */
+export declare function addKeyToKeyring(keyring: BackupKeyring, key: Uint8Array, { makeCurrent, createdAt }?: {
+    makeCurrent?: boolean | undefined;
+    createdAt?: number | undefined;
+}): BackupKeyring;
+/** Returns the keyring with a current key, generating one if it had none. */
+export declare function ensureCurrentKey(keyring: BackupKeyring, randomBytes?: RandomBytes): BackupKeyring;
+/**
+ * Union of two keyrings. `preferred`'s current key wins (e.g. the one already
+ * on the cloud, so every device converges on it), falling back to `other`'s.
+ */
+export declare function mergeKeyrings(preferred: BackupKeyring, other: BackupKeyring): BackupKeyring;
+/** Same current key and same set of keys — i.e. nothing to save or upload. */
+export declare function sameKeyring(a: BackupKeyring, b: BackupKeyring): boolean;
+/**
+ * Decrypts with whichever key of the keyring the backup was written with.
+ * Throws `unknown-key` if none matches.
+ */
+export declare function decryptBackupWithKeyring(content: string, keyring: BackupKeyring): string;
+/**
+ * JSON form, for a secure store or a private cloud file. Contains the raw keys.
+ */
+export declare function serializeKeyring(keyring: BackupKeyring): string;
+/**
+ * Reverse of {@link serializeKeyring}. Key ids are recomputed from the keys
+ * rather than trusted; a `currentId` that matches none of them is dropped.
+ */
+export declare function parseKeyring(content: string): BackupKeyring;
+//# sourceMappingURL=keyring.d.ts.map

package/dist/keyring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring.d.ts","sourceRoot":"","sources":["../src/keyring.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAGpE,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,GAAG,EAAE,UAAU,CAAC;IAChB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,aAA6C,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,GACrB,kBAAkB,GAAG,SAAS,CAIhC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,UAAU,EACf,EAAE,WAAmB,EAAE,SAAsB,EAAE;;;CAAK,GACnD,aAAa,CAQf;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,WAAW,GAAE,WAAgC,GAC5C,aAAa,CAKf;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,aAAa,GACnB,aAAa,CAMf;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAMvE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,GACrB,MAAM,CAKR;AASD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAW/D;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAmC3D"}

package/dist/keyring.js

@@ -0,0 +1,134 @@
+import { decodeBackupKey, defaultRandomBytes, encodeBackupKey, generateBackupKey, getBackupKeyId, } from "./backupKey.js";
+import { decryptBackup, readEncryptedBackup } from "./envelope.js";
+import { BackupCryptoError } from "./errors.js";
+/**
+ * Value of the `format` field of a serialized keyring (see {@link
+ * serializeKeyring}).
+ */
+export const BACKUP_KEYRING_FORMAT = "forthtilliath.backup-keyring";
+const BACKUP_KEYRING_VERSION = 1;
+/**
+ * A keyring with no key, the starting point before {@link ensureCurrentKey}.
+ */
+export const emptyKeyring = { currentId: null, keys: [] };
+/**
+ * Looks a key up by id.
+ * @param keyring - The keyring to search.
+ * @param id - A key id, e.g. an envelope's `keyId`.
+ * @returns The entry, or `undefined` when this keyring doesn't have it.
+ */
+export function findKeyringKey(keyring, id) {
+    return keyring.keys.find((entry) => entry.id === id);
+}
+/**
+ * Returns the key new backups should be encrypted with.
+ * @param keyring - The keyring.
+ * @returns The current entry, or `undefined` when the keyring has none.
+ */
+export function getCurrentKey(keyring) {
+    return keyring.currentId === null
+        ? undefined
+        : findKeyringKey(keyring, keyring.currentId);
+}
+/**
+ * Adds `key` (a no-op if already there). It becomes the current key when
+ * `makeCurrent` is set or when the keyring had none.
+ */
+export function addKeyToKeyring(keyring, key, { makeCurrent = false, createdAt = Date.now() } = {}) {
+    const id = getBackupKeyId(key);
+    const keys = findKeyringKey(keyring, id)
+        ? keyring.keys
+        : [...keyring.keys, { id, key, createdAt }];
+    const currentId = makeCurrent || keyring.currentId === null ? id : keyring.currentId;
+    return { currentId, keys };
+}
+/** Returns the keyring with a current key, generating one if it had none. */
+export function ensureCurrentKey(keyring, randomBytes = defaultRandomBytes) {
+    if (getCurrentKey(keyring))
+        return keyring;
+    return addKeyToKeyring(keyring, generateBackupKey(randomBytes), {
+        makeCurrent: true,
+    });
+}
+/**
+ * Union of two keyrings. `preferred`'s current key wins (e.g. the one already
+ * on the cloud, so every device converges on it), falling back to `other`'s.
+ */
+export function mergeKeyrings(preferred, other) {
+    const keys = [...preferred.keys];
+    for (const entry of other.keys) {
+        if (!findKeyringKey(preferred, entry.id))
+            keys.push(entry);
+    }
+    return { currentId: preferred.currentId ?? other.currentId, keys };
+}
+/** Same current key and same set of keys — i.e. nothing to save or upload. */
+export function sameKeyring(a, b) {
+    return (a.currentId === b.currentId &&
+        a.keys.length === b.keys.length &&
+        a.keys.every((entry) => findKeyringKey(b, entry.id)));
+}
+/**
+ * Decrypts with whichever key of the keyring the backup was written with.
+ * Throws `unknown-key` if none matches.
+ */
+export function decryptBackupWithKeyring(content, keyring) {
+    const { keyId } = readEncryptedBackup(content);
+    const entry = findKeyringKey(keyring, keyId);
+    if (!entry)
+        throw new BackupCryptoError("unknown-key");
+    return decryptBackup(content, entry.key);
+}
+/**
+ * JSON form, for a secure store or a private cloud file. Contains the raw keys.
+ */
+export function serializeKeyring(keyring) {
+    const serialized = {
+        format: BACKUP_KEYRING_FORMAT,
+        version: BACKUP_KEYRING_VERSION,
+        currentId: keyring.currentId,
+        keys: keyring.keys.map(({ key, createdAt }) => ({
+            key: encodeBackupKey(key),
+            createdAt,
+        })),
+    };
+    return JSON.stringify(serialized);
+}
+function corrupted() {
+    return new BackupCryptoError("corrupted", "Malformed backup keyring.");
+}
+/**
+ * Reverse of {@link serializeKeyring}. Key ids are recomputed from the keys
+ * rather than trusted; a `currentId` that matches none of them is dropped.
+ */
+export function parseKeyring(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw corrupted();
+    }
+    const data = parsed;
+    if (data?.format !== BACKUP_KEYRING_FORMAT) {
+        throw corrupted();
+    }
+    if (typeof data.version !== "number" ||
+        data.version > BACKUP_KEYRING_VERSION) {
+        throw new BackupCryptoError("unsupported-version");
+    }
+    if (!Array.isArray(data.keys))
+        throw corrupted();
+    let keyring = emptyKeyring;
+    for (const entry of data.keys) {
+        const { key, createdAt } = (entry ?? {});
+        if (typeof key !== "string" || typeof createdAt !== "number")
+            throw corrupted();
+        keyring = addKeyToKeyring(keyring, decodeBackupKey(key), { createdAt });
+    }
+    const currentId = typeof data.currentId === "string" &&
+        findKeyringKey(keyring, data.currentId)
+        ? data.currentId
+        : null;
+    return { ...keyring, currentId };
+}

package/dist/recoveryCode.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Human-friendly form of a key, to write down or store in a password manager:
+ * Crockford base32 (no I/L/O/U, case-insensitive) in dash-separated groups of
+ * 5, with a 16-bit checksum so a typo is reported as such instead of silently
+ * yielding a different key. 55 characters, e.g. `7K3QD-…-XW0`.
+ */
+export declare function formatRecoveryCode(key: Uint8Array): string;
+/**
+ * Reverse of {@link formatRecoveryCode}. Tolerant of what people actually
+ * type: lowercase, spaces, missing or extra dashes, and I/L/O mistaken for
+ * 1/1/0. Throws `invalid-recovery-code` on a wrong length or checksum.
+ */
+export declare function parseRecoveryCode(code: string): Uint8Array;
+//# sourceMappingURL=recoveryCode.d.ts.map

package/dist/recoveryCode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryCode.d.ts","sourceRoot":"","sources":["../src/recoveryCode.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAU1D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAkB1D"}

package/dist/recoveryCode.js

@@ -0,0 +1,51 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { base32crockford } from "@scure/base";
+import { BACKUP_KEY_LENGTH } from "./backupKey.js";
+import { BackupCryptoError } from "./errors.js";
+const CHECKSUM_LENGTH = 2;
+const GROUP_SIZE = 5;
+function checksum(key) {
+    return sha256(key).subarray(0, CHECKSUM_LENGTH);
+}
+/**
+ * Human-friendly form of a key, to write down or store in a password manager:
+ * Crockford base32 (no I/L/O/U, case-insensitive) in dash-separated groups of
+ * 5, with a 16-bit checksum so a typo is reported as such instead of silently
+ * yielding a different key. 55 characters, e.g. `7K3QD-…-XW0`.
+ */
+export function formatRecoveryCode(key) {
+    const payload = new Uint8Array(BACKUP_KEY_LENGTH + CHECKSUM_LENGTH);
+    payload.set(key);
+    payload.set(checksum(key), BACKUP_KEY_LENGTH);
+    const code = base32crockford.encode(payload);
+    const groups = [];
+    for (let i = 0; i < code.length; i += GROUP_SIZE) {
+        groups.push(code.slice(i, i + GROUP_SIZE));
+    }
+    return groups.join("-");
+}
+/**
+ * Reverse of {@link formatRecoveryCode}. Tolerant of what people actually
+ * type: lowercase, spaces, missing or extra dashes, and I/L/O mistaken for
+ * 1/1/0. Throws `invalid-recovery-code` on a wrong length or checksum.
+ */
+export function parseRecoveryCode(code) {
+    const normalized = code.toUpperCase().replace(/[^0-9A-Z]/g, "");
+    let payload;
+    try {
+        payload = base32crockford.decode(normalized);
+    }
+    catch {
+        throw new BackupCryptoError("invalid-recovery-code");
+    }
+    if (payload.length !== BACKUP_KEY_LENGTH + CHECKSUM_LENGTH) {
+        throw new BackupCryptoError("invalid-recovery-code");
+    }
+    const key = payload.slice(0, BACKUP_KEY_LENGTH);
+    const expected = checksum(key);
+    const actual = payload.subarray(BACKUP_KEY_LENGTH);
+    if (expected[0] !== actual[0] || expected[1] !== actual[1]) {
+        throw new BackupCryptoError("invalid-recovery-code");
+    }
+    return key;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@forthtilliath/backup-crypto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Forthtilliath/forthtilliath-packages.git",
+    "directory": "packages/backup-crypto"
+  },
+  "homepage": "https://github.com/Forthtilliath/forthtilliath-packages/tree/main/packages/backup-crypto#readme",
+  "bugs": "https://github.com/Forthtilliath/forthtilliath-packages/issues",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@scure/base": "^2.4.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "5.0.5",
+    "eslint": "10.14.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5",
+    "@forthtilliath/eslint-config": "0.10.2",
+    "@forthtilliath/typescript-config": "0.1.1"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  }
 }