@forthtilliath/backup-crypto 0.1.0 → 0.1.1

package/README.md

@@ -69,6 +69,28 @@ A keyring keeps every key an app ever encrypted with, so files written before a
 | `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`.

package/dist/backupKey.d.ts

@@ -8,7 +8,14 @@ export type RandomBytes = (length: number) => Uint8Array;
  * 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. */
+/**
+ * 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
@@ -18,6 +25,9 @@ export declare function generateBackupKey(randomBytes?: RandomBytes): Uint8Array
 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. */
+/**
+ * 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

@@ -1 +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,iDAAiD;AACjD,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,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAW3D"}
+{"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

@@ -17,7 +17,14 @@ export function defaultRandomBytes(length) {
     }
     return webCrypto.getRandomValues(new Uint8Array(length));
 }
-/** Generates a new random 256-bit backup key. */
+/**
+ * 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) {
@@ -40,7 +47,10 @@ export function getBackupKeyId(key) {
 export function encodeBackupKey(key) {
     return base64.encode(key);
 }
-/** Reverse of {@link encodeBackupKey}. Throws `corrupted` on anything else than a 256-bit key. */
+/**
+ * Reverse of {@link encodeBackupKey}. Throws `corrupted` on anything else than
+ * a 256-bit key.
+ */
 export function decodeBackupKey(encoded) {
     let key;
     try {

package/dist/envelope.d.ts

@@ -1,5 +1,13 @@
 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";
 /**
@@ -8,19 +16,36 @@ declare const CIPHER = "xchacha20-poly1305";
  * 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;
 }
 /**

package/dist/envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAGxB,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AACxE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,QAAA,MAAM,MAAM,uBAAuB,CAAC;AAGpC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,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"}
+{"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

@@ -3,7 +3,15 @@ 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;

package/dist/errors.d.ts

@@ -11,6 +11,11 @@
  *   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);

package/dist/errors.d.ts.map

@@ -1 +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,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;gBAEzB,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,MAAM;CAK1D"}
+{"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

@@ -1,3 +1,8 @@
+/**
+ * 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) {

package/dist/keyring.d.ts

@@ -1,7 +1,20 @@
 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;
@@ -12,11 +25,33 @@ export interface BackupKeyringEntry {
  * 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
@@ -40,7 +75,9 @@ export declare function sameKeyring(a: BackupKeyring, b: BackupKeyring): boolean
  * 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. */
+/**
+ * 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

package/dist/keyring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyring.d.ts","sourceRoot":"","sources":["../src/keyring.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAIxB,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAGpE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,UAAU,CAAC;IAChB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,YAAY,EAAE,aAA6C,CAAC;AAEzE,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,MAAM,GACT,kBAAkB,GAAG,SAAS,CAEhC;AAED,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,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAW/D;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAmC3D"}
+{"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

@@ -1,12 +1,30 @@
 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
@@ -61,7 +79,9 @@ export function decryptBackupWithKeyring(content, keyring) {
         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. */
+/**
+ * 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/backup-crypto",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -27,11 +27,11 @@
     "@scure/base": "^2.4.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "5.0.2",
-    "eslint": "10.7.0",
+    "@vitest/coverage-v8": "5.0.5",
+    "eslint": "10.14.0",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.2",
-    "@forthtilliath/eslint-config": "0.9.0",
+    "vitest": "^5.0.5",
+    "@forthtilliath/eslint-config": "0.10.2",
     "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {