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

package/src/__tests__/owner-link-grant-wipe.test.ts

@@ -0,0 +1,75 @@
+/**
+ * A read grant's secret bytes exist in the clear only for the length of one call on each end: the
+ * buffer the initiator seals and the buffer the responder decrypts are zero-filled before the call
+ * returns, and the read keys own copies of their own. Kept apart because it wraps the AEAD module
+ * for the whole file to see those buffers.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it, vi } from 'vitest';
+
+const seen = vi.hoisted(() => ({ sealed: [] as Uint8Array[], opened: [] as Uint8Array[] }));
+
+vi.mock('../aead.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../aead.js')>();
+  return {
+    ...actual,
+    gcmEncrypt: (...args: Parameters<typeof actual.gcmEncrypt>) => {
+      seen.sealed.push(args[2]);
+      return actual.gcmEncrypt(...args);
+    },
+    gcmDecrypt: (...args: Parameters<typeof actual.gcmDecrypt>) => {
+      const plaintext = actual.gcmDecrypt(...args);
+      seen.opened.push(plaintext);
+      return plaintext;
+    },
+  };
+});
+
+const { createLinkInitiator, createLinkResponder, openOwnerHandover, parseKeyring } =
+  await import('../index.js');
+const {
+  FIXTURE_RECOVERY_KEY,
+  KAT_BINDING,
+  KNOWN_AUTHORSHIP_MESSAGE,
+  KNOWN_AUTHORSHIP_TAG_HEX,
+  bytesOf,
+  hex,
+} = await import('./helpers.js');
+const { certifiedRuntime } = await import('./link-helpers.js');
+
+const fixture = parseKeyring(
+  readFileSync(fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)), 'utf8'),
+);
+
+describe('the read grant buffers', () => {
+  it('are zero-filled on both ends once the grant is sealed and opened', async () => {
+    const owner = await openOwnerHandover(fixture, {
+      type: 'recoveryKey',
+      recoveryKey: FIXTURE_RECOVERY_KEY,
+    });
+    const identity = certifiedRuntime(owner, KAT_BINDING);
+    const initiator = createLinkInitiator({ mode: 'owner', handover: owner });
+    const responder = createLinkResponder(identity, KAT_BINDING);
+    const { proof, link } = initiator.answer(responder.challenge(initiator.hello()));
+    const { link: runtimeSide } = responder.accept(proof);
+
+    seen.sealed.length = 0;
+    seen.opened.length = 0;
+    const grant = link.sealReadGrant(owner);
+    expect(seen.sealed).toHaveLength(1);
+    expect(seen.sealed[0]).toHaveLength(65);
+    expect(seen.sealed[0]!.every((byte) => byte === 0)).toBe(true);
+
+    const keys = runtimeSide.openReadGrant(grant);
+    expect(seen.opened).toHaveLength(1);
+    expect(seen.opened[0]).toHaveLength(65);
+    expect(seen.opened[0]!.every((byte) => byte === 0)).toBe(true);
+    expect(hex(keys.tagAuthorship(bytesOf(KNOWN_AUTHORSHIP_MESSAGE)))).toBe(
+      KNOWN_AUTHORSHIP_TAG_HEX,
+    );
+    keys.lock();
+    owner.dispose();
+  });
+});

package/src/__tests__/owner-link-known-answers.test.ts

@@ -0,0 +1,117 @@
+/**
+ * The owner link byte for byte: from fixed keys, ephemerals and nonces, both handshake modes give
+ * the pinned hello, challenge, transcript hash, proofs and frame keys, and every frame kind seals to
+ * the pinned bytes. The answers were computed outside this package (see `link-helpers.ts`), so a
+ * change to any label, field order, length prefix or nonce layout fails here.
+ */
+import { Buffer } from 'node:buffer';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { openOwnerHandover, parseKeyring, type IOwnerHandover } from '../index.js';
+import { deriveFrameKeys, transcriptHash } from '../owner-link.js';
+import {
+  FIXTURE_RECOVERY_KEY,
+  KAT_BINDING,
+  KAT_CERTIFICATE_HEX,
+  KAT_INSTANCE_PUBLIC_KEY_HEX,
+  KNOWN_AUTHORSHIP_MESSAGE,
+  KNOWN_AUTHORSHIP_TAG_HEX,
+  KNOWN_SEALING_PUBLIC_KEY_HEX,
+  bytesOf,
+  hex,
+} from './helpers.js';
+import {
+  KAT_FRAMES,
+  KAT_OWNER_LINK,
+  KAT_SPAWNER_LINK,
+  katOwnerLink,
+  katSpawnerLink,
+} from './link-helpers.js';
+
+const fixture = parseKeyring(
+  readFileSync(fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)), 'utf8'),
+);
+let owner: IOwnerHandover;
+
+beforeAll(async () => {
+  owner = await openOwnerHandover(fixture, {
+    type: 'recoveryKey',
+    recoveryKey: FIXTURE_RECOVERY_KEY,
+  });
+});
+
+describe('owner link known answers', () => {
+  it('runs the spawner-mode handshake to the pinned bytes', () => {
+    const { hello, challenge, proof, standing, initiatorLink } = katSpawnerLink();
+    expect(hex(hello)).toBe(KAT_SPAWNER_LINK.hello);
+    expect(hex(challenge)).toBe(KAT_SPAWNER_LINK.challenge);
+    expect(hex(proof)).toBe(KAT_SPAWNER_LINK.proof);
+    expect(standing).toBe('spawner');
+    expect(initiatorLink.binding).toEqual(KAT_BINDING);
+    expect(hex(initiatorLink.instancePublicKey)).toBe(KAT_INSTANCE_PUBLIC_KEY_HEX);
+  });
+
+  it('runs the owner-mode handshake to the pinned bytes, with the pinned certificate', () => {
+    const { hello, challenge, proof, standing, initiatorLink } = katOwnerLink(owner);
+    expect(hex(hello)).toBe(KAT_OWNER_LINK.hello);
+    expect(hex(challenge)).toBe(KAT_OWNER_LINK.challenge);
+    expect(hex(challenge)).toContain(KAT_CERTIFICATE_HEX);
+    expect(hex(proof)).toBe(KAT_OWNER_LINK.proof);
+    expect(standing).toBe('owner');
+    expect(initiatorLink.binding).toEqual(KAT_BINDING);
+  });
+
+  it('hashes the transcript and derives the frame keys as pinned', () => {
+    for (const [link, mode, certificate] of [
+      [KAT_SPAWNER_LINK, 'spawner', ''],
+      [KAT_OWNER_LINK, 'owner', KAT_CERTIFICATE_HEX],
+    ] as const) {
+      const challenge = Buffer.from(link.challenge, 'hex');
+      const hello = Buffer.from(link.hello, 'hex');
+      const th = transcriptHash({
+        mode,
+        initiatorEphemeral: hello.subarray(2, 34),
+        initiatorNonce: hello.subarray(34, 66),
+        responderEphemeral: challenge.subarray(0, 32),
+        responderNonce: challenge.subarray(32, 64),
+        instancePublicKey: challenge.subarray(64, 96),
+        binding: KAT_BINDING,
+        certificate: Buffer.from(certificate, 'hex'),
+      });
+      expect(hex(th)).toBe(link.transcript);
+      const keys = deriveFrameKeys(Buffer.from(link.sharedSecret, 'hex'), th);
+      expect(hex(keys.initiatorToResponder)).toBe(link.initiatorToResponder);
+      expect(hex(keys.responderToInitiator)).toBe(link.responderToInitiator);
+    }
+  });
+
+  it('seals one frame of each kind to the pinned bytes, and opens them on the other end', () => {
+    const spawner = katSpawnerLink();
+    const session = spawner.initiatorLink.seal('session', bytesOf(KAT_FRAMES.session.plaintext));
+    const ownerFrame = spawner.initiatorLink.seal('owner', bytesOf(KAT_FRAMES.owner.plaintext));
+    const reply = spawner.link.seal('owner', bytesOf(KAT_FRAMES.ownerReply.plaintext));
+    expect(hex(session)).toBe(KAT_FRAMES.session.sealed);
+    expect(hex(ownerFrame)).toBe(KAT_FRAMES.owner.sealed);
+    expect(hex(reply)).toBe(KAT_FRAMES.ownerReply.sealed);
+    expect(spawner.link.open(session)).toMatchObject({ kind: 'session' });
+    expect(Buffer.from(spawner.link.open(ownerFrame).plaintext).toString()).toBe(
+      KAT_FRAMES.owner.plaintext,
+    );
+    expect(Buffer.from(spawner.initiatorLink.open(reply).plaintext).toString()).toBe(
+      KAT_FRAMES.ownerReply.plaintext,
+    );
+
+    const ownerSide = katOwnerLink(owner);
+    const grant = ownerSide.initiatorLink.sealReadGrant(owner);
+    expect(hex(grant)).toBe(KAT_FRAMES.grant.sealed);
+    const keys = ownerSide.link.openReadGrant(grant);
+    expect(hex(keys.sealing.publicKey)).toBe(KNOWN_SEALING_PUBLIC_KEY_HEX);
+    expect(hex(keys.tagAuthorship(bytesOf(KNOWN_AUTHORSHIP_MESSAGE)))).toBe(
+      KNOWN_AUTHORSHIP_TAG_HEX,
+    );
+    keys.lock();
+  });
+});

package/src/__tests__/owner-link-secret-wipe.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Secrets that live only for part of a handshake are zero-filled when that part ends: the responder
+ * wipes the frame keys it derived and the proof it expected when the proof it gets is refused (and
+ * the expected proof once it is accepted), and the spawner wipes the shared secret of the exchange
+ * once the spawner key is derived. Kept apart because it wraps the link primitives for the whole file
+ * to see the buffers they hand out; the frame keys are copies made inside the derivation, so those
+ * are found by their known values among what the derivation allocates.
+ */
+import { Buffer } from 'node:buffer';
+
+import { describe, expect, it, vi } from 'vitest';
+
+type TSecret = { readonly before: Uint8Array; readonly live: Uint8Array };
+
+const seen = vi.hoisted(() => ({ agreed: [] as TSecret[], macs: [] as TSecret[] }));
+
+vi.mock('../link-primitives.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../link-primitives.js')>();
+  return {
+    ...actual,
+    agree: (...args: Parameters<typeof actual.agree>) => {
+      const shared = actual.agree(...args);
+      seen.agreed.push({ before: Uint8Array.from(shared), live: shared });
+      return shared;
+    },
+    hmac: (...args: Parameters<typeof actual.hmac>) => {
+      const mac = actual.hmac(...args);
+      seen.macs.push({ before: Uint8Array.from(mac), live: mac });
+      return mac;
+    },
+  };
+});
+
+const { createLinkResponder, createRuntimeIdentity, startSpawnerExchange } =
+  await import('../index.js');
+const { createLinkInitiatorWith } = await import('../owner-link.js');
+const { KAT_BINDING, hex } = await import('./helpers.js');
+const { KAT_SPAWNER_LINK, fixedEntropy, katRuntime, refusalOf } = await import('./link-helpers.js');
+
+const isZero = (bytes: Uint8Array): boolean => bytes.every((byte) => byte === 0);
+
+/** Every buffer `Buffer.from` makes while `run` runs. */
+function buffersMadeBy(run: () => void): Buffer[] {
+  const original = Buffer.from.bind(Buffer) as (...args: unknown[]) => Buffer;
+  const made: Buffer[] = [];
+  const spy = vi.spyOn(Buffer, 'from').mockImplementation(((...args: unknown[]) => {
+    const buffer = original(...args);
+    made.push(buffer);
+    return buffer;
+  }) as typeof Buffer.from);
+  try {
+    run();
+  } finally {
+    spy.mockRestore();
+  }
+  return made;
+}
+
+/** The KAT spawner-mode responder that has answered the KAT hello, and what it is holding for the proof. */
+function answeredResponder() {
+  const { identity, spawnerKey, instancePublicKey } = katRuntime(KAT_SPAWNER_LINK);
+  const initiator = createLinkInitiatorWith(
+    { mode: 'spawner', spawnerKey, instancePublicKey },
+    fixedEntropy([KAT_SPAWNER_LINK.initiatorSeed], [KAT_SPAWNER_LINK.initiatorNonce]),
+  );
+  const responder = createLinkResponder(identity, KAT_BINDING);
+  const hello = initiator.hello();
+  const macsBefore = seen.macs.length;
+  const made = buffersMadeBy(() => responder.challenge(hello));
+  const frameKeys = [KAT_SPAWNER_LINK.initiatorToResponder, KAT_SPAWNER_LINK.responderToInitiator].map(
+    (known) => made.find((buffer) => hex(buffer) === known),
+  );
+  const expectedProof = seen.macs
+    .slice(macsBefore)
+    .find((mac) => hex(mac.before) === KAT_SPAWNER_LINK.proof);
+  return { responder, frameKeys, expectedProof: expectedProof?.live };
+}
+
+describe('the responder, once the proof it waited for has come', () => {
+  it('wipes the frame keys and the expected proof when it refuses the proof', () => {
+    const { responder, frameKeys, expectedProof } = answeredResponder();
+    const held = [...frameKeys, expectedProof];
+    expect(held.every((secret) => secret !== undefined && !isZero(secret))).toBe(true);
+
+    expect(refusalOf(() => responder.accept(Buffer.alloc(32, 7)))).toBe('bad-proof');
+    for (const secret of held) expect(isZero(secret!)).toBe(true);
+  });
+
+  it('wipes the expected proof, and not the frame keys the link now owns, when it accepts it', () => {
+    const { responder, frameKeys, expectedProof } = answeredResponder();
+    expect(expectedProof).toBeDefined();
+    expect(isZero(expectedProof!)).toBe(false);
+
+    const proof = Buffer.from(KAT_SPAWNER_LINK.proof, 'hex');
+    const { link } = responder.accept(proof);
+    expect(isZero(expectedProof!)).toBe(true);
+    expect(frameKeys.every((key) => key !== undefined && !isZero(key))).toBe(true);
+    link.close();
+  });
+});
+
+describe('the spawner exchange', () => {
+  it('wipes the shared secret once the spawner key is derived', () => {
+    const identity = createRuntimeIdentity();
+    const exchange = startSpawnerExchange();
+    const reply = identity.answerSpawnerExchange(exchange.message);
+    const agreedBefore = seen.agreed.length;
+
+    const { spawnerKey } = exchange.complete(reply);
+    const secrets = seen.agreed.slice(agreedBefore);
+    expect(secrets).toHaveLength(1);
+    expect(isZero(secrets[0]!.before)).toBe(false);
+    expect(isZero(secrets[0]!.live)).toBe(true);
+    spawnerKey.wipe();
+  });
+});

package/src/__tests__/owner-link.test.ts

@@ -0,0 +1,229 @@
+/**
+ * The owner link as its two ends use it: a spawner links with its spawner key and learns the
+ * binding it then certifies; an owner links with its handover once the runtime is certified; frames
+ * flow both ways under the link keys; and the read grant goes only over an owner link, from the
+ * handover that opened it, into read keys on the runtime's side.
+ */
+import { Buffer } from 'node:buffer';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import {
+  createKeyring,
+  createLinkInitiator,
+  createLinkResponder,
+  linkFrameKind,
+  openOwnerHandover,
+  parseKeyring,
+  type IOwnerHandover,
+  type IRuntimeIdentity,
+  type ILinkBinding,
+} from '../index.js';
+import {
+  FIXTURE_RECOVERY_KEY,
+  KAT_BINDING,
+  KNOWN_AUTHORSHIP_MESSAGE,
+  KNOWN_AUTHORSHIP_TAG_HEX,
+  KNOWN_SEALING_PUBLIC_KEY_HEX,
+  bytesOf,
+  codeOf,
+  hex,
+} from './helpers.js';
+import { certifiedRuntime, refusalOf, spawnedRuntime } from './link-helpers.js';
+
+const fixture = parseKeyring(
+  readFileSync(fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)), 'utf8'),
+);
+let owner: IOwnerHandover;
+let stranger: IOwnerHandover;
+
+beforeAll(async () => {
+  owner = await openOwnerHandover(fixture, {
+    type: 'recoveryKey',
+    recoveryKey: FIXTURE_RECOVERY_KEY,
+  });
+  const other = await createKeyring({ passphrase: 'a keyring that is not the owner one' });
+  stranger = await openOwnerHandover(other.keyring, {
+    type: 'recoveryKey',
+    recoveryKey: other.recoveryKey,
+  });
+});
+
+afterAll(() => {
+  owner.dispose();
+  stranger.dispose();
+});
+
+function ownerLink(identity: IRuntimeIdentity, binding: ILinkBinding = KAT_BINDING) {
+  const initiator = createLinkInitiator({ mode: 'owner', handover: owner });
+  const responder = createLinkResponder(identity, binding);
+  const { proof, link } = initiator.answer(responder.challenge(initiator.hello()));
+  return { initiatorLink: link, ...responder.accept(proof) };
+}
+
+describe('a spawner link', () => {
+  it('admits the spawner, teaches it the binding, and lets it certify the runtime', () => {
+    const { identity, spawnerKey, instancePublicKey } = spawnedRuntime();
+    const initiator = createLinkInitiator({ mode: 'spawner', spawnerKey, instancePublicKey });
+    const responder = createLinkResponder(identity, KAT_BINDING);
+    const { proof, link } = initiator.answer(responder.challenge(initiator.hello()));
+    const accepted = responder.accept(proof);
+    expect(accepted.standing).toBe('spawner');
+    expect(link.standing).toBe('spawner');
+    expect(link.binding).toEqual(KAT_BINDING);
+    expect(hex(link.instancePublicKey)).toBe(hex(identity.instancePublicKey));
+
+    // What the spawner learned is authentic, so it is what it certifies.
+    identity.installTrustRoot(owner.certify(link.instancePublicKey, link.binding), link.binding);
+    spawnerKey.wipe();
+    expect(identity.certified).toBe(true);
+    expect(ownerLink(identity).standing).toBe('owner');
+  });
+});
+
+describe('an owner link', () => {
+  it('admits the owner of a certified runtime with owner standing', () => {
+    const identity = certifiedRuntime(owner, KAT_BINDING);
+    const { initiatorLink, link, standing } = ownerLink(identity);
+    expect(standing).toBe('owner');
+    expect(link.standing).toBe('owner');
+    expect(initiatorLink.binding).toEqual(KAT_BINDING);
+    expect(hex(initiatorLink.instancePublicKey)).toBe(hex(identity.instancePublicKey));
+  });
+
+  it('carries frames both ways, in order, with their kinds', () => {
+    const { initiatorLink, link } = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    for (let index = 0; index < 5; index += 1) {
+      const up = initiatorLink.seal(index % 2 === 0 ? 'session' : 'owner', bytesOf(`up ${index}`));
+      expect(linkFrameKind(up)).toBe(index % 2 === 0 ? 'session' : 'owner');
+      const opened = link.open(up);
+      expect(opened.kind).toBe(index % 2 === 0 ? 'session' : 'owner');
+      expect(Buffer.from(opened.plaintext).toString()).toBe(`up ${index}`);
+      const down = link.seal('session', bytesOf(`down ${index}`));
+      expect(Buffer.from(initiatorLink.open(down).plaintext).toString()).toBe(`down ${index}`);
+    }
+    const empty = initiatorLink.seal('owner', new Uint8Array(0));
+    expect(link.open(empty).plaintext).toHaveLength(0);
+  });
+
+  it('is closed by close(), which ends sealing and opening on that end', () => {
+    const { initiatorLink, link } = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    const frame = initiatorLink.seal('session', bytesOf('before'));
+    initiatorLink.close();
+    expect(initiatorLink.closed).toBe(true);
+    expect(codeOf(() => initiatorLink.seal('session', bytesOf('after')))).toBe('link-closed');
+    expect(codeOf(() => initiatorLink.open(link.seal('session', bytesOf('x'))))).toBe(
+      'link-closed',
+    );
+    initiatorLink.close();
+    expect(Buffer.from(link.open(frame).plaintext).toString()).toBe('before');
+  });
+});
+
+describe('the read grant', () => {
+  it('opens on the runtime into read keys of the owner, never the attach key', () => {
+    const { initiatorLink, link } = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    const keys = link.openReadGrant(initiatorLink.sealReadGrant(owner));
+    expect(hex(keys.sealing.publicKey)).toBe(KNOWN_SEALING_PUBLIC_KEY_HEX);
+    expect(keys.sealing.privateKey.asymmetricKeyType).toBe('x25519');
+    expect(hex(keys.tagAuthorship(bytesOf(KNOWN_AUTHORSHIP_MESSAGE)))).toBe(
+      KNOWN_AUTHORSHIP_TAG_HEX,
+    );
+    expect('attach' in keys).toBe(false);
+    keys.lock();
+    expect(codeOf(() => keys.sealing)).toBe('keys-locked');
+  });
+
+  it('is sealed only over an owner link, and only from the handover that opened it', () => {
+    const { identity, spawnerKey, instancePublicKey } = spawnedRuntime();
+    const initiator = createLinkInitiator({ mode: 'spawner', spawnerKey, instancePublicKey });
+    const responder = createLinkResponder(identity, KAT_BINDING);
+    const { link } = initiator.answer(responder.challenge(initiator.hello()));
+    expect(codeOf(() => link.sealReadGrant(owner))).toBe('invalid-argument');
+
+    const { initiatorLink } = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    expect(codeOf(() => initiatorLink.sealReadGrant(stranger))).toBe('invalid-argument');
+  });
+
+  it('is refused by a spawner-standing link, which closes', () => {
+    const { identity, spawnerKey, instancePublicKey } = spawnedRuntime();
+    const initiator = createLinkInitiator({ mode: 'spawner', spawnerKey, instancePublicKey });
+    const responder = createLinkResponder(identity, KAT_BINDING);
+    const { proof, link: spawnerSide } = initiator.answer(responder.challenge(initiator.hello()));
+    const { link } = responder.accept(proof);
+    // A grant-kind frame sealed under the spawner link's own keys still opens nothing.
+    const { initiatorLink } = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    const grant = initiatorLink.sealReadGrant(owner);
+    expect(codeOf(() => link.openReadGrant(grant))).toBe('invalid-argument');
+    expect(link.closed).toBe(true);
+    expect(spawnerSide.closed).toBe(false);
+  });
+
+  it('is opened only as a grant: open() refuses it, and openReadGrant refuses other kinds', () => {
+    const first = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    const grant = first.initiatorLink.sealReadGrant(owner);
+    expect(linkFrameKind(grant)).toBe('grant');
+    expect(codeOf(() => first.link.open(grant))).toBe('invalid-argument');
+    expect(first.link.closed).toBe(true);
+
+    const second = ownerLink(certifiedRuntime(owner, KAT_BINDING));
+    expect(
+      codeOf(() => second.link.openReadGrant(second.initiatorLink.seal('owner', bytesOf('x')))),
+    ).toBe('invalid-argument');
+    expect(second.link.closed).toBe(true);
+  });
+});
+
+describe('steps out of turn', () => {
+  it('are refused on both ends, and a spent end stays spent', () => {
+    const identity = certifiedRuntime(owner, KAT_BINDING);
+    const initiator = createLinkInitiator({ mode: 'owner', handover: owner });
+    expect(refusalOf(() => initiator.answer(new Uint8Array(10)))).toBe('out-of-order');
+    const hello = initiator.hello();
+    expect(refusalOf(() => initiator.hello())).toBe('out-of-order');
+    const responder = createLinkResponder(identity, KAT_BINDING);
+    expect(refusalOf(() => responder.accept(new Uint8Array(64)))).toBe('out-of-order');
+    const challenge = responder.challenge(hello);
+    expect(refusalOf(() => responder.challenge(hello))).toBe('out-of-order');
+    const { proof } = initiator.answer(challenge);
+    expect(refusalOf(() => initiator.answer(challenge))).toBe('out-of-order');
+    responder.accept(proof);
+    expect(refusalOf(() => responder.accept(proof))).toBe('out-of-order');
+  });
+
+  it('refuse a disposed handover or a wiped spawner key before any message', async () => {
+    const disposed = await openOwnerHandover(fixture, {
+      type: 'recoveryKey',
+      recoveryKey: FIXTURE_RECOVERY_KEY,
+    });
+    disposed.dispose();
+    expect(codeOf(() => createLinkInitiator({ mode: 'owner', handover: disposed }))).toBe(
+      'keys-locked',
+    );
+    const { identity, spawnerKey, instancePublicKey } = spawnedRuntime();
+    spawnerKey.wipe();
+    expect(
+      codeOf(() => createLinkInitiator({ mode: 'spawner', spawnerKey, instancePublicKey })),
+    ).toBe('keys-locked');
+    expect(identity.spawnerKeyHeld).toBe(true);
+    expect(codeOf(() => createLinkInitiator({ mode: 'other' } as never))).toBe('invalid-argument');
+    expect(codeOf(() => createLinkResponder(identity, { runtimeId: '', generation: 'g' }))).toBe(
+      'invalid-argument',
+    );
+  });
+});
+
+describe('linkFrameKind', () => {
+  it('names the kind byte and refuses anything that is not a frame', () => {
+    expect(refusalOf(() => linkFrameKind(new Uint8Array(0)))).toBe('malformed');
+    expect(refusalOf(() => linkFrameKind(Buffer.from([4, ...new Uint8Array(16)])))).toBe(
+      'malformed',
+    );
+    expect(refusalOf(() => linkFrameKind(Buffer.from([1, ...new Uint8Array(15)])))).toBe(
+      'malformed',
+    );
+    expect(linkFrameKind(Buffer.from([3, ...new Uint8Array(16)]))).toBe('grant');
+  });
+});

package/src/__tests__/read-keys.test.ts

@@ -0,0 +1,67 @@
+/**
+ * What an unlock yields is what reading needs and nothing more: the sealing keypair and the
+ * authorship key. The attach keypair, which proves ownership to a verifier, is reachable from none
+ * of it, so a process that holds read keys for a while can read and vouch but never present itself
+ * as the owner.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { KeyObject } from 'node:crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  checkSealingPublicKey,
+  createKeyring,
+  getSealingPublicKey,
+  parseKeyring,
+  repairSealingPublicKey,
+  unlockWithPassphrase,
+  unlockWithRecoveryKey,
+  type IReadKeys,
+} from '../index.js';
+import {
+  FIXTURE_PASSPHRASE_AS_TYPED,
+  FIXTURE_RECOVERY_KEY,
+  KNOWN_SEALING_PUBLIC_KEY_HEX,
+  codeOf,
+  hex,
+  reachableValues,
+} from './helpers.js';
+
+const fixture = parseKeyring(
+  readFileSync(fileURLToPath(new URL('./fixtures/keyring-v1.json', import.meta.url)), 'utf8'),
+);
+
+function keyTypes(keys: IReadKeys): string[] {
+  return reachableValues(keys)
+    .filter((value): value is KeyObject => value instanceof KeyObject)
+    .map((key) => `${key.type}:${key.asymmetricKeyType ?? 'secret'}`)
+    .sort();
+}
+
+describe('read keys', () => {
+  it('are what every unlock yields, with the sealing keypair and no attach keypair', async () => {
+    const created = await createKeyring({ passphrase: 'a passphrase for this test' });
+    for (const keys of [
+      await unlockWithPassphrase(fixture, FIXTURE_PASSPHRASE_AS_TYPED),
+      await unlockWithRecoveryKey(fixture, FIXTURE_RECOVERY_KEY),
+      created.unlocked,
+    ]) {
+      expect('attach' in keys).toBe(false);
+      expect(keyTypes(keys)).toEqual(['private:x25519']);
+      keys.lock();
+    }
+  });
+
+  it('carry what the sealing-key check and repair need, and stop doing so once locked', async () => {
+    const keys = await unlockWithRecoveryKey(fixture, FIXTURE_RECOVERY_KEY);
+    const swapped = { ...fixture, sealingPublicKey: 'A'.repeat(42) + 'E' };
+    expect(checkSealingPublicKey(swapped, keys)).toEqual({ matches: false });
+    const repaired = repairSealingPublicKey(swapped, keys);
+    expect(hex(getSealingPublicKey(repaired))).toBe(KNOWN_SEALING_PUBLIC_KEY_HEX);
+    keys.lock();
+    expect(codeOf(() => checkSealingPublicKey(fixture, keys))).toBe('keys-locked');
+    expect(codeOf(() => repairSealingPublicKey(swapped, keys))).toBe('keys-locked');
+  });
+});

package/src/__tests__/recovery-key.test.ts

@@ -0,0 +1,76 @@
+import { randomBytes } from 'node:crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import { formatRecoveryKey, parseRecoveryKey, RECOVERY_KEY_BYTES } from '../recovery-key.js';
+import {
+  bytesOf,
+  codeOf,
+  FIXTURE_RECOVERY_KEY,
+  FIXTURE_RECOVERY_KEY_BYTES,
+  hex,
+} from './helpers.js';
+
+describe('recovery key format', () => {
+  it('formats known bytes as grouped Crockford base32', () => {
+    expect(formatRecoveryKey(FIXTURE_RECOVERY_KEY_BYTES)).toBe(FIXTURE_RECOVERY_KEY);
+    expect(formatRecoveryKey(new Uint8Array(RECOVERY_KEY_BYTES))).toBe(
+      '0000-0000-0000-0000-0000-0000-0000-0000',
+    );
+    expect(formatRecoveryKey(new Uint8Array(RECOVERY_KEY_BYTES).fill(0xff))).toBe(
+      'ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZ',
+    );
+  });
+
+  it('round-trips random keys', () => {
+    for (let index = 0; index < 200; index += 1) {
+      const bytes = randomBytes(RECOVERY_KEY_BYTES);
+      const text = formatRecoveryKey(bytes);
+      expect(text).toMatch(/^[0-9A-HJKMNP-TV-Z]{4}(-[0-9A-HJKMNP-TV-Z]{4}){7}$/);
+      expect(hex(parseRecoveryKey(text))).toBe(hex(bytes));
+    }
+  });
+
+  it('reads the key the way a person types it', () => {
+    const expected = hex(FIXTURE_RECOVERY_KEY_BYTES);
+    const lower = FIXTURE_RECOVERY_KEY.toLowerCase();
+    expect(hex(parseRecoveryKey(lower))).toBe(expected);
+    expect(hex(parseRecoveryKey(FIXTURE_RECOVERY_KEY.replaceAll('-', '')))).toBe(expected);
+    expect(hex(parseRecoveryKey(FIXTURE_RECOVERY_KEY.replaceAll('-', ' ')))).toBe(expected);
+    expect(hex(parseRecoveryKey(`  ${FIXTURE_RECOVERY_KEY}\n`))).toBe(expected);
+    // Crockford look-alikes: O reads as 0, I and L read as 1.
+    expect(
+      hex(parseRecoveryKey('0000-0000-0000-0000-0000-0000-0000-0000'.replaceAll('0', 'o'))),
+    ).toBe('00'.repeat(RECOVERY_KEY_BYTES));
+    expect(
+      hex(parseRecoveryKey('1111-1111-1111-1111-1111-1111-1111-1111'.replaceAll('1', 'L'))),
+    ).toBe(hex(parseRecoveryKey('1111-1111-1111-1111-1111-1111-1111-1111')));
+    expect(
+      hex(parseRecoveryKey('1111-1111-1111-1111-1111-1111-1111-1111'.replaceAll('1', 'i'))),
+    ).toBe(hex(parseRecoveryKey('1111-1111-1111-1111-1111-1111-1111-1111')));
+  });
+
+  it('rejects text that is not a recovery key with invalid-recovery-key', () => {
+    const wrong = [
+      '',
+      FIXTURE_RECOVERY_KEY.slice(0, -1),
+      `${FIXTURE_RECOVERY_KEY}0`,
+      FIXTURE_RECOVERY_KEY.replace('M', 'U'), // U is not in the Crockford alphabet
+      FIXTURE_RECOVERY_KEY.replace('M', '*'),
+      FIXTURE_RECOVERY_KEY.replace('M', 'ß'), // would fold to "SS" under toUpperCase
+      FIXTURE_RECOVERY_KEY.replace('M', 'ı'), // would fold to "I"
+      'x'.repeat(10_000),
+    ];
+    for (const text of wrong)
+      expect(codeOf(() => parseRecoveryKey(text))).toBe('invalid-recovery-key');
+    expect(codeOf(() => parseRecoveryKey(undefined))).toBe('invalid-recovery-key');
+    expect(codeOf(() => parseRecoveryKey(bytesOf(FIXTURE_RECOVERY_KEY)))).toBe(
+      'invalid-recovery-key',
+    );
+  });
+
+  it('refuses to format anything but 20 bytes', () => {
+    expect(codeOf(() => formatRecoveryKey(new Uint8Array(19)))).toBe('invalid-argument');
+    expect(codeOf(() => formatRecoveryKey(new Uint8Array(21)))).toBe('invalid-argument');
+  });
+});