@forgezero/runtime 0.1.4 → 0.1.6

package/dist/ssh-agent.d.ts

@@ -1,83 +0,0 @@
-/**
- * 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[]>;
-/**
- * Sign arbitrary bytes with an identity the agent holds.
- *
- * Exported because a fresh proof from a terminal needs it: the server issues a
- * nonce and this is what turns it into something the server can verify against
- * a registered public key. `deriveCustodyKey` signs a FIXED challenge and hashes
- * the result — that is a key-derivation, not a proof, and using it as one would
- * replay.
- *
- * Returns the raw ed25519 signature, unwrapped from the agent's blob, because
- * that is what a verifier takes.
- */
-export declare function signWithIdentity(identity: AgentIdentity, data: Uint8Array, socketPath?: string): Promise<Uint8Array>;
-/**
- * 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>;

package/dist/ssh-agent.js

@@ -1,147 +0,0 @@
-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/ssh-agent.ts
-import { Socket } from "node:net";
-import { createHash, hkdfSync } from "node:crypto";
-
-class SshAgentError extends Error {
-}
-var SSH_AGENTC_REQUEST_IDENTITIES = 11;
-var SSH_AGENT_IDENTITIES_ANSWER = 12;
-var SSH_AGENTC_SIGN_REQUEST = 13;
-var SSH_AGENT_SIGN_RESPONSE = 14;
-var CUSTODY_CHALLENGE = Buffer.from("forgezero/custody/ssh-agent/v1", "utf8");
-function readString(buffer, offset) {
-  const length = buffer.readUInt32BE(offset);
-  const start = offset + 4;
-  return [buffer.subarray(start, start + length), start + length];
-}
-function writeString(value) {
-  const length = Buffer.alloc(4);
-  length.writeUInt32BE(value.length);
-  return Buffer.concat([length, value]);
-}
-function frame(payload) {
-  const length = Buffer.alloc(4);
-  length.writeUInt32BE(payload.length);
-  return Buffer.concat([length, payload]);
-}
-var AGENT_TIMEOUT_MS = 3000;
-async function request(socketPath, payload) {
-  return new Promise((resolve, reject) => {
-    const socket = new Socket;
-    const chunks = [];
-    let expected = null;
-    let settled = false;
-    const fail = (message) => {
-      if (settled)
-        return;
-      settled = true;
-      socket.destroy();
-      reject(new SshAgentError(message));
-    };
-    socket.setTimeout(AGENT_TIMEOUT_MS, () => fail("SSH_AGENT_TIMEOUT"));
-    socket.on("error", () => fail("SSH_AGENT_UNREACHABLE"));
-    socket.on("connect", () => socket.write(frame(payload)));
-    socket.on("data", (chunk) => {
-      chunks.push(chunk);
-      const all = Buffer.concat(chunks);
-      if (expected === null && all.length >= 4)
-        expected = all.readUInt32BE(0);
-      if (expected !== null && all.length >= expected + 4) {
-        if (settled)
-          return;
-        settled = true;
-        socket.end();
-        resolve(all.subarray(4, expected + 4));
-      }
-    });
-    socket.on("close", () => {
-      if (expected === null)
-        fail("SSH_AGENT_CLOSED_EARLY");
-    });
-    socket.connect(socketPath);
-  });
-}
-function agentSocket(explicit) {
-  const path = explicit ?? process.env.SSH_AUTH_SOCK;
-  if (!path)
-    throw new SshAgentError("SSH_AUTH_SOCK_NOT_SET");
-  return path;
-}
-async function listIdentities(socketPath) {
-  const response = await request(agentSocket(socketPath), Buffer.from([SSH_AGENTC_REQUEST_IDENTITIES]));
-  if (response[0] !== SSH_AGENT_IDENTITIES_ANSWER) {
-    throw new SshAgentError("SSH_AGENT_BAD_RESPONSE");
-  }
-  const count = response.readUInt32BE(1);
-  const identities = [];
-  let offset = 5;
-  for (let index = 0;index < count; index += 1) {
-    const [blob, afterBlob] = readString(response, offset);
-    const [comment, afterComment] = readString(response, afterBlob);
-    offset = afterComment;
-    const [type] = readString(blob, 0);
-    identities.push({
-      blob,
-      comment: comment.toString("utf8"),
-      type: type.toString("utf8"),
-      fingerprint: `SHA256:${createHash("sha256").update(blob).digest("base64").replace(/=+$/, "")}`
-    });
-  }
-  return identities;
-}
-async function listCustodyIdentities(socketPath) {
-  return (await listIdentities(socketPath)).filter((id) => id.type === "ssh-ed25519");
-}
-async function signWithIdentity(identity, data, socketPath) {
-  const wrapped = await sign(identity.blob, Buffer.from(data), socketPath);
-  const [raw] = readString(wrapped, readString(wrapped, 0)[1]);
-  return new Uint8Array(raw);
-}
-async function sign(blob, data, socketPath) {
-  const payload = Buffer.concat([
-    Buffer.from([SSH_AGENTC_SIGN_REQUEST]),
-    writeString(blob),
-    writeString(data),
-    Buffer.alloc(4)
-  ]);
-  const response = await request(agentSocket(socketPath), payload);
-  if (response[0] !== SSH_AGENT_SIGN_RESPONSE) {
-    throw new SshAgentError("SSH_AGENT_SIGN_REFUSED");
-  }
-  const [signature] = readString(response, 1);
-  return signature;
-}
-async function deriveCustodyKey(identity, socketPath) {
-  if (identity.type !== "ssh-ed25519") {
-    throw new SshAgentError("SSH_KEY_TYPE_UNSUPPORTED");
-  }
-  const signature = await sign(identity.blob, CUSTODY_CHALLENGE, socketPath);
-  if (signature.length < 32)
-    throw new SshAgentError("SSH_AGENT_SIGNATURE_TOO_SHORT");
-  return new Uint8Array(hkdfSync("sha256", signature, identity.blob, Buffer.from("forgezero/custody/ssh-key/v1", "utf8"), 32));
-}
-async function assertDeterministic(identity, socketPath) {
-  const first = await deriveCustodyKey(identity, socketPath);
-  const second = await deriveCustodyKey(identity, socketPath);
-  if (Buffer.compare(Buffer.from(first), Buffer.from(second)) !== 0) {
-    throw new SshAgentError("SSH_AGENT_NOT_DETERMINISTIC");
-  }
-  return first;
-}
-export {
-  signWithIdentity,
-  listIdentities,
-  listCustodyIdentities,
-  deriveCustodyKey,
-  assertDeterministic,
-  SshAgentError,
-  AGENT_TIMEOUT_MS
-};