@forgezero/runtime 0.1.0

package/dist/schema.js

@@ -0,0 +1,169 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/schema.ts
+class SchemaError extends Error {
+  code;
+  path;
+  constructor(code, message, path) {
+    super(message);
+    this.code = code;
+    this.path = path;
+    this.name = "SchemaError";
+  }
+}
+var DEFAULT_RESTRICTIONS = {
+  maxDepth: 4,
+  maxFields: 100,
+  maxBytes: 64 * 1024,
+  forbidden: ["$ref", "$id", "$dynamicRef", "$dynamicAnchor", "$schema", "definitions", "$defs"]
+};
+function restrictJsonSchema(schema, limits = DEFAULT_RESTRICTIONS) {
+  const bytes = JSON.stringify(schema).length;
+  if (bytes > limits.maxBytes) {
+    throw new SchemaError("SCHEMA_TOO_LARGE", `Schema is ${bytes} bytes; the limit is ${limits.maxBytes}.`);
+  }
+  let fields = 0;
+  const walk = (node, depth, path) => {
+    if (node === null || typeof node !== "object")
+      return;
+    if (Array.isArray(node)) {
+      node.forEach((child, index) => walk(child, depth, `${path}[${index}]`));
+      return;
+    }
+    const record = node;
+    for (const keyword of limits.forbidden) {
+      if (keyword in record) {
+        throw new SchemaError("SCHEMA_FORBIDDEN_KEYWORD", `"${keyword}" is not permitted: it can point validation at a document we do not control.`, path || "(root)");
+      }
+    }
+    if (depth > limits.maxDepth) {
+      throw new SchemaError("SCHEMA_TOO_DEEP", `Nesting exceeds ${limits.maxDepth} levels.`, path || "(root)");
+    }
+    if (record.type === "object") {
+      const properties = record.properties ?? {};
+      const names = Object.keys(properties);
+      fields += names.length;
+      if (fields > limits.maxFields) {
+        throw new SchemaError("SCHEMA_TOO_WIDE", `Schema declares more than ${limits.maxFields} fields.`, path || "(root)");
+      }
+      if (record.additionalProperties !== false) {
+        throw new SchemaError("SCHEMA_OPEN_OBJECT", "Objects must set additionalProperties:false, or unvalidated fields pass through.", path || "(root)");
+      }
+      for (const name of names) {
+        walk(properties[name], depth + 1, path ? `${path}.${name}` : name);
+      }
+    }
+    if (record.type === "array" && record.items) {
+      walk(record.items, depth + 1, `${path}[]`);
+    }
+  };
+  walk(schema, 1, "");
+  return schema;
+}
+function deriveAnnotation(property) {
+  const raw = property["x-fz-derive"];
+  if (typeof raw !== "object" || raw === null)
+    return;
+  const spec = raw;
+  const scheme = typeof spec.scheme === "string" ? spec.scheme : undefined;
+  if (!scheme)
+    return;
+  return {
+    custody: spec.custody === "supplied" ? "supplied" : "derived",
+    scheme,
+    expose: typeof spec.expose === "string" ? spec.expose : undefined
+  };
+}
+function describeJsonSchema(schema, prefix = "") {
+  if (schema.type !== "object")
+    return [];
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  return Object.entries(properties).map(([name, property]) => {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const kind = fieldKind(property);
+    const field = {
+      path,
+      label: property.title ?? humanise(name),
+      kind,
+      required: required.has(name),
+      description: property.description,
+      writeOnly: property.writeOnly === true ? true : undefined,
+      default: property.default,
+      format: property.format,
+      minLength: property.minLength,
+      maxLength: property.maxLength,
+      minimum: property.minimum,
+      maximum: property.maximum,
+      pattern: property.pattern,
+      derive: deriveAnnotation(property)
+    };
+    if (kind === "enum") {
+      return { ...field, options: property.enum ?? property.anyOf };
+    }
+    if (kind === "object") {
+      return { ...field, items: describeJsonSchema(property, path) };
+    }
+    if (kind === "array" && property.items) {
+      return {
+        ...field,
+        items: describeJsonSchema(property.items, path)
+      };
+    }
+    return field;
+  });
+}
+function fieldKind(property) {
+  if (Array.isArray(property.enum))
+    return "enum";
+  if (Array.isArray(property.anyOf) && property.anyOf.every((m) => typeof m === "object" && m !== null && ("const" in m))) {
+    return "enum";
+  }
+  switch (property.type) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "integer":
+      return "integer";
+    case "boolean":
+      return "boolean";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    default:
+      return "unknown";
+  }
+}
+function humanise(name) {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim().toLowerCase();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function readableFields(fields) {
+  return fields.filter((field) => !field.writeOnly).map((field) => field.items ? { ...field, items: readableFields(field.items) } : field);
+}
+function writeOnlyPaths(fields) {
+  return fields.flatMap((field) => [
+    ...field.writeOnly ? [field.path] : [],
+    ...field.items ? writeOnlyPaths(field.items) : []
+  ]);
+}
+var SCHEMA_VERSION = 1;
+var VERSION = "0.1.0";
+export {
+  writeOnlyPaths,
+  restrictJsonSchema,
+  readableFields,
+  describeJsonSchema,
+  VERSION,
+  SchemaError,
+  SCHEMA_VERSION,
+  DEFAULT_RESTRICTIONS
+};

package/dist/serial.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Run work for one key strictly in order, and give the caller the result back.
+ *
+ * ## Why this is not `@forgezero/runtime/queue`
+ *
+ * The queue is for work that happens LATER: it persists a message, hands it to
+ * a handler, retries, dead-letters. It is the right answer when the caller does
+ * not need the outcome — a deposit credit, a webhook, a scan.
+ *
+ * This is for work that happens NOW and whose result the caller returns. A
+ * request writing a ledger posting has to answer with the posting; enqueuing it
+ * would mean replying "accepted" to something the caller needs to have
+ * happened. Two different problems, and using the queue for this one would mean
+ * inventing a way to wait for a message — which is a worse version of this file.
+ *
+ * It was written twice before it was written once: the audit chain needed it to
+ * keep sequence numbers gapless, and accounts needed it to stop two credits
+ * interleaving. Two copies of a concurrency primitive is two chances to get it
+ * wrong, so it lives here.
+ *
+ * ## What it does NOT give you
+ *
+ * Ordering within ONE process. Two API nodes each hold their own chain, so a
+ * durable guarantee still needs a unique index on whatever must not happen
+ * twice. This makes the common case cheap and correct; the index makes every
+ * case correct. Anything relying on this alone across a cluster is relying on
+ * there being one node, which stops being true without warning.
+ */
+export interface SerialOptions {
+    /**
+     * Keys to keep chains for.
+     *
+     * A chain per key is a promise per key, and a process serving a million
+     * accounts would hold a million of them forever. Idle chains are dropped once
+     * settled, so the map holds only keys with work in flight.
+     */
+    maxKeys?: number;
+}
+export declare function createKeyedSerial(options?: SerialOptions): {
+    /**
+     * Run `work` after everything already queued for this key.
+     *
+     * A rejection does NOT poison the chain: the tail is always replaced with a
+     * settled promise, so one transient failure cannot take every subsequent
+     * call for that key with it — which is how a single database blip becomes a
+     * permanently stuck account.
+     */
+    run<T>(key: string, work: () => Promise<T>): Promise<T>;
+    /** How many keys have work in flight. For a health endpoint. */
+    size: () => number;
+    /** Wait for everything currently queued. Tests, and a graceful shutdown. */
+    drain: () => Promise<void>;
+};
+export type KeyedSerial = ReturnType<typeof createKeyedSerial>;

package/dist/serial.js

@@ -0,0 +1,40 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/serial.ts
+function createKeyedSerial(options = {}) {
+  const maxKeys = options.maxKeys ?? 1e4;
+  const chains = new Map;
+  return {
+    run(key, work) {
+      const previous = chains.get(key) ?? Promise.resolve();
+      const next = previous.then(work, work);
+      const settled = next.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+      chains.set(key, settled);
+      settled.then(() => {
+        if (chains.get(key) === settled)
+          chains.delete(key);
+      });
+      if (chains.size > maxKeys) {
+        console.warn(`[serial] ${chains.size} keys in flight, above the ${maxKeys} guideline.`);
+      }
+      return next;
+    },
+    size: () => chains.size,
+    drain: async () => {
+      await Promise.allSettled([...chains.values()]);
+    }
+  };
+}
+export {
+  createKeyedSerial
+};

package/dist/slip10.d.ts

@@ -0,0 +1,37 @@
+/** SLIP-0010 hardens by adding 2^31. Anything below it is a public index. */
+export declare const HARDENED_OFFSET = 2147483648;
+export declare class Slip10Error extends Error {
+    readonly code: 'NOT_HARDENED' | 'BAD_PATH' | 'BAD_SEED';
+    constructor(code: 'NOT_HARDENED' | 'BAD_PATH' | 'BAD_SEED', message: string);
+}
+export interface Slip10Node {
+    /** 32 bytes. The ed25519 secret scalar seed, not an expanded key. */
+    key: Uint8Array;
+    chainCode: Uint8Array;
+}
+/**
+ * The master node.
+ *
+ * Seeds shorter than 16 bytes are refused. SLIP-0010 permits 128 to 512 bits
+ * and a caller passing something smaller has almost certainly passed a
+ * passphrase rather than a seed — accepting it would derive a whole key tree
+ * from guessable entropy.
+ */
+export declare function masterFromSeed(seed: Uint8Array): Slip10Node;
+/**
+ * One hardened step.
+ *
+ * The data is `0x00 || key || index`, and the leading zero byte is not padding
+ * — it is what distinguishes this from BIP-32's secp256k1 construction, which
+ * puts a compressed public key there for a public step. Omitting it produces
+ * plausible keys that match nothing.
+ */
+export declare function deriveChild(node: Slip10Node, index: number): Slip10Node;
+/**
+ * `m/44'/501'/0'/0'` — every component hardened.
+ *
+ * Accepts `'` or `h` as the hardening mark, because both appear in the wild and
+ * a path copied from a wallet that writes `h` should not silently derive a
+ * different key than the same path written with an apostrophe.
+ */
+export declare function derivePath(seed: Uint8Array, path: string): Slip10Node;

package/dist/slip10.js

@@ -0,0 +1,74 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/slip10.ts
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+var ED25519_SEED = new TextEncoder().encode("ed25519 seed");
+var HARDENED_OFFSET = 2147483648;
+
+class Slip10Error extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "Slip10Error";
+  }
+}
+function masterFromSeed(seed) {
+  if (seed.length < 16 || seed.length > 64) {
+    throw new Slip10Error("BAD_SEED", "A SLIP-0010 seed is 16 to 64 bytes.");
+  }
+  const digest = hmac(sha512, ED25519_SEED, seed);
+  return { key: digest.slice(0, 32), chainCode: digest.slice(32) };
+}
+function deriveChild(node, index) {
+  if (!Number.isInteger(index) || index < 0 || index > 4294967295) {
+    throw new Slip10Error("BAD_PATH", `${index} is not a derivation index.`);
+  }
+  if (index < HARDENED_OFFSET) {
+    throw new Slip10Error("NOT_HARDENED", `ed25519 has no public derivation. Index ${index} must be hardened — SLIP-0010 defines only hardened steps for this curve.`);
+  }
+  const data = new Uint8Array(1 + 32 + 4);
+  data[0] = 0;
+  data.set(node.key, 1);
+  new DataView(data.buffer).setUint32(33, index >>> 0, false);
+  const digest = hmac(sha512, node.chainCode, data);
+  data.fill(0);
+  return { key: digest.slice(0, 32), chainCode: digest.slice(32) };
+}
+function derivePath(seed, path) {
+  const trimmed = path.trim();
+  if (!/^m(\/\d+['h]?)*$/.test(trimmed)) {
+    throw new Slip10Error("BAD_PATH", `"${path}" is not a derivation path.`);
+  }
+  let node = masterFromSeed(seed);
+  const parts = trimmed.split("/").slice(1).filter(Boolean);
+  for (const part of parts) {
+    const hardened = part.endsWith("'") || part.endsWith("h");
+    const raw = Number.parseInt(hardened ? part.slice(0, -1) : part, 10);
+    if (!hardened) {
+      throw new Slip10Error("NOT_HARDENED", `"${path}" contains a non-hardened component (${part}). ed25519 derivation is hardened-only.`);
+    }
+    if (raw >= HARDENED_OFFSET) {
+      throw new Slip10Error("BAD_PATH", `Index ${raw} is already past the hardened offset.`);
+    }
+    const next = deriveChild(node, raw + HARDENED_OFFSET);
+    node.key.fill(0);
+    node.chainCode.fill(0);
+    node = next;
+  }
+  return node;
+}
+export {
+  masterFromSeed,
+  derivePath,
+  deriveChild,
+  Slip10Error,
+  HARDENED_OFFSET
+};

package/dist/snp.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Parsing an AMD SEV-SNP attestation report.
+ *
+ * The report is a fixed 1184-byte structure the PSP produces and signs. Every
+ * offset below comes from the SEV Secure Nested Paging Firmware ABI
+ * specification, table "ATTESTATION_REPORT Structure" — they are not derived
+ * from anything and must not be adjusted to make a sample parse.
+ *
+ * ## Why this is separate from verifying it
+ *
+ * Parsing is total and testable: given bytes, produce fields or refuse. Deciding
+ * whether those fields are ACCEPTABLE is policy, and it already lives in
+ * `api/src/server/compute/attestation.ts`. Keeping them apart means a parser bug
+ * cannot be mistaken for a policy decision, and a policy change does not require
+ * touching byte offsets.
+ *
+ * ## What this does NOT do
+ *
+ * It does not verify the signature. Chaining a report to AMD's root needs the
+ * VCEK certificate for that specific chip at that specific TCB, fetched from
+ * AMD's KDS — a network dependency with its own failure modes, and a
+ * hand-rolled ECDSA-P384 verification here would be worse than none because it
+ * would produce `verified: true` for a report nobody signed.
+ *
+ * So `parseSnpReport` returns the signature bytes and says nothing about them.
+ * The caller supplies a verifier, which is the same shape every other trust
+ * decision in this codebase takes.
+ */
+/** The structure is exactly this long. Anything else is not a report. */
+export declare const REPORT_BYTES = 1184;
+export declare class SnpError extends Error {
+    readonly code: 'BAD_LENGTH' | 'BAD_VERSION' | 'BAD_VMPL';
+    constructor(code: 'BAD_LENGTH' | 'BAD_VERSION' | 'BAD_VMPL', message: string);
+}
+/**
+ * Guest policy bits.
+ *
+ * `debug` is the one that matters most and the one an operator is most likely
+ * to leave on: a guest launched with debugging enabled can have its memory
+ * inspected by the hypervisor, which removes the entire property SEV-SNP is
+ * bought for. It is surfaced by name rather than as a bitmask so a policy check
+ * reads as a sentence.
+ */
+export interface GuestPolicy {
+    /** Minimum ABI the guest requires. */
+    abiMinor: number;
+    abiMajor: number;
+    /** SMT permitted on the host. */
+    smt: boolean;
+    /** Migration agent permitted — the guest's memory may leave this machine. */
+    migrateMa: boolean;
+    /** Debugging enabled. Memory is inspectable; this must be false in production. */
+    debug: boolean;
+    /** The guest must run on a single socket. */
+    singleSocket: boolean;
+    /** The raw value, so a caller can record exactly what was reported. */
+    raw: string;
+}
+export interface SnpReport {
+    version: number;
+    guestSvn: number;
+    policy: GuestPolicy;
+    vmpl: number;
+    /** 48 bytes of hex. What the guest actually booted. */
+    measurement: string;
+    /** 64 bytes of hex. Whatever the guest asked the PSP to bind in — our nonce. */
+    reportData: string;
+    hostData: string;
+    /** Identifies the physical chip. Two reports from one machine share it. */
+    chipId: string;
+    /** TCB the report was produced under. Lower than a floor is a downgrade. */
+    reportedTcb: TcbVersion;
+    currentTcb: TcbVersion;
+    /** 512 bytes. Returned, never interpreted here. */
+    signature: string;
+}
+/** The four component versions packed into a TCB_VERSION. */
+export interface TcbVersion {
+    bootLoader: number;
+    tee: number;
+    snp: number;
+    microcode: number;
+    raw: string;
+}
+/**
+ * Bytes to fields.
+ *
+ * Refuses before reading anything when the length is wrong. A short buffer read
+ * with a DataView produces either an exception at an arbitrary offset or, worse,
+ * plausible values from adjacent memory — and a measurement assembled from
+ * whatever followed the buffer is the one failure that must never look like a
+ * successful parse.
+ */
+export declare function parseSnpReport(bytes: Uint8Array): SnpReport;
+/**
+ * Is every TCB component at least the floor?
+ *
+ * Field by field, and ALL of them. A single packed comparison would let a
+ * microcode bump mask an SNP firmware downgrade — which is precisely the
+ * direction an attacker wants, because older firmware is where the known
+ * vulnerabilities are.
+ */
+export declare function tcbAtLeast(reported: TcbVersion, floor: TcbVersion): boolean;
+/**
+ * Does the report bind OUR challenge?
+ *
+ * `REPORT_DATA` is 64 bytes the guest chooses and the PSP signs. A nonce placed
+ * there is what makes a report fresh rather than replayed — without this check a
+ * report captured once is valid for ever, and attestation degrades into "this
+ * machine was an SNP guest at some point".
+ *
+ * Compared over the whole field, including the zero padding, so a nonce shorter
+ * than 64 bytes cannot be matched by a report that merely starts with it.
+ */
+export declare function bindsNonce(report: SnpReport, nonce: string): boolean;

package/dist/snp.js

@@ -0,0 +1,109 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/snp.ts
+var REPORT_BYTES = 1184;
+var OFFSET = {
+  version: 0,
+  guestSvn: 4,
+  policy: 8,
+  familyId: 16,
+  imageId: 32,
+  vmpl: 48,
+  signatureAlgo: 52,
+  currentTcb: 56,
+  platformInfo: 64,
+  reportData: 80,
+  measurement: 144,
+  hostData: 192,
+  idKeyDigest: 224,
+  authorKeyDigest: 272,
+  reportId: 320,
+  reportIdMa: 352,
+  reportedTcb: 384,
+  chipId: 416,
+  signature: 672
+};
+
+class SnpError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SnpError";
+  }
+}
+var hex = (bytes) => [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+function readTcb(view, offset) {
+  const raw = new Uint8Array(view.buffer, view.byteOffset + offset, 8);
+  return {
+    bootLoader: raw[0],
+    tee: raw[1],
+    snp: raw[6],
+    microcode: raw[7],
+    raw: hex(raw)
+  };
+}
+function readPolicy(view, offset) {
+  const low = view.getUint32(offset, true);
+  const high = view.getUint32(offset + 4, true);
+  const bit = (index) => (low >>> index & 1) === 1;
+  return {
+    abiMinor: low & 255,
+    abiMajor: low >>> 8 & 255,
+    smt: bit(16),
+    migrateMa: bit(18),
+    debug: bit(19),
+    singleSocket: bit(20),
+    raw: `${high.toString(16).padStart(8, "0")}${low.toString(16).padStart(8, "0")}`
+  };
+}
+function parseSnpReport(bytes) {
+  if (bytes.length !== REPORT_BYTES) {
+    throw new SnpError("BAD_LENGTH", `An SEV-SNP attestation report is ${REPORT_BYTES} bytes; this is ${bytes.length}.`);
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const version = view.getUint32(OFFSET.version, true);
+  if (version !== 2 && version !== 3) {
+    throw new SnpError("BAD_VERSION", `Report version ${version} is not one this parser understands.`);
+  }
+  const vmpl = view.getUint32(OFFSET.vmpl, true);
+  if (vmpl > 3) {
+    throw new SnpError("BAD_VMPL", `VMPL ${vmpl} is outside the defined range.`);
+  }
+  const slice = (offset, length) => hex(bytes.subarray(offset, offset + length));
+  return {
+    version,
+    guestSvn: view.getUint32(OFFSET.guestSvn, true),
+    policy: readPolicy(view, OFFSET.policy),
+    vmpl,
+    measurement: slice(OFFSET.measurement, 48),
+    reportData: slice(OFFSET.reportData, 64),
+    hostData: slice(OFFSET.hostData, 32),
+    chipId: slice(OFFSET.chipId, 64),
+    reportedTcb: readTcb(view, OFFSET.reportedTcb),
+    currentTcb: readTcb(view, OFFSET.currentTcb),
+    signature: slice(OFFSET.signature, 512)
+  };
+}
+function tcbAtLeast(reported, floor) {
+  return reported.bootLoader >= floor.bootLoader && reported.tee >= floor.tee && reported.snp >= floor.snp && reported.microcode >= floor.microcode;
+}
+function bindsNonce(report, nonce) {
+  const bare = nonce.replace(/^0x/, "").toLowerCase();
+  if (bare.length === 0 || bare.length > 128 || bare.length % 2 !== 0)
+    return false;
+  return report.reportData === bare.padEnd(128, "0");
+}
+export {
+  tcbAtLeast,
+  parseSnpReport,
+  bindsNonce,
+  SnpError,
+  REPORT_BYTES
+};

package/dist/ssh-agent.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SSH agent as a custody factor.
+ *
+ * The ceremony seals every custodian share twice — once under a key derived from
+ * a WebAuthn PRF output, once under a key derived from a BIP-39 phrase — and
+ * either alone opens it. That works in a browser and not at all over SSH, which
+ * is where the platform is first brought up: there is no passkey before there is
+ * a platform to register one against.
+ *
+ * An SSH agent fills the same slot. Both are an agent-held key that produces a
+ * stable secret without ever exposing the key itself, so the SSH signature over
+ * a fixed challenge substitutes for the PRF output with no change to the sealing
+ * code. The custodian later registers a passkey through the UI and the same
+ * share gains a browser route.
+ *
+ * **Ed25519 only, and that is a correctness requirement rather than a
+ * preference.** The derived key must be identical on every enrolment and every
+ * unlock, so the signature has to be deterministic. Ed25519 is (RFC 8032). RSA
+ * with PKCS#1 v1.5 happens to be, but agents are free to offer RSA-PSS for the
+ * same key, and PSS is randomised — a share sealed under one PSS signature could
+ * never be opened again. Refusing everything except Ed25519 makes that
+ * impossible rather than rare.
+ */
+export declare class SshAgentError extends Error {
+}
+export interface AgentIdentity {
+    /** Raw SSH public key blob, as the agent returns it. */
+    blob: Buffer;
+    comment: string;
+    /** `ssh-ed25519`, etc. Anything else is refused — see the module note. */
+    type: string;
+    /** `SHA256:…`, matching `ssh-add -l`, so a human can confirm which key. */
+    fingerprint: string;
+}
+/**
+ * How long to wait on the agent before giving up.
+ *
+ * An agent holding a forwarded key whose upstream is gone, or a confirm-on-use
+ * key with nobody at the terminal, does not refuse — it simply never answers.
+ * Without a socket-level deadline those connections are never closed, and a
+ * caller that races them against its own timer leaks one socket per attempt
+ * until the agent stops accepting connections entirely.
+ */
+export declare const AGENT_TIMEOUT_MS = 3000;
+/** The keys the agent is holding. Matches `ssh-add -l`. */
+export declare function listIdentities(socketPath?: string): Promise<AgentIdentity[]>;
+/** Ed25519 only. See the module note — determinism is the whole mechanism. */
+export declare function listCustodyIdentities(socketPath?: string): Promise<AgentIdentity[]>;
+/**
+ * Derive the 32-byte custody key for an identity.
+ *
+ * Stable across processes and machines for the same key, which is what lets a
+ * custodian enrol today and unlock next month from a different laptop with the
+ * same key in their agent.
+ *
+ * HKDF over the signature rather than the signature itself: the signature is a
+ * value the agent will hand to anything that asks, so using it directly as a
+ * key would mean any process that can reach the socket holds the custody key.
+ * The salt and info bind it to this purpose.
+ */
+export declare function deriveCustodyKey(identity: AgentIdentity, socketPath?: string): Promise<Uint8Array>;
+/**
+ * Prove the derivation reproduces before it is trusted with a share.
+ *
+ * Signs twice and compares. A non-deterministic agent — a smartcard doing PSS, a
+ * forwarded agent that swapped keys mid-ceremony — would otherwise seal a share
+ * under a key that can never be reproduced, and the failure would surface only
+ * at the worst possible moment: recovery.
+ */
+export declare function assertDeterministic(identity: AgentIdentity, socketPath?: string): Promise<Uint8Array>;