@blamejs/core 0.17.23 → 0.18.0

package/lib/auth/oauth.js

@@ -272,6 +272,27 @@ function _generatePkce() {
   return { verifier: verifier, challenge: challenge };
 }
 
+/**
+ * @primitive  b.auth.oauth.generatePkce
+ * @signature  b.auth.oauth.generatePkce()
+ * @since      0.18.0
+ * @status     stable
+ * @related    b.auth.oauth.parseCallback
+ *
+ * Generate a PKCE (RFC 7636) verifier/challenge pair for a hand-rolled
+ * authorization-code flow that does not go through `create()`. The
+ * `code_challenge_method` is always `S256`: the challenge is the base64url
+ * of SHA-256 over the verifier, and the verifier is 43 base64url characters
+ * (32 CSPRNG bytes).
+ *
+ * @example
+ *   var pkce = b.auth.oauth.generatePkce();
+ *   // → { verifier: "…43 chars…", challenge: "…base64url(SHA-256(verifier))…" }
+ */
+function generatePkce() {
+  return _generatePkce();
+}
+
 function _validateUrl(url, allowHttp, label) {
   if (typeof url !== "string" || url.length === 0) {
     throw new OAuthError("auth-oauth/bad-url", label + ": URL is required");
@@ -550,6 +571,7 @@ function _toAttestationPrivateKey(value, label) {
   catch (e) {
     var code = (e && e.code) === "auth-jwt-external/sign-no-key"
       ? "auth-oauth/attestation-no-key" : "auth-oauth/attestation-bad-key";
+    /* c8 ignore next -- String(e) fallback: the jwt-external error always carries a message */
     throw new OAuthError(code, (e && e.message) || String(e));
   }
 }
@@ -567,8 +589,10 @@ function _resolveAttestationAlg(explicitAlg, privateKey, label) {
   try {
     return jwtExternal._resolveSignAlg(explicitAlg, privateKey, label);
   } catch (e) {
+    /* c8 ignore next -- || "" is unreachable: _resolveSignAlg always throws a coded AuthError */
     var ec = (e && e.code) || "";
     if (ec === "auth-jwt-external/sign-alg-key-mismatch") {
+      /* c8 ignore next -- String(e) fallback: the mapped error always carries a message */
       throw new OAuthError("auth-oauth/attestation-alg-key-mismatch", (e && e.message) || String(e));
     }
     if (ec === "auth-jwt-external/sign-alg-refused" || ec === "auth-jwt-external/sign-alg-unsupported") {
@@ -576,8 +600,10 @@ function _resolveAttestationAlg(explicitAlg, privateKey, label) {
         label + ": alg '" + explicitAlg + "' is not an accepted attestation algorithm");
     }
     if (ec === "auth-jwt-external/sign-key-unsupported") {
+      /* c8 ignore next -- String(e) fallback: the mapped error always carries a message */
       throw new OAuthError("auth-oauth/attestation-key-unsupported", (e && e.message) || String(e));
     }
+    /* c8 ignore next -- unreachable: _resolveSignAlg only emits the four codes handled above */
     throw new OAuthError("auth-oauth/attestation-bad-key", (e && e.message) || String(e));
   }
 }
@@ -613,6 +639,7 @@ function _verifyAttestationJws(jws, publicKeyJwk, label, expectedTyp) {
     header  = safeJson.parse(_b64urlDecode(parts[0]).toString("utf8"), { maxBytes: MAX_ATTESTATION_JWT_BYTES });
     payload = safeJson.parse(_b64urlDecode(parts[1]).toString("utf8"), { maxBytes: MAX_ATTESTATION_JWT_BYTES });
   } catch (e) {
+    /* c8 ignore next 2 -- String(e) fallback: the decode error always carries a message */
     throw new OAuthError("auth-oauth/attestation-malformed",
       label + ": header/payload decode failed: " + ((e && e.message) || String(e)));
   }
@@ -653,6 +680,7 @@ function _verifyAttestationJws(jws, publicKeyJwk, label, expectedTyp) {
   var ok;
   try {
     ok = nodeCrypto.verify(params.hash, Buffer.from(signingInput, "ascii"), verifyOpts, sig);
+    /* c8 ignore next 4 -- verify cannot raise: the alg/kty/crv cross-check above guarantees a compatible key/params pairing, so a bad signature returns false rather than throwing */
   } catch (verifyErr) {
     throw new OAuthError("auth-oauth/attestation-bad-signature",
       label + ": signature verification raised: " + ((verifyErr && verifyErr.message) || String(verifyErr)));
@@ -667,6 +695,7 @@ function _verifyAttestationJws(jws, publicKeyJwk, label, expectedTyp) {
 // never reach the attestation's cnf claim. Mirrors the dpop.buildProof
 // public-only embed.
 function _publicCnfJwk(jwk, label) {
+  /* c8 ignore next 4 -- unreachable: the sole caller validates instanceKeyJwk as a required object before this call */
   if (!jwk || typeof jwk !== "object") {
     throw new OAuthError("auth-oauth/attestation-bad-cnf",
       label + ": instanceKeyJwk (public JWK for the cnf claim) is required");
@@ -1006,6 +1035,7 @@ async function verifyClientAttestation(attestationJwt, popJwt, vopts) {
 // strings, returns false (never throws) on length mismatch, and refuses
 // non-string/Buffer input — so it carries the timing + type discipline.
 function _constantTimeStrEq(a, b) {
+  /* c8 ignore next -- every caller passes a String()-wrapped first argument, so the typeof-a arm never short-circuits */
   if (typeof a !== "string" || typeof b !== "string") return false;
   return cryptoTimingSafeEqual(a, b);
 }
@@ -1040,6 +1070,7 @@ var RESERVED_AUTHZ_PARAMS = {
 // closed; shared by authorizationUrl, pushAuthorizationRequest, and
 // endSessionUrl so every URL/PAR builder guards the same way.
 function _assertNoReservedExtraParams(extraParams, reserved, errCode, ctx) {
+  /* c8 ignore next -- every caller guards `extraParams && typeof === "object"` first, so the !extraParams arm never short-circuits */
   if (!extraParams || typeof extraParams !== "object") return;
   var ek = Object.keys(extraParams);
   for (var i = 0; i < ek.length; i++) {
@@ -1187,13 +1218,16 @@ function create(opts) {
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
     if (res.statusCode < 200 || res.statusCode >= 300) {
+      /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
       var bodyText = res.body ? res.body.toString("utf8") : "";
       throw new OAuthError("auth-oauth/http-" + res.statusCode,
         url + " returned " + res.statusCode + ": " + bodyText.slice(0, 500));
     }
+    /* c8 ignore next -- httpClient always yields a Buffer body (empty Buffer for no content), so this never returns null */
     if (!res.body) return null;
     try { return safeJson.parse(res.body.toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/bad-json",
         url + " response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -1262,6 +1296,7 @@ function create(opts) {
   async function _peekDiscovery() {
     if (!isOidc || !issuer) return null;
     try { return (await _discoveryCache.get("config")) || null; }
+    /* c8 ignore next -- defensive: the in-memory discovery cache get() does not throw */
     catch (_e) { return null; }
   }
 
@@ -1312,6 +1347,7 @@ function create(opts) {
     // base64url(SHA-256(verifier)) per RFC 7636.
     var state = uopts.state || _generateRandomToken(STATE_NONCE_BYTES);
     var nonce = uopts.nonce || (isOidc ? _generateRandomToken(STATE_NONCE_BYTES) : null);
+    /* c8 ignore next -- pkce is always true (create() refuses pkce:false), so the : null alternate is dead */
     var pkceVals = pkce ? _generatePkce() : null;
     var params = new URLSearchParams();
     params.set("response_type", "code");
@@ -1356,6 +1392,7 @@ function create(opts) {
       url:       endpoint + sep + params.toString(),
       state:     state,
       nonce:     nonce,
+      /* c8 ignore next 2 -- pkceVals is always truthy (pkce is always on), so the : null alternates are dead */
       verifier:  pkceVals ? pkceVals.verifier  : null,
       challenge: pkceVals ? pkceVals.challenge : null,
       authorizationDetails: requestedAuthzDetails,
@@ -1764,6 +1801,7 @@ function create(opts) {
     if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
+    /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     if (res.statusCode < 200 || res.statusCode >= 300) {
       throw new OAuthError("auth-oauth/token-error-" + res.statusCode,
@@ -1772,6 +1810,7 @@ function create(opts) {
     var parsed;
     try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/bad-token-json",
         "token endpoint response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -1779,6 +1818,7 @@ function create(opts) {
   }
 
   async function _normalizeTokens(raw, vopts) {
+    /* c8 ignore next -- every caller passes a vopts object, so the || {} default is unreachable */
     vopts = vopts || {};
     // RFC 6749 §3.3 — scope is space-separated, ONLY U+0020. `\s+` previously
     // matched U+0085 NEL, U+00A0 NBSP, etc., so a hostile AS returning
@@ -1879,6 +1919,7 @@ function create(opts) {
         action:   "jwt.jwe.refused",
         outcome:  "denied",
         metadata: { reason: "jwe-on-jws-verifier", primitive: "oauth.verifyIdToken" },
+        /* c8 ignore next -- drop-silent observability sink: safeEmit does not throw */
       }); } catch (_e) { /* drop-silent — observability sink */ }
       throw new OAuthError("auth-oauth/jwe-refused",
         "5-segment JWE id_token refused — verifyIdToken only handles JWS " +
@@ -1892,6 +1933,7 @@ function create(opts) {
       header  = safeJson.parse(_b64urlDecode(parts[0]).toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES });
       payload = safeJson.parse(_b64urlDecode(parts[1]).toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES });
     } catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the decode error always carries a message */
       throw new OAuthError("auth-oauth/malformed-jwt",
         "ID token header/payload base64 decode failed: " + ((e && e.message) || String(e)));
     }
@@ -1980,6 +2022,7 @@ function create(opts) {
     var verified;
     try {
       verified = nodeCrypto.verify(params.hash, Buffer.from(signingInput, "ascii"), verifyOpts, sig);
+      /* c8 ignore next 5 -- verify cannot raise: the alg/kty/crv cross-check above guarantees a compatible key/params pairing, so a bad signature returns false rather than throwing */
     } catch (verifyErr) {
       throw new OAuthError("auth-oauth/bad-signature",
         "ID token signature verification raised: " +
@@ -2055,6 +2098,7 @@ function create(opts) {
             reason:          "cross-realm-jwt-refused",
             primitive:       "oauth.verifyIdToken",
           },
+          /* c8 ignore next -- drop-silent observability sink: safeEmit does not throw */
         }); } catch (_e) { /* drop-silent — observability sink */ }
         throw new OAuthError("auth-oauth/iss-mismatch",
           "ID token iss '" + payload.iss + "' does not match expected '" + issuer +
@@ -2335,6 +2379,7 @@ function create(opts) {
           reason:          "frontchannel-logout-cross-realm",
           primitive:       "oauth.parseFrontchannelLogoutRequest",
         },
+        /* c8 ignore next -- drop-silent observability sink: safeEmit does not throw */
       }); } catch (_e) { /* drop-silent — observability sink */ }
       throw new OAuthError("auth-oauth/frontchannel-logout-iss-mismatch",
         "parseFrontchannelLogoutRequest: iss \"" + iss +
@@ -2423,6 +2468,7 @@ function create(opts) {
     var claims = verified.claims;
 
     // §2.6 — events claim presence + correct shape
+    /* c8 ignore next 5 -- defense-in-depth: verifyIdToken's skipExpCheck self-guard already enforced the backchannel-logout event before returning, so this re-check never fires */
     if (!claims.events || typeof claims.events !== "object" ||
         !claims.events["http://schemas.openid.net/event/backchannel-logout"]) {
       throw new OAuthError("auth-oauth/missing-logout-event",
@@ -2449,6 +2495,7 @@ function create(opts) {
       ? vopts.maxAgeSec
       : DEFAULT_LOGOUT_TOKEN_MAX_AGE_SEC;
     var nowSecLogout = Math.floor(Date.now() / C.TIME.seconds(1));
+    /* c8 ignore next 4 -- defense-in-depth: verifyIdToken's skipExpCheck freshness gate already required a numeric iat before returning, so this re-check never fires */
     if (typeof claims.iat !== "number") {
       throw new OAuthError("auth-oauth/logout-token-no-iat",
         "verifyBackchannelLogoutToken: payload.iat required (OIDC BCL §2.4)");
@@ -2513,6 +2560,7 @@ function create(opts) {
       sub:    claims.sub || null,
       sid:    claims.sid || null,
       jti:    claims.jti || null,
+      /* c8 ignore next -- iat is always a positive number here (enforced above), so the || null arm is unreachable */
       iat:    claims.iat || null,
       events: claims.events,
       claims: claims,
@@ -2672,6 +2720,7 @@ function create(opts) {
     if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res  = await hc.request(req);
+    /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     if (res.statusCode < 200 || res.statusCode >= 300) {
       throw new OAuthError("auth-oauth/register-failed-" + res.statusCode,
@@ -2680,6 +2729,7 @@ function create(opts) {
     var parsed;
     try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/bad-register-response",
         "registerClient: response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -2803,13 +2853,16 @@ function create(opts) {
         "deleteClient: " + res.statusCode);
     }
     if (res.statusCode < 200 || res.statusCode >= 300) {
+      /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
       var errText = res.body ? res.body.toString("utf8").slice(0, 500) : "";
       throw new OAuthError("auth-oauth/dcr-" + method.toLowerCase() + "-failed-" + res.statusCode,
         method.toLowerCase() + "Client: " + res.statusCode + ": " + errText);
     }
+    /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     try { return safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/dcr-bad-response",
         method.toLowerCase() + "Client: response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -2937,6 +2990,7 @@ function create(opts) {
       // reinstate buffer mode.
       req.responseMode = "always-resolve";
       var res    = await hc.request(req);
+      /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
       var text   = res.body ? res.body.toString("utf8") : "";
       var parsed;
       try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
@@ -2959,6 +3013,7 @@ function create(opts) {
       throw new OAuthError("auth-oauth/device-" + (err || "unknown"),
         "pollDeviceCode: " + (parsed && parsed.error_description ? parsed.error_description : text.slice(0, 200)));   // 200-char error-snippet cap, not bytes
     }
+    /* c8 ignore next 2 -- the || fallback is unreachable: reaching this timeout requires a truthy (small) maxWaitMs; a falsy one yields the 10-minute deadline that never expires within a test window */
     throw new OAuthError("auth-oauth/device-poll-timeout",
       "pollDeviceCode: exceeded maxWaitMs " + (popts.maxWaitMs || C.TIME.minutes(10)));
   }
@@ -3180,6 +3235,8 @@ module.exports = {
   buildClientAttestation:    buildClientAttestation,
   buildClientAttestationPop: buildClientAttestationPop,
   verifyClientAttestation:   verifyClientAttestation,
+  // PKCE (RFC 7636) generator for hand-rolled authorization-code flows.
+  generatePkce:              generatePkce,
   // Internal helpers exposed for tests
   _generatePkce:         _generatePkce,
   _generateRandomToken:  _generateRandomToken,

package/lib/cli.js

@@ -1425,15 +1425,21 @@ var MTLS_USAGE = [
   "                         'auto' loads whichever form exists.",
   "",
   "Subcommand flags:",
+  "  init:      [--algorithm ECDSA-P384-SHA384]",
   "  issue:     --subject <CN>    [--days <N>]",
   "  issue-p12: --subject <CN>    --password <pkcs12-passphrase>    [--days <N>]    [--out <path>]",
   "",
   "Cert issuance ('init', 'issue', 'issue-p12') uses the framework's",
-  "bundled pure-JS engine (lib/mtls-engine-default.js, ECDSA P-384",
-  "signatures, AES-256-CBC + HMAC-SHA-512 PBKDF2 PKCS#12 with 2,000,000",
-  "iterations). Operators with custom requirements pass a different",
-  "engine via b.mtlsCa.create({ engine: ... }) when wiring their app;",
-  "the CLI always uses the default.",
+  "bundled pure-JS engine (lib/mtls-engine-default.js) on the vendored",
+  "@blamejs/pki toolkit: post-quantum ML-DSA-87 (FIPS 204) certificate",
+  "signatures by default, which node:tls verifies in a real mutual-auth",
+  "handshake on OpenSSL 3.5. Pass 'init --algorithm ECDSA-P384-SHA384'",
+  "for a classical CA a peer predating OpenSSL 3.5 can verify (the pin",
+  "covers the CA and its leaves). PKCS#12 export keeps AES-256-CBC +",
+  "PBKDF2-HMAC-SHA-512 @ 2,000,000-iter bag protection with a",
+  "tier-dependent integrity MAC (PBMAC1/RFC 9579 for the PQC default,",
+  "RFC 7292 HMAC MacData for the classical bridge). Operators with custom",
+  "requirements pass a different engine via b.mtlsCa.create({ engine: ... }).",
 ].join("\n");
 
 async function _runMtls(args, ctx) {
@@ -1481,6 +1487,10 @@ async function _runMtls(args, ctx) {
       dataDir:         dataDir,
       vault:           booted.b.vault,
       caKeySealedMode: sealedMode,
+      // --algorithm pins the CA + its leaves; omitted -> the ML-DSA-87 default.
+      // Pass "ECDSA-P384-SHA384" for the classical bridge (a peer predating
+      // OpenSSL 3.5). undefined when the flag is absent.
+      algorithm:       args.flags.algorithm,
       // No engine passed — b.mtlsCa falls back to the bundled default
       // (lib/mtls-engine-default.js).
     });

package/lib/daemon.js

@@ -72,6 +72,13 @@ var DEFAULT_STOP_TIMEOUT_MS = C.TIME.seconds(30);
 var DEFAULT_STOP_SIGNAL     = "SIGTERM";
 var DEFAULT_POLL_MS         = 100;
 var DEFAULT_LOG_FILE_MODE   = 0o600;
+// A detached child that exits within this window of spawn is treated as a boot
+// death (spawn_failed audit); an abnormal exit after it is a normal run/crash,
+// and a clean exit or an operator stop() is never a spawn failure.
+var BOOT_DEATH_WINDOW_MS    = C.TIME.seconds(5);
+// setTimeout clamps a delay above this 32-bit ceiling to ~1ms, which would
+// silently defeat the boot-window loop-hold — so the opt is refused above it.
+var MAX_BOOT_DEATH_WINDOW_MS = 0x7FFFFFFF;   // 2,147,483,647
 // Poll cadence for the Windows cooperative-stop sentinel (a synchronous
 // existsSync on this interval; see _installStopSentinelWatcher for why it is a
 // poll and not a filesystem watch). Runs for a foreground daemon's whole
@@ -90,6 +97,71 @@ function _safeAuditEmit(action, outcome, metadata) {
 var _isLivePid  = pidProbe.isLivePid;
 var _readPidFile = pidProbe.readPidFile;
 
+// An in-flight stop() writes a `<pidFile>.stopping` marker holding the pid it is
+// stopping. The detached boot-death exit handler consults it so a stop()-induced
+// exit within the boot window is not misread as a spawn failure — a FILESYSTEM
+// marker (not an in-process flag) so it works whether stop() runs in the same
+// process that called start() OR a different one (e.g. a `daemon stop` CLI). The
+// marker carries the target pid so a stale marker from a crashed stopper can
+// only ever suppress that same pid, never a later daemon reusing the pidfile.
+function _stoppingMarkerPath(pidFile) { return pidFile + ".stopping"; }
+
+// Reap the boot-dead child's OWN stale pidfile without a check-then-unlink race.
+// A naive `if (read(pidFile) === childPid) unlink(pidFile)` can delete the WRONG
+// file: a fast operator restart that rewrites pidFile with a NEW child's pid
+// between the read and the unlink leaves the new daemon unmanageable via stop().
+//
+// A NON-DESTRUCTIVE ownership pre-check runs first: only when the sidecar still
+// records THIS child's pid do we ATOMICALLY claim it (rename it to a per-pid path)
+// so the confirming check and the removal act on the same exclusive file. A fast
+// restart's replacement pidfile (a different pid) is thus never even temporarily
+// hidden — we leave it untouched. Should a restart land in the tiny window between
+// the pre-check and the claim, the post-claim re-check catches it (the claimed
+// file's pid won't match) and restores the file. `readPid` defaults to the
+// hardened reader and is injectable for tests. Returns whether the reaped sidecar
+// was this child's.
+function _reapOwnStalePidfile(pidFile, childPid, readPid) {
+  readPid = readPid || _readPidFile;
+  // Pre-check: don't claim (and momentarily hide) a pidfile that isn't ours.
+  var preOwned = false;
+  try { preOwned = String(readPid(pidFile)) === String(childPid); } catch (_pe) { preOwned = false; }
+  if (!preOwned) return false;
+  var claim = pidFile + ".reap-" + childPid;
+  try {
+    atomicFile.renameWithRetry(pidFile, claim);   // retries a transient Windows AV/indexer lock
+  } catch (_e) {
+    return false;   // pidFile vanished between the pre-check and the claim (stop() / a restart) — nothing to reap
+  }
+  // We now exclusively hold `claim`. Verify ownership against it (not pidFile) so
+  // the check and the removal act on the same file; a restart that rewrites
+  // pidFile after our rename creates a fresh, separate pidfile we never touch.
+  var mine = false;
+  try { mine = String(readPid(claim)) === String(childPid); } catch (_e2) { mine = false; }
+  if (mine) {
+    try { nodeFs.unlinkSync(claim); } catch (_e3) { /* best-effort reap — the sidecar is already off pidFile */ }
+  } else {
+    // Not ours (a fast restart's newer pidfile, or an unreadable one) — put it
+    // back so stop() still finds the running daemon's sidecar, but ONLY if nothing
+    // newer has since taken pidFile's place. linkSync is atomic and fails with
+    // EEXIST when a still-newer daemon already wrote pidFile during our inspection,
+    // so the restore never clobbers the newest pidfile with our older claimed one
+    // (a plain rename would). A NON-EEXIST failure means hard links aren't
+    // available on this filesystem (ENOTSUP on FAT / some network mounts), where
+    // nothing newer is present — fall back to a plain rename so the pidfile isn't
+    // lost entirely (it may clobber, but losing the running daemon's pidfile is
+    // worse). Either way, drop our claim afterward.
+    try {
+      nodeFs.linkSync(claim, pidFile);
+    } catch (linkErr) {
+      if (linkErr.code !== "EEXIST") {
+        try { atomicFile.renameWithRetry(claim, pidFile); } catch (_re) { /* best-effort restore */ }
+      }
+    }
+    try { nodeFs.unlinkSync(claim); } catch (_e5) { /* consumed by the rename fallback, or already gone */ }
+  }
+  return mine;
+}
+
 function _validateStartOpts(opts) {
   validateOpts.shape(opts, {
     pidFile: { rule: "required-string", code: "daemon/bad-pid-file",
@@ -118,6 +190,15 @@ function _validateStartOpts(opts) {
           "daemon.start: opts.args requires opts.command");
       }
     },
+    bootDeathWindowMs: function (value) {
+      if (value !== undefined && (typeof value !== "number" || !isFinite(value) ||
+                                  value < 0 || value > MAX_BOOT_DEATH_WINDOW_MS)) {
+        throw new DaemonError("daemon/bad-boot-window",
+          "daemon.start: opts.bootDeathWindowMs must be a finite number of " +
+          "milliseconds in [0, " + MAX_BOOT_DEATH_WINDOW_MS + "] when present " +
+          "(a larger delay clamps setTimeout to ~1ms and defeats the boot window)");
+      }
+    },
   }, "daemon.start", DaemonError, "daemon/bad-opts");
 }
 
@@ -166,6 +247,7 @@ function _maybeReapStale(pidFile) {
 // Used both by detached-spawn (passed via stdio) and by foreground
 // redirect of the current process' stdout/stderr.
 function _openLogFd(logFile) {
+  /* c8 ignore next -- every caller gates on a truthy logFile string, so this guard never returns null */
   if (typeof logFile !== "string" || logFile.length === 0) return null;
   atomicFile.ensureDir(nodePath.dirname(logFile));
   // O_NOFOLLOW append: refuse (ELOOP) a symlink planted at the daemon log
@@ -182,6 +264,7 @@ function _openLogFd(logFile) {
 // pattern for foreground daemons that don't want to lose output when
 // detached from a terminal.
 function _redirectStdio(fd) {
+  /* c8 ignore next -- only ever called with the numeric fd from _openLogFd; the non-number guard is unreachable */
   if (typeof fd !== "number") return;
   function _writer(chunk, encOrCb, maybeCb) {
     var enc = typeof encOrCb === "string" ? encOrCb : "utf8";
@@ -247,6 +330,7 @@ function _installStopSentinelWatcher(pidFile, orchestrator) {
     timer = null;
   }
   function _maybeFire() {
+    /* c8 ignore next -- _stopPolling clears the interval on the first fire, so _maybeFire can't re-enter with fired=true */
     if (fired) return;
     // Synchronous existsSync on the main thread — deliberately not an async
     // stat, so detection never queues behind a saturated libuv threadpool.
@@ -310,6 +394,7 @@ function _installStopSentinelWatcher(pidFile, orchestrator) {
  *   command: string,    // executable for detached-fork mode
  *   args:    string[],  // argv for the detached child
  *   cwd:     string,    // cwd for the detached child
+ *   bootDeathWindowMs: number,  // detached: keep the parent loop alive this long after spawn to observe a boot death (an abnormal exit in the window is audited as a spawn failure + reaps the pidfile); default 5000, 0 opts out (fire-and-forget)
  *
  * @example
  *   var handle = b.daemon.start({
@@ -378,6 +463,12 @@ function start(opts) {
       throw new DaemonError("daemon/spawn-failed",
         "daemon.start: spawn failed: " + ((e && e.message) || String(e)));
     }
+    // Boot-death window is measured from the moment the child was spawned. An
+    // abnormal exit within it is a boot failure; a later one is a normal
+    // run/crash. Operators tune it for a slow-booting child (default 5s).
+    var spawnedAt = Date.now();
+    var bootWindowMs = (typeof opts.bootDeathWindowMs === "number")
+      ? opts.bootDeathWindowMs : BOOT_DEATH_WINDOW_MS;
     // A bad command does NOT throw synchronously from spawn — child_process
     // reports it ASYNC via a 'error' event, with child.pid left undefined. The
     // sync try/catch above only covers spawn() itself, so without this the old
@@ -385,7 +476,18 @@ function start(opts) {
     // one-shot 'error' handler that reaps the sidecar + audits the failure, then
     // refuse to proceed for a child that never got a pid.
     child.on("error", function (err) {
-      try { nodeFs.unlinkSync(pidFile); } catch (_e) { /* best-effort — may not exist */ }
+      // Reap ONLY a pidfile this child actually wrote. A numeric pid means the
+      // sync path below wrote one, and the claim-then-verify reap removes only its
+      // own sidecar (never a fast restart's). A no-pid spawn failure (child.pid
+      // undefined) throws below BEFORE any pidfile write, so this late-firing
+      // callback must not touch pidFile at all — else a caller that catches that
+      // sync throw and retries with the same pidFile would have its replacement
+      // daemon's pidfile deleted. (A numeric-but-invalid pid never reaches here:
+      // child_process yields a positive int or undefined, and either way the
+      // claim-then-verify reap only removes a sidecar recording that exact pid.)
+      if (typeof child.pid === "number") {
+        _reapOwnStalePidfile(pidFile, child.pid);
+      }
       _safeAuditEmit("daemon.spawn_failed", "failure", {
         pidFile: pidFile,
         command: opts.command,
@@ -408,9 +510,76 @@ function start(opts) {
     // Write the child's PID via atomic temp+rename so a concurrent
     // observer never sees a half-written pidFile.
     atomicFile.ensureDir(nodePath.dirname(pidFile));
+    // Clear any STALE stop marker before claiming this pidfile: a stopper that was
+    // SIGKILLed mid-stop leaves `<pidFile>.stopping` behind, and if the OS later
+    // reuses that stopped pid for THIS fresh child, the stale marker would
+    // wrongly suppress a genuine boot-death audit. A fresh start means no stop is
+    // in flight, so the marker can only be stale.
+    try { nodeFs.unlinkSync(_stoppingMarkerPath(pidFile)); } catch (_sm) { /* best-effort — usually absent */ }
     var pidStr = String(child.pid) + "\n";
     atomicFile.writeSync(pidFile, pidStr, { fileMode: 0o600 });
-    // Detach so the child survives parent exit.
+    // A detached child can spawn cleanly (valid pid above) yet DIE AT BOOT —
+    // exit before it ever serves. The synchronous success handle is already
+    // committed (detached mode returns immediately, so the sync return contract
+    // stands), so recover asynchronously: a one-shot 'exit' handler reaps the
+    // sidecar we just wrote — but ONLY when the pidFile still records THIS
+    // child's pid, so a fast operator restart that rewrote it is never
+    // clobbered — and audits the boot death so it leaves a trail instead of a
+    // silently-stranded pidfile that daemon.stop would misread as running.
+    // bootWatch (installed after this handler) holds the parent loop open through
+    // the boot window so a short-lived launcher can't exit before observing the
+    // death; the handler clears it the instant the child exits.
+    var bootWatch = null;
+    child.on("exit", function (code, signal) {
+      if (bootWatch) { clearTimeout(bootWatch); bootWatch = null; }   // death observed — release the loop
+      // Was the sidecar still OURS at exit? Atomically claim-then-verify (see
+      // _reapOwnStalePidfile) so a fast operator restart that rewrote the pidfile
+      // can't make us delete the NEW daemon's sidecar, and so the boot-death
+      // signal survives a swallowed unlink failure. A stop() or a restart that
+      // rewrote/cleared it means someone else owns it now — not a boot death.
+      var wasOurs = _reapOwnStalePidfile(pidFile, child.pid);
+      // Only a BOOT DEATH is a spawn failure: an ABNORMAL exit (non-zero code or
+      // a terminating signal) SHORTLY after spawn, while the sidecar was still
+      // ours (nobody stop()'d it). A clean exit (code 0), a later run/crash, or
+      // an operator stop() is NOT a spawn failure — auditing those as one emits a
+      // contradictory failure alongside the daemon.stopped record.
+      var abnormal   = (typeof code === "number" && code !== 0) || signal != null;
+      var withinBoot = (Date.now() - spawnedAt) <= bootWindowMs;
+      // stop() (this process OR another) sends SIGTERM but unlinks the pidfile
+      // only after observing the exit, so wasOurs is still true here. A
+      // `<pidFile>.stopping` marker holding THIS child's pid means an operator
+      // stop is in flight, so the exit is intentional — not a boot death that
+      // should emit spawn_failed right before daemon.stopped.
+      // Read the marker through the HARDENED pid-sidecar reader (1 KiB cap,
+      // refuse-symlink, positive-int parse, null on any failure) — the marker
+      // lives in the pidfile directory, so a raw readFileSync here would follow a
+      // planted symlink or buffer an unbounded file (CWE-59 / DoS), the exact
+      // threat _readPidFile hardens the pid read against. null (no/garbage marker)
+      // !== child.pid, so a missing marker correctly reads as "not being stopped".
+      var beingStopped = _readPidFile(_stoppingMarkerPath(pidFile)) === child.pid;
+      if (wasOurs && abnormal && withinBoot && !beingStopped) {
+        _safeAuditEmit("daemon.spawn_failed", "failure", {
+          pidFile:  pidFile,
+          command:  opts.command,
+          exitCode: code,
+          signal:   signal || null,
+        });
+      }
+    });
+    // Keep the parent event loop alive through the boot-death window so the exit
+    // handler above can actually observe a child that dies at boot. A short-lived
+    // launcher (e.g. `blamejs daemon start`) would otherwise reach child.unref()
+    // and exit before the child dies — stranding the pidfile for a later stop()
+    // to misread, the very failure the handler exists to prevent. The timer is
+    // ref'd (holds the loop), is cleared the instant the child exits, and
+    // otherwise fires a no-op once the window elapses (boot succeeded → release
+    // the loop, which child.unref() no longer holds). bootDeathWindowMs:0 opts
+    // out entirely: no monitor, immediate exit (historical fire-and-forget).
+    if (bootWindowMs > 0) {
+      bootWatch = setTimeout(function () { bootWatch = null; }, bootWindowMs);
+    }
+    // Detach so a HEALTHY long-running child never holds the parent open past the
+    // boot window (bootWatch is the only remaining ref, and it self-clears).
     try { child.unref(); } catch (_u) { /* best-effort */ }
     if (typeof logFd === "number") {
       // Parent doesn't need its handle to the log; child inherited it.
@@ -446,6 +615,7 @@ function start(opts) {
       logFdForeground = _openLogFd(logFile);
       _redirectStdio(logFdForeground);
     } catch (e) {
+      /* c8 ignore next -- pidLock.release() swallows its own fs errors, so this guard never catches */
       try { lock.release(); } catch (_r) { /* best-effort */ }
       throw new DaemonError("daemon/log-open-failed",
         "daemon.start: failed to open logFile '" + logFile + "': " +
@@ -469,7 +639,9 @@ function start(opts) {
       {
         name: "pidLock-release",
         run:  function () {
+          /* c8 ignore next -- close() delegates to _stopPolling, which self-catches, so stopWatcher.close never throws */
           if (stopWatcher) { try { stopWatcher.close(); } catch (_w) { /* best-effort */ } }
+          /* c8 ignore next -- pidLock.release() swallows its own fs errors, so this guard never catches */
           try { lock.release(); } catch (_e) { /* best-effort */ }
           if (logFdForeground !== null) {
             try { nodeFs.closeSync(logFdForeground); } catch (_c) { /* best-effort */ }
@@ -555,6 +727,23 @@ async function stop(opts) {
     return { stopped: false, pid: pid, reason: "stale" };
   }
 
+  // Publish a `<pidFile>.stopping` marker (holding the pid we are stopping) so the
+  // boot-death exit handler — in THIS process or the still-alive starter of a
+  // cross-process stop — treats the SIGTERM-induced exit as intentional, not a
+  // boot death. The finally removes it on every exit (return OR a kill-failed
+  // throw) so a later start() at the same path is never suppressed.
+  var stopMarker = _stoppingMarkerPath(pidFile);
+  try { atomicFile.writeSync(stopMarker, String(pid), { fileMode: 0o600 }); } catch (_w) { /* best-effort hint */ }
+  try {
+    return await _stopLivePid(pidFile, pid, signal, timeoutMs, pollMs, opts);
+  } finally {
+    try { nodeFs.unlinkSync(stopMarker); } catch (_u) { /* best-effort */ }
+  }
+}
+
+// Signal a confirmed-live pid and wait for exit, escalating SIGTERM -> SIGKILL.
+// Extracted from stop() so the .stopping marker wraps every exit via try/finally.
+async function _stopLivePid(pidFile, pid, signal, timeoutMs, pollMs, opts) {
   var t0 = Date.now();
 
   // Windows has no cooperative signal: process.kill(pid, "SIGTERM") maps to
@@ -733,4 +922,5 @@ module.exports = {
   DEFAULT_STOP_SIGNAL:  DEFAULT_STOP_SIGNAL,
   DEFAULT_STOP_TIMEOUT_MS: DEFAULT_STOP_TIMEOUT_MS,
   _resetForTest:        _resetForTest,
+  _reapOwnStalePidfile: _reapOwnStalePidfile,
 };

package/lib/guard-tenant-id.js

@@ -27,6 +27,7 @@
 var { defineClass } = require("./framework-error");
 var gateContract = require("./gate-contract");
 var codepointClass = require("./codepoint-class");
+var pick = require("./pick");
 
 var GuardTenantIdError = defineClass("GuardTenantIdError", { alwaysPermanent: true });
 
@@ -78,10 +79,20 @@ function validate(tenantId, opts) {
     throw new GuardTenantIdError("tenant-id/oversize",
       "guardTenantId.validate: tenantId exceeds maxBytes=" + profile.maxBytes);
   }
-  if (RESERVED[tenantId]) {
+  if (Object.prototype.hasOwnProperty.call(RESERVED, tenantId)) {
     throw new GuardTenantIdError("tenant-id/reserved",
       "guardTenantId.validate: tenantId '" + tenantId + "' is framework-reserved");
   }
+  // Refuse the prototype-pollution key names outright via the framework's single
+  // poisoned-key predicate (lib/pick.js). The own-property RESERVED check above
+  // (deliberately) will not match these as inherited keys, and a tenant id used to
+  // key a plain-object store must never be __proto__ / constructor / prototype (or
+  // an operator-registered dangerous name), which would pollute the prototype
+  // chain instead of isolating the tenant.
+  if (pick.isPoisonedKey(tenantId)) {
+    throw new GuardTenantIdError("tenant-id/reserved",
+      "guardTenantId.validate: tenantId '" + tenantId + "' is a prototype-pollution key name");
+  }
   if (tenantId.charAt(0) === ".") {
     throw new GuardTenantIdError("tenant-id/hidden",
       "guardTenantId.validate: tenantId cannot start with '.'");