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

package/src/keyslot.ts

@@ -0,0 +1,66 @@
+import { Buffer } from 'node:buffer';
+import { randomBytes } from 'node:crypto';
+
+import { gcmDecrypt, gcmEncrypt, GCM_IV_BYTES } from './aead.js';
+import { concatLengthPrefixed, decodeKeyringField, toBase64Url, utf8 } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { hkdf32 } from './kdf.js';
+import { SLOT_ID_BYTES, WRAPPED_KEY_BYTES } from './keyring-document.js';
+import { KEYRING_VERSION, type TKeyslot, type TKeyslotType } from './keyring-types.js';
+
+/** `info` of the recovery slot's key-encryption key. Versioned like every other HKDF label. */
+export const RECOVERY_KEK_LABEL = 'robota/keyring/v1/recovery-kek';
+
+export function newSlotId(): string {
+  return toBase64Url(randomBytes(SLOT_ID_BYTES));
+}
+
+/**
+ * The key-encryption key of a recovery slot. The recovery key is 160 random bits, so HKDF is all it
+ * needs; stretching it with scrypt would add cost and no strength.
+ */
+export function deriveRecoveryKek(recoveryKeyBytes: Uint8Array): Buffer {
+  return hkdf32(recoveryKeyBytes, RECOVERY_KEK_LABEL);
+}
+
+/**
+ * What the wrapping authenticates: version, slot id and slot type. A slot that is relabelled,
+ * re-identified or moved to a document of another version stops unwrapping. The sealing public key
+ * is deliberately NOT bound: the product detects a swapped public key at unlock and repairs it, and
+ * a binding would turn that repairable tamper into a lockout.
+ */
+export function keyslotAad(slotId: string, slotType: TKeyslotType): Buffer {
+  return concatLengthPrefixed([Buffer.from([KEYRING_VERSION]), utf8(slotId), utf8(slotType)]);
+}
+
+export interface IWrappedMasterKey {
+  readonly iv: string;
+  readonly wrappedKey: string;
+}
+
+/** AES-256-GCM wrap of the master key under `kek` with a fresh random 12-byte IV. */
+export function wrapMasterKey(
+  kek: Uint8Array,
+  masterKey: Uint8Array,
+  slotId: string,
+  slotType: TKeyslotType,
+): IWrappedMasterKey {
+  const iv = randomBytes(GCM_IV_BYTES);
+  const wrapped = gcmEncrypt(kek, iv, masterKey, keyslotAad(slotId, slotType));
+  return { iv: toBase64Url(iv), wrappedKey: toBase64Url(wrapped) };
+}
+
+/**
+ * Unwraps the master key of `slot` with `kek`. Any failure to authenticate is `wrong-credential`:
+ * a wrong passphrase, a wrong recovery key and a tampered slot cannot be told apart, and the
+ * caller must not be able to either. The caller owns (and wipes) `kek` and the returned key.
+ */
+export function unwrapMasterKey(kek: Uint8Array, slot: TKeyslot): Buffer {
+  const iv = decodeKeyringField(slot.iv, GCM_IV_BYTES);
+  const wrapped = decodeKeyringField(slot.wrappedKey, WRAPPED_KEY_BYTES);
+  try {
+    return gcmDecrypt(kek, iv, wrapped, keyslotAad(slot.id, slot.type));
+  } catch {
+    throw new KeyringError('wrong-credential', 'The credential did not open the keyring.');
+  }
+}

package/src/link-entropy.ts

@@ -0,0 +1,24 @@
+/**
+ * Where the owner link's randomness comes from. Every instance key, ephemeral key and nonce of the
+ * spawner exchange and the handshake is drawn here, so the package's known-answer tests can replay a
+ * whole exchange or handshake from fixed values. The entry point only ever draws from `randomBytes`;
+ * nothing a caller of the package can reach takes other entropy.
+ */
+import { randomBytes } from 'node:crypto';
+
+import type { Buffer } from 'node:buffer';
+
+export const LINK_SEED_BYTES = 32;
+export const LINK_NONCE_BYTES = 32;
+
+export interface ILinkEntropy {
+  /** A fresh 32-byte private-key seed. The caller wipes it once the key exists. */
+  seed(): Buffer;
+  /** A fresh 32-byte nonce. */
+  nonce(): Buffer;
+}
+
+export const SYSTEM_LINK_ENTROPY: ILinkEntropy = {
+  seed: () => randomBytes(LINK_SEED_BYTES),
+  nonce: () => randomBytes(LINK_NONCE_BYTES),
+};

package/src/link-frames.ts

@@ -0,0 +1,271 @@
+/**
+ * Frame protection once a link is established.
+ *
+ * Every frame after the handshake is AES-256-GCM under the key of its direction, with a 96-bit
+ * big-endian counter as the nonce and the direction and frame kind as the AAD. The counter is never
+ * sent: each end expects the next one, so a replayed, reordered, dropped or misdirected frame fails
+ * authentication like a tampered one, and the first frame that fails closes the link. A relay
+ * between the two ends can only carry or drop frames.
+ *
+ * There are three kinds. `session` and `owner` frames carry bytes the carrier decodes. A `grant`
+ * frame carries the owner's read keys and never passes through JSON: it is sealed from and opened
+ * into key objects and byte buffers this module zero-fills. A grant travels only on an owner link,
+ * from the handover that opened it, because whoever can send one decides which key the runtime
+ * seals to.
+ */
+import { Buffer } from 'node:buffer';
+
+import { gcmDecrypt, gcmEncrypt, GCM_IV_BYTES, GCM_TAG_BYTES } from './aead.js';
+import { isBytes, wipe } from './bytes.js';
+import { KeyringError, LinkRefusedError } from './errors.js';
+import { x25519KeyPairFromSeed } from './key-pairs.js';
+import { KEY_BYTES } from './kdf.js';
+import { ownerHandoverSecrets, type IOwnerHandover } from './owner-handover.js';
+import { createReadKeys, type IReadKeys } from './read-keys.js';
+import type { ILinkBinding } from './runtime-certificate.js';
+
+/** How the initiator was admitted, which is the standing its link has. */
+export type TLinkMode = 'spawner' | 'owner';
+export type TLinkFrameKind = 'session' | 'owner' | 'grant';
+/** The kinds a caller seals and opens as bytes; a grant has its own two operations. */
+export type TLinkDataFrameKind = Exclude<TLinkFrameKind, 'grant'>;
+
+const KIND_BYTES: Readonly<Record<TLinkFrameKind, number>> = { session: 1, owner: 2, grant: 3 };
+const KINDS_BY_BYTE: ReadonlyMap<number, TLinkFrameKind> = new Map(
+  Object.entries(KIND_BYTES).map(([kind, byte]) => [byte, kind as TLinkFrameKind]),
+);
+/** The direction byte of the AAD names the sending end. */
+const DIRECTION_BYTES = { initiator: 1, responder: 2 } as const;
+type TLinkRole = keyof typeof DIRECTION_BYTES;
+
+/** The kind byte and the GCM tag around every frame's ciphertext. */
+export const LINK_FRAME_OVERHEAD_BYTES = 1 + GCM_TAG_BYTES;
+/** The most one frame carries; a carrier bounds its frames below this. */
+export const LINK_FRAME_MAX_PLAINTEXT_BYTES = 16 * 1024 * 1024;
+const GRANT_VERSION = 1;
+/** version | sealing key seed | authorship key */
+const GRANT_PLAINTEXT_BYTES = 1 + KEY_BYTES + KEY_BYTES;
+/** A sealed read grant is always exactly this long. */
+export const LINK_GRANT_FRAME_BYTES = GRANT_PLAINTEXT_BYTES + LINK_FRAME_OVERHEAD_BYTES;
+
+export interface ILinkFrameKeys {
+  readonly initiatorToResponder: Buffer;
+  readonly responderToInitiator: Buffer;
+}
+
+/** The kind a frame says it is. Unauthenticated until it opens, which checks the kind too. */
+export function linkFrameKind(frame: Uint8Array): TLinkFrameKind {
+  const kind =
+    isBytes(frame) && frame.length >= LINK_FRAME_OVERHEAD_BYTES
+      ? KINDS_BY_BYTE.get(frame[0]!)
+      : undefined;
+  if (kind === undefined) throw new LinkRefusedError('malformed');
+  return kind;
+}
+
+function nonceFor(counter: number): Buffer {
+  const nonce = Buffer.alloc(GCM_IV_BYTES);
+  nonce.writeBigUInt64BE(BigInt(counter), GCM_IV_BYTES - 8);
+  return nonce;
+}
+
+/** One end of an established link. */
+export interface IEstablishedLink {
+  readonly standing: TLinkMode;
+  /** The runtime start the link is bound to: authenticated by the handshake on both ends. */
+  readonly binding: ILinkBinding;
+  /** The runtime's instance key: checked by the initiator, its own at the responder. */
+  readonly instancePublicKey: Uint8Array;
+  readonly closed: boolean;
+  seal(kind: TLinkDataFrameKind, plaintext: Uint8Array): Uint8Array;
+  /** The next frame from the other end; throws, and closes the link, unless it is exactly that. */
+  open(frame: Uint8Array): { readonly kind: TLinkDataFrameKind; readonly plaintext: Buffer };
+  /** Zero-fills both frame keys. Idempotent. */
+  close(): void;
+}
+
+export interface IInitiatorLink extends IEstablishedLink {
+  /**
+   * The owner's read keys (the sealing key and the authorship key, never the master key or the
+   * attach key) as one grant frame. Only on an owner link, and only from the handover that opened it.
+   */
+  sealReadGrant(handover: IOwnerHandover): Uint8Array;
+}
+
+export interface IResponderLink extends IEstablishedLink {
+  /** The read keys a grant frame carries. Only on an owner-standing link; anything else closes it. */
+  openReadGrant(frame: Uint8Array): IReadKeys;
+}
+
+abstract class LinkEnd implements IEstablishedLink {
+  readonly standing: TLinkMode;
+  readonly binding: ILinkBinding;
+  readonly #role: TLinkRole;
+  readonly #instancePublicKey: Uint8Array;
+  #sendKey: Buffer | undefined;
+  #receiveKey: Buffer | undefined;
+  #sent = 0;
+  #received = 0;
+
+  constructor(
+    role: TLinkRole,
+    standing: TLinkMode,
+    binding: ILinkBinding,
+    instancePublicKey: Uint8Array,
+    keys: ILinkFrameKeys,
+  ) {
+    this.#role = role;
+    this.standing = standing;
+    this.binding = Object.freeze({ runtimeId: binding.runtimeId, generation: binding.generation });
+    this.#instancePublicKey = Uint8Array.from(instancePublicKey);
+    this.#sendKey = role === 'initiator' ? keys.initiatorToResponder : keys.responderToInitiator;
+    this.#receiveKey = role === 'initiator' ? keys.responderToInitiator : keys.initiatorToResponder;
+  }
+
+  get instancePublicKey(): Uint8Array {
+    return Uint8Array.from(this.#instancePublicKey);
+  }
+
+  get closed(): boolean {
+    return this.#sendKey === undefined;
+  }
+
+  seal(kind: TLinkDataFrameKind, plaintext: Uint8Array): Uint8Array {
+    if (kind !== 'session' && kind !== 'owner') {
+      throw new KeyringError('invalid-argument', 'A frame is a session or an owner frame.');
+    }
+    return this.sealKind(kind, plaintext);
+  }
+
+  open(frame: Uint8Array): { readonly kind: TLinkDataFrameKind; readonly plaintext: Buffer } {
+    const kind = this.kindOf(frame);
+    if (kind === 'grant') {
+      this.close();
+      throw new KeyringError('invalid-argument', 'A read grant opens only as a grant.');
+    }
+    return { kind, plaintext: this.openKind(frame, kind) };
+  }
+
+  close(): void {
+    wipe(this.#sendKey, this.#receiveKey);
+    this.#sendKey = undefined;
+    this.#receiveKey = undefined;
+  }
+
+  protected sealKind(kind: TLinkFrameKind, plaintext: Uint8Array): Uint8Array {
+    if (!isBytes(plaintext) || plaintext.length > LINK_FRAME_MAX_PLAINTEXT_BYTES) {
+      throw new KeyringError(
+        'invalid-argument',
+        `A frame carries 0-${LINK_FRAME_MAX_PLAINTEXT_BYTES} bytes.`,
+      );
+    }
+    const key = this.#requireOpen(this.#sendKey);
+    if (!Number.isSafeInteger(this.#sent + 1)) {
+      this.close();
+      throw new KeyringError('link-closed', 'The link has sent all the frames it can.');
+    }
+    const aad = Buffer.from([DIRECTION_BYTES[this.#role], KIND_BYTES[kind]]);
+    const sealed = gcmEncrypt(key, nonceFor(this.#sent), plaintext, aad);
+    this.#sent += 1;
+    return Buffer.concat([Buffer.from([KIND_BYTES[kind]]), sealed]);
+  }
+
+  /** The frame's kind; a frame that is not one closes the link. */
+  protected kindOf(frame: Uint8Array): TLinkFrameKind {
+    this.#requireOpen(this.#receiveKey);
+    try {
+      return linkFrameKind(frame);
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+  }
+
+  /** The next frame's plaintext, which the caller owns; any failure closes the link. */
+  protected openKind(frame: Uint8Array, kind: TLinkFrameKind): Buffer {
+    const key = this.#requireOpen(this.#receiveKey);
+    const peer: TLinkRole = this.#role === 'initiator' ? 'responder' : 'initiator';
+    const aad = Buffer.from([DIRECTION_BYTES[peer], KIND_BYTES[kind]]);
+    let plaintext: Buffer;
+    try {
+      plaintext = gcmDecrypt(key, nonceFor(this.#received), frame.subarray(1), aad);
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+    this.#received += 1;
+    return plaintext;
+  }
+
+  #requireOpen(key: Buffer | undefined): Buffer {
+    if (key === undefined) throw new KeyringError('link-closed', 'The link is closed.');
+    return key;
+  }
+}
+
+export class InitiatorLink extends LinkEnd implements IInitiatorLink {
+  readonly #handover: IOwnerHandover | undefined;
+
+  constructor(
+    standing: TLinkMode,
+    binding: ILinkBinding,
+    instancePublicKey: Uint8Array,
+    keys: ILinkFrameKeys,
+    handover: IOwnerHandover | undefined,
+  ) {
+    super('initiator', standing, binding, instancePublicKey, keys);
+    this.#handover = handover;
+  }
+
+  sealReadGrant(handover: IOwnerHandover): Uint8Array {
+    if (this.standing !== 'owner' || handover !== this.#handover) {
+      throw new KeyringError(
+        'invalid-argument',
+        'A read grant goes only over an owner link, from the handover that opened it.',
+      );
+    }
+    const { sealingSeed, authorship } = ownerHandoverSecrets(handover);
+    const plaintext = Buffer.alloc(GRANT_PLAINTEXT_BYTES);
+    try {
+      plaintext[0] = GRANT_VERSION;
+      sealingSeed.copy(plaintext, 1);
+      authorship.copy(plaintext, 1 + KEY_BYTES);
+      return this.sealKind('grant', plaintext);
+    } finally {
+      wipe(plaintext);
+    }
+  }
+}
+
+export class ResponderLink extends LinkEnd implements IResponderLink {
+  constructor(
+    standing: TLinkMode,
+    binding: ILinkBinding,
+    instancePublicKey: Uint8Array,
+    keys: ILinkFrameKeys,
+  ) {
+    super('responder', standing, binding, instancePublicKey, keys);
+  }
+
+  openReadGrant(frame: Uint8Array): IReadKeys {
+    if (this.standing !== 'owner') {
+      this.close();
+      throw new KeyringError('invalid-argument', 'A read grant is accepted only on an owner link.');
+    }
+    if (this.kindOf(frame) !== 'grant') {
+      this.close();
+      throw new KeyringError('invalid-argument', 'Only a read grant opens as a grant.');
+    }
+    const plaintext = this.openKind(frame, 'grant');
+    try {
+      if (plaintext.length !== GRANT_PLAINTEXT_BYTES || plaintext[0] !== GRANT_VERSION) {
+        this.close();
+        throw new LinkRefusedError('malformed');
+      }
+      const sealing = x25519KeyPairFromSeed(plaintext.subarray(1, 1 + KEY_BYTES));
+      return createReadKeys(sealing, Buffer.from(plaintext.subarray(1 + KEY_BYTES)));
+    } finally {
+      wipe(plaintext);
+    }
+  }
+}

package/src/link-primitives.ts

@@ -0,0 +1,77 @@
+/**
+ * The few operations the spawner exchange and the handshake are built from, each in the one form
+ * they use it: a key agreement that refuses a point with no usable secret, transcript hashing and
+ * MACs over length-prefixed parts, and HKDF to any length. Each wraps a `node:crypto` primitive the
+ * keyring already uses, so the link adds nothing a supported runtime lacks.
+ */
+import { Buffer } from 'node:buffer';
+import {
+  createHash,
+  createHmac,
+  diffieHellman,
+  hkdfSync,
+  timingSafeEqual,
+  type KeyObject,
+} from 'node:crypto';
+
+import { concatLengthPrefixed, isBytes, wipe } from './bytes.js';
+import { KeyringError, LinkRefusedError } from './errors.js';
+import { x25519KeyPairFromSeed, x25519PublicKeyFromRaw, type IKeyPair } from './key-pairs.js';
+import { KEY_BYTES } from './kdf.js';
+import type { ILinkEntropy } from './link-entropy.js';
+
+/** A fresh X25519 keypair from the entropy's seed; the seed is wiped once the pair exists. */
+export function ephemeralKeyPair(entropy: ILinkEntropy): IKeyPair {
+  const seed = entropy.seed();
+  try {
+    return x25519KeyPairFromSeed(seed);
+  } finally {
+    wipe(seed);
+  }
+}
+
+/**
+ * The X25519 shared secret with the peer's raw public key. A value that is not a 32-byte key, or a
+ * low-order point with no usable secret, is the peer's malformed message: refused, never retried.
+ */
+export function agree(privateKey: KeyObject, peerPublicKey: Uint8Array): Buffer {
+  if (!isBytes(peerPublicKey) || peerPublicKey.length !== KEY_BYTES) {
+    throw new LinkRefusedError('malformed');
+  }
+  try {
+    return diffieHellman({ privateKey, publicKey: x25519PublicKeyFromRaw(peerPublicKey) });
+  } catch {
+    throw new LinkRefusedError('malformed');
+  }
+}
+
+/** SHA-256 over length-prefixed parts, so no two part lists hash alike. */
+export function hashParts(parts: readonly Uint8Array[]): Buffer {
+  return createHash('sha256').update(concatLengthPrefixed(parts)).digest();
+}
+
+/** HMAC-SHA256 of the concatenation of `parts` under `key`. */
+export function hmac(key: Uint8Array, ...parts: readonly Uint8Array[]): Buffer {
+  const mac = createHmac('sha256', key);
+  for (const part of parts) mac.update(part);
+  return mac.digest();
+}
+
+/** Whether two byte strings are equal, in constant time once their (public) lengths match. */
+export function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+/** HKDF-SHA256 to `length` bytes; a host that cannot run it fails as `kdf-failed`. */
+export function hkdf(
+  inputKeyMaterial: Uint8Array,
+  salt: Uint8Array,
+  info: string,
+  length: number,
+): Buffer {
+  try {
+    return Buffer.from(hkdfSync('sha256', inputKeyMaterial, salt, info, length));
+  } catch {
+    throw new KeyringError('kdf-failed', 'The key derivation could not run on this host.');
+  }
+}

package/src/owner-handover.ts

@@ -0,0 +1,155 @@
+/**
+ * The owner, present for a moment.
+ *
+ * Reading needs only the read keys; proving ownership needs the attach key, and that is the one key
+ * a runtime must never hold, since whoever holds it can certify impostors and present as the owner to
+ * any runtime. So the attach key has one home: a handover, opened from the keyring with a credential
+ * a person just typed, held for the seconds a command needs it, and disposed. A handover hands out
+ * operations and public values, never a key. Certifying a runtime instance is its one public
+ * operation; signing an owner proof and sealing a read grant happen inside the link initiator,
+ * through an accessor this package does not export.
+ */
+import type { Buffer } from 'node:buffer';
+
+import { deriveAuthorshipKey } from './authorship.js';
+import { wipe } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { fingerprint } from './fingerprint.js';
+import {
+  deriveAttachKeyPair,
+  deriveSealingSeed,
+  x25519KeyPairFromSeed,
+  type IKeyPair,
+} from './key-pairs.js';
+import { validateKeyring } from './keyring-document.js';
+import { recoverMasterKey, sealingPublicKeyMatches, type TKeyringCredential } from './keyring.js';
+import type { IKeyring } from './keyring-types.js';
+import {
+  runtimeCertificateMessage,
+  type ILinkBinding,
+  type ITrustRoot,
+} from './runtime-certificate.js';
+import { signEd25519 } from './signatures.js';
+
+export interface IOwnerHandover {
+  /**
+   * Whether the keyring file holds the sealing public key the credential derives. `false` means the
+   * file was altered: a runtime given these keys seals to the derived key, and the file is repaired
+   * by `secure verify`, not here.
+   */
+  readonly sealingKeyMatches: boolean;
+  /** The derived sealing public key's fingerprint, shown so a replaced keyring file is noticed. */
+  readonly fingerprint: string;
+  readonly disposed: boolean;
+  /**
+   * The trust root that tells a runtime its owner: the attach public key and the certificate of
+   * `instancePublicKey` for `binding`. Give it only for an instance key and binding learned over an
+   * authenticated link, since the certificate vouches for exactly them.
+   */
+  certify(instancePublicKey: Uint8Array, binding: ILinkBinding): ITrustRoot;
+  /** Zero-fills what it can and drops every key; later calls throw `keys-locked`. Idempotent. */
+  dispose(): void;
+}
+
+/** What only the link initiator reaches: everything an owner proof and a read grant are made of. */
+export interface IOwnerHandoverSecrets {
+  readonly attach: IKeyPair;
+  /** The 32-byte seed of the sealing keypair: what a read grant carries, since it rebuilds the pair. */
+  readonly sealingSeed: Buffer;
+  readonly sealingPublicKey: Uint8Array;
+  readonly authorship: Buffer;
+}
+
+const SECRETS = new WeakMap<IOwnerHandover, () => IOwnerHandoverSecrets>();
+
+class OwnerHandover implements IOwnerHandover {
+  #secrets: IOwnerHandoverSecrets | undefined;
+  readonly #sealingKeyMatches: boolean;
+
+  constructor(secrets: IOwnerHandoverSecrets, sealingKeyMatches: boolean) {
+    this.#secrets = secrets;
+    this.#sealingKeyMatches = sealingKeyMatches;
+    SECRETS.set(this, () => this.#require());
+  }
+
+  get sealingKeyMatches(): boolean {
+    this.#require();
+    return this.#sealingKeyMatches;
+  }
+
+  get fingerprint(): string {
+    return fingerprint(this.#require().sealingPublicKey);
+  }
+
+  get disposed(): boolean {
+    return this.#secrets === undefined;
+  }
+
+  certify(instancePublicKey: Uint8Array, binding: ILinkBinding): ITrustRoot {
+    const { attach } = this.#require();
+    const message = runtimeCertificateMessage(instancePublicKey, binding);
+    return {
+      attachPublicKey: Uint8Array.from(attach.publicKey),
+      certificate: Uint8Array.from(signEd25519(attach.privateKey, message)),
+    };
+  }
+
+  dispose(): void {
+    const secrets = this.#secrets;
+    if (secrets === undefined) return;
+    this.#secrets = undefined;
+    wipe(secrets.sealingSeed, secrets.authorship);
+  }
+
+  #require(): IOwnerHandoverSecrets {
+    if (this.#secrets === undefined) {
+      throw new KeyringError('keys-locked', 'The owner handover was disposed.');
+    }
+    return this.#secrets;
+  }
+}
+
+/**
+ * Package-private: the owner's keys behind a handover, for the link initiator alone. It is not
+ * exported from the entry point, and it answers only for a handover this package opened.
+ */
+export function ownerHandoverSecrets(handover: IOwnerHandover): IOwnerHandoverSecrets {
+  const secrets = SECRETS.get(handover);
+  if (secrets === undefined) {
+    throw new KeyringError(
+      'invalid-argument',
+      'This is not an owner handover this package opened.',
+    );
+  }
+  return secrets();
+}
+
+/**
+ * Opens the owner handover with `credential`: one key derivation (one scrypt run per passphrase
+ * slot, as an unlock), from whose master key the attach keypair and the read keys are derived; the
+ * master key is zero-filled before this returns. A wrong credential and a tampered slot fail alike.
+ */
+export async function openOwnerHandover(
+  keyring: IKeyring,
+  credential: TKeyringCredential,
+): Promise<IOwnerHandover> {
+  const document = validateKeyring(keyring);
+  const { masterKey } = await recoverMasterKey(document, credential);
+  let sealingSeed: Buffer | undefined;
+  let authorship: Buffer | undefined;
+  try {
+    sealingSeed = deriveSealingSeed(masterKey);
+    authorship = deriveAuthorshipKey(masterKey);
+    const attach = deriveAttachKeyPair(masterKey);
+    const sealingPublicKey = x25519KeyPairFromSeed(sealingSeed).publicKey;
+    return new OwnerHandover(
+      { attach, sealingSeed, sealingPublicKey, authorship },
+      sealingPublicKeyMatches(document, sealingPublicKey),
+    );
+  } catch (error) {
+    wipe(sealingSeed, authorship);
+    throw error;
+  } finally {
+    wipe(masterKey);
+  }
+}