@ijfw/memory-server 1.4.1 → 1.4.3

package/src/extension-signer.js

@@ -45,6 +45,16 @@ import {
   SIGNATURE_PATTERN,
   PUBLISHER_KEY_ID_PATTERN,
 } from './extension-manifest-schema.js';
+import {
+  SOFTWARE_BACKEND,
+  SSH_AGENT_BACKEND,
+  resolveBackend,
+} from './hardware-signer.js';
+
+// B15: re-export backend primitives so callers can sign/verify via the
+// backend abstraction without a second import. Software backend remains
+// the default; ssh-agent backend is opt-in via manifest.publisher_key_backend.
+export { SOFTWARE_BACKEND, SSH_AGENT_BACKEND, resolveBackend };
 
 /**
  * Recursively sort object keys to produce a stable canonical representation.
@@ -580,6 +590,59 @@ export function signManifest(manifest, privateKeyPem) {
   return computeIntegrity(signed);
 }
 
+/**
+ * B15: Backend-aware async manifest signer. Dispatches to the backend
+ * named by `manifest.publisher_key_backend` (default: 'software').
+ *
+ * The software backend reads the on-disk private PEM at
+ * `<home>/.ijfw/keys/<keyId>/private.pem` and signs in-process. The
+ * ssh-agent backend forwards the signing op to the running SSH agent
+ * — the private key never enters the IJFW process.
+ *
+ * Identity selection at sign time:
+ *   - keyId is supplied via `opts.keyId`. The chosen backend uses keyId
+ *     to look up its key material (PEM on disk for software; pubkey blob
+ *     in backend.json for ssh-agent, then identity match in the agent).
+ *
+ * Returns a NEW manifest with `publisher_key_id`, `publisher_key_backend`
+ * (when explicitly non-software), `signature`, and re-computed `integrity`.
+ *
+ * @param {object} manifest
+ * @param {object} opts
+ * @param {string} opts.keyId required — the keyId to sign with
+ * @param {string} [opts.home] override for ~/.ijfw root (test isolation)
+ * @param {string} [opts.socketPath] override SSH_AUTH_SOCK (test isolation)
+ * @returns {Promise<object>}
+ */
+export async function signManifestWithBackend(manifest, opts = {}) {
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new TypeError('signManifestWithBackend: manifest must be an object');
+  }
+  if (typeof opts.keyId !== 'string' || !PUBLISHER_KEY_ID_PATTERN.test(opts.keyId)) {
+    throw new TypeError('signManifestWithBackend: opts.keyId required (sha256 hex)');
+  }
+  const backendName = manifest.publisher_key_backend; // undefined OK
+  const backend = resolveBackend(backendName);
+
+  const toSign = {
+    ...manifest,
+    publisher_key_id: opts.keyId,
+  };
+  // Only emit `publisher_key_backend` field when explicitly non-default to
+  // keep software-backend manifests byte-identical to the v1.4.0 shape.
+  if (backendName !== undefined && backendName !== 'software') {
+    toSign.publisher_key_backend = backendName;
+  }
+  const bytes = canonicalSigningBytes(toSign);
+  const sigBuf = await backend.sign(bytes, opts.keyId, {
+    home: opts.home,
+    socketPath: opts.socketPath,
+  });
+  const signature = `ed25519:${Buffer.from(sigBuf).toString('base64')}`;
+  const signed = { ...toSign, signature };
+  return computeIntegrity(signed);
+}
+
 /**
  * Verify a manifest's signature against a map of trusted publishers.
  *
@@ -810,6 +873,48 @@ export function signRotationToken(oldPrivateKeyPem, newPublicKeyPem, opts = {})
   return { ...token, signature: `ed25519:${sigBuf.toString('base64')}` };
 }
 
+/**
+ * B15: Backend-aware async rotation-token signer. Mirrors signRotationToken
+ * but dispatches the actual signing operation to the named backend.
+ *
+ * The token shape is identical to the software-backend version
+ * (`signRotationToken`); the only difference is WHO holds the private
+ * key. For ssh-agent backend, the OLD key's signing op is forwarded to
+ * the agent — the old private key never enters IJFW process memory.
+ *
+ * @param {object} opts
+ * @param {string} opts.oldKeyId required — keyId for the OLD key
+ * @param {string} opts.newPublicKeyPem required — PEM of the NEW key
+ * @param {string} [opts.backend] 'software' | 'ssh-agent' (default software)
+ * @param {string} [opts.rotated_at] ISO timestamp override
+ * @param {string} [opts.home] override for ~/.ijfw root (test isolation)
+ * @param {string} [opts.socketPath] override SSH_AUTH_SOCK (test isolation)
+ * @returns {Promise<{rotated_at, old_key_id, new_key_id, new_public_key, signature}>}
+ */
+export async function signRotationTokenWithBackend(opts = {}) {
+  if (typeof opts.oldKeyId !== 'string' || !PUBLISHER_KEY_ID_PATTERN.test(opts.oldKeyId)) {
+    throw new TypeError('signRotationTokenWithBackend: opts.oldKeyId required (sha256 hex)');
+  }
+  if (typeof opts.newPublicKeyPem !== 'string' || opts.newPublicKeyPem.indexOf('BEGIN PUBLIC KEY') === -1) {
+    throw new TypeError('signRotationTokenWithBackend: opts.newPublicKeyPem must be PEM');
+  }
+  const backend = resolveBackend(opts.backend);
+  const new_key_id = publicKeyFingerprint(opts.newPublicKeyPem);
+
+  const token = {
+    rotated_at: opts.rotated_at || new Date().toISOString(),
+    old_key_id: opts.oldKeyId,
+    new_key_id,
+    new_public_key: opts.newPublicKeyPem,
+  };
+  const bytes = Buffer.from(JSON.stringify(sortKeysDeep(token)), 'utf8');
+  const sigBuf = await backend.sign(bytes, opts.oldKeyId, {
+    home: opts.home,
+    socketPath: opts.socketPath,
+  });
+  return { ...token, signature: `ed25519:${Buffer.from(sigBuf).toString('base64')}` };
+}
+
 /**
  * Verify a rotation token against the old public key.
  * Checks:

package/src/fs-lock.js

@@ -0,0 +1,205 @@
+/**
+ * fs-lock.js — Cross-platform directory-based exclusive lock primitive.
+ *
+ * Frozen contract for v1.4.3 W9-A (consumed by W9-A1 cache writes + W9-A3
+ * quota counters). The directory itself is the lock; `mkdir` with
+ * `recursive:false` is atomic on POSIX + Windows, so any two processes racing
+ * to create the same path will see exactly one winner (EEXIST for the other).
+ *
+ * NO `process.on('exit')` cleanup. If a holder is SIGKILL'd between mkdir and
+ * the `finally` clause, the next caller's stale-recovery path handles it
+ * (single retry after rm).
+ *
+ * Closes SEC-H-01 (cross-process race) from v1.4.3 cross-audit round 1.
+ */
+
+import { mkdir, writeFile, readFile, rm, stat } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+
+const DEFAULT_ACQUIRE_TIMEOUT_MS = 5000;
+const DEFAULT_STALE_MS = 30000;
+const BACKOFF_START_MS = 25;
+const BACKOFF_MAX_MS = 250;
+
+export class FsLockBusyError extends Error {
+  constructor(lockPath, timeoutMs) {
+    super(
+      `fs-lock: could not acquire "${lockPath}" within ${timeoutMs}ms (holder still alive)`,
+    );
+    this.name = 'FsLockBusyError';
+    this.code = 'FS_LOCK_BUSY';
+    this.lockPath = lockPath;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export class FsLockStaleError extends Error {
+  constructor(lockPath, cause) {
+    super(
+      `fs-lock: stale lock recovery failed for "${lockPath}"${
+        cause ? `: ${cause.message || cause}` : ''
+      }`,
+    );
+    this.name = 'FsLockStaleError';
+    this.code = 'FS_LOCK_STALE';
+    this.lockPath = lockPath;
+    if (cause) this.cause = cause;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function readHolder(lockPath) {
+  try {
+    const raw = await readFile(join(lockPath, 'holder.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      typeof parsed.acquired_at === 'number'
+    ) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    // holder.json may not exist yet (mkdir landed, write hadn't), or be
+    // truncated. Treat as "no readable holder" — caller decides what to do.
+    return null;
+  }
+}
+
+async function tryAcquireOnce(lockPath) {
+  await mkdir(lockPath, { recursive: false });
+  // Write holder file inside the lock dir — purely forensic. The directory's
+  // existence is what holds the lock.
+  const holder = { pid: process.pid, acquired_at: Date.now() };
+  try {
+    await writeFile(
+      join(lockPath, 'holder.json'),
+      JSON.stringify(holder),
+      'utf8',
+    );
+  } catch {
+    // Best-effort. The lock is still held even if forensic write failed.
+  }
+  return holder;
+}
+
+/**
+ * withFsLock(lockPath, fn, { staleMs, acquireTimeoutMs })
+ *
+ * See module docstring for contract details.
+ */
+export async function withFsLock(lockPath, fn, opts = {}) {
+  const staleMs =
+    typeof opts.staleMs === 'number' ? opts.staleMs : DEFAULT_STALE_MS;
+  const acquireTimeoutMs =
+    typeof opts.acquireTimeoutMs === 'number'
+      ? opts.acquireTimeoutMs
+      : DEFAULT_ACQUIRE_TIMEOUT_MS;
+
+  // Ensure the lock's parent directory exists. `tryAcquireOnce` uses
+  // `mkdir(lockPath, { recursive: false })` which fails with ENOENT when any
+  // parent is missing — surfacing as a non-EEXIST error and breaking callers
+  // that expect locks to "just work" in fresh tmp HOMEs. Single best-effort
+  // recursive mkdir up-front is cheap (one stat on the common case) and makes
+  // the lock primitive safe to invoke against any path under a writable root.
+  // Surfaced as a Windows CI regression in v1.4.3 (test-extension-registry
+  // tests 523/527/534/535 — Linux/macOS passed only because earlier tests
+  // happened to create ~/.ijfw/state by side-effect).
+  try {
+    await mkdir(dirname(lockPath), { recursive: true });
+  } catch {
+    // Ignore — the subsequent mkdir(lockPath) will surface a clearer error.
+  }
+
+  const deadline = Date.now() + acquireTimeoutMs;
+  let staleRecoveryUsed = false;
+  let backoff = BACKOFF_START_MS;
+
+  // Acquire loop. We try mkdir; if EEXIST, decide between waiting and stale
+  // recovery; otherwise propagate the error.
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      await tryAcquireOnce(lockPath);
+      break;
+    } catch (err) {
+      if (err && err.code !== 'EEXIST') {
+        // Real filesystem error (ENOENT on parent, EACCES, etc.) — surface.
+        throw err;
+      }
+
+      // R12-M-01: when holder.json is missing or unparseable (crash between
+      // mkdir and the holder write, OR an attacker pre-creating an empty lock
+      // dir to starve callers), fall back to the lock directory's own mtime so
+      // stale-recovery can still fire. Without this fallback the local-DoS
+      // surface is "mkdir <lockPath> && walk away".
+      const holder = await readHolder(lockPath);
+      let age = null;
+      if (holder) {
+        age = Date.now() - holder.acquired_at;
+      } else {
+        try {
+          const st = await stat(lockPath);
+          age = Date.now() - st.mtimeMs;
+        } catch {
+          // The lock dir vanished between EEXIST and stat — fall through to
+          // the deadline check; the next loop iteration will try mkdir again.
+          age = null;
+        }
+      }
+      const isStale = age != null && age > staleMs;
+
+      if (isStale && !staleRecoveryUsed) {
+        staleRecoveryUsed = true;
+        try {
+          await rm(lockPath, { recursive: true, force: true });
+        } catch (rmErr) {
+          throw new FsLockStaleError(lockPath, rmErr);
+        }
+        try {
+          await tryAcquireOnce(lockPath);
+          break;
+        } catch (retryErr) {
+          if (retryErr && retryErr.code === 'EEXIST') {
+            throw new FsLockStaleError(lockPath, retryErr);
+          }
+          throw retryErr;
+        }
+      }
+
+      if (Date.now() >= deadline) {
+        throw new FsLockBusyError(lockPath, acquireTimeoutMs);
+      }
+
+      // Bounded exponential backoff; clamp to remaining time so we don't
+      // overshoot the deadline by a full BACKOFF_MAX_MS slice.
+      const remaining = Math.max(0, deadline - Date.now());
+      const waitMs = Math.min(backoff, BACKOFF_MAX_MS, remaining);
+      if (waitMs > 0) await sleep(waitMs);
+      backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+    }
+  }
+
+  // Lock acquired — run fn and ALWAYS release.
+  let fnResult;
+  let fnError;
+  try {
+    fnResult = await fn();
+  } catch (err) {
+    fnError = err;
+  }
+
+  try {
+    await rm(lockPath, { recursive: true, force: true });
+  } catch {
+    // Release failures don't override the caller's result/error. The next
+    // caller's stale-recovery will reclaim if needed.
+  }
+
+  if (fnError !== undefined) throw fnError;
+  return fnResult;
+}