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

package/src/__tests__/spawner-exchange.test.ts

@@ -0,0 +1,127 @@
+/**
+ * The spawner exchange: the spawner writes its ephemeral first, the runtime answers with its own and
+ * its instance public key, and both sides derive the spawner key from the one shared secret. Pinned
+ * from fixed ephemerals, and strict about every byte it reads.
+ */
+import { Buffer } from 'node:buffer';
+
+import { describe, expect, it } from 'vitest';
+
+import { SpawnerKey, createRuntimeIdentity, startSpawnerExchange } from '../index.js';
+import { createRuntimeIdentityWith, runtimeIdentitySecrets } from '../runtime-identity.js';
+import { spawnerKeyBytes, startSpawnerExchangeWith } from '../spawner-exchange.js';
+import {
+  KAT_INSTANCE_PUBLIC_KEY_HEX,
+  KAT_INSTANCE_SEED,
+  codeOf,
+  hex,
+  reachableValues,
+} from './helpers.js';
+import {
+  KAT_EXCHANGE,
+  KAT_RUNTIME_EXCHANGE_SEED,
+  KAT_SPAWNER_EPHEMERAL_SEED,
+  fixedEntropy,
+  refusalOf,
+} from './link-helpers.js';
+
+function katPair() {
+  const spawner = startSpawnerExchangeWith(fixedEntropy([KAT_SPAWNER_EPHEMERAL_SEED]));
+  const runtime = createRuntimeIdentityWith(
+    fixedEntropy([KAT_INSTANCE_SEED, KAT_RUNTIME_EXCHANGE_SEED]),
+  );
+  return { spawner, runtime };
+}
+
+describe('the spawner exchange', () => {
+  it('derives the pinned spawner key on both sides from fixed ephemerals', () => {
+    const { spawner, runtime } = katPair();
+    expect(hex(spawner.message)).toBe(KAT_EXCHANGE.spawnerEphemeral);
+    const reply = runtime.answerSpawnerExchange(spawner.message);
+    expect(hex(reply)).toBe(KAT_EXCHANGE.runtimeEphemeral + KAT_INSTANCE_PUBLIC_KEY_HEX);
+    const result = spawner.complete(reply);
+    expect(hex(result.instancePublicKey)).toBe(KAT_INSTANCE_PUBLIC_KEY_HEX);
+    expect(hex(spawnerKeyBytes(result.spawnerKey))).toBe(KAT_EXCHANGE.spawnerKey);
+    expect(hex(runtimeIdentitySecrets(runtime).spawnerKey() ?? Buffer.alloc(0))).toBe(
+      KAT_EXCHANGE.spawnerKey,
+    );
+  });
+
+  it('draws fresh ephemerals every time, so no two exchanges share a key', () => {
+    const keys = new Set<string>();
+    for (let index = 0; index < 4; index += 1) {
+      const spawner = startSpawnerExchange();
+      expect(spawner.message).toHaveLength(32);
+      const runtime = createRuntimeIdentity();
+      const { spawnerKey, instancePublicKey } = spawner.complete(
+        runtime.answerSpawnerExchange(spawner.message),
+      );
+      expect(hex(instancePublicKey)).toBe(hex(runtime.instancePublicKey));
+      keys.add(hex(spawnerKeyBytes(spawnerKey)));
+    }
+    expect(keys.size).toBe(4);
+  });
+
+  it('completes once, and only with a reply of exactly an ephemeral and an instance key', () => {
+    const lowOrder = Buffer.concat([Buffer.alloc(32), Buffer.alloc(32, 1)]);
+    for (const reply of [Buffer.alloc(63, 9), Buffer.alloc(65, 9), lowOrder, 'reply' as never]) {
+      expect(refusalOf(() => startSpawnerExchange().complete(reply))).toBe('malformed');
+    }
+    const { spawner, runtime } = katPair();
+    const reply = runtime.answerSpawnerExchange(spawner.message);
+    spawner.complete(reply);
+    expect(refusalOf(() => spawner.complete(reply))).toBe('out-of-order');
+    const spent = startSpawnerExchange();
+    expect(refusalOf(() => spent.complete(Buffer.alloc(10)))).toBe('malformed');
+    expect(refusalOf(() => spent.complete(reply))).toBe('out-of-order');
+  });
+
+  it('is answered once by a runtime, and only for exactly an ephemeral', () => {
+    for (const message of [
+      Buffer.alloc(31, 9),
+      Buffer.alloc(33, 9),
+      Buffer.alloc(32),
+      7 as never,
+    ]) {
+      expect(refusalOf(() => createRuntimeIdentity().answerSpawnerExchange(message))).toBe(
+        'malformed',
+      );
+    }
+    const runtime = createRuntimeIdentity();
+    expect(runtime.spawnerKeyHeld).toBe(false);
+    runtime.answerSpawnerExchange(startSpawnerExchange().message);
+    expect(runtime.spawnerKeyHeld).toBe(true);
+    expect(refusalOf(() => runtime.answerSpawnerExchange(startSpawnerExchange().message))).toBe(
+      'out-of-order',
+    );
+    const refusedOnce = createRuntimeIdentity();
+    expect(refusalOf(() => refusedOnce.answerSpawnerExchange(Buffer.alloc(3)))).toBe('malformed');
+    expect(refusalOf(() => refusedOnce.answerSpawnerExchange(startSpawnerExchange().message))).toBe(
+      'out-of-order',
+    );
+    expect(refusedOnce.spawnerKeyHeld).toBe(false);
+  });
+});
+
+describe('a spawner key', () => {
+  it('is opaque: nothing reachable from it is key bytes', () => {
+    const { spawner, runtime } = katPair();
+    const { spawnerKey } = spawner.complete(runtime.answerSpawnerExchange(spawner.message));
+    expect(spawnerKey).toBeInstanceOf(SpawnerKey);
+    expect(reachableValues(spawnerKey).some((value) => ArrayBuffer.isView(value))).toBe(false);
+    expect(JSON.stringify(spawnerKey)).toBe('{}');
+  });
+
+  it('is zero-filled by wipe and refused afterwards; wipe is idempotent', () => {
+    const { spawner, runtime } = katPair();
+    const { spawnerKey } = spawner.complete(runtime.answerSpawnerExchange(spawner.message));
+    const bytes = spawnerKeyBytes(spawnerKey);
+    expect(spawnerKey.wiped).toBe(false);
+    spawnerKey.wipe();
+    expect(spawnerKey.wiped).toBe(true);
+    expect(bytes.every((byte) => byte === 0)).toBe(true);
+    expect(codeOf(() => spawnerKeyBytes(spawnerKey))).toBe('keys-locked');
+    spawnerKey.wipe();
+    expect(spawnerKey.wiped).toBe(true);
+  });
+});

package/src/__tests__/transient-key-pair.test.ts

@@ -0,0 +1,36 @@
+import { Buffer } from 'node:buffer';
+import { createPublicKey } from 'node:crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import { generateTransientSealingKeyPair, openBlob, sealBlob } from '../index.js';
+import { rawPublicKey } from '../key-pairs.js';
+import { bytesOf, codeOf, hex } from './helpers.js';
+
+const aad = bytesOf('robota/artifact/v1|tool-result-spill|token');
+const plaintext = bytesOf('a tool result only this process reads back');
+
+describe('a transient sealing keypair', () => {
+  it('is an X25519 pair whose public half is the one its private key has', () => {
+    const pair = generateTransientSealingKeyPair();
+    expect(pair.privateKey.type).toBe('private');
+    expect(pair.privateKey.asymmetricKeyType).toBe('x25519');
+    expect(pair.publicKey).toHaveLength(32);
+    expect(hex(pair.publicKey)).toBe(hex(rawPublicKey(createPublicKey(pair.privateKey))));
+  });
+
+  it('opens what is sealed to its public key, and nothing sealed to another pair', () => {
+    const pair = generateTransientSealingKeyPair();
+    const other = generateTransientSealingKeyPair();
+    const blob = sealBlob(pair.publicKey, plaintext, aad);
+    expect(Buffer.from(openBlob(pair.privateKey, blob, aad)).equals(plaintext)).toBe(true);
+    expect(codeOf(() => openBlob(other.privateKey, blob, aad))).toBe('decryption-failed');
+  });
+
+  it('is new every time: no two calls give the same key', () => {
+    const keys = new Set(
+      Array.from({ length: 8 }, () => hex(generateTransientSealingKeyPair().publicKey)),
+    );
+    expect(keys.size).toBe(8);
+  });
+});

package/src/aead.ts

@@ -0,0 +1,62 @@
+import { Buffer } from 'node:buffer';
+import { createCipheriv, createDecipheriv } from 'node:crypto';
+
+import { wipe } from './bytes.js';
+import { KeyringError } from './errors.js';
+
+export const GCM_IV_BYTES = 12;
+export const GCM_TAG_BYTES = 16;
+const AES_256_GCM = 'aes-256-gcm';
+
+/**
+ * AES-256-GCM seal. Returns `ciphertext || tag`. The cipher is AES-GCM everywhere because it is the
+ * AEAD both Node and Bun implement (ChaCha20-Poly1305 is not available on Bun).
+ */
+export function gcmEncrypt(
+  key: Uint8Array,
+  iv: Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  try {
+    const cipher = createCipheriv(AES_256_GCM, key, iv, { authTagLength: GCM_TAG_BYTES });
+    cipher.setAAD(aad);
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return Buffer.concat([body, cipher.getAuthTag()]);
+  } catch {
+    // The inputs are checked before they get here; what is left is a key or IV the cipher refused.
+    throw new KeyringError('invalid-argument', 'The key or IV cannot be used for encryption.');
+  }
+}
+
+/**
+ * AES-256-GCM open of `ciphertext || tag`. Plaintext is returned only after the tag verified; any
+ * failure — wrong key, wrong AAD, modified or truncated bytes — is one `decryption-failed`.
+ */
+export function gcmDecrypt(
+  key: Uint8Array,
+  iv: Uint8Array,
+  sealed: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  if (sealed.length < GCM_TAG_BYTES) {
+    throw new KeyringError('decryption-failed', 'Authentication of the ciphertext failed.');
+  }
+  const bodyLength = sealed.length - GCM_TAG_BYTES;
+  const body = sealed.subarray(0, bodyLength);
+  const tag = sealed.subarray(bodyLength);
+  const parts: Buffer[] = [];
+  try {
+    const decipher = createDecipheriv(AES_256_GCM, key, iv, { authTagLength: GCM_TAG_BYTES });
+    decipher.setAAD(aad);
+    decipher.setAuthTag(tag);
+    parts.push(decipher.update(body));
+    parts.push(decipher.final());
+    return Buffer.concat(parts);
+  } catch {
+    throw new KeyringError('decryption-failed', 'Authentication of the ciphertext failed.');
+  } finally {
+    // `update` hands out unauthenticated plaintext before `final` verifies the tag; never keep it.
+    wipe(...parts);
+  }
+}

package/src/authorship.ts

@@ -0,0 +1,61 @@
+import { Buffer } from 'node:buffer';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+import { isBytes } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { hkdf32 } from './kdf.js';
+
+/**
+ * The HKDF `info` label of the authorship key, versioned and part of the on-disk contract like the
+ * keypairs' labels: a tag written under one label never verifies under another.
+ */
+export const AUTHORSHIP_KEY_LABEL = 'robota/keyring/v1/authorship-hmac';
+
+/** An HMAC-SHA256 tag. */
+export const AUTHORSHIP_TAG_BYTES = 32;
+
+/**
+ * The authorship key: an HMAC-SHA256 key from its own HKDF-SHA256 label (empty salt), so it says
+ * nothing about the keypairs and they say nothing about it. Unlike the sealing key it has no public
+ * half, so only a process that recovered the master key can make a tag that verifies.
+ */
+export function deriveAuthorshipKey(masterKey: Uint8Array): Buffer {
+  return hkdf32(masterKey, AUTHORSHIP_KEY_LABEL);
+}
+
+function asBuffer(bytes: Uint8Array): Buffer {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+/** HMAC-SHA256 of `message` under `key`; a non-byte argument is a caller bug (`invalid-argument`). */
+export function authorshipTag(key: Uint8Array, message: Uint8Array): Buffer {
+  if (!isBytes(key) || !isBytes(message)) {
+    throw new KeyringError('invalid-argument', 'An authorship tag is made over bytes.');
+  }
+  try {
+    return createHmac('sha256', asBuffer(key)).update(asBuffer(message)).digest();
+  } catch {
+    throw new KeyringError('invalid-argument', 'The authorship tag could not be computed.');
+  }
+}
+
+/**
+ * Whether `tag` is the authorship tag of `message` under `key`, compared in constant time. A tag of
+ * another length is simply not one (the length is public), so it is refused before any comparison.
+ */
+export function verifyAuthorshipTag(
+  key: Uint8Array,
+  message: Uint8Array,
+  tag: Uint8Array,
+): boolean {
+  if (!isBytes(tag)) {
+    throw new KeyringError('invalid-argument', 'An authorship tag is bytes.');
+  }
+  const expected = authorshipTag(key, message);
+  try {
+    if (tag.length !== expected.length) return false;
+    return timingSafeEqual(expected, asBuffer(tag));
+  } finally {
+    expected.fill(0);
+  }
+}

package/src/bytes.ts

@@ -0,0 +1,67 @@
+import { Buffer } from 'node:buffer';
+
+import { KeyringError } from './errors.js';
+
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
+const LENGTH_PREFIX_BYTES = 2;
+const MAX_PART_BYTES = 0xffff;
+
+/** A byte array from any realm (a `Buffer` qualifies); `instanceof` fails across realms. */
+export function isBytes(value: unknown): value is Uint8Array {
+  return Object.prototype.toString.call(value) === '[object Uint8Array]';
+}
+
+export function toBase64Url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64url');
+}
+
+/**
+ * Decodes canonical, unpadded base64url of exactly `expectedLength` bytes, or returns `undefined`.
+ * `Buffer` alone is lenient (it skips junk characters and accepts non-canonical trailing bits), so a
+ * document could carry two spellings of one value; the round-trip check keeps the encoding unique.
+ */
+export function fromBase64Url(text: unknown, expectedLength: number): Buffer | undefined {
+  if (typeof text !== 'string' || !BASE64URL_PATTERN.test(text)) return undefined;
+  const decoded = Buffer.from(text, 'base64url');
+  if (decoded.length !== expectedLength) return undefined;
+  return decoded.toString('base64url') === text ? decoded : undefined;
+}
+
+/** {@link fromBase64Url} for keyring fields, where a bad encoding means a malformed document. */
+export function decodeKeyringField(text: unknown, expectedLength: number): Buffer {
+  const decoded = fromBase64Url(text, expectedLength);
+  if (!decoded) {
+    throw new KeyringError(
+      'malformed-keyring',
+      'The keyring is malformed: a field is not decodable.',
+    );
+  }
+  return decoded;
+}
+
+export function utf8(text: string): Buffer {
+  return Buffer.from(text, 'utf8');
+}
+
+/**
+ * Joins parts so that no two different part lists produce the same bytes (each part is preceded by
+ * its 2-byte big-endian length). Used wherever several values are bound into one AEAD AAD or one
+ * HKDF input.
+ */
+export function concatLengthPrefixed(parts: readonly Uint8Array[]): Buffer {
+  const chunks: Buffer[] = [];
+  for (const part of parts) {
+    if (part.length > MAX_PART_BYTES) {
+      throw new KeyringError('invalid-argument', 'A value bound into the AAD exceeds 65535 bytes.');
+    }
+    const prefix = Buffer.alloc(LENGTH_PREFIX_BYTES);
+    prefix.writeUInt16BE(part.length);
+    chunks.push(prefix, Buffer.from(part.buffer, part.byteOffset, part.byteLength));
+  }
+  return Buffer.concat(chunks);
+}
+
+/** Zeroes buffers in place. Best effort: it cannot reach copies the JavaScript engine made. */
+export function wipe(...buffers: ReadonlyArray<Uint8Array | undefined>): void {
+  for (const buffer of buffers) buffer?.fill(0);
+}

package/src/errors.ts

@@ -0,0 +1,106 @@
+/**
+ * Why an operation was refused. The union is the whole error vocabulary: a caller decides on `code`,
+ * never on the message.
+ *
+ * - `wrong-credential` — the passphrase or recovery key did not open the keyslot. A mistyped
+ *   credential and a tampered slot are indistinguishable by design (both fail authentication).
+ * - `malformed-keyring` / `unsupported-version` — the keyring document is not a valid version-1
+ *   document, or names a version this build does not know. `unsupported-version` also covers an
+ *   unknown version byte on a sealed key, record or blob.
+ * - `kdf-parameters-out-of-bounds` — a slot asks for a scrypt cost outside the accepted range; raised
+ *   before any key derivation runs. `kdf-failed` means a key derivation or key generation could not
+ *   run on this host (for example memory, or a crypto build without the curve), with inputs that
+ *   were in range.
+ * - `empty-passphrase` / `invalid-recovery-key` — the credential has the wrong form; no key
+ *   derivation ran.
+ * - `slot-not-found` — the keyring has no slot of the type the operation needs.
+ * - `malformed-ciphertext` — a sealed key, record or blob is structurally impossible (too short).
+ * - `decryption-failed` — authentication failed: wrong key, wrong AAD, or modified bytes.
+ * - `invalid-argument` — a key or buffer argument has the wrong type or length, or a key the
+ *   cipher or key import refuses.
+ * - `keys-locked` — the unlocked key set was locked and no longer hands out keys.
+ * - `link-refused` — an owner-link step was refused; the error is a {@link LinkRefusedError}, whose
+ *   `reason` names the check that failed. The other end of a link is never told the reason.
+ * - `link-closed` — the link was closed, by `close()` or by a frame that did not open, and protects
+ *   nothing more.
+ */
+export type TKeyringErrorCode =
+  | 'wrong-credential'
+  | 'malformed-keyring'
+  | 'unsupported-version'
+  | 'kdf-parameters-out-of-bounds'
+  | 'kdf-failed'
+  | 'empty-passphrase'
+  | 'invalid-recovery-key'
+  | 'slot-not-found'
+  | 'malformed-ciphertext'
+  | 'decryption-failed'
+  | 'invalid-argument'
+  | 'keys-locked'
+  | 'link-refused'
+  | 'link-closed';
+
+/**
+ * The only error this package throws on purpose. Messages are fixed text that names a field or a
+ * rule; no message or property ever carries a passphrase, a key, a recovery key or any value derived
+ * from them, and the original `node:crypto` error is deliberately not chained.
+ */
+export class KeyringError extends Error {
+  readonly code: TKeyringErrorCode;
+
+  constructor(code: TKeyringErrorCode, message: string) {
+    super(message);
+    this.name = 'KeyringError';
+    this.code = code;
+  }
+}
+
+/**
+ * Why an owner-link step was refused. Each names the one check that failed, for logs and for the
+ * caller's fixed wording; none says anything about a key.
+ *
+ * - `malformed` — a message or value of the wrong length, version, mode or encoding.
+ * - `out-of-order` — a step taken twice, or before its turn.
+ * - `spawner-unavailable` — spawner standing was asked of a runtime without a spawner key: it never
+ *   ran its exchange, or its spawner key was forgotten when its trust root was installed.
+ * - `not-certified` — owner mode was asked of a runtime with no trust root.
+ * - `already-certified` — a second trust root.
+ * - `certificate-mismatch` — the certificate is not the attach key's signature over this instance
+ *   and binding: made by another keyring, or for another runtime or start.
+ * - `instance-mismatch` — the runtime answered with an instance key other than its exchange's.
+ * - `bad-runtime-proof` — the runtime's proof of the transcript did not verify.
+ * - `bad-proof` — the initiator's proof of the transcript did not verify.
+ */
+export type TLinkRefusalReason =
+  | 'malformed'
+  | 'out-of-order'
+  | 'spawner-unavailable'
+  | 'not-certified'
+  | 'already-certified'
+  | 'certificate-mismatch'
+  | 'instance-mismatch'
+  | 'bad-runtime-proof'
+  | 'bad-proof';
+
+const LINK_REFUSAL_MESSAGES: Readonly<Record<TLinkRefusalReason, string>> = {
+  malformed: 'The owner link refused a malformed message.',
+  'out-of-order': 'The owner link refused a step out of order.',
+  'spawner-unavailable': 'The runtime holds no spawner key.',
+  'not-certified': 'The runtime holds no trust root.',
+  'already-certified': 'The runtime already holds a trust root.',
+  'certificate-mismatch': 'The certificate does not certify this runtime for this owner.',
+  'instance-mismatch': 'The runtime answered with another instance key.',
+  'bad-runtime-proof': 'The runtime did not prove the transcript.',
+  'bad-proof': 'The initiator did not prove the transcript.',
+};
+
+/** An owner-link refusal: a `KeyringError` with code `link-refused` and the failed check as `reason`. */
+export class LinkRefusedError extends KeyringError {
+  readonly reason: TLinkRefusalReason;
+
+  constructor(reason: TLinkRefusalReason) {
+    super('link-refused', LINK_REFUSAL_MESSAGES[reason]);
+    this.name = 'LinkRefusedError';
+    this.reason = reason;
+  }
+}

package/src/fingerprint.ts

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto';
+
+import { isBytes } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { KEY_BYTES } from './kdf.js';
+
+const FINGERPRINT_BYTES = 10;
+const GROUP_HEX_CHARS = 4;
+
+/**
+ * A short string two people can read to each other to confirm they hold the same public key: the
+ * first 10 bytes of SHA-256 of the raw 32-byte key, as upper-case hex in groups of four
+ * (`A1B2-C3D4-E5F6-0718-293A`). 80 bits is for a human comparing out loud or on screen; it is a
+ * check against accidents and casual swaps, not a collision-resistant identifier.
+ */
+export function fingerprint(publicKey: Uint8Array): string {
+  if (!isBytes(publicKey) || publicKey.length !== KEY_BYTES) {
+    throw new KeyringError(
+      'invalid-argument',
+      'A public key must be a Uint8Array of exactly 32 bytes.',
+    );
+  }
+  const hex = createHash('sha256')
+    .update(publicKey)
+    .digest('hex')
+    .slice(0, FINGERPRINT_BYTES * 2);
+  const groups: string[] = [];
+  for (let index = 0; index < hex.length; index += GROUP_HEX_CHARS) {
+    groups.push(hex.slice(index, index + GROUP_HEX_CHARS).toUpperCase());
+  }
+  return groups.join('-');
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * `@robota-sdk/agent-keyring` — key custody and sealing primitives for secure conversations, on
+ * `node:crypto` only. A passphrase and a recovery key each unwrap one master key; the master key
+ * derives an X25519 sealing keypair, an Ed25519 attach keypair and an HMAC authorship key; artifacts
+ * are encrypted under per-artifact keys that are sealed to the public sealing key, so a locked process
+ * can still write, and only an unlocked one can tag what it wrote. An unlock yields the read keys;
+ * the attach key stays inside a short-lived owner handover, which certifies runtimes.
+ */
+export { KeyringError, LinkRefusedError } from './errors.js';
+export type { TKeyringErrorCode, TLinkRefusalReason } from './errors.js';
+
+export type {
+  IKeyring,
+  IPassphraseKeyslot,
+  IRecoveryKeyslot,
+  IScryptKdfParameters,
+  TKeyslot,
+  TKeyslotType,
+} from './keyring-types.js';
+export { KEYRING_VERSION } from './keyring-types.js';
+export { getSealingPublicKey, parseKeyring, serializeKeyring } from './keyring-document.js';
+
+export {
+  changePassphrase,
+  checkSealingPublicKey,
+  createKeyring,
+  repairSealingPublicKey,
+  unlockWithPassphrase,
+  unlockWithRecoveryKey,
+} from './keyring.js';
+export type { ICreateKeyringOptions, ICreatedKeyring, TKeyringCredential } from './keyring.js';
+
+export type { IReadKeys } from './read-keys.js';
+export { openOwnerHandover } from './owner-handover.js';
+export type { IOwnerHandover } from './owner-handover.js';
+export type { ILinkBinding, ITrustRoot } from './runtime-certificate.js';
+export { SpawnerKey, startSpawnerExchange } from './spawner-exchange.js';
+export type { ISpawnerExchange, ISpawnerExchangeResult } from './spawner-exchange.js';
+export { createRuntimeIdentity } from './runtime-identity.js';
+export type { IRuntimeIdentity } from './runtime-identity.js';
+export {
+  LINK_CHALLENGE_MAX_BYTES,
+  LINK_HELLO_BYTES,
+  LINK_PROOF_MAX_BYTES,
+  createLinkInitiator,
+  createLinkResponder,
+} from './owner-link.js';
+export type { ILinkInitiator, ILinkResponder, TLinkInitiatorAuth } from './owner-link.js';
+export {
+  LINK_FRAME_MAX_PLAINTEXT_BYTES,
+  LINK_FRAME_OVERHEAD_BYTES,
+  LINK_GRANT_FRAME_BYTES,
+  linkFrameKind,
+} from './link-frames.js';
+export type {
+  IEstablishedLink,
+  IInitiatorLink,
+  IResponderLink,
+  TLinkDataFrameKind,
+  TLinkFrameKind,
+  TLinkMode,
+} from './link-frames.js';
+export type { IKeyPair } from './key-pairs.js';
+export { generateTransientSealingKeyPair } from './key-pairs.js';
+
+export { fingerprint } from './fingerprint.js';
+
+export {
+  decryptRecord,
+  encryptRecord,
+  generateArtifactKey,
+  openArtifactKey,
+  openBlob,
+  sealArtifactKey,
+  sealBlob,
+  splitSealedBlob,
+} from './sealing.js';

package/src/kdf.ts

@@ -0,0 +1,111 @@
+import { Buffer } from 'node:buffer';
+import { hkdfSync, scrypt } from 'node:crypto';
+
+import { utf8 } from './bytes.js';
+import { KeyringError } from './errors.js';
+
+export const KEY_BYTES = 32;
+export const SCRYPT_SALT_BYTES = 16;
+
+export interface IScryptParameters {
+  readonly N: number;
+  readonly r: number;
+  readonly p: number;
+}
+
+/** The cost a new passphrase slot is written with (OWASP's scrypt baseline, ~128 MiB, ~160 ms). */
+export const DEFAULT_SCRYPT_PARAMETERS: IScryptParameters = { N: 2 ** 17, r: 8, p: 1 };
+
+/**
+ * The cost range an unlock accepts. The floor stops a hostile keyring from downgrading the work
+ * factor; the ceiling stops one from making unlock allocate gigabytes or run for minutes. The file
+ * is writable by every program of the user, so the memory a keyring may ask for is capped at 512 MiB
+ * (four times the default) however N and r are combined. All of it is checked before any key
+ * derivation starts.
+ */
+export const SCRYPT_BOUNDS = {
+  minN: 2 ** 15,
+  maxN: 2 ** 19,
+  minR: 8,
+  maxR: 16,
+  p: 1,
+  maxMemoryBytes: 2 ** 29,
+} as const;
+
+const SCRYPT_BLOCK_BYTES = 128;
+const SCRYPT_MEMORY_HEADROOM_BYTES = 1024 * 1024;
+
+export function assertScryptParametersInBounds(parameters: IScryptParameters): void {
+  const { N, r, p } = parameters;
+  const nInBounds =
+    Number.isInteger(N) &&
+    N >= SCRYPT_BOUNDS.minN &&
+    N <= SCRYPT_BOUNDS.maxN &&
+    (N & (N - 1)) === 0;
+  const rInBounds = Number.isInteger(r) && r >= SCRYPT_BOUNDS.minR && r <= SCRYPT_BOUNDS.maxR;
+  const memoryInBounds = SCRYPT_BLOCK_BYTES * r * N <= SCRYPT_BOUNDS.maxMemoryBytes;
+  if (!nInBounds || !rInBounds || !memoryInBounds || p !== SCRYPT_BOUNDS.p) {
+    throw new KeyringError(
+      'kdf-parameters-out-of-bounds',
+      'A passphrase slot requests scrypt parameters outside the accepted range.',
+    );
+  }
+}
+
+/**
+ * NFKC then UTF-8, so the same typed text unlocks on every platform and keyboard layout. Only the
+ * empty string is refused; length and strength policy belong to the caller. The returned buffer is
+ * the caller's to wipe (the JavaScript string it came from cannot be wiped).
+ */
+export function normalizePassphrase(passphrase: unknown): Buffer {
+  if (typeof passphrase !== 'string') {
+    throw new KeyringError('invalid-argument', 'The passphrase must be a string.');
+  }
+  const normalized = passphrase.normalize('NFKC');
+  if (normalized.length === 0) {
+    throw new KeyringError('empty-passphrase', 'The passphrase is empty.');
+  }
+  return utf8(normalized);
+}
+
+/**
+ * Derives the passphrase slot's key-encryption key. Asynchronous (`crypto.scrypt` runs on the
+ * libuv thread pool) so ~160 ms of work never blocks the caller's event loop.
+ */
+export function deriveKeyFromPassphrase(
+  passphrase: Uint8Array,
+  salt: Uint8Array,
+  parameters: IScryptParameters,
+): Promise<Buffer> {
+  assertScryptParametersInBounds(parameters);
+  const { N, r, p } = parameters;
+  // scrypt needs ~128*r*(N+p+2) bytes; Node refuses unless maxmem is above that.
+  const maxmem = SCRYPT_BLOCK_BYTES * r * (N + p + 2) + SCRYPT_MEMORY_HEADROOM_BYTES;
+  return new Promise<Buffer>((resolve, reject) => {
+    try {
+      scrypt(passphrase, salt, KEY_BYTES, { N, r, p, maxmem }, (error, derivedKey) => {
+        if (error) reject(kdfFailed());
+        else resolve(derivedKey);
+      });
+    } catch {
+      reject(kdfFailed());
+    }
+  });
+}
+
+function kdfFailed(): KeyringError {
+  return new KeyringError('kdf-failed', 'The key derivation could not run on this host.');
+}
+
+/** HKDF-SHA256 to 32 bytes. An empty salt is RFC 5869's "no salt" (a string of zero bytes). */
+export function hkdf32(
+  inputKeyMaterial: Uint8Array,
+  info: string | Uint8Array,
+  salt: Uint8Array = new Uint8Array(0),
+): Buffer {
+  try {
+    return Buffer.from(hkdfSync('sha256', inputKeyMaterial, salt, info, KEY_BYTES));
+  } catch {
+    throw kdfFailed();
+  }
+}