@robota-sdk/agent-keyring 0.0.0-stage → 3.1.1

package/src/key-pairs.ts

@@ -0,0 +1,148 @@
+import { Buffer } from 'node:buffer';
+import { createPrivateKey, createPublicKey, randomBytes, type KeyObject } from 'node:crypto';
+
+import { isBytes, wipe } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { hkdf32, KEY_BYTES } from './kdf.js';
+
+/**
+ * The HKDF `info` labels. They are versioned and part of the on-disk contract: changing a byte
+ * changes every derived key, so the known-answer tests pin the public keys they produce.
+ */
+export const SEALING_KEY_LABEL = 'robota/keyring/v1/sealing-x25519';
+export const ATTACH_KEY_LABEL = 'robota/keyring/v1/attach-ed25519';
+
+// `node:crypto` has no "private key from raw seed" import that Bun and Node both accept, so the raw
+// 32-byte seed is wrapped in the fixed PKCS#8 / SPKI headers of RFC 8410.
+const PKCS8_X25519_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const SPKI_X25519_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+const SPKI_ED25519_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const SPKI_PREFIX_BYTES = SPKI_X25519_PREFIX.length;
+
+export interface IKeyPair {
+  /** The raw 32-byte public key. */
+  readonly publicKey: Uint8Array;
+  readonly privateKey: KeyObject;
+}
+
+export interface IDerivedKeyPairs {
+  readonly sealing: IKeyPair;
+  readonly attach: IKeyPair;
+}
+
+/** The raw 32-byte public key of an X25519 or Ed25519 key object. */
+export function rawPublicKey(key: KeyObject): Buffer {
+  try {
+    const spki = (key.type === 'public' ? key : createPublicKey(key)).export({
+      format: 'der',
+      type: 'spki',
+    });
+    return Buffer.from(spki.subarray(SPKI_PREFIX_BYTES));
+  } catch {
+    throw new KeyringError('invalid-argument', 'The key has no exportable public key.');
+  }
+}
+
+/** An X25519 public key object from its raw 32 bytes, from any realm (see `isBytes`). */
+export function x25519PublicKeyFromRaw(raw: Uint8Array): KeyObject {
+  if (!isBytes(raw) || raw.length !== KEY_BYTES) {
+    throw new KeyringError('invalid-argument', 'A public key must be exactly 32 bytes.');
+  }
+  try {
+    return createPublicKey({
+      key: Buffer.concat([SPKI_X25519_PREFIX, raw]),
+      format: 'der',
+      type: 'spki',
+    });
+  } catch {
+    throw new KeyringError('invalid-argument', 'The public key is not a valid X25519 key.');
+  }
+}
+
+/** An Ed25519 public key object from its raw 32 bytes, from any realm (see `isBytes`). */
+export function ed25519PublicKeyFromRaw(raw: Uint8Array): KeyObject {
+  if (!isBytes(raw) || raw.length !== KEY_BYTES) {
+    throw new KeyringError('invalid-argument', 'A public key must be exactly 32 bytes.');
+  }
+  try {
+    return createPublicKey({
+      key: Buffer.concat([SPKI_ED25519_PREFIX, raw]),
+      format: 'der',
+      type: 'spki',
+    });
+  } catch {
+    throw new KeyringError('invalid-argument', 'The public key is not a valid Ed25519 key.');
+  }
+}
+
+/** A keypair from a derived seed; a host that cannot build one fails as `kdf-failed`, whatever it threw. */
+function keyPairFromSeed(prefix: Buffer, seed: Uint8Array): IKeyPair {
+  const pkcs8 = Buffer.concat([prefix, seed]);
+  try {
+    const privateKey = createPrivateKey({ key: pkcs8, format: 'der', type: 'pkcs8' });
+    return { publicKey: rawPublicKey(privateKey), privateKey };
+  } catch {
+    throw new KeyringError('kdf-failed', 'The key derivation could not run on this host.');
+  } finally {
+    wipe(pkcs8);
+  }
+}
+
+/** The X25519 keypair a 32-byte seed makes: what a sealing seed, derived or granted, becomes. */
+export function x25519KeyPairFromSeed(seed: Uint8Array): IKeyPair {
+  return keyPairFromSeed(PKCS8_X25519_PREFIX, seed);
+}
+
+/** The Ed25519 keypair a 32-byte seed makes. */
+export function ed25519KeyPairFromSeed(seed: Uint8Array): IKeyPair {
+  return keyPairFromSeed(PKCS8_ED25519_PREFIX, seed);
+}
+
+/** The sealing keypair's seed; the caller wipes it. */
+export function deriveSealingSeed(masterKey: Uint8Array): Buffer {
+  return hkdf32(masterKey, SEALING_KEY_LABEL);
+}
+
+/** The attach keypair alone, for the one holder that may have it (the owner handover). */
+export function deriveAttachKeyPair(masterKey: Uint8Array): IKeyPair {
+  const attachSeed = hkdf32(masterKey, ATTACH_KEY_LABEL);
+  try {
+    return keyPairFromSeed(PKCS8_ED25519_PREFIX, attachSeed);
+  } finally {
+    wipe(attachSeed);
+  }
+}
+
+/**
+ * Derives the two long-lived keypairs from the master key: an X25519 sealing keypair and an Ed25519
+ * attach keypair, each from its own HKDF-SHA256 seed (empty salt, versioned `info` label), so
+ * neither key says anything about the other.
+ */
+export function deriveKeyPairs(masterKey: Uint8Array): IDerivedKeyPairs {
+  const sealingSeed = hkdf32(masterKey, SEALING_KEY_LABEL);
+  const attachSeed = hkdf32(masterKey, ATTACH_KEY_LABEL);
+  try {
+    return {
+      sealing: keyPairFromSeed(PKCS8_X25519_PREFIX, sealingSeed),
+      attach: keyPairFromSeed(PKCS8_ED25519_PREFIX, attachSeed),
+    };
+  } finally {
+    wipe(sealingSeed, attachSeed);
+  }
+}
+
+/**
+ * A new X25519 sealing keypair from a random seed, for a key that lives only in the memory of the
+ * process that made it: nothing derives it again, so whatever is sealed to it opens only while that
+ * process keeps the private key. Built from the seed as the derived pairs are, so it has their shape
+ * on every runtime.
+ */
+export function generateTransientSealingKeyPair(): IKeyPair {
+  const seed = randomBytes(KEY_BYTES);
+  try {
+    return keyPairFromSeed(PKCS8_X25519_PREFIX, seed);
+  } finally {
+    wipe(seed);
+  }
+}

package/src/keyring-document.ts

@@ -0,0 +1,168 @@
+import { Buffer } from 'node:buffer';
+
+import { fromBase64Url } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { GCM_IV_BYTES, GCM_TAG_BYTES } from './aead.js';
+import { KEY_BYTES, SCRYPT_SALT_BYTES } from './kdf.js';
+import {
+  KEYRING_VERSION,
+  type IKeyring,
+  type IPassphraseKeyslot,
+  type IRecoveryKeyslot,
+  type TKeyslot,
+} from './keyring-types.js';
+
+export const SLOT_ID_BYTES = 16;
+export const WRAPPED_KEY_BYTES = KEY_BYTES + GCM_TAG_BYTES;
+/** A keyring is a few hundred bytes; anything near this size is not one. */
+export const MAX_KEYRING_JSON_CHARS = 16 * 1024;
+export const MAX_KEYSLOTS = 8;
+
+const KEYRING_KEYS = ['version', 'sealingPublicKey', 'slots'];
+const SLOT_COMMON_KEYS = ['id', 'type', 'iv', 'wrappedKey'];
+const PASSPHRASE_SLOT_KEYS = [...SLOT_COMMON_KEYS, 'kdf'];
+const KDF_KEYS = ['algorithm', 'N', 'r', 'p', 'salt'];
+
+function malformed(detail: string): KeyringError {
+  return new KeyringError('malformed-keyring', `The keyring is malformed: ${detail}.`);
+}
+
+/** A plain data object (JSON-shaped), not an array, class instance or null-prototype oddity. */
+function asRecord(value: unknown, what: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw malformed(`${what} must be an object`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw malformed(`${what} must be a plain object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+/** Exactly the allowed own keys: an unknown key (including `__proto__` as data) is refused. */
+function requireExactKeys(record: Record<string, unknown>, allowed: string[], what: string): void {
+  const keys = Object.keys(record);
+  if (keys.length !== allowed.length || keys.some((key) => !allowed.includes(key))) {
+    throw malformed(`${what} must have exactly the fields ${allowed.join(', ')}`);
+  }
+}
+
+function requireBytes(value: unknown, length: number, what: string): string {
+  if (fromBase64Url(value, length) === undefined) {
+    throw malformed(`${what} must be canonical base64url of ${length} bytes`);
+  }
+  return value as string;
+}
+
+function requirePositiveInteger(value: unknown, what: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+    throw malformed(`${what} must be a positive integer`);
+  }
+  return value;
+}
+
+function readPassphraseSlot(record: Record<string, unknown>, what: string): IPassphraseKeyslot {
+  requireExactKeys(record, PASSPHRASE_SLOT_KEYS, what);
+  const kdf = asRecord(record.kdf, `${what}.kdf`);
+  requireExactKeys(kdf, KDF_KEYS, `${what}.kdf`);
+  if (kdf.algorithm !== 'scrypt') throw malformed(`${what}.kdf.algorithm must be "scrypt"`);
+  // Built field by field in the document's fixed order, so serialization is deterministic.
+  return {
+    id: requireBytes(record.id, SLOT_ID_BYTES, `${what}.id`),
+    type: 'passphrase',
+    kdf: Object.freeze({
+      algorithm: 'scrypt',
+      N: requirePositiveInteger(kdf.N, `${what}.kdf.N`),
+      r: requirePositiveInteger(kdf.r, `${what}.kdf.r`),
+      p: requirePositiveInteger(kdf.p, `${what}.kdf.p`),
+      salt: requireBytes(kdf.salt, SCRYPT_SALT_BYTES, `${what}.kdf.salt`),
+    } as const),
+    iv: requireBytes(record.iv, GCM_IV_BYTES, `${what}.iv`),
+    wrappedKey: requireBytes(record.wrappedKey, WRAPPED_KEY_BYTES, `${what}.wrappedKey`),
+  };
+}
+
+function readRecoverySlot(record: Record<string, unknown>, what: string): IRecoveryKeyslot {
+  requireExactKeys(record, SLOT_COMMON_KEYS, what);
+  return {
+    id: requireBytes(record.id, SLOT_ID_BYTES, `${what}.id`),
+    type: 'recovery',
+    iv: requireBytes(record.iv, GCM_IV_BYTES, `${what}.iv`),
+    wrappedKey: requireBytes(record.wrappedKey, WRAPPED_KEY_BYTES, `${what}.wrappedKey`),
+  };
+}
+
+function readSlot(value: unknown, index: number): TKeyslot {
+  const what = `slots[${index}]`;
+  const record = asRecord(value, what);
+  switch (record.type) {
+    case 'passphrase':
+      return Object.freeze(readPassphraseSlot(record, what));
+    case 'recovery':
+      return Object.freeze(readRecoverySlot(record, what));
+    default:
+      // Not "ignore and carry on": dropping an unknown slot on the next write would destroy it.
+      throw malformed(`${what}.type is not a known slot type`);
+  }
+}
+
+/**
+ * Validates a version-1 keyring document and returns a fresh, frozen copy built only from
+ * validated primitives — nothing from the input object (and nothing from its prototype chain)
+ * is carried over. Used by `parseKeyring` and by every operation that accepts a keyring, so a
+ * hand-built object gets the same scrutiny as a parsed file.
+ */
+export function validateKeyring(value: unknown): IKeyring {
+  const record = asRecord(value, 'the document');
+  // Version first: a future document may legitimately have a different shape.
+  if (record.version !== KEYRING_VERSION) {
+    if (typeof record.version === 'number' && Number.isSafeInteger(record.version)) {
+      throw new KeyringError(
+        'unsupported-version',
+        'The keyring was written by a version this build does not support.',
+      );
+    }
+    throw malformed('version must be an integer');
+  }
+  requireExactKeys(record, KEYRING_KEYS, 'the document');
+  const sealingPublicKey = requireBytes(record.sealingPublicKey, KEY_BYTES, 'sealingPublicKey');
+  if (
+    !Array.isArray(record.slots) ||
+    record.slots.length < 1 ||
+    record.slots.length > MAX_KEYSLOTS
+  ) {
+    throw malformed(`slots must be an array of 1 to ${MAX_KEYSLOTS} entries`);
+  }
+  const slots = record.slots.map((slot, index) => readSlot(slot, index));
+  if (new Set(slots.map((slot) => slot.id)).size !== slots.length) {
+    throw malformed('slot ids must be unique');
+  }
+  return Object.freeze({
+    version: KEYRING_VERSION,
+    sealingPublicKey,
+    slots: Object.freeze(slots),
+  });
+}
+
+/** Parses keyring JSON strictly; see {@link validateKeyring}. */
+export function parseKeyring(json: string): IKeyring {
+  if (typeof json !== 'string') throw malformed('the document must be a JSON string');
+  if (json.length > MAX_KEYRING_JSON_CHARS) throw malformed('the document is too large');
+  let value: unknown;
+  try {
+    value = JSON.parse(json);
+  } catch {
+    throw malformed('the document is not valid JSON');
+  }
+  return validateKeyring(value);
+}
+
+/** The keyring as JSON with a fixed field order, ready to write to disk. */
+export function serializeKeyring(keyring: IKeyring): string {
+  return JSON.stringify(validateKeyring(keyring), null, 2);
+}
+
+/** The raw 32-byte sealing public key — all a locked process needs to seal new artifacts. */
+export function getSealingPublicKey(keyring: IKeyring): Buffer {
+  return Buffer.from(validateKeyring(keyring).sealingPublicKey, 'base64url');
+}

package/src/keyring-types.ts

@@ -0,0 +1,51 @@
+/** The only keyring document version this build reads and writes. */
+export const KEYRING_VERSION = 1;
+
+/**
+ * How a passphrase slot stretches the passphrase. All fields are stored in the slot so a keyring
+ * written at one cost still unlocks after the default cost changes.
+ */
+export interface IScryptKdfParameters {
+  readonly algorithm: 'scrypt';
+  readonly N: number;
+  readonly r: number;
+  readonly p: number;
+  /** base64url, 16 bytes. */
+  readonly salt: string;
+}
+
+interface IKeyslotBase {
+  /** base64url, 16 random bytes; bound into the wrapping AAD. */
+  readonly id: string;
+  /** base64url, 12 bytes. */
+  readonly iv: string;
+  /** base64url, the AES-256-GCM-wrapped master key plus its 16-byte tag (48 bytes). */
+  readonly wrappedKey: string;
+}
+
+export interface IPassphraseKeyslot extends IKeyslotBase {
+  readonly type: 'passphrase';
+  readonly kdf: IScryptKdfParameters;
+}
+
+export interface IRecoveryKeyslot extends IKeyslotBase {
+  readonly type: 'recovery';
+}
+
+/**
+ * A keyslot is a tagged union on `type`: a future way to unlock (a device secret, for example) adds
+ * a member here and a branch in the parser, without touching the existing slots.
+ */
+export type TKeyslot = IPassphraseKeyslot | IRecoveryKeyslot;
+export type TKeyslotType = TKeyslot['type'];
+
+/**
+ * The persisted keyring document. There is deliberately no field for the attach public key: the
+ * file lets anyone seal to the owner, but nothing in it lets a program claim to be the owner.
+ */
+export interface IKeyring {
+  readonly version: typeof KEYRING_VERSION;
+  /** base64url, the raw 32-byte X25519 sealing public key. */
+  readonly sealingPublicKey: string;
+  readonly slots: readonly TKeyslot[];
+}

package/src/keyring.ts

@@ -0,0 +1,307 @@
+import type { Buffer } from 'node:buffer';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+import { deriveAuthorshipKey } from './authorship.js';
+import { decodeKeyringField, toBase64Url, wipe } from './bytes.js';
+import { KeyringError } from './errors.js';
+import {
+  deriveKeyPairs,
+  deriveSealingSeed,
+  x25519KeyPairFromSeed,
+  type IDerivedKeyPairs,
+} from './key-pairs.js';
+import {
+  assertScryptParametersInBounds,
+  DEFAULT_SCRYPT_PARAMETERS,
+  deriveKeyFromPassphrase,
+  KEY_BYTES,
+  normalizePassphrase,
+  SCRYPT_SALT_BYTES,
+} from './kdf.js';
+import { getSealingPublicKey, validateKeyring } from './keyring-document.js';
+import {
+  KEYRING_VERSION,
+  type IKeyring,
+  type IPassphraseKeyslot,
+  type IRecoveryKeyslot,
+  type TKeyslot,
+} from './keyring-types.js';
+import { deriveRecoveryKek, newSlotId, unwrapMasterKey, wrapMasterKey } from './keyslot.js';
+import { formatRecoveryKey, parseRecoveryKey, RECOVERY_KEY_BYTES } from './recovery-key.js';
+import { createReadKeys, type IReadKeys } from './read-keys.js';
+
+/** What proves the right to open a keyring. A tagged union so a future credential is one more member. */
+export type TKeyringCredential =
+  | { readonly type: 'passphrase'; readonly passphrase: string }
+  | { readonly type: 'recoveryKey'; readonly recoveryKey: string };
+
+export interface ICreateKeyringOptions {
+  /** Any non-empty string; minimum length and strength are the caller's policy. */
+  readonly passphrase: string;
+}
+
+export interface ICreatedKeyring {
+  readonly keyring: IKeyring;
+  /**
+   * The recovery key, formatted for a person to write down. It exists only here: it is not stored
+   * anywhere and cannot be shown again, so the caller must present it exactly once.
+   */
+  readonly recoveryKey: string;
+  readonly unlocked: IReadKeys;
+}
+
+export interface IAssembleKeyringInput {
+  readonly masterKey: Uint8Array;
+  /** Normalized passphrase bytes (see `normalizePassphrase`). */
+  readonly passphrase: Uint8Array;
+  readonly recoveryKeyBytes: Uint8Array;
+}
+
+function isPassphraseSlot(slot: TKeyslot): slot is IPassphraseKeyslot {
+  return slot.type === 'passphrase';
+}
+
+function isRecoverySlot(slot: TKeyslot): slot is IRecoveryKeyslot {
+  return slot.type === 'recovery';
+}
+
+async function makePassphraseSlot(
+  masterKey: Uint8Array,
+  passphrase: Uint8Array,
+  slotId: string,
+): Promise<IPassphraseKeyslot> {
+  const salt = randomBytes(SCRYPT_SALT_BYTES);
+  const kek = await deriveKeyFromPassphrase(passphrase, salt, DEFAULT_SCRYPT_PARAMETERS);
+  try {
+    const wrapped = wrapMasterKey(kek, masterKey, slotId, 'passphrase');
+    return {
+      id: slotId,
+      type: 'passphrase',
+      kdf: { algorithm: 'scrypt', ...DEFAULT_SCRYPT_PARAMETERS, salt: toBase64Url(salt) },
+      ...wrapped,
+    };
+  } finally {
+    wipe(kek);
+  }
+}
+
+function makeRecoverySlot(masterKey: Uint8Array, recoveryKeyBytes: Uint8Array): IRecoveryKeyslot {
+  const slotId = newSlotId();
+  const kek = deriveRecoveryKek(recoveryKeyBytes);
+  try {
+    return { id: slotId, type: 'recovery', ...wrapMasterKey(kek, masterKey, slotId, 'recovery') };
+  } finally {
+    wipe(kek);
+  }
+}
+
+/**
+ * Wraps `masterKey` into a fresh keyring with one passphrase slot and one recovery slot. Exposed to
+ * the package's own tests (a fixed master key makes the known-answer vectors possible); it is not
+ * part of the public entry point, whose only way to make a keyring draws the master key at random.
+ */
+export async function assembleKeyring(
+  input: IAssembleKeyringInput,
+): Promise<{ keyring: IKeyring; pairs: IDerivedKeyPairs }> {
+  const pairs = deriveKeyPairs(input.masterKey);
+  const passphraseSlot = await makePassphraseSlot(input.masterKey, input.passphrase, newSlotId());
+  const recoverySlot = makeRecoverySlot(input.masterKey, input.recoveryKeyBytes);
+  const keyring = validateKeyring({
+    version: KEYRING_VERSION,
+    sealingPublicKey: toBase64Url(pairs.sealing.publicKey),
+    slots: [passphraseSlot, recoverySlot],
+  });
+  return { keyring, pairs };
+}
+
+/**
+ * Creates a keyring around a new random 256-bit master key, protected by the passphrase and by a
+ * new recovery key, and returns it already unlocked. The master key is wiped before this returns.
+ */
+export async function createKeyring(options: ICreateKeyringOptions): Promise<ICreatedKeyring> {
+  const passphrase = normalizePassphrase(options.passphrase);
+  const masterKey = randomBytes(KEY_BYTES);
+  const recoveryKeyBytes = randomBytes(RECOVERY_KEY_BYTES);
+  try {
+    const { keyring, pairs } = await assembleKeyring({ masterKey, passphrase, recoveryKeyBytes });
+    return {
+      keyring,
+      recoveryKey: formatRecoveryKey(recoveryKeyBytes),
+      unlocked: createReadKeys(pairs.sealing, deriveAuthorshipKey(masterKey)),
+    };
+  } finally {
+    wipe(passphrase, masterKey, recoveryKeyBytes);
+  }
+}
+
+export interface IRecoveredMasterKey {
+  readonly masterKey: Buffer;
+  readonly slotId: string;
+}
+
+function isWrongCredential(error: unknown): boolean {
+  return error instanceof KeyringError && error.code === 'wrong-credential';
+}
+
+async function recoverWithPassphrase(
+  keyring: IKeyring,
+  passphraseText: unknown,
+): Promise<IRecoveredMasterKey> {
+  const passphrase = normalizePassphrase(passphraseText);
+  try {
+    const slots = keyring.slots.filter(isPassphraseSlot);
+    if (slots.length === 0) {
+      throw new KeyringError('slot-not-found', 'The keyring has no passphrase slot.');
+    }
+    // Every slot's cost is checked before the first derivation, so a hostile keyring cannot make
+    // an earlier, in-range slot burn CPU on the way to a refusal.
+    for (const slot of slots) assertScryptParametersInBounds(slot.kdf);
+    for (const slot of slots) {
+      const salt = decodeKeyringField(slot.kdf.salt, SCRYPT_SALT_BYTES);
+      const kek = await deriveKeyFromPassphrase(passphrase, salt, slot.kdf);
+      try {
+        return { masterKey: unwrapMasterKey(kek, slot), slotId: slot.id };
+      } catch (error) {
+        if (!isWrongCredential(error)) throw error;
+      } finally {
+        wipe(kek);
+      }
+    }
+    throw new KeyringError('wrong-credential', 'The credential did not open the keyring.');
+  } finally {
+    wipe(passphrase);
+  }
+}
+
+function recoverWithRecoveryKey(keyring: IKeyring, recoveryKeyText: unknown): IRecoveredMasterKey {
+  const recoveryKeyBytes = parseRecoveryKey(recoveryKeyText);
+  try {
+    const slots = keyring.slots.filter(isRecoverySlot);
+    if (slots.length === 0) {
+      throw new KeyringError('slot-not-found', 'The keyring has no recovery slot.');
+    }
+    for (const slot of slots) {
+      const kek = deriveRecoveryKek(recoveryKeyBytes);
+      try {
+        return { masterKey: unwrapMasterKey(kek, slot), slotId: slot.id };
+      } catch (error) {
+        if (!isWrongCredential(error)) throw error;
+      } finally {
+        wipe(kek);
+      }
+    }
+    throw new KeyringError('wrong-credential', 'The credential did not open the keyring.');
+  } finally {
+    wipe(recoveryKeyBytes);
+  }
+}
+
+/**
+ * The master key `credential` opens, and the slot it opened. The caller owns and wipes it; nothing
+ * outside this package ever sees one.
+ */
+export async function recoverMasterKey(
+  keyring: IKeyring,
+  credential: TKeyringCredential,
+): Promise<IRecoveredMasterKey> {
+  switch (credential?.type) {
+    case 'passphrase':
+      return recoverWithPassphrase(keyring, credential.passphrase);
+    case 'recoveryKey':
+      return recoverWithRecoveryKey(keyring, credential.recoveryKey);
+    default:
+      throw new KeyringError('invalid-argument', 'The credential type is not recognised.');
+  }
+}
+
+async function unlock(keyring: IKeyring, credential: TKeyringCredential): Promise<IReadKeys> {
+  const document = validateKeyring(keyring);
+  const { masterKey } = await recoverMasterKey(document, credential);
+  const sealingSeed = deriveSealingSeed(masterKey);
+  try {
+    return createReadKeys(x25519KeyPairFromSeed(sealingSeed), deriveAuthorshipKey(masterKey));
+  } finally {
+    wipe(masterKey, sealingSeed);
+  }
+}
+
+/**
+ * Unlocks with the passphrase, for reading: the read keys and nothing that proves ownership (see
+ * `openOwnerHandover` for that). Costs one scrypt run per passphrase slot (~160 ms at the default
+ * cost, off the event loop). The stored sealing public key is NOT consulted — see
+ * {@link checkSealingPublicKey}.
+ */
+export function unlockWithPassphrase(keyring: IKeyring, passphrase: string): Promise<IReadKeys> {
+  return unlock(keyring, { type: 'passphrase', passphrase });
+}
+
+/** Unlocks with the recovery key shown at creation (case-insensitive, hyphens optional). */
+export function unlockWithRecoveryKey(keyring: IKeyring, recoveryKey: string): Promise<IReadKeys> {
+  return unlock(keyring, { type: 'recoveryKey', recoveryKey });
+}
+
+/**
+ * Replaces the passphrase slot with one that wraps the same master key under `newPassphrase`, and
+ * returns the new keyring; the input is untouched. Everything encrypted under the keys stays
+ * readable because the master key does not change. The caller must prove the right to change it by
+ * supplying a working credential — the current passphrase, or the recovery key to reset a forgotten
+ * one. The new slot is written at the current default scrypt cost with a fresh salt and IV, and
+ * keeps the old slot's id. The stored sealing public key and the recovery slot are carried over
+ * as they are.
+ */
+export async function changePassphrase(
+  keyring: IKeyring,
+  credential: TKeyringCredential,
+  newPassphrase: string,
+): Promise<IKeyring> {
+  const document = validateKeyring(keyring);
+  const replacement = normalizePassphrase(newPassphrase);
+  let recovered: IRecoveredMasterKey | undefined;
+  try {
+    recovered = await recoverMasterKey(document, credential);
+    const targetId =
+      credential.type === 'passphrase'
+        ? recovered.slotId
+        : document.slots.find(isPassphraseSlot)?.id;
+    if (targetId === undefined) {
+      throw new KeyringError('slot-not-found', 'The keyring has no passphrase slot.');
+    }
+    const slot = await makePassphraseSlot(recovered.masterKey, replacement, targetId);
+    return validateKeyring({
+      ...document,
+      slots: document.slots.map((existing) => (existing.id === targetId ? slot : existing)),
+    });
+  } finally {
+    wipe(replacement, recovered?.masterKey);
+  }
+}
+
+/**
+ * Whether the sealing public key stored in the keyring is the one the master key derives. A
+ * mismatch means the file was altered (an attacker who can write it could substitute their own key
+ * so new artifacts are sealed to them); the stored key cannot be authenticated without the master
+ * key, so this check is only possible after an unlock.
+ */
+export function checkSealingPublicKey(
+  keyring: IKeyring,
+  keys: Pick<IReadKeys, 'sealing'>,
+): { matches: boolean } {
+  return { matches: sealingPublicKeyMatches(keyring, keys.sealing.publicKey) };
+}
+
+/** Whether the keyring's stored sealing public key is `derived`, compared in constant time. */
+export function sealingPublicKeyMatches(keyring: IKeyring, derived: Uint8Array): boolean {
+  const stored = getSealingPublicKey(keyring);
+  return stored.length === derived.length && timingSafeEqual(stored, derived);
+}
+
+/** A copy of the keyring whose stored sealing public key is the one derived from the read keys. */
+export function repairSealingPublicKey(
+  keyring: IKeyring,
+  keys: Pick<IReadKeys, 'sealing'>,
+): IKeyring {
+  return validateKeyring({
+    ...validateKeyring(keyring),
+    sealingPublicKey: toBase64Url(keys.sealing.publicKey),
+  });
+}