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

package/src/__tests__/crypto-failures.test.ts

@@ -0,0 +1,89 @@
+/**
+ * A `node:crypto` call that throws (an OpenSSL build without a curve, memory, a host refusing an
+ * operation) must still surface as a `KeyringError` with a code from the closed vocabulary, and the
+ * original error, which may describe its inputs, must not be chained. Kept apart because it replaces
+ * `node:crypto` for the whole file.
+ */
+import { Buffer } from 'node:buffer';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const broken = vi.hoisted(() => new Set<string>());
+
+vi.mock('node:crypto', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:crypto')>();
+  const breakable =
+    <TArgs extends unknown[], TResult>(name: string, original: (...args: TArgs) => TResult) =>
+    (...args: TArgs): TResult => {
+      if (broken.has(name)) throw new Error(`${name} failed: SECRET-INPUT-DESCRIPTION`);
+      return original(...args);
+    };
+  return {
+    ...actual,
+    createCipheriv: breakable('createCipheriv', actual.createCipheriv),
+    createPrivateKey: breakable('createPrivateKey', actual.createPrivateKey),
+    generateKeyPairSync: breakable('generateKeyPairSync', actual.generateKeyPairSync),
+    hkdfSync: breakable('hkdfSync', actual.hkdfSync),
+  };
+});
+
+const {
+  KeyringError,
+  encryptRecord,
+  generateArtifactKey,
+  sealBlob,
+  unlockWithRecoveryKey,
+  parseKeyring,
+} = await import('../index.js');
+const { readFileSync } = await import('node:fs');
+const { fileURLToPath } = await import('node:url');
+const { FIXTURE_RECOVERY_KEY, bytesOf } = await import('./helpers.js');
+const { KNOWN_SEALING_PUBLIC_KEY_HEX } = await import('./helpers.js');
+
+const fixture = parseKeyring(
+  readFileSync(fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)), 'utf8'),
+);
+const sealingPublicKey = Buffer.from(KNOWN_SEALING_PUBLIC_KEY_HEX, 'hex');
+
+afterEach(() => broken.clear());
+
+async function failureOf(action: () => unknown): Promise<InstanceType<typeof KeyringError>> {
+  try {
+    await action();
+  } catch (error) {
+    expect(error).toBeInstanceOf(KeyringError);
+    const keyringError = error as InstanceType<typeof KeyringError>;
+    expect(keyringError.message).not.toContain('SECRET-INPUT-DESCRIPTION');
+    expect(keyringError.cause).toBeUndefined();
+    return keyringError;
+  }
+  throw new Error('expected the call to fail');
+}
+
+describe('node:crypto failures become KeyringErrors', () => {
+  it('the AEAD cipher', async () => {
+    broken.add('createCipheriv');
+    const error = await failureOf(() =>
+      encryptRecord(generateArtifactKey(), bytesOf('x'), bytesOf('a')),
+    );
+    expect(error.code).toBe('invalid-argument');
+  });
+
+  it('HKDF', async () => {
+    broken.add('hkdfSync');
+    const error = await failureOf(() => sealBlob(sealingPublicKey, bytesOf('x'), bytesOf('a')));
+    expect(error.code).toBe('kdf-failed');
+  });
+
+  it('the ephemeral keypair of a seal', async () => {
+    broken.add('generateKeyPairSync');
+    const error = await failureOf(() => sealBlob(sealingPublicKey, bytesOf('x'), bytesOf('a')));
+    expect(error.code).toBe('kdf-failed');
+  });
+
+  it('the keypairs derived at unlock', async () => {
+    broken.add('createPrivateKey');
+    const error = await failureOf(() => unlockWithRecoveryKey(fixture, FIXTURE_RECOVERY_KEY));
+    expect(error.code).toBe('kdf-failed');
+  });
+});

package/src/__tests__/fixtures/keyring-v1.json

@@ -0,0 +1,25 @@
+{
+  "version": 1,
+  "sealingPublicKey": "S3PDVnZjG2MH-yij9wqvR8MxuGraSZbOLzyfXATNuno",
+  "slots": [
+    {
+      "id": "BSuNhJoNIIOA2MM1VUsXYg",
+      "type": "passphrase",
+      "kdf": {
+        "algorithm": "scrypt",
+        "N": 131072,
+        "r": 8,
+        "p": 1,
+        "salt": "0Qv4qMa3OvgcDF9eFqExDQ"
+      },
+      "iv": "pkFJv5arSD8useGU",
+      "wrappedKey": "c7imvonyCA9GAwCOf8BmFWtQaiDBLm1Farv9S3D5YpFegST_YV7w87ws0u69ppN9"
+    },
+    {
+      "id": "HTws5i75-WV7H-xswoQbEQ",
+      "type": "recovery",
+      "iv": "c61f5DrELmrz6FsB",
+      "wrappedKey": "-FvFhexFSR2bVxkb72LURxYZ6b7PWk0jItxcCtaYkl1NPD1ObjJJC1-JGkGIPmdG"
+    }
+  ]
+}

package/src/__tests__/fixtures/sealed-v1.json

@@ -0,0 +1,8 @@
+{
+  "aad": "726f626f74612f6b657972696e672f6b61742f76317c61727469666163742d376633617c7365713a30",
+  "plaintext": "7b22726f6c65223a2275736572222c2274657874223a226b6e6f776e2d616e7377657220706c61696e746578742c207365616c656420666f726d6174207631227d0a",
+  "artifactKey": "404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f",
+  "sealedKey": "0181711a3372cb1cccc7e5828edc725f341b68679f70e6e3ba3e9e9fac41bd782423a151416fbcce1afac3ec7c9b847365baeb35e694672d55794e07e751a969719bf77347b76b919a21dab8422d5567173746c218e183a40c3b1ae7c7",
+  "record": "01dff68c3272f950c78f87cd8fc01efa25e70bfcb0414df457d83c8741c3968ff2e4cca7213026193356906a9aec4886510bf1ad52fe8e4ada62bd88d13ef564fefc304436acc20f73bd0ca36829c44b91b10a6823c0ca4873ca93d3e58ecf",
+  "blob": "01253a771bda2b0182d5f913104593e94038619858dfcc9b17b7d7dbb2cbbe4b35174311bf50de606ef73bce6befcaed3d43668a203cc3bdf91bc757f407b8d28f5ad450495b50937ab50837291d92f7936aa1f3390807273c5d70009101b0ff154935fce36115c2d523de58ae3c4db6b0a70314ceada305d92594e1ddefc28e1099159e7b7a6f18f24c66ff7037929426e3f8206b77d4dbdc33d4874d2f6f084f9df88de2da534bed1d510f24a593d2d1d04d3d7b55af268284a25f"
+}

package/src/__tests__/helpers.ts

@@ -0,0 +1,130 @@
+import { Buffer } from 'node:buffer';
+
+import { KeyringError, type TKeyringErrorCode } from '../index.js';
+
+/** Bytes 0x00..0x1f. A fixed master key makes derived keys comparable with the known-answer values. */
+export const FIXED_MASTER_KEY: Buffer = Buffer.from(Array.from({ length: 32 }, (_, i) => i));
+
+/** Public keys derived from FIXED_MASTER_KEY, cross-checked outside this package (HMAC-based HKDF in Python, public keys from the openssl CLI). */
+export const KNOWN_SEALING_PUBLIC_KEY_HEX =
+  '4b73c35676631b6307fb28a3f70aaf47c331b86ada4996ce2f3c9f5c04cdba7a';
+export const KNOWN_ATTACH_PUBLIC_KEY_HEX =
+  '92ffeb9a3ccccde96ea227ff3e2f467989d8fdc5b234e8fdcf1d159a7f56ad54';
+/** The authorship HMAC key FIXED_MASTER_KEY derives, and its tag of {@link KNOWN_AUTHORSHIP_MESSAGE}, cross-checked in Python (hmac, hashlib). */
+export const KNOWN_AUTHORSHIP_KEY_HEX =
+  '645f0686ee7ef6c5073ec8930c220db556c495be7dfdbd07f56226a0bf34e4a1';
+export const KNOWN_AUTHORSHIP_MESSAGE = 'robota/keyring known-answer authorship message v1';
+export const KNOWN_AUTHORSHIP_TAG_HEX =
+  '5067021c80974a4875b70314442ef0f6cfffe90dad155dfa9bcbe72644f0749d';
+
+/**
+ * A runtime instance for the owner-link known answers: the Ed25519 key from seed bytes 0x40..0x5f,
+ * a binding shaped like a supervised runtime's, and the certificate the fixture keyring's attach key
+ * makes for them. Cross-checked outside this package (HKDF in Python, the public key and the
+ * signature from the openssl CLI).
+ */
+export const KAT_INSTANCE_SEED: Buffer = Buffer.from(
+  Array.from({ length: 32 }, (_, i) => 0x40 + i),
+);
+export const KAT_INSTANCE_PUBLIC_KEY_HEX =
+  '2543b92ff1095511476adc8369db6ddc933665a11978dda1404ee1066ca9559d';
+export const KAT_BINDING = {
+  runtimeId: '6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f',
+  generation: 'AAECAwQFBgcICQoLDA0ODw',
+} as const;
+export const KAT_CERTIFICATE_HEX =
+  '9d76a228a4824881c96050ff31eaa9287dc99efe238c592aab67189ef16fe5b6' +
+  'ad90e67b84f5334e771534ec0496d9a5edeae8568c0f92d73a3ae252638e1302';
+/** The certificate for the same instance and runtime id at the next generation. */
+export const KAT_CERTIFICATE_NEXT_GENERATION_HEX =
+  'fad24766d3f13d910825aa39016bc203bd5a7237d77e4037189389f28735b1ac' +
+  'ca9f41b16a9bdfba3fdc61b0b4bc2dc58bf1cd787834c7232d164ed4bd6b8c06';
+export const KAT_NEXT_GENERATION = 'AAECAwQFBgcICQoLDA0OEA';
+
+export const FIXTURE_RECOVERY_KEY_BYTES: Buffer = Buffer.from(
+  Array.from({ length: 20 }, (_, i) => 0xa0 + i),
+);
+export const FIXTURE_RECOVERY_KEY = 'M2GT-58X4-MPKA-FA59-NANT-SBDE-NYRB-3CNK';
+/** Decomposed letters plus compatibility characters; NFKC turns it into `Pässwörd-fixture-1`. */
+export const FIXTURE_PASSPHRASE_AS_TYPED = 'Pässwörd-fixture-①';
+
+export function hex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('hex');
+}
+
+export function bytesOf(text: string): Buffer {
+  return Buffer.from(text, 'utf8');
+}
+
+/** A copy of `bytes` with `mask` XOR-ed into the byte at `index`. */
+export function tamper(bytes: Uint8Array, index: number, mask = 0x01): Buffer {
+  const copy = Buffer.from(bytes);
+  copy[index] ^= mask;
+  return copy;
+}
+
+/** Joins parts with a 2-byte big-endian length before each, written here apart from the package's own. */
+export function lengthPrefixed(...parts: readonly Uint8Array[]): Buffer {
+  return Buffer.concat(
+    parts.flatMap((part) => {
+      const prefix = Buffer.alloc(2);
+      prefix.writeUInt16BE(part.length);
+      return [prefix, Buffer.from(part)];
+    }),
+  );
+}
+
+/**
+ * Every value reachable from `root` through its own properties and the getters of its prototype
+ * chain, two levels deep: what a holder of the object can get at without a package-private accessor.
+ */
+export function reachableValues(root: object): unknown[] {
+  const found: unknown[] = [];
+  const visit = (value: unknown, depth: number): void => {
+    found.push(value);
+    if (depth === 0 || typeof value !== 'object' || value === null || ArrayBuffer.isView(value)) {
+      return;
+    }
+    const names = new Set<string | symbol>();
+    for (
+      let prototype: object | null = value;
+      prototype !== null && prototype !== Object.prototype;
+      prototype = Object.getPrototypeOf(prototype)
+    ) {
+      for (const name of Reflect.ownKeys(prototype)) names.add(name);
+    }
+    for (const name of names) {
+      if (name === 'constructor') continue;
+      let child: unknown;
+      try {
+        child = (value as Record<string | symbol, unknown>)[name];
+      } catch {
+        continue;
+      }
+      if (typeof child !== 'function') visit(child, depth - 1);
+    }
+  };
+  visit(root, 2);
+  return found;
+}
+
+/** The `code` of the KeyringError a call throws; any other throw (or none) fails the test loudly. */
+export function codeOf(call: () => unknown): TKeyringErrorCode {
+  try {
+    call();
+  } catch (error) {
+    if (error instanceof KeyringError) return error.code;
+    throw error;
+  }
+  throw new Error('Expected a KeyringError but nothing was thrown.');
+}
+
+export async function codeOfAsync(promise: Promise<unknown>): Promise<TKeyringErrorCode> {
+  try {
+    await promise;
+  } catch (error) {
+    if (error instanceof KeyringError) return error.code;
+    throw error;
+  }
+  throw new Error('Expected a KeyringError but nothing was thrown.');
+}

package/src/__tests__/kdf-bounds.test.ts

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Counts calls into `crypto.scrypt` while still running the real thing. The bounds check has to
+// refuse BEFORE any derivation, and a call count is the only direct evidence of that.
+const scryptCalls = vi.hoisted(() => ({ count: 0 }));
+
+vi.mock('node:crypto', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:crypto')>();
+  const counted = ((...args: Parameters<typeof actual.scrypt>) => {
+    scryptCalls.count += 1;
+    return (actual.scrypt as (...rest: unknown[]) => void)(...args);
+  }) as typeof actual.scrypt;
+  return { ...actual, scrypt: counted, default: { ...actual, scrypt: counted } };
+});
+
+import {
+  createKeyring,
+  parseKeyring,
+  unlockWithPassphrase,
+  unlockWithRecoveryKey,
+  type IKeyring,
+} from '../index.js';
+import {
+  assertScryptParametersInBounds,
+  DEFAULT_SCRYPT_PARAMETERS,
+  SCRYPT_BOUNDS,
+} from '../kdf.js';
+import { codeOf, codeOfAsync, FIXTURE_PASSPHRASE_AS_TYPED } from './helpers.js';
+
+const fixtureText = readFileSync(
+  fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)),
+  'utf8',
+);
+const fixture = parseKeyring(fixtureText);
+
+function withKdf(change: Record<string, number>): IKeyring {
+  const [passphrase, recovery] = fixture.slots;
+  if (passphrase.type !== 'passphrase') throw new Error('fixture layout changed');
+  return {
+    ...fixture,
+    slots: [{ ...passphrase, kdf: { ...passphrase.kdf, ...change } }, recovery],
+  };
+}
+
+beforeEach(() => {
+  scryptCalls.count = 0;
+});
+
+describe('scrypt cost bounds', () => {
+  it('accepts the default cost and the inclusive edges of the range', () => {
+    expect(() => assertScryptParametersInBounds(DEFAULT_SCRYPT_PARAMETERS)).not.toThrow();
+    for (const [N, r] of [
+      [SCRYPT_BOUNDS.minN, SCRYPT_BOUNDS.minR],
+      [SCRYPT_BOUNDS.minN, SCRYPT_BOUNDS.maxR],
+      [SCRYPT_BOUNDS.maxN, SCRYPT_BOUNDS.minR], // exactly the 512 MiB ceiling
+    ]) {
+      expect(() => assertScryptParametersInBounds({ N, r, p: 1 })).not.toThrow();
+    }
+  });
+
+  it('caps the memory a keyring may request, whatever N and r are combined', () => {
+    // Each of N and r is in range on its own; together they would need 1 GiB.
+    expect(
+      codeOf(() =>
+        assertScryptParametersInBounds({ N: SCRYPT_BOUNDS.maxN, r: SCRYPT_BOUNDS.maxR, p: 1 }),
+      ),
+    ).toBe('kdf-parameters-out-of-bounds');
+  });
+
+  it('refuses a cost outside the range, with its own error code', () => {
+    const outside = [
+      { N: 2 ** 14, r: 8, p: 1 },
+      { N: 2 ** 20, r: 8, p: 1 }, // above the ceiling
+      { N: 2 ** 21, r: 8, p: 1 },
+      { N: 3 * 2 ** 15, r: 8, p: 1 }, // in range but not a power of two
+      { N: 2 ** 17, r: 7, p: 1 },
+      { N: 2 ** 17, r: 17, p: 1 },
+      { N: 2 ** 17, r: 8, p: 2 },
+      { N: 2 ** 17, r: 8, p: 0 },
+      { N: 2 ** 17 + 0.5, r: 8, p: 1 },
+      { N: Number.NaN, r: 8, p: 1 },
+    ];
+    for (const parameters of outside) {
+      expect(codeOf(() => assertScryptParametersInBounds(parameters))).toBe(
+        'kdf-parameters-out-of-bounds',
+      );
+    }
+  });
+});
+
+describe('unlock refuses hostile KDF parameters before doing any work', () => {
+  it('runs no scrypt for any out-of-range slot', async () => {
+    const hostile = [
+      withKdf({ N: 2 ** 14 }), // a downgrade
+      withKdf({ N: 2 ** 21 }), // a memory bomb
+      withKdf({ N: 2 ** 19, r: 16 }), // a 1 GiB request, each value in range on its own
+      withKdf({ N: 2 ** 20, r: 17 }),
+      withKdf({ r: 7 }),
+      withKdf({ p: 2 }),
+      withKdf({ N: 3 * 2 ** 15 }),
+    ];
+    for (const keyring of hostile) {
+      expect(await codeOfAsync(unlockWithPassphrase(keyring, FIXTURE_PASSPHRASE_AS_TYPED))).toBe(
+        'kdf-parameters-out-of-bounds',
+      );
+    }
+    expect(scryptCalls.count).toBe(0);
+  });
+
+  it('checks every passphrase slot before deriving for the first', async () => {
+    const [passphrase, recovery] = fixture.slots;
+    if (passphrase.type !== 'passphrase') throw new Error('fixture layout changed');
+    const hostileSecond = withKdf({ N: 2 ** 21 }).slots[0];
+    const keyring: IKeyring = {
+      ...fixture,
+      slots: [passphrase, { ...hostileSecond, id: 'AAAAAAAAAAAAAAAAAAAAAA' }, recovery],
+    };
+    expect(await codeOfAsync(unlockWithPassphrase(keyring, FIXTURE_PASSPHRASE_AS_TYPED))).toBe(
+      'kdf-parameters-out-of-bounds',
+    );
+    expect(scryptCalls.count).toBe(0);
+  });
+
+  it('does run scrypt for an in-range slot (so the counter is not vacuous)', async () => {
+    // The lowest accepted cost with the fixture's wrapped key: derives a different key, then fails.
+    expect(
+      await codeOfAsync(unlockWithPassphrase(withKdf({ N: 2 ** 15 }), FIXTURE_PASSPHRASE_AS_TYPED)),
+    ).toBe('wrong-credential');
+    expect(scryptCalls.count).toBe(1);
+  });
+
+  it('does not refuse the recovery path because of a hostile passphrase slot', async () => {
+    // Nothing to unlock with here (the fixture's recovery key is not under test); only that no
+    // scrypt ran and no KDF error was raised for a credential that never reaches the passphrase slot.
+    expect(
+      await codeOfAsync(
+        unlockWithRecoveryKey(withKdf({ N: 2 ** 21 }), 'ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ'),
+      ),
+    ).toBe('wrong-credential');
+    expect(scryptCalls.count).toBe(0);
+  });
+});
+
+describe('createKeyring', () => {
+  it('runs scrypt once, at the default cost', async () => {
+    const { keyring } = await createKeyring({ passphrase: 'a passphrase' });
+    expect(scryptCalls.count).toBe(1);
+    const slot = keyring.slots[0];
+    expect(slot.type === 'passphrase' && slot.kdf).toMatchObject(DEFAULT_SCRYPT_PARAMETERS);
+  });
+});

package/src/__tests__/keyring-document.test.ts

@@ -0,0 +1,251 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getSealingPublicKey,
+  KeyringError,
+  parseKeyring,
+  serializeKeyring,
+  type IKeyring,
+} from '../index.js';
+import { MAX_KEYRING_JSON_CHARS, MAX_KEYSLOTS } from '../keyring-document.js';
+import { codeOf, KNOWN_SEALING_PUBLIC_KEY_HEX, hex } from './helpers.js';
+
+const fixtureText = readFileSync(
+  fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)),
+  'utf8',
+);
+// A loosely typed JSON view: these tests deliberately build documents that break the schema.
+type TLooseDocument = Record<string, any>;
+const fixture = JSON.parse(fixtureText) as TLooseDocument;
+
+function documentWith(change: (copy: TLooseDocument) => void): string {
+  const copy = structuredClone(fixture);
+  change(copy);
+  return JSON.stringify(copy);
+}
+
+describe('parseKeyring and serializeKeyring', () => {
+  it('reads the fixed schema and writes it back identically', () => {
+    const keyring = parseKeyring(fixtureText);
+    expect(keyring.version).toBe(1);
+    expect(keyring.slots).toHaveLength(2);
+    expect(serializeKeyring(keyring)).toBe(fixtureText.trimEnd());
+    expect(Object.keys(JSON.parse(serializeKeyring(keyring)))).toEqual([
+      'version',
+      'sealingPublicKey',
+      'slots',
+    ]);
+    expect(hex(getSealingPublicKey(keyring))).toBe(KNOWN_SEALING_PUBLIC_KEY_HEX);
+  });
+
+  it('returns a frozen copy that shares nothing with its input', () => {
+    const keyring = parseKeyring(fixtureText);
+    expect(Object.isFrozen(keyring)).toBe(true);
+    expect(Object.isFrozen(keyring.slots)).toBe(true);
+    expect(Object.isFrozen(keyring.slots[0])).toBe(true);
+  });
+
+  it('reports a document of another version as unsupported-version, whatever else it contains', () => {
+    expect(codeOf(() => parseKeyring(documentWith((copy) => (copy.version = 2))))).toBe(
+      'unsupported-version',
+    );
+    expect(codeOf(() => parseKeyring(JSON.stringify({ version: 0 })))).toBe('unsupported-version');
+    expect(codeOf(() => parseKeyring(JSON.stringify({ version: 2, somethingNew: [1, 2] })))).toBe(
+      'unsupported-version',
+    );
+  });
+
+  it('refuses a missing, mistyped or fractional version', () => {
+    for (const version of [undefined, '1', 1.5, null, true, [], {}]) {
+      const text = documentWith((copy) => {
+        copy.version = version;
+      });
+      expect(codeOf(() => parseKeyring(text))).toBe('malformed-keyring');
+    }
+  });
+
+  it('has no field for an attach public key, and refuses any extra field', () => {
+    expect(
+      codeOf(() => parseKeyring(documentWith((copy) => (copy.attachPublicKey = 'AAAA')))),
+    ).toBe('malformed-keyring');
+    expect(codeOf(() => parseKeyring(documentWith((copy) => (copy.slots[0].extra = 1))))).toBe(
+      'malformed-keyring',
+    );
+    expect(codeOf(() => parseKeyring(documentWith((copy) => (copy.slots[0].kdf.extra = 1))))).toBe(
+      'malformed-keyring',
+    );
+  });
+
+  it('refuses missing fields at every level', () => {
+    const removals: Array<(copy: TLooseDocument) => void> = [
+      (copy) => delete copy.sealingPublicKey,
+      (copy) => delete copy.slots,
+      (copy) => delete copy.slots[0].id,
+      (copy) => delete copy.slots[0].type,
+      (copy) => delete copy.slots[0].iv,
+      (copy) => delete copy.slots[0].wrappedKey,
+      (copy) => delete copy.slots[0].kdf,
+      (copy) => delete copy.slots[0].kdf.salt,
+      (copy) => delete copy.slots[0].kdf.N,
+      (copy) => delete copy.slots[1].wrappedKey,
+    ];
+    for (const remove of removals) {
+      expect(codeOf(() => parseKeyring(documentWith(remove)))).toBe('malformed-keyring');
+    }
+  });
+
+  it('refuses wrong types and wrong lengths', () => {
+    const changes: Array<(copy: TLooseDocument) => void> = [
+      (copy) => (copy.sealingPublicKey = 42),
+      (copy) => (copy.sealingPublicKey = copy.sealingPublicKey.slice(0, -2)),
+      (copy) => (copy.sealingPublicKey = `${copy.sealingPublicKey}AA`),
+      (copy) => (copy.slots = {}),
+      (copy) => (copy.slots = []),
+      (copy) => (copy.slots = [null]),
+      (copy) => (copy.slots = ['x']),
+      (copy) => (copy.slots[0].id = 'short'),
+      (copy) => (copy.slots[0].iv = copy.slots[0].iv.slice(2)),
+      (copy) => (copy.slots[0].wrappedKey = copy.slots[0].wrappedKey.slice(2)),
+      (copy) => (copy.slots[0].type = 'unknown'),
+      (copy) => (copy.slots[0].type = 'recovery'), // carries a kdf, which a recovery slot has no field for
+      (copy) => (copy.slots[1].type = 'passphrase'), // has no kdf
+      (copy) => (copy.slots[0].kdf = 'scrypt'),
+      (copy) => (copy.slots[0].kdf.algorithm = 'argon2id'),
+      (copy) => (copy.slots[0].kdf.N = '131072'),
+      (copy) => (copy.slots[0].kdf.N = 131072.5),
+      (copy) => (copy.slots[0].kdf.r = 0),
+      (copy) => (copy.slots[0].kdf.p = -1),
+      (copy) => (copy.slots[0].kdf.N = Number.MAX_SAFE_INTEGER + 2),
+      (copy) => (copy.slots[0].kdf.salt = copy.slots[0].kdf.salt.slice(1)),
+    ];
+    for (const change of changes) {
+      expect(codeOf(() => parseKeyring(documentWith(change)))).toBe('malformed-keyring');
+    }
+  });
+
+  it('accepts only canonical, unpadded base64url', () => {
+    const publicKey: string = fixture.sealingPublicKey;
+    const variants = [
+      `${publicKey}=`, // padding
+      publicKey.replace(/[-_]/, '+'), // standard alphabet (the fixture's key contains a - or _)
+      `${publicKey.slice(0, -1)}${publicKey.endsWith('o') ? 'p' : 'o'}`, // different trailing bits
+      ` ${publicKey}`,
+      publicKey.replace(/./, 'é'),
+    ];
+    for (const variant of variants) {
+      if (variant === publicKey) continue;
+      expect(
+        codeOf(() => parseKeyring(documentWith((copy) => (copy.sealingPublicKey = variant)))),
+      ).toBe('malformed-keyring');
+    }
+  });
+
+  it('refuses duplicate slot ids, too many slots and an oversized document', () => {
+    expect(
+      codeOf(() => parseKeyring(documentWith((copy) => (copy.slots[1].id = copy.slots[0].id)))),
+    ).toBe('malformed-keyring');
+    expect(
+      codeOf(() =>
+        parseKeyring(
+          documentWith((copy) => {
+            copy.slots = Array.from({ length: MAX_KEYSLOTS + 1 }, (_, index) => ({
+              ...copy.slots[1],
+              id: Buffer.alloc(16, index).toString('base64url'),
+            }));
+          }),
+        ),
+      ),
+    ).toBe('malformed-keyring');
+    const padded = `${fixtureText}${' '.repeat(MAX_KEYRING_JSON_CHARS)}`;
+    expect(codeOf(() => parseKeyring(padded))).toBe('malformed-keyring');
+  });
+
+  it('refuses input that is not a JSON object document', () => {
+    for (const text of ['', 'not json', 'null', '[]', '1', '"x"', '{', '[[[[[[[[[[', 'true']) {
+      expect(codeOf(() => parseKeyring(text))).toBe('malformed-keyring');
+    }
+    expect(codeOf(() => parseKeyring(undefined as never))).toBe('malformed-keyring');
+    expect(codeOf(() => parseKeyring(Buffer.from(fixtureText) as never))).toBe('malformed-keyring');
+    expect(codeOf(() => parseKeyring(`[${'['.repeat(8000)}${']'.repeat(8000)}]`))).toBe(
+      'malformed-keyring',
+    );
+  });
+
+  it('is not steered by prototype-shaped keys', () => {
+    const polluted = [
+      `{"__proto__": {"polluted": true}, "version": 1, "sealingPublicKey": "${fixture.sealingPublicKey}", "slots": ${JSON.stringify(fixture.slots)}}`,
+      `{"version": 1, "__proto__": {"version": 1}, "sealingPublicKey": "${fixture.sealingPublicKey}", "slots": ${JSON.stringify(fixture.slots)}}`,
+      `{"constructor": {"prototype": {"polluted": true}}, "version": 1}`,
+      `{"version": 1, "sealingPublicKey": "${fixture.sealingPublicKey}", "slots": [{"__proto__": {"type": "recovery"}}]}`,
+      documentWith((copy) => (copy.slots[0].constructor = 'x')),
+      // A plain assignment would set the prototype; defineProperty makes `__proto__` an own, enumerable key.
+      documentWith((copy) =>
+        Object.defineProperty(copy.slots[0].kdf, '__proto__', {
+          value: { N: 1 },
+          enumerable: true,
+        }),
+      ),
+    ];
+    for (const text of polluted) {
+      expect(codeOf(() => parseKeyring(text))).toBe('malformed-keyring');
+    }
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(Object.prototype, 'polluted')).toBe(false);
+  });
+
+  it('applies the same validation to hand-built objects', () => {
+    const keyring = parseKeyring(fixtureText);
+    expect(
+      codeOf(() => serializeKeyring({ ...keyring, attachPublicKey: 'x' } as unknown as IKeyring)),
+    ).toBe('malformed-keyring');
+    expect(codeOf(() => serializeKeyring(Object.create(keyring) as IKeyring))).toBe(
+      'malformed-keyring',
+    );
+    expect(codeOf(() => getSealingPublicKey({ ...keyring, slots: [] }))).toBe('malformed-keyring');
+  });
+
+  it('survives a seeded mutation fuzz: always a KeyringError or a document that round-trips', () => {
+    // mulberry32: a small deterministic PRNG, so a failure reproduces.
+    let state = 0x5eed1234;
+    const random = () => {
+      state = (state + 0x6d2b79f5) | 0;
+      let t = Math.imul(state ^ (state >>> 15), 1 | state);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    const pick = (limit: number) => Math.floor(random() * limit);
+    const alphabet = 'AZaz09-_+/=",:{}[] \né';
+    let accepted = 0;
+    let rejected = 0;
+    for (let round = 0; round < 1500; round += 1) {
+      let text = fixtureText;
+      for (let edits = 1 + pick(3); edits > 0; edits -= 1) {
+        const at = pick(text.length);
+        const kind = pick(4);
+        if (kind === 0)
+          text = text.slice(0, at) + alphabet[pick(alphabet.length)] + text.slice(at + 1);
+        else if (kind === 1) text = text.slice(0, at) + text.slice(at + 1 + pick(8));
+        else if (kind === 2)
+          text = text.slice(0, at) + alphabet[pick(alphabet.length)] + text.slice(at);
+        else text = text.slice(0, at) + text.slice(at, at + 1 + pick(40)) + text.slice(at);
+      }
+      try {
+        const keyring = parseKeyring(text);
+        accepted += 1;
+        expect(parseKeyring(serializeKeyring(keyring))).toEqual(keyring);
+      } catch (error) {
+        rejected += 1;
+        expect(error).toBeInstanceOf(KeyringError);
+        expect(['malformed-keyring', 'unsupported-version']).toContain(
+          (error as KeyringError).code,
+        );
+      }
+    }
+    // The fuzz must exercise both outcomes, or it proves nothing.
+    expect(rejected).toBeGreaterThan(500);
+    expect(accepted).toBeGreaterThan(0);
+  });
+});