@twinsearth/w2m-dsh-plugin 0.6.2 → 0.8.0

package/src/chatops/approval-broker.mjs

@@ -0,0 +1,320 @@
+/**
+ * The approval broker (v0.7.0).
+ *
+ * ## The defect this file exists to make impossible
+ *
+ * A chat bridge that wants to answer approvals from a phone joins the
+ * `approval/request` **waterfall**. The contract, as this host documents it, is:
+ *
+ *     'approval/request'(this, req, next: () => Promise<ApprovalOutcome>)
+ *       -> "Return an outcome to claim the request or call `next()` to delegate."
+ *
+ * `dsh-chatops` 0.1.0 registers `(req) => this.onApprovalRequest(req)` and **never
+ * calls `next()`** — the identifier does not appear in its source at all. Because a
+ * waterfall consults the next listener only when the current one calls `next()`, a
+ * listener that returns without delegating removes every answerer registered after
+ * it from the decision. In that plugin the listener is also `async`, so the *first*
+ * thing it hands back is a Promise, and the harness treats any non-`undefined`
+ * value as the final answer. Measured consequence: approvals for sessions that have
+ * a bound IM window are held until the plugin's own timer expires, and the host's
+ * GUI answerer is never asked. Whether that happens at all depends on listener
+ * registration order, which the plugin does nothing to control.
+ *
+ * Two properties make the correct version look different from the obvious one:
+ *
+ *   1. **Declining must be synchronous.** If the bridge has nothing to ask (no bound
+ *      window, push disabled), it must return `undefined` *without* having touched
+ *      `next`, so the waterfall proceeds normally. Awaiting anything first — even a
+ *      resolved promise — hands a Promise to the harness and claims the request.
+ *   2. **A timeout must delegate, not decide.** A bridge that answers "no decision"
+ *      after its own deadline has still answered. The host is entitled to a real
+ *      outcome, so the deadline calls `next()` and lets the answerers behind it
+ *      decide. This is the difference between "the phone did not answer" and
+ *      "the request was denied".
+ *
+ * ## Why the state is keyed the way it is
+ *
+ * Pending approvals are keyed by **approval id**, and each window keeps a queue of
+ * ids. The 0.1.0 code used a single `Map<windowKey, PendingApproval>`, so a second
+ * concurrent request in one window overwrote the first: the older request became
+ * unanswerable from IM and was reclaimed only by its timer, while `/approve` always
+ * resolved the newer one. Keying by id and queueing per window makes that state
+ * unrepresentable rather than merely unlikely.
+ *
+ * Ids carry full entropy. 0.1.0 minted `randomUUID().slice(0, 8)` — 32 bits — which
+ * its own core then held for up to five minutes. Nothing here is guessable.
+ *
+ * ## What this module deliberately is not
+ *
+ * It is not an answerer and it does not touch Cordis. It is a pure state machine
+ * with injected clock, timer and id source, so every property above is testable
+ * without a host, a phone, or a five-minute wait. The wiring — one listener, four
+ * lines — lives in the transport layer and can be read at a glance.
+ *
+ * The timer is injectable for a reason that cost a hanging test run to learn: an
+ * injected *clock* with a real `setTimeout` is two clocks, and a test that advances
+ * the one it controls then waits on the other hangs forever. Anything that reads
+ * time here — `now`, `setTimer`, `clearTimer` — comes from the same place.
+ */
+
+/** Outcomes the host's approval service can accept. Mirrors `ApprovalOutcome`. */
+export const OUTCOMES = Object.freeze(['allowed-once', 'rejected', 'cancelled', 'unavailable']);
+
+/**
+ * Why a pending request stopped being answerable. Reported, never thrown: an
+ * approval that nobody answered is a normal event, not an error.
+ */
+export const RESOLUTION = Object.freeze({
+  /** The operator answered from IM. */
+  OPERATOR: 'operator',
+  /** The deadline passed and the request was delegated to the answerers behind us. */
+  DELEGATED: 'delegated',
+  /** The host withdrew the request (`signal` aborted) before anyone answered. */
+  CANCELLED: 'cancelled',
+  /** The bridge was disposed, or the broker shut down. */
+  DISPOSED: 'disposed',
+});
+
+/**
+ * A decision is only ever one of these two. The host's `ApprovalOutcome` includes
+ * `'cancelled'` and `'unavailable'`, but those describe *why a decision is absent*
+ * — they are produced by the host, not claimed by an answerer. Accepting them from
+ * an operator would let a bridge report its own failure as the operator's choice.
+ */
+const OPERATOR_OUTCOMES = new Set(['allowed-once', 'rejected']);
+
+/**
+ * Create a broker.
+ *
+ * @param {object} options
+ * @param {() => number} [options.now] Injected clock, for tests and for a host that virtualises time.
+ * @param {(fn: () => void, ms: number) => unknown} [options.setTimer] Injected timer. Must pair with `now`.
+ * @param {(handle: unknown) => void} [options.clearTimer] Cancels a `setTimer` handle.
+ * @param {() => string} [options.mintId] Injected id source. Must be unguessable.
+ * @param {(event: string, detail?: object) => void} [options.audit] Called on every state change.
+ * @param {number} [options.defaultTimeoutMs] Deadline for a request nobody answers.
+ * @param {number} [options.maxPendingPerWindow] Refuse rather than queue without bound.
+ */
+export function createApprovalBroker(options = {}) {
+  const now = options.now ?? (() => Date.now());
+  const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const mintId = options.mintId ?? (() => globalThis.crypto.randomUUID());
+  const audit = options.audit ?? (() => {});
+  const defaultTimeoutMs = options.defaultTimeoutMs ?? 300_000;
+  const maxPendingPerWindow = options.maxPendingPerWindow ?? 4;
+
+  /** approvalId -> pending record. */
+  const pending = new Map();
+  /** windowKey -> approvalId[], oldest first. The queue is the fix for the overwrite bug. */
+  const byWindow = new Map();
+  let disposed = false;
+
+  function queueFor(windowKey) {
+    let q = byWindow.get(windowKey);
+    if (!q) {
+      q = [];
+      byWindow.set(windowKey, q);
+    }
+    return q;
+  }
+
+  function unlink(windowKey, approvalId) {
+    const q = byWindow.get(windowKey);
+    if (!q) return;
+    const i = q.indexOf(approvalId);
+    if (i !== -1) q.splice(i, 1);
+    if (q.length === 0) byWindow.delete(windowKey);
+  }
+
+  /** Settle one record exactly once. Every path out of `pending` goes through here. */
+  function settle(record, outcome, resolution) {
+    if (record.settled) return;
+    record.settled = true;
+    if (record.timer !== null) clearTimer(record.timer);
+    if (record.onAbort && record.signal) record.signal.removeEventListener('abort', record.onAbort);
+    pending.delete(record.id);
+    unlink(record.windowKey, record.id);
+    audit(resolution === RESOLUTION.OPERATOR ? 'approval/decided' : 'approval/delegated', {
+      approval_id: record.id,
+      window: record.windowKey,
+      tool: record.toolName,
+      outcome,
+      resolution,
+      waited_ms: now() - record.openedAt,
+    });
+    record.resolve(outcome);
+  }
+
+  /**
+   * Offer a request to the bridge.
+   *
+   * Returns a discriminated result rather than an outcome, because "I will not
+   * answer this" and "the answer is no" are different things to the caller and the
+   * host. `claim: false` means the caller must return `undefined` **without having
+   * called `next`**; `claim: true` means the caller owns the outcome and `promise`
+   * settles exactly once.
+   *
+   * @param {object} input
+   * @param {{agent?: {id?: string}, toolName?: string, callId?: string, reason?: string, signal?: AbortSignal}} input.request
+   * @param {string|null} input.windowKey The IM window bound to this request's session, or null.
+   * @param {number} [input.timeoutMs]
+   * @param {() => Promise<string>} input.delegate Calls the answerers registered behind us.
+   *        Called at most once, and only when the bridge declines *after* claiming.
+   * @returns {{claim: false, reason: string} | {claim: true, id: string, promise: Promise<string>}}
+   */
+  function offer({ request, windowKey, timeoutMs, delegate }) {
+    if (disposed) return { claim: false, reason: 'disposed' };
+    if (typeof delegate !== 'function') {
+      throw new TypeError('offer() requires a delegate() that calls the answerers behind this one');
+    }
+    if (request?.signal?.aborted) return { claim: false, reason: 'aborted' };
+    // Nothing to ask. Declining here — synchronously, with `next` untouched — is what
+    // keeps this plugin from swallowing approvals it has no business answering.
+    if (windowKey === null || windowKey === undefined || windowKey === '') {
+      return { claim: false, reason: 'no_window' };
+    }
+
+    const queue = queueFor(windowKey);
+    if (queue.length >= maxPendingPerWindow) {
+      audit('approval/refused-backlog', { window: windowKey, depth: queue.length });
+      return { claim: false, reason: 'backlog' };
+    }
+
+    const id = mintId();
+    const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : defaultTimeoutMs;
+    let resolveOutcome;
+    const promise = new Promise((resolve) => {
+      resolveOutcome = resolve;
+    });
+
+    const record = {
+      id,
+      windowKey,
+      toolName: request?.toolName ?? null,
+      callId: request?.callId ?? null,
+      reason: request?.reason ?? null,
+      signal: request?.signal ?? null,
+      openedAt: now(),
+      deadlineAt: now() + timeout,
+      settled: false,
+      timer: null,
+      onAbort: null,
+      resolve: resolveOutcome,
+    };
+
+    // Order matters: the record must be reachable by the time the timer or the
+    // abort listener can fire, or a zero-length timeout would settle nothing.
+    pending.set(id, record);
+    queue.push(id);
+    audit('approval/asked', {
+      approval_id: id,
+      window: windowKey,
+      tool: record.toolName,
+      timeout_ms: timeout,
+    });
+
+    record.timer = setTimer(() => {
+      // Delegating rather than deciding. The answerers behind us are allowed to
+      // allow this; reporting our own silence as a denial would be a lie about what
+      // the operator chose, and would deny work the host would have permitted.
+      void delegate().then(
+        (outcome) => settle(record, normaliseDelegated(outcome), RESOLUTION.DELEGATED),
+        () => settle(record, 'unavailable', RESOLUTION.DELEGATED),
+      );
+    }, timeout);
+    if (typeof record.timer?.unref === 'function') record.timer.unref();
+
+    if (record.signal) {
+      record.onAbort = () => settle(record, 'cancelled', RESOLUTION.CANCELLED);
+      record.signal.addEventListener('abort', record.onAbort, { once: true });
+    }
+
+    return { claim: true, id, promise };
+  }
+
+  /** The host may return any of its four outcomes; keep it, but never invent one. */
+  function normaliseDelegated(outcome) {
+    return OUTCOMES.includes(outcome) ? outcome : 'unavailable';
+  }
+
+  /**
+   * Answer a pending request from IM.
+   *
+   * @param {string} approvalId
+   * @param {'allowed-once'|'rejected'} outcome
+   * @returns {{ok: true} | {ok: false, reason: string}}
+   */
+  function decide(approvalId, outcome) {
+    if (!OPERATOR_OUTCOMES.has(outcome)) return { ok: false, reason: 'bad_outcome' };
+    const record = pending.get(approvalId);
+    // Already decided, already delegated, or never ours. The 0.1.0 code answered
+    // "✅ approved" on the strength of a promise resolving; here an unknown id is a
+    // refusal with a name.
+    if (!record) return { ok: false, reason: 'unknown_or_settled' };
+    if (now() >= record.deadlineAt) return { ok: false, reason: 'expired' };
+    settle(record, outcome, RESOLUTION.OPERATOR);
+    return { ok: true };
+  }
+
+  /** The oldest request still waiting in a window, or null. `/pending` renders this. */
+  function oldestFor(windowKey) {
+    const q = byWindow.get(windowKey);
+    if (!q || q.length === 0) return null;
+    const record = pending.get(q[0]);
+    return record ? publicView(record) : null;
+  }
+
+  /** Every request still waiting in a window, oldest first. */
+  function listFor(windowKey) {
+    const q = byWindow.get(windowKey);
+    if (!q) return [];
+    return q.map((id) => pending.get(id)).filter(Boolean).map(publicView);
+  }
+
+  function publicView(record) {
+    return {
+      approval_id: record.id,
+      window: record.windowKey,
+      tool: record.toolName,
+      reason: record.reason,
+      opened_at: record.openedAt,
+      deadline_at: record.deadlineAt,
+      remaining_ms: Math.max(0, record.deadlineAt - now()),
+    };
+  }
+
+  /**
+   * Delegate everything still pending, then refuse new work.
+   *
+   * Called from the plugin's disposer. Without this, a reload leaves timers alive
+   * that will resolve promises belonging to a fiber that no longer exists — the
+   * 0.1.0 code had exactly that leak.
+   */
+  function dispose() {
+    if (disposed) return { delegated: 0 };
+    disposed = true;
+    let delegated = 0;
+    for (const record of [...pending.values()]) {
+      delegated += 1;
+      // On shutdown there is nobody left to ask, so the host's own answerers must
+      // take it. `unavailable` would be an answer; this is not an answer.
+      settle(record, 'unavailable', RESOLUTION.DISPOSED);
+    }
+    byWindow.clear();
+    return { delegated };
+  }
+
+  return {
+    offer,
+    decide,
+    oldestFor,
+    listFor,
+    dispose,
+    get size() {
+      return pending.size;
+    },
+    /** Exposed for tests and diagnostics only. */
+    _internals: { pending, byWindow },
+  };
+}

package/src/chatops/auth.mjs

@@ -0,0 +1,376 @@
+/**
+ * The device keypair and the authorisation statement (v0.7.6).
+ *
+ * ## Why this exists
+ *
+ * v0.7.5 gave a machine an account code and a serial number. Both are **client-computed**, so
+ * neither proves anything: anyone who knows an account id can produce a well-formed SN for
+ * hardware they do not own. `ACCOUNT-FLEET-DESIGN.md` §2.5 says so in as many words, and this
+ * file is the part that fixes it.
+ *
+ * The fix is a signature chain with three links:
+ *
+ * 1. **The device generates a keypair** on first run. The private key never leaves the machine
+ *    and is never logged.
+ * 2. **The relay signs a statement** naming this device, its serial number, its public key and
+ *    its fleet. The fleet comes from *the pairing code*, not from anything the device said — so a
+ *    device **cannot choose which fleet it joins**. That is the whole of §3.2.
+ * 3. **Every request carries a signature** over the statement plus the request, so membership is
+ *    proven per request rather than asserted once.
+ *
+ * ## What this file is careful about
+ *
+ * **The statement is signed over a canonical encoding.** Two JSON encodings of the same object
+ * can sign differently, and a verifier that re-serialises the object it received cannot tell a
+ * tampered field from a key-order difference. So the statement travels **as the exact bytes that
+ * were signed**, and the verifier signs nothing it reassembled.
+ *
+ * **Expiry is mandatory.** A statement with no expiry is a permanent credential; a leaked one
+ * cannot be aged out. `verifyStatement` refuses a statement without one rather than defaulting to
+ * "never expires".
+ *
+ * **A device cannot widen its own statement.** The fleet id, the machine id and the public key
+ * are all inside the signature, so changing any of them invalidates it — which is what makes
+ * "this device is in this fleet" a fact rather than a claim.
+ */
+
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  createHash,
+  randomUUID,
+  sign as edSign,
+  verify as edVerify,
+  createHmac,
+  timingSafeEqual,
+} from 'node:crypto';
+
+/** Signature algorithms this module will use, and nothing else. */
+export const ALGORITHM = 'ed25519';
+
+/** Default statement lifetime: 90 days, per the design. */
+export const DEFAULT_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+
+/** How long before expiry a statement may be renewed. */
+export const RENEW_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Why a statement or a signature was refused. */
+export const AUTH_REFUSAL = Object.freeze({
+  MALFORMED: 'malformed',
+  BAD_SIGNATURE: 'bad_signature',
+  EXPIRED: 'expired',
+  NOT_YET_VALID: 'not_yet_valid',
+  NO_EXPIRY: 'no_expiry',
+  FLEET_MISMATCH: 'fleet_mismatch',
+  MACHINE_MISMATCH: 'machine_mismatch',
+  WRONG_ALGORITHM: 'wrong_algorithm',
+  CLOCK_SKEW: 'clock_skew',
+});
+
+/** How far a device's clock may drift before its request timestamps are refused. */
+export const CLOCK_SKEW_MS = 120_000;
+
+/**
+ * A canonical, unambiguous encoding of a statement's signed fields.
+ *
+ * Built by hand rather than with `JSON.stringify` so that **key order is fixed here** and cannot
+ * depend on how the object was constructed. A verifier that re-serialised a received object would
+ * be verifying its own encoding, which is not the same string the signer signed.
+ *
+ * Length-prefixing each field removes the other classic ambiguity: without it,
+ * `{a:'x', b:'yz'}` and `{a:'xy', b:'z'}` concatenate identically.
+ */
+export function canonicalStatement(statement) {
+  const fields = ['algorithm', 'fleet_id', 'machine_id', 'sn', 'public_key', 'issued_at_ms', 'expires_at_ms'];
+  const parts = [];
+  for (const field of fields) {
+    const value = statement?.[field];
+    if (value === undefined || value === null) throw new TypeError(`statement is missing ${field}`);
+    const text = String(value);
+    parts.push(`${field}:${Buffer.byteLength(text, 'utf8')}:${text}`);
+  }
+  return parts.join('\n');
+}
+
+/**
+ * A canonical encoding of one signed request.
+ *
+ * `body_hash` is the hash of the request body rather than the body itself: a body can be large,
+ * and the signature only needs to commit to it.
+ */
+export function canonicalRequest({ method, path, timestampMs, nonce, bodyHash }) {
+  const parts = [
+    `method:${Buffer.byteLength(String(method), 'utf8')}:${method}`,
+    `path:${Buffer.byteLength(String(path), 'utf8')}:${path}`,
+    `timestamp_ms:${String(timestampMs).length}:${timestampMs}`,
+    `nonce:${Buffer.byteLength(String(nonce), 'utf8')}:${nonce}`,
+    `body_hash:${String(bodyHash).length}:${bodyHash}`,
+  ];
+  return parts.join('\n');
+}
+
+/** Hash a request body for signing. Absent body hashes as the empty string's hash, not as null. */
+export function hashBody(body) {
+  const text = body === undefined || body === null ? '' : typeof body === 'string' ? body : JSON.stringify(body);
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/**
+ * Create a device identity: a keypair plus a stable machine id.
+ *
+ * @param {object} [options]
+ * @param {string} [options.privateKeyPem] An existing key, so a restart keeps its identity.
+ * @param {string} [options.machineId]
+ * @param {() => string} [options.mintMachineId]
+ */
+export function createDeviceKey(options = {}) {
+  const mintMachineId = options.mintMachineId ?? randomUUID;
+  let privateKey;
+  let generated = false;
+
+  if (typeof options.privateKeyPem === 'string' && options.privateKeyPem !== '') {
+    privateKey = createPrivateKey(options.privateKeyPem);
+  } else {
+    // Ed25519 needs no parameters and no randomness argument here; the platform CSPRNG supplies it.
+    const pair = generateKeyPairSync(ALGORITHM);
+    privateKey = pair.privateKey;
+    generated = true;
+  }
+
+  if (privateKey.asymmetricKeyType !== ALGORITHM) {
+    throw new TypeError(`the device key must be ${ALGORITHM}, not ${privateKey.asymmetricKeyType}`);
+  }
+
+  const publicKey = createPublicKey(privateKey);
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const machineId = options.machineId ?? mintMachineId();
+
+  return {
+    machineId,
+    publicKeyPem,
+    generated,
+    /** The private key, for persistence. Callers must write it 0600 and never log it. */
+    privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+    /** Sign arbitrary bytes with the device key. */
+    sign(bytes) {
+      return edSign(null, Buffer.from(bytes, 'utf8'), privateKey);
+    },
+  };
+}
+
+/**
+ * Verify a detached signature against a public key.
+ *
+ * Returns a value rather than throwing, because a bad signature is an expected input on the
+ * relay's hot path and an exception there is a denial-of-service shape.
+ */
+export function verifyWith(publicKeyPem, bytes, signature) {
+  try {
+    const key = createPublicKey(publicKeyPem);
+    return edVerify(null, Buffer.from(bytes, 'utf8'), key, Buffer.from(signature));
+  } catch {
+    // An unparseable key or signature is a failed verification, not a crash.
+    return false;
+  }
+}
+
+/**
+ * Sign a statement into the wire form.
+ *
+ * The wire form carries **the exact bytes that were signed** alongside the signature, so a
+ * verifier never re-serialises. `canonical` is included rather than recomputed for that reason.
+ *
+ * @param {object} options
+ * @param {object} options.statement The fields to commit to.
+ * @param {(bytes: string) => Buffer} options.sign The relay's signer.
+ */
+export function sealStatement({ statement, sign }) {
+  const canonical = canonicalStatement(statement);
+  const signature = sign(canonical);
+  return {
+    statement,
+    canonical,
+    signature: Buffer.from(signature).toString('base64'),
+  };
+}
+
+/**
+ * Verify a sealed statement.
+ *
+ * @param {object} options
+ * @param {object} options.sealed The wire form.
+ * @param {(canonical: string, signature: Buffer) => boolean} options.verify The relay's verifier.
+ * @param {string} [options.expectFleet] Refuse a statement for another fleet.
+ * @param {string} [options.expectMachine] Refuse a statement for another machine.
+ * @param {number} [options.now]
+ */
+export function verifyStatement({ sealed, verify, expectFleet, expectMachine, now = Date.now() }) {
+  if (sealed === null || typeof sealed !== 'object') return { ok: false, reason: AUTH_REFUSAL.MALFORMED };
+  const { statement, canonical, signature } = sealed;
+  if (statement === null || typeof statement !== 'object' || typeof canonical !== 'string' || typeof signature !== 'string') {
+    return { ok: false, reason: AUTH_REFUSAL.MALFORMED };
+  }
+  if (statement.algorithm !== ALGORITHM) {
+    return { ok: false, reason: AUTH_REFUSAL.WRONG_ALGORITHM, detail: String(statement.algorithm) };
+  }
+
+  /**
+   * Expiry is checked **before** the canonical form is recomputed.
+   *
+   * Order matters here, and a test is what found it. `canonicalStatement` refuses a statement
+   * missing a signed field, so a statement with no expiry reported `malformed` — technically true
+   * and useless, because the actionable answer is "this statement has no expiry and must not be
+   * treated as permanent". Checking it first names the real problem.
+   */
+  const expires = Number(statement.expires_at_ms);
+  if (!Number.isFinite(expires)) return { ok: false, reason: AUTH_REFUSAL.NO_EXPIRY };
+
+  // The signed bytes must be the bytes that describe this statement. Recomputing and comparing
+  // is what stops a caller swapping in a different statement beside a valid signature — and it is
+  // cheap, because the canonical form is already on the wire.
+  let recomputed;
+  try {
+    recomputed = canonicalStatement(statement);
+  } catch (error) {
+    return { ok: false, reason: AUTH_REFUSAL.MALFORMED, detail: error.message };
+  }
+  if (recomputed !== canonical) {
+    return { ok: false, reason: AUTH_REFUSAL.MALFORMED, detail: 'the canonical form does not match the statement' };
+  }
+
+  let signatureBytes;
+  try {
+    signatureBytes = Buffer.from(signature, 'base64');
+  } catch {
+    return { ok: false, reason: AUTH_REFUSAL.MALFORMED, detail: 'signature is not base64' };
+  }
+  if (!verify(canonical, signatureBytes)) return { ok: false, reason: AUTH_REFUSAL.BAD_SIGNATURE };
+
+  const issued = Number(statement.issued_at_ms);
+  if (!Number.isFinite(issued)) return { ok: false, reason: AUTH_REFUSAL.MALFORMED, detail: 'issued_at_ms is not a number' };
+
+  if (now > expires) return { ok: false, reason: AUTH_REFUSAL.EXPIRED, detail: new Date(expires).toISOString() };
+  // A statement issued in the future means a clock problem, which is worth naming separately from
+  // an expiry: the fixes are different.
+  if (issued > now + CLOCK_SKEW_MS) return { ok: false, reason: AUTH_REFUSAL.NOT_YET_VALID, detail: new Date(issued).toISOString() };
+
+  if (typeof expectFleet === 'string' && statement.fleet_id !== expectFleet) {
+    return { ok: false, reason: AUTH_REFUSAL.FLEET_MISMATCH, detail: `statement is for ${statement.fleet_id}` };
+  }
+  if (typeof expectMachine === 'string' && statement.machine_id !== expectMachine) {
+    return { ok: false, reason: AUTH_REFUSAL.MACHINE_MISMATCH };
+  }
+  return { ok: true, statement };
+}
+
+/**
+ * Sign one request.
+ *
+ * @param {object} options
+ * @param {object} options.device From `createDeviceKey`.
+ * @param {string} options.method
+ * @param {string} options.path
+ * @param {unknown} [options.body]
+ * @param {number} [options.now]
+ * @param {() => string} [options.mintNonce]
+ */
+export function signRequest({ device, method, path, body, now = Date.now(), mintNonce = randomUUID }) {
+  const timestampMs = now;
+  const nonce = mintNonce();
+  const bodyHash = hashBody(body);
+  const canonical = canonicalRequest({ method, path, timestampMs, nonce, bodyHash });
+  return {
+    timestampMs,
+    nonce,
+    bodyHash,
+    signature: device.sign(canonical).toString('base64'),
+  };
+}
+
+/**
+ * Verify one request's signature.
+ *
+ * @param {object} options
+ * @param {object} options.headers The request headers, lower-cased.
+ * @param {string} options.publicKeyPem
+ * @param {string} options.method
+ * @param {string} options.path
+ * @param {unknown} [options.body]
+ * @param {number} [options.now]
+ * @param {(nonce: string, timestampMs: number) => boolean} [options.rememberNonce]
+ *        Replay defence, injected: without it a captured request is valid forever.
+ */
+export function verifyRequest({ headers, publicKeyPem, method, path, body, now = Date.now(), rememberNonce }) {
+  const ts = Number(headers['x-w2m-timestamp']);
+  const nonce = headers['x-w2m-nonce'];
+  const signature = headers['x-w2m-signature'];
+  const claimedHash = headers['x-w2m-body-hash'];
+  if (!Number.isFinite(ts) || typeof nonce !== 'string' || nonce === '' || typeof signature !== 'string' || signature === '') {
+    return { ok: false, reason: AUTH_REFUSAL.MALFORMED, detail: 'missing signature headers' };
+  }
+  if (Math.abs(now - ts) > CLOCK_SKEW_MS) {
+    // Outside the window the request is either replayed or from a machine whose clock is wrong;
+    // both are refused, and the window is named so the second case is diagnosable.
+    return { ok: false, reason: AUTH_REFUSAL.CLOCK_SKEW, detail: `timestamp is ${Math.round((now - ts) / 1000)}s from now` };
+  }
+
+  const bodyHash = hashBody(body);
+  // The body must hash to what was signed. Without this check the signature would authorise the
+  // *route* while saying nothing about the payload.
+  if (typeof claimedHash === 'string' && claimedHash !== '' && claimedHash !== bodyHash) {
+    return { ok: false, reason: AUTH_REFUSAL.BAD_SIGNATURE, detail: 'the body does not match the signed hash' };
+  }
+
+  const canonical = canonicalRequest({ method, path, timestampMs: ts, nonce, bodyHash });
+  let signatureBytes;
+  try {
+    signatureBytes = Buffer.from(signature, 'base64');
+  } catch {
+    return { ok: false, reason: AUTH_REFUSAL.MALFORMED };
+  }
+  if (!verifyWith(publicKeyPem, canonical, signatureBytes)) {
+    return { ok: false, reason: AUTH_REFUSAL.BAD_SIGNATURE };
+  }
+  // Recorded only after the signature checks out, so an attacker cannot fill the replay table by
+  // sending garbage nonces.
+  if (typeof rememberNonce === 'function' && rememberNonce(nonce, ts) === false) {
+    return { ok: false, reason: AUTH_REFUSAL.BAD_SIGNATURE, detail: 'this nonce was already used' };
+  }
+  return { ok: true, nonce, timestampMs: ts };
+}
+
+/** Constant-time string comparison, for tokens. */
+export function safeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const ab = Buffer.from(a, 'utf8');
+  const bb = Buffer.from(b, 'utf8');
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+/**
+ * A bounded replay window.
+ *
+ * Bounded on purpose: an unbounded set of seen nonces is a memory leak that a peer can drive, and
+ * the timestamp window already rejects anything old enough to have fallen out.
+ */
+export function createReplayGuard({ windowMs = CLOCK_SKEW_MS, now = Date.now } = {}) {
+  const seen = new Map();
+  return function remember(nonce, timestampMs) {
+    const current = now();
+    for (const [key, at] of seen) {
+      if (current - at > windowMs) seen.delete(key);
+    }
+    if (seen.has(nonce)) return false;
+    seen.set(nonce, Number.isFinite(timestampMs) ? timestampMs : current);
+    return true;
+  };
+}
+
+/** Derive a relay's fleet signing key from a master secret, so one secret serves many fleets. */
+export function deriveFleetKey(masterSecret, fleetId) {
+  if (typeof masterSecret !== 'string' || masterSecret === '') throw new TypeError('deriveFleetKey needs a master secret');
+  if (typeof fleetId !== 'string' || fleetId === '') throw new TypeError('deriveFleetKey needs a fleet id');
+  return createHmac('sha256', masterSecret).update(`w2m-fleet-v1:${fleetId}`, 'utf8').digest();
+}