@blamejs/core 0.7.51 → 0.7.61

package/CHANGELOG.md

@@ -8,6 +8,26 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.61** (2026-05-06) — eslint cleanup in `lib/guard-regex.js` and `lib/guard-shell.js`. The `no-useless-escape` rule (eslint v9+) flagged unnecessary backslashes inside regex character classes — `*`, `+`, `?`, `[` don't need escaping when they appear inside `[...]`. Behavior unchanged: regex semantics are identical with or without the escapes (the engine treats both forms as the literal character). The framework's CI gate runs eslint with `--max-warnings 0`; this slice unblocks the CI lint job that's been failing on tag pushes since v0.7.53. No operator-facing behavior change.
+
+- **0.7.60** (2026-05-05) — `b.crypto.encryptEnvelopeAsCertPeer` + `b.crypto.decryptEnvelopeAsCertPeer` — cert-bound envelope primitives. The default `b.crypto.encrypt` / `b.crypto.decrypt` source the recipient from a published framework keypair (operator owns both halves); the new cert-peer variants source the recipient's ECDH P-384 half from a TLS peer cert plus a peer-supplied ML-KEM-1024 pubkey. Wire format unchanged — the envelope dispatches on the same version bytes and KEM ID; only the input keys differ. Use cases: sealed-storage records with peer recipients (operator A seals to operator B's TLS cert + KEM pubkey), cross-service messages between cert-identified peers without a shared framework keypair, audit log entries tagged with peer recipients. The encrypt path extracts the cert's SPKI as P-384 ECDH pubkey and refuses with `crypto/cert-key-not-ecdh-p384` if the cert isn't `id-ecPublicKey` over `secp384r1`; the decrypt path accepts either a `KeyObject` or a PEM string for `certPrivateKey` and applies the same curve check. Math is the existing hybrid ML-KEM-1024 + P-384 ECDH + SHAKE256 + XChaCha20-Poly1305 — these are convenience wrappers, not new crypto.
+
+- **0.7.59** (2026-05-05) — `b.guardAuth` — composite auth-bundle safety primitive (KIND="auth-bundle"). Composes `guardJwt` + `guardOauth` + `b.cookies.parseSafe` + light header-smuggling detection into a single auth-flow gate. Consumes `ctx.authBundle` shape `{ jwtToken?, oauthFlow?, cookieHeader?, requestHeaders? }`. Each sub-validator runs independently; aggregated issues carry a `source` field (`"jwt"` / `"oauth"` / `"cookies"` / `"headers"` / `"auth"`) so operators see which sub-guard raised which issue. Sub-guards run at the operator's chosen `childProfile` (default tracks the auth profile). `requireAtLeastOne: true` (strict default) refuses empty bundles to defend against the operator-misuse class where the gate runs but no auth input is supplied. Profiles: `strict` (childProfile=strict, requireAtLeastOne), `balanced` (childProfile=balanced, allow empty), `permissive` (childProfile=permissive, allow empty). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Adaptive integration harness gains a KIND="auth-bundle" dispatcher reading `ctx.authBundle`. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
+
+- **0.7.58** (2026-05-05) — `b.guardPdf` — PDF identifier-safety primitive (KIND="metadata"). Validates PDF inputs without vendoring a full parser; operators bring their own PDF library (pdf-lib, pdfjs-dist, vendored mupdf) and feed structural metadata to the guard for policy enforcement. Threat catalog: magic-byte missing (`%PDF-` header check); JavaScript action (`/JS` / `/JavaScript` — RCE class in vulnerable readers, Adobe / Foxit / nitro CVEs — universally refused); LaunchAction (`/Launch` invokes external program — universally refused); OpenAction trigger (drive-by class when paired with JavaScript / Launch); embedded files (`/EmbeddedFile` — may carry executable payloads); encrypted PDF refuse (many AV / sandbox tools can't scan); polyglot signal via operator-supplied `polyglotDetected: true`; oversized bytes / page count / embedded-file count caps. **`b.guardPdf.inspectMagic(bytes)`** is the operator helper that returns `true` when bytes start with `%PDF-`. Profiles: `strict` (max 500 pages, 0 embedded files, 64 MiB), `balanced` (max 5000 pages, 10 embedded files, 128 MiB; audit non-RCE classes), `permissive` (max 50000 pages, 100 embedded files, 512 MiB; allow encrypted). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD. Group F of the original guard-family expansion plan complete.
+
+- **0.7.57** (2026-05-05) — `b.guardImage` — image-format identifier-safety primitive (KIND="metadata"). Validates image-format inputs without vendoring a full decoder; the framework's stance is operators bring their own decoder (sharp, jimp, libvips wrappers, etc.) and `guardImage` closes the magic-byte vs declared-Content-Type mismatch class plus operator-supplied metadata bounds. Magic-byte detection covers PNG / JPEG / GIF (87a + 89a) / WebP (RIFF + WEBP marker) / BMP / ICO / TIFF (II + MM) / AVIF / HEIC + SVG-routing detection. Threat catalog: magic-byte vs declared-MIME mismatch (drive-by content-type confusion class — `Content-Type: image/png` with JPEG bytes); polyglot file (multiple format magic bytes detected — PHP-in-JPEG / JS-in-PNG class); unknown / no magic-byte match (refused at strict, audited at balanced+); SVG-routing-via-image bypass (operators MUST pass SVG through `b.guardSvg` directly — strict + balanced + permissive all refuse); oversized dimensions (operator passes `width` / `height`; refused against `maxWidth` / `maxHeight`); excessive frame count for animated formats; oversized bytes. **`b.guardImage.inspectMagic(bytes)`** is the operator helper that returns the detected MIME types without running the full validate / gate flow. Profiles: `strict` (8192×8192, 60 frames, 32 MiB), `balanced` (16384×16384, 200 frames, 64 MiB), `permissive` (65536×65536, 1000 frames, 256 MiB). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Adaptive integration harness gains a KIND="metadata" dispatcher reading `ctx.metadata`. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
+
+- **0.7.56** (2026-05-05) — `b.guardTemplate` — Server-Side Template Injection (SSTI) identifier-safety primitive (KIND="identifier"). Detects template-engine syntax in user-input strings before they're rendered through any template engine; refused by default at every profile because operator-untrusted input rarely legitimately contains template syntax. Threat catalog: Jinja / Django / Twig / Liquid / Handlebars / AngularJS `{{...}}` + `{%...%}` (CVE-2024-22195 Jinja `xml_attr` filter, CVE-2024-26139 Bottle, CVE-2024-23348 Pyrogram); ERB / Tornado `<%...%>` and `<%=...%>`; Pug `#{...}` + `!{...}` interpolation; Mako / Velocity / Tornado `${...}` interpolation; Velocity directives (`#set` / `#if` / `#else` / `#elseif` / `#end` / `#foreach` / `#parse` / `#include` / `#stop`); BIDI / null / control / zero-width universal refuse. Profiles: `strict` (refuse everything), `balanced` (Jinja / ERB / Pug / Velocity directives still refused; audit `${...}` since it can also be a JS template-literal in some operator contexts), `permissive` (universal SSTI shapes still refused; audit `${...}` + Velocity directives). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD. Group E of the original guard-family expansion plan complete.
+
+- **0.7.55** (2026-05-05) — `b.guardJsonpath` — JSONPath identifier-safety primitive (KIND="identifier"). Validates user-supplied JSONPath strings (RFC 9535) before they're handed to a JSONPath evaluator. Many JSONPath libraries (notably the original Stefan Goessner implementation and several JS forks) route filter / script expressions through dynamic-code execution, turning a query path into an RCE primitive. Threat catalog: filter expression `?(...)` (dynamic-code-execution class — universally refused); script expression `(@.x)` style; JS-source hint detection (path containing tokens that only appear in code-injection attempts — dynamic-code-exec keyword, constructor invocation keyword, function-declaration keyword, arrow-function arrow, statement-separator semicolon — all built from explicit substrings to keep the source file free of the literal keywords); recursive-descent depth bombs (operator-tunable `maxRecursiveDescents`); excessive bracket nesting; oversized pattern; BIDI / null / control / zero-width universal refuse. Profiles: `strict` (refuse everything), `balanced` (RCE class refused; audit bracket nesting + recursive descent), `permissive` (RCE class still refused; allow recursive descent up to 16). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
+
+- **0.7.54** (2026-05-05) — `b.guardRegex` — regex pattern identifier-safety primitive (KIND="identifier"). Validates user-supplied regex pattern strings for catastrophic-backtracking (ReDoS) shapes BEFORE compilation. Threat catalog: nested quantifiers (canonical ReDoS class — `(a+)+`, `(a*)+`, `(.+)+` — CVE-2024-21538 cross-spawn / CVE-2022-25929 chartjs-adapter-luxon are recent prominent examples; universally refused at every profile); alternation with quantifier (`(a|b)+`); bounded-repeat upper-bound overflow (operator-tunable `maxBoundedRepeat` — strict 100 / balanced 1000 / permissive 10000); lookaround with internal quantifier; oversized pattern; BIDI / null / control / zero-width universal refuse. Profiles: `strict` (refuse everything), `balanced` (nested quants still refused; audit the rest), `permissive` (nested quants + codepoint class still refused; allow alternation-quant). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
+
+- **0.7.53** (2026-05-05) — `b.guardShell` — shell-argument identifier-safety primitive (KIND="identifier"). Validates user-input strings BEFORE they're handed to a child-process spawn. The canonical defense remains "use array args + `shell: false`", but operators still receive operator-untrusted strings that flow through path-arg or arg-list shapes — `guardShell` refuses obvious shell-injection shapes before the spawn call. Threat catalog: POSIX shell metacharacters (`;`, `&`, `|`, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`, `*`, `?`, `~`, `!`, `#`, `\`, single+double quotes), cmd.exe metacharacters (`&`, `|`, `<`, `>`, `^`, `%`, `"`, `'`, `(`, `)`, `,`, `;`, `=`), `$(...)` + `${VAR}` command + parameter substitution, backtick command substitution, `<(...)` / `>(...)` Bash process substitution, `$VAR` parameter expansion, newline / NUL injection (line-splitting class), leading-hyphen option-flag injection (operator opt-in to refuse args starting with `-` — defends against `-rf` / `--exec` shapes interpreted as option flags), BIDI / null / control / zero-width universal refuse. Profiles: `strict` (refuse everything), `balanced` (universal-refuse class only — substitutions / newline / BIDI / null still refused; metacharacters audited), `permissive` (universal-refuse class still refused; metacharacters audited; leading hyphen allowed). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
+
+- **0.7.52** (2026-05-05) — `b.guardGraphql` — GraphQL request-shape safety primitive (KIND="graphql-request"). Validates user-supplied GraphQL request bundles against the canonical query-shape DoS catalog before the framework hands the query to a schema-aware executor. Threat catalog: query depth bombs (N² query-shape DoS — caps at strict 8 / balanced 12 / permissive 24); alias-bomb breadth DoS (caps at 8/16/32 aliases per selection-set); introspection in production (`__schema` / `__type` schema-leak); batch query DoS (caps at 1/10/50 entries per array); persisted-query enforcement (refuse free-form queries when `persistedQueryPolicy: "require"`); operation-name allowlist drift; variable type confusion (operator declares `variableShapes: { id: "string", limit: "number" }`); oversized query / variable / total bytes; BIDI / null / control / zero-width universal refuse on the query string. Brace-counting query-shape walker handles strings + comments correctly without requiring a full GraphQL parser. Profiles: `strict` (refuse introspection + batch + shape-DoS), `balanced` (audit most, allow batch up to 10), `permissive` (universal-refuse class still refused; rest allow / audit). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Adaptive integration harness gains a KIND="graphql-request" dispatcher reading `ctx.graphqlRequest`. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
+
 - **0.7.51** (2026-05-05) — `b.guardOauth` — OAuth flow-shape safety primitive (KIND="oauth-flow"). Validates user-supplied OAuth 2.x / OIDC authorization-code-flow parameter bundles before the framework's `b.auth.oauth` client exchanges them. Threat catalog: PKCE missing or non-S256 (RFC 7636 / OAuth 2.1 mandate; `plain` is the downgrade-attack class); state missing (RFC 6749 §10.12 CSRF); redirect_uri not in operator allowlist (exact-match per OAuth 2.1 — no prefix / wildcard / scheme drift); response_type allowlist drift (refuse implicit `token` deprecated in OAuth 2.1, require operator-allowed types); scope-token shape per RFC 6749 §3.3 (refuse non-printable / control / whitespace-other-than-space); issuer missing on callback (RFC 9207 IdP-mix-up defense — set `flow._isCallback = true` to enforce); authorization-code reuse via operator-supplied `seenCodeStore.hasSeen(code)` (RFC 6749 §10.5 replay class); excessive parameter / total bytes; BIDI / null / control / zero-width universal refuse. Profiles: `strict` (PKCE S256, state required, redirect_uri exact-match, RFC 9207 iss required), `balanced` (PKCE any method, state + redirect_uri allowlist required, iss audited), `permissive` (universal-refuse class still refused; rest audit). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Adaptive integration harness gains a KIND="oauth-flow" dispatcher reading `ctx.oauthFlow`. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.
 
 - **0.7.50** (2026-05-05) — `b.guardJwt` — JWT identifier-safety primitive (KIND="identifier"). Validates user-supplied JWT compact-serialization strings against the canonical CVE-class refuse list before hand-off to a verifier — `b.guardJwt` never replaces signature verification, it reduces the input space the verifier sees. Threat catalog: shape malformation; `alg=none` (CVE-2015-9235 jsonwebtoken / CVE-2018-0114 java-jwt) — universally refused at every profile; alg-allowlist drift (PQC-first default: ML-DSA / SLH-DSA / EdDSA / ES* / RS* / PS*); `kid` path-traversal (operator `keyResolver` path-injection class — e.g. `kid: "../etc/passwd"` would escape a key-directory `fs.readFile(keyDir + kid)` resolver); `typ` confusion (non-JWT-shape media-type tokens coerced into the slot); oversized header / payload / signature segment defense (decompression bomb + parser DoS); `exp` / `nbf` / `iat` sanity (past `exp` = replay; far-future `nbf` / `iat` = clock-skew / attacker-shaped); required-claims enforcement (default `iss` / `exp` / `iat` at strict); unknown `crit` field refuse (RFC 7515 §4.1.11 — operator MUST refuse crit values it doesn't understand); BIDI / null / control / zero-width universal refuse. **`b.guardJwt.kidSafe(kid)`** is the documented contract for operator `keyResolver` implementations: throws on traversal indicators or control bytes, returns the validated kid on success. Profiles: `strict` (refuse everything), `balanced` (refuse alg=none / kid-traversal / unknown-crit; audit the rest), `permissive` (universal-refuse class still refused). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD.

package/index.js

@@ -117,6 +117,14 @@ var guardTime = require("./lib/guard-time");
 var guardMime = require("./lib/guard-mime");
 var guardJwt = require("./lib/guard-jwt");
 var guardOauth = require("./lib/guard-oauth");
+var guardGraphql = require("./lib/guard-graphql");
+var guardShell = require("./lib/guard-shell");
+var guardRegex = require("./lib/guard-regex");
+var guardJsonpath = require("./lib/guard-jsonpath");
+var guardTemplate = require("./lib/guard-template");
+var guardImage = require("./lib/guard-image");
+var guardPdf = require("./lib/guard-pdf");
+var guardAuth = require("./lib/guard-auth");
 var guardAll = require("./lib/guard-all");
 var ssrfGuard = require("./lib/ssrf-guard");
 var authHeader = require("./lib/auth-header");
@@ -265,6 +273,14 @@ module.exports = {
   guardMime:        guardMime,
   guardJwt:         guardJwt,
   guardOauth:       guardOauth,
+  guardGraphql:     guardGraphql,
+  guardShell:       guardShell,
+  guardRegex:       guardRegex,
+  guardJsonpath:    guardJsonpath,
+  guardTemplate:    guardTemplate,
+  guardImage:       guardImage,
+  guardPdf:         guardPdf,
+  guardAuth:        guardAuth,
   guardAll:         guardAll,
   ssrfGuard:        ssrfGuard,
   authHeader:       authHeader,

package/lib/crypto.js

@@ -321,6 +321,129 @@ function encryptMlkem768X25519(plaintext, recipient) {
   ]).toString("base64");
 }
 
+// ---- Cert-peer envelope primitives ----
+//
+// The framework's default `encrypt` / `decrypt` source the recipient
+// from a published framework keypair (operator owns both halves). The
+// cert-peer variants source the recipient from a TLS peer cert (peer
+// owns the ECDH P-384 half) plus a peer-supplied ML-KEM-1024 pubkey.
+// Wire format is unchanged — the envelope dispatches on the same
+// version bytes and KEM ID. Only the input keys differ.
+//
+// Use cases beyond the b.middleware.apiEncrypt strategy:
+//   - Sealed-storage records with peer recipients (operator A seals
+//     to operator B's TLS cert + KEM pubkey).
+//   - Cross-service messages between cert-identified peers without
+//     a shared framework keypair.
+//   - Audit log entries tagged with peer recipients.
+
+function _extractEcdhP384FromCert(certDer) {
+  // The cert's SubjectPublicKeyInfo carries the ECDH P-384 pubkey when
+  // the cert is issued for that curve. node:crypto's X509Certificate
+  // exposes `publicKey` as a KeyObject; we only export the SPKI as PEM
+  // so the existing `encrypt` path consumes the same shape it accepts
+  // for `ecPublicKey`.
+  var cert = new nodeCrypto.X509Certificate(certDer);
+  var keyObj = cert.publicKey;
+  var details = keyObj.asymmetricKeyDetails || {};
+  if (keyObj.asymmetricKeyType !== "ec" ||
+      details.namedCurve !== "secp384r1") {
+    var err = new Error(
+      "cert public key is not ECDH P-384 (got asymmetricKeyType=" +
+      keyObj.asymmetricKeyType + ", namedCurve=" + details.namedCurve + ")");
+    err.code = "crypto/cert-key-not-ecdh-p384";
+    throw err;
+  }
+  return keyObj.export({ type: "spki", format: "pem" });
+}
+
+// encryptEnvelopeAsCertPeer — produce a cert-bound envelope for the
+// peer identified by their TLS cert + ML-KEM-1024 pubkey.
+//
+//   var envelope = b.crypto.encryptEnvelopeAsCertPeer(plaintext, {
+//     peerCertDer:    Buffer | Uint8Array,    // peer's TLS cert (DER)
+//     peerKemPubkey:  string,                  // peer's ML-KEM-1024 pubkey PEM
+//   });
+function encryptEnvelopeAsCertPeer(plaintext, opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new Error("encryptEnvelopeAsCertPeer: opts object required");
+  }
+  if (!opts.peerCertDer) {
+    var e1 = new Error("peerCertDer required (peer's TLS cert as DER bytes)");
+    e1.code = "crypto/peer-cert-missing";
+    throw e1;
+  }
+  if (typeof opts.peerKemPubkey !== "string") {                                  // allow:inline-require-non-empty-string-validation — crypto module avoids validateOpts dependency to stay minimal
+    var e2 = new Error("peerKemPubkey required (peer's ML-KEM-1024 pubkey PEM)");
+    e2.code = "crypto/peer-kem-pubkey-missing";
+    throw e2;
+  }
+  if (opts.peerKemPubkey.length === 0) {
+    var e2b = new Error("peerKemPubkey is empty");
+    e2b.code = "crypto/peer-kem-pubkey-missing";
+    throw e2b;
+  }
+  var ecPubPem = _extractEcdhP384FromCert(opts.peerCertDer);
+  return encrypt(plaintext, {
+    publicKey:   opts.peerKemPubkey,
+    ecPublicKey: ecPubPem,
+  });
+}
+
+// decryptEnvelopeAsCertPeer — decrypt an envelope sealed to this
+// operator's TLS cert ECDH-pubkey + ML-KEM-1024 pubkey.
+//
+//   var plaintext = b.crypto.decryptEnvelopeAsCertPeer(envelope, {
+//     certPrivateKey: KeyObject | string,    // this operator's cert P-384 priv
+//     kemSecret:      string,                 // this operator's ML-KEM-1024 priv PEM
+//   });
+function decryptEnvelopeAsCertPeer(envelope, opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new Error("decryptEnvelopeAsCertPeer: opts object required");
+  }
+  if (!opts.certPrivateKey) {
+    var e1 = new Error("certPrivateKey required");
+    e1.code = "crypto/cert-private-key-missing";
+    throw e1;
+  }
+  if (typeof opts.kemSecret !== "string") {                                      // allow:inline-require-non-empty-string-validation — crypto module avoids validateOpts dependency to stay minimal
+    var e2 = new Error("kemSecret required (operator's ML-KEM-1024 priv PEM)");
+    e2.code = "crypto/kem-secret-missing";
+    throw e2;
+  }
+  if (opts.kemSecret.length === 0) {
+    var e2b = new Error("kemSecret is empty");
+    e2b.code = "crypto/kem-secret-missing";
+    throw e2b;
+  }
+  // Normalize certPrivateKey to PEM string (existing decrypt accepts
+  // PEM string).
+  var ecPrivPem;
+  if (typeof opts.certPrivateKey === "string") {
+    ecPrivPem = opts.certPrivateKey;
+  } else if (typeof opts.certPrivateKey.export === "function") {
+    var details = opts.certPrivateKey.asymmetricKeyDetails || {};
+    if (opts.certPrivateKey.asymmetricKeyType !== "ec" ||
+        details.namedCurve !== "secp384r1") {
+      var e3 = new Error(
+        "certPrivateKey is not ECDH P-384 (got asymmetricKeyType=" +
+        opts.certPrivateKey.asymmetricKeyType + ", namedCurve=" +
+        details.namedCurve + ")");
+      e3.code = "crypto/cert-key-not-ecdh-p384";
+      throw e3;
+    }
+    ecPrivPem = opts.certPrivateKey.export({ type: "pkcs8", format: "pem" });
+  } else {
+    var e4 = new Error("certPrivateKey must be a KeyObject or PEM string");
+    e4.code = "crypto/cert-private-key-bad-shape";
+    throw e4;
+  }
+  return decrypt(envelope, {
+    privateKey:   opts.kemSecret,
+    ecPrivateKey: ecPrivPem,
+  });
+}
+
 // Operator-audit accessor — exposes every supported KEM hybrid for
 // compliance audit visibility ("which envelopes does this deploy
 // accept on decrypt?").
@@ -351,6 +474,8 @@ module.exports = {
   encrypt:                     encrypt,
   decrypt:                     decrypt,
   encryptMlkem768X25519:       encryptMlkem768X25519,
+  encryptEnvelopeAsCertPeer:   encryptEnvelopeAsCertPeer,
+  decryptEnvelopeAsCertPeer:   decryptEnvelopeAsCertPeer,
   SUPPORTED_KEM_ALGORITHMS:    SUPPORTED_KEM_ALGORITHMS,
   // Symmetric buffer encrypt/decrypt
   encryptPacked:               encryptPacked,

package/lib/framework-error.js

@@ -306,6 +306,60 @@ var GuardJwtError         = defineClass("GuardJwtError",         { alwaysPermane
 // BIDI / null / control / zero-width universal refuse.
 // alwaysPermanent.
 var GuardOauthError       = defineClass("GuardOauthError",       { alwaysPermanent: true });
+// GuardGraphqlError covers GraphQL request-shape violations: query
+// depth bombs (N² query-shape DoS), alias-bomb breadth DoS,
+// introspection in production, batch-query DoS, persisted-query
+// enforcement, operation-name allowlist drift, variable type
+// confusion, oversized query / variable / total bytes, BIDI / null /
+// control / zero-width universal refuse on the query string.
+// alwaysPermanent.
+var GuardGraphqlError     = defineClass("GuardGraphqlError",     { alwaysPermanent: true });
+// GuardShellError covers shell-arg identifier violations: POSIX +
+// cmd.exe metacharacters, $(...) / ${...} command + parameter
+// substitution, backtick substitution, process substitution
+// (`<(...)` / `>(...)`), `$VAR` parameter expansion, newline
+// injection, leading-hyphen option-flag injection (`-rf` / `--exec`
+// class), BIDI / null / control / zero-width universal refuse.
+// alwaysPermanent.
+var GuardShellError       = defineClass("GuardShellError",       { alwaysPermanent: true });
+// GuardRegexError covers regex-pattern identifier violations: nested
+// quantifier ReDoS class (CVE-2024-21538 / CVE-2022-25929), alternation
+// with quantifier, bounded-repeat upper-bound overflow, lookaround
+// with internal quantifier, oversized pattern, BIDI / null / control /
+// zero-width universal refuse. alwaysPermanent.
+var GuardRegexError       = defineClass("GuardRegexError",       { alwaysPermanent: true });
+// GuardJsonpathError covers JSONPath identifier violations: filter
+// expression (`?(...)` — RCE class in eval-based implementations),
+// script expression, JS-source hints (`eval` / `new` / `function` /
+// `=>` / `;`), excessive bracket nesting, recursive-descent depth
+// bombs, oversized pattern, BIDI / null / control / zero-width
+// universal refuse. alwaysPermanent.
+var GuardJsonpathError    = defineClass("GuardJsonpathError",    { alwaysPermanent: true });
+// GuardTemplateError covers Server-Side Template Injection (SSTI)
+// identifier violations: Jinja / Django / Twig / Liquid / Handlebars /
+// AngularJS `{{...}}` + `{%...%}` shapes (CVE-2024-22195 / 26139 /
+// 23348 class), ERB / Tornado `<%...%>`, Pug `#{...}` / `!{...}`
+// interpolation, Mako / Velocity / Tornado `${...}`, Velocity
+// directives (#set / #if / #foreach), BIDI / null / control / zero-
+// width universal refuse. alwaysPermanent.
+var GuardTemplateError    = defineClass("GuardTemplateError",    { alwaysPermanent: true });
+// GuardImageError covers image-metadata violations: magic-byte vs
+// declared-MIME mismatch (drive-by content-type confusion class),
+// polyglot (multiple format magic bytes — PHP-in-JPEG / JS-in-PNG
+// class), unknown magic-byte, SVG-routing-via-image bypass, oversized
+// dimensions / frame count, oversized total bytes. alwaysPermanent.
+var GuardImageError       = defineClass("GuardImageError",       { alwaysPermanent: true });
+// GuardPdfError covers PDF-metadata violations: magic-byte missing,
+// JavaScript action (`/JS` / `/JavaScript` — RCE class), Launch
+// action, OpenAction trigger, embedded-file presence + count cap,
+// encrypted PDF refuse, polyglot signal, oversized bytes / page
+// count. alwaysPermanent.
+var GuardPdfError         = defineClass("GuardPdfError",         { alwaysPermanent: true });
+// GuardAuthError covers composite auth-bundle violations: aggregates
+// guardJwt + guardOauth + b.cookies.parseSafe + light header-smuggling
+// detection into a single gate with `source` tagging on each issue.
+// alwaysPermanent.
+var GuardAuthError        = defineClass("GuardAuthError",        { alwaysPermanent: true });
 // DoraError covers DORA Article 17 incident-reporting workflow errors
 // (classification refusal, report-shape validation, ESA-template
 // generation, audit-chain integration). Permanent — these are
@@ -372,6 +426,14 @@ module.exports = {
   GuardMimeError:         GuardMimeError,
   GuardJwtError:          GuardJwtError,
   GuardOauthError:        GuardOauthError,
+  GuardGraphqlError:      GuardGraphqlError,
+  GuardShellError:        GuardShellError,
+  GuardRegexError:        GuardRegexError,
+  GuardJsonpathError:     GuardJsonpathError,
+  GuardTemplateError:     GuardTemplateError,
+  GuardImageError:        GuardImageError,
+  GuardPdfError:          GuardPdfError,
+  GuardAuthError:         GuardAuthError,
   DoraError:              DoraError,
   ComplianceError:        ComplianceError,
   SmtpPolicyError:        SmtpPolicyError,

package/lib/guard-all.js

@@ -96,6 +96,14 @@ var STANDALONE_GUARDS = [
   require("./guard-mime"),
   require("./guard-jwt"),
   require("./guard-oauth"),
+  require("./guard-graphql"),
+  require("./guard-shell"),
+  require("./guard-regex"),
+  require("./guard-jsonpath"),
+  require("./guard-template"),
+  require("./guard-image"),
+  require("./guard-pdf"),
+  require("./guard-auth"),
 ];
 
 // Framework-wide profile + posture vocabulary that every guard MUST

package/lib/guard-auth.js

@@ -0,0 +1,278 @@
+"use strict";
+/**
+ * guard-auth — Composite auth-bundle safety primitive (b.guardAuth).
+ *
+ * Composes guardJwt + guardOauth + the cookie/header middleware
+ * validators into a single auth-flow check. KIND="auth-bundle" —
+ * consumes `ctx.authBundle` shape:
+ *   {
+ *     jwtToken?:           string,           // routed to guardJwt
+ *     oauthFlow?:          object,           // routed to guardOauth
+ *     cookieHeader?:       string,           // routed to b.cookies.parseSafe
+ *     requestHeaders?:     object,           // routed through threat-detection
+ *   }
+ *
+ * Each sub-validator runs independently; aggregated issues are
+ * returned with a `source` field tagging which sub-guard raised them.
+ * Operators get one gate to drop into a request lifecycle that covers
+ * the full canonical-auth threat surface.
+ *
+ *   var rv = b.guardAuth.validate({
+ *     jwtToken:     bearerToken,
+ *     oauthFlow:    req.query,
+ *     cookieHeader: req.headers.cookie,
+ *     requestHeaders: req.headers,
+ *   }, { profile: "strict" });
+ *
+ *   var g = b.guardAuth.gate({ profile: "strict" });
+ */
+
+var lazyRequire = require("./lazy-require");
+var gateContract = require("./gate-contract");
+var C = require("./constants");
+var numericBounds = require("./numeric-bounds");
+var guardJwt = require("./guard-jwt");
+var guardOauth = require("./guard-oauth");
+var cookies = require("./cookies");
+var { GuardAuthError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardAuthError.factory;
+
+// ---- Profile presets ----
+
+var PROFILES = Object.freeze({
+  "strict": {
+    bidiPolicy:        "reject",
+    controlPolicy:     "reject",
+    nullBytePolicy:    "reject",
+    zeroWidthPolicy:   "reject",
+    childProfile:      "strict",
+    requireAtLeastOne: true,
+    maxBytes:          C.BYTES.kib(64),
+    maxRuntimeMs:      C.TIME.seconds(2),
+  },
+  "balanced": {
+    bidiPolicy:        "reject",
+    controlPolicy:     "reject",
+    nullBytePolicy:    "reject",
+    zeroWidthPolicy:   "reject",
+    childProfile:      "balanced",
+    requireAtLeastOne: false,
+    maxBytes:          C.BYTES.kib(128),
+    maxRuntimeMs:      C.TIME.seconds(2),
+  },
+  "permissive": {
+    bidiPolicy:        "reject",                                                 // BIDI refused at every profile
+    controlPolicy:     "reject",                                                  // controls refused at every profile
+    nullBytePolicy:    "reject",                                                  // null refused at every profile
+    zeroWidthPolicy:   "reject",                                                  // zero-width refused at every profile
+    childProfile:      "permissive",
+    requireAtLeastOne: false,
+    maxBytes:          C.BYTES.kib(512),
+    maxRuntimeMs:      C.TIME.seconds(2),
+  },
+});
+
+var DEFAULTS = Object.freeze(Object.assign({}, PROFILES["strict"], {
+  mode: "enforce",
+}));
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "hipaa":   Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  }),
+  "pci-dss": Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  }),
+  "gdpr":    Object.assign({}, PROFILES["balanced"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+  "soc2":    Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(1024),
+  }),
+});
+
+function _resolveOpts(opts) {
+  return gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardAuthError,
+    errCodePrefix:      "auth",
+  });
+}
+
+function _detectIssues(bundle, opts) {
+  var issues = [];
+  if (!bundle || typeof bundle !== "object") {
+    return [{ kind: "bad-input", severity: "high",
+              ruleId: "auth.bad-input", source: "auth",
+              snippet: "auth bundle is not an object" }];
+  }
+
+  var sawAny = false;
+
+  // JWT routing.
+  if (typeof bundle.jwtToken === "string" && bundle.jwtToken.length > 0) {
+    sawAny = true;
+    var jwtRv = guardJwt.validate(bundle.jwtToken,
+                                  { profile: opts.childProfile });
+    for (var ji = 0; ji < jwtRv.issues.length; ji += 1) {
+      issues.push(Object.assign({}, jwtRv.issues[ji], { source: "jwt" }));
+    }
+  }
+
+  // OAuth routing.
+  if (bundle.oauthFlow && typeof bundle.oauthFlow === "object") {
+    sawAny = true;
+    var oauthRv = guardOauth.validate(bundle.oauthFlow,
+      Object.assign({ profile: opts.childProfile },
+        opts.allowedRedirectUris ?
+          { allowedRedirectUris: opts.allowedRedirectUris } : {}));
+    for (var oi = 0; oi < oauthRv.issues.length; oi += 1) {
+      issues.push(Object.assign({}, oauthRv.issues[oi], { source: "oauth" }));
+    }
+  }
+
+  // Cookie-header threat detection.
+  if (typeof bundle.cookieHeader === "string" && bundle.cookieHeader.length > 0) {
+    sawAny = true;
+    var ckRv = cookies.parseSafe(bundle.cookieHeader, {});
+    for (var ci = 0; ci < ckRv.issues.length; ci += 1) {
+      var iss = ckRv.issues[ci];
+      issues.push({
+        kind:     "cookie-" + iss.kind,
+        severity: iss.severity,
+        source:   "cookies",
+        ruleId:   "auth.cookie-" + iss.kind,
+        snippet:  iss.snippet,
+      });
+    }
+  }
+
+  // Request-header threat detection — light shape (CRLF / token-grammar
+  // would otherwise be done by b.middleware.headers; here we sample
+  // for the high-severity classes only).
+  if (bundle.requestHeaders && typeof bundle.requestHeaders === "object") {
+    sawAny = true;
+    var rh = bundle.requestHeaders;
+    if (rh["content-length"] !== undefined &&
+        rh["transfer-encoding"] !== undefined) {
+      issues.push({
+        kind: "header-smuggling-cl-te", severity: "high",
+        source: "headers", ruleId: "auth.header-smuggling-cl-te",
+        snippet: "request carries both Content-Length and Transfer-" +
+                 "Encoding (RFC 9112 §6.1 — CL.TE / TE.CL smuggling " +
+                 "vector)",
+      });
+    }
+  }
+
+  if (opts.requireAtLeastOne && !sawAny) {
+    issues.push({
+      kind: "no-auth-input", severity: "high",
+      source: "auth", ruleId: "auth.no-auth-input",
+      snippet: "auth bundle has no jwtToken / oauthFlow / cookieHeader / " +
+               "requestHeaders — strict requires at least one input",
+    });
+  }
+
+  return issues;
+}
+
+function validate(input, opts) {
+  opts = _resolveOpts(opts);
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxBytes"],
+    "guardAuth.validate", GuardAuthError, "auth.bad-opt");
+  return gateContract.aggregateIssues(_detectIssues(input, opts));
+}
+
+function sanitize(input, opts) {
+  opts = _resolveOpts(opts);
+  if (!input || typeof input !== "object") {
+    throw _err("auth.bad-input", "sanitize requires bundle object");
+  }
+  var issues = _detectIssues(input, opts);
+  for (var i = 0; i < issues.length; i += 1) {
+    if (issues[i].severity === "critical" || issues[i].severity === "high") {
+      throw _err(issues[i].ruleId || "auth.refused",
+        "guardAuth.sanitize [" + issues[i].source + "]: " +
+        issues[i].snippet);
+    }
+  }
+  return input;
+}
+
+function gate(opts) {
+  opts = _resolveOpts(opts);
+  return gateContract.buildGuardGate(
+    opts.name || "guardAuth:" + (opts.profile || "default"),
+    opts,
+    async function (ctx) {
+      var bundle = ctx && (ctx.authBundle || ctx.auth);
+      if (!bundle) return { ok: true, action: "serve" };
+      var rv = validate(bundle, opts);
+      if (rv.issues.length === 0) return { ok: true, action: "serve" };
+      var hasCritical = rv.issues.some(function (i) {
+        return i.severity === "critical";
+      });
+      var hasHigh = rv.issues.some(function (i) {
+        return i.severity === "high";
+      });
+      if (!hasCritical && !hasHigh) {
+        return { ok: true, action: "audit-only", issues: rv.issues };
+      }
+      return { ok: false, action: "refuse", issues: rv.issues };
+    });
+}
+
+var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+
+function compliancePosture(name) {
+  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
+    _err, "auth");
+}
+
+var _authRulePacks = gateContract.makeRulePackLoader(GuardAuthError, "auth");
+var loadRulePack = _authRulePacks.load;
+
+module.exports = {
+  // ---- guard-* family registry exports ----
+  NAME:                "auth",
+  KIND:                "auth-bundle",
+  INTEGRATION_FIXTURES: Object.freeze({
+    kind:              "auth-bundle",
+    benignBytes: Buffer.from(JSON.stringify({
+      jwtToken: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9." +
+                "eyJpc3MiOiJleGFtcGxlIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE3MDAwMDAwMDB9.sig",
+      cookieHeader: "sid=abc123; theme=dark",
+    }), "utf8"),
+    hostileBytes: Buffer.from(JSON.stringify({
+      jwtToken: "eyJhbGciOiJub25lIn0.eyJzdWIiOiJ4In0.",
+    }), "utf8"),
+    benignAuthBundle: {
+      jwtToken: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9." +
+                "eyJpc3MiOiJleGFtcGxlIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE3MDAwMDAwMDB9.sig",
+      cookieHeader: "sid=abc123; theme=dark",
+    },
+    // Hostile: alg=none JWT — universal refuse routed through guardJwt.
+    hostileAuthBundle: {
+      jwtToken: "eyJhbGciOiJub25lIn0.eyJzdWIiOiJ4In0.",
+    },
+  }),
+  // ---- primitive surface ----
+  validate:            validate,
+  sanitize:            sanitize,
+  gate:                gate,
+  buildProfile:        buildProfile,
+  compliancePosture:   compliancePosture,
+  loadRulePack:        loadRulePack,
+  PROFILES:            PROFILES,
+  DEFAULTS:            DEFAULTS,
+  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
+  GuardAuthError:      GuardAuthError,
+};