@blamejs/core 0.8.42 → 0.8.49

package/lib/graphql-federation.js

@@ -1,14 +1,24 @@
 "use strict";
 /**
- * GraphQL Federation _service.sdl trust-boundary guard.
+ * @module b.graphqlFederation
+ * @nav    AI
+ * @title  GraphQL Federation
  *
- * Apollo Federation subgraphs expose the schema via _service.sdl
- * which is independent of the introspection toggle — operators who
- * disable introspection in production still leak the full SDL.
+ * @intro
+ *   GraphQL federation gateway with SDL trust boundary, sub-graph
+ *   health, subgraph SDL signing, query plan caps.
  *
- * Public API:
- *   graphqlFederation.guardSdl(opts) -> middleware
- *   graphqlFederation.queryProbesSdl(query) -> bool
+ *   Apollo Federation subgraphs expose the schema via the
+ *   `_service { sdl }` query and `_entities` resolver — independent of
+ *   the introspection toggle. Operators who disable introspection in
+ *   production still leak the full SDL through these federation
+ *   probes. The guard refuses such queries unless they carry a
+ *   shared-secret router token (timing-safe-compared, 32-char
+ *   minimum), with optional nonce-store replay protection so a
+ *   captured router token can't be replayed across requests.
+ *
+ * @card
+ *   GraphQL federation gateway with SDL trust boundary, sub-graph health, subgraph SDL signing, query plan caps.
  */
 
 var crypto = require("crypto");
@@ -27,6 +37,26 @@ var NONCE_MAX_LEN = 256;
 var NONCE_PREVIEW_LEN = 8;                                                                  // allow:raw-byte-literal — log-preview slice length, not bytes
 var SDL_PROBE_RE = /(^|[\s,{])_service\b|_entities\b/;
 
+/**
+ * @primitive b.graphqlFederation.queryProbesSdl
+ * @signature b.graphqlFederation.queryProbesSdl(query)
+ * @since     0.7.68
+ * @related   b.graphqlFederation.guardSdl
+ *
+ * Cheap textual probe — does the GraphQL query reference `_service`
+ * or `_entities`? Returns `true` for anything that matches the
+ * federation-SDL detector after a 64 KiB length bound, `false`
+ * otherwise. Used by `guardSdl` to skip the auth gate for non-
+ * federation queries; operator-callable so a custom middleware can
+ * apply the same gate to a non-HTTP transport (queue worker, RPC).
+ *
+ * @example
+ *   b.graphqlFederation.queryProbesSdl("query { _service { sdl } }");
+ *   // → true
+ *
+ *   b.graphqlFederation.queryProbesSdl("query { user(id: 1) { name } }");
+ *   // → false
+ */
 function queryProbesSdl(query) {
   if (typeof query !== "string") return false;
   if (query.length > SDL_PROBE_MAX) return false;                                        // length-bound before regex test
@@ -69,6 +99,37 @@ function _readBody(req, errorClass) {
   });
 }
 
+/**
+ * @primitive b.graphqlFederation.guardSdl
+ * @signature b.graphqlFederation.guardSdl(opts)
+ * @since     0.7.68
+ * @related   b.graphqlFederation.queryProbesSdl
+ *
+ * Build the federation-SDL trust-boundary middleware. Reads the
+ * GraphQL query from the JSON body (capped at 1 MiB), passes
+ * non-federation queries straight through, and refuses
+ * `_service { sdl }` / `_entities` queries with HTTP 401 unless the
+ * request carries a `Bearer <routerToken>` (timing-safe compare,
+ * 32-char minimum) — or `publicSchemaOk:true` is explicitly set.
+ * Optional `nonceStore` keyed off `x-apollographql-router-nonce`
+ * blocks replay of a captured token across requests; default TTL is
+ * 5 minutes. Returns a `(req, res, next)` middleware function.
+ *
+ * @opts
+ *   publicSchemaOk:   boolean,                                       // default false — explicit override to publish the SDL
+ *   routerToken:      string,                                        // required unless publicSchemaOk; 32+ chars
+ *   nonceStore:       { has(nonce): bool, remember(nonce, ttlMs) },  // optional — replay protection
+ *   nonceTtlMs:       number,                                        // default 5 minutes
+ *   errorClass:       Function,                                      // default GraphqlFederationError
+ *   audit:            boolean,                                       // default true
+ *
+ * @example
+ *   var guard = b.graphqlFederation.guardSdl({
+ *     routerToken: "router-shared-secret-thirty-two-chars",
+ *   });
+ *   typeof guard;
+ *   // → "function"
+ */
 function guardSdl(opts) {
   opts = opts || {};
   var errorClass = opts.errorClass || GraphqlFederationError;

package/lib/guard-all.js

@@ -1,61 +1,40 @@
 "use strict";
 /**
- * guard-all — registry + aggregator for the guard-* content-safety
- * family.
+ * @module b.guardAll
+ * @featured true
+ * @nav    Guards
+ * @title  Guard All
  *
- * The framework thesis applied to content safety: every shipped guard
- * is ON by default; operators opt OUT explicitly with an audited reason
- * per guard. New guards added in future slices auto-register and
- * operators get the new coverage without re-wiring.
+ * @intro
+ *   Aggregate gate that dispatches to every registered b.guard* member
+ *   by KIND. Content guards (csv / html / svg / archive / json / yaml /
+ *   xml / markdown / email) route by MIME type or file extension;
+ *   standalone guards (filename / domain / uuid / cidr / time / mime /
+ *   jwt / oauth / graphql / shell / regex / jsonpath / template /
+ *   image / pdf / auth) operate on non-content axes and surface via
+ *   `allGuards()` for the adaptive integration harness.
  *
- *   var b = require("@blamejs/core");
- *
- *   // Every shipped guard, every threat, strict profile, one line.
- *   var safety = b.guardAll.gate({ profile: "strict", audit: b.audit });
- *
- *   // Opt-out is explicit, named, and audited.
- *   var safety = b.guardAll.gate({
- *     profile: "strict",
- *     exceptFor: {
- *       html: { reason: "every HTML response is server-rendered + CSP-locked" },
- *       pdf:  { reason: "no PDF uploads in this app" },
- *     },
- *     override: {
- *       csv: { profile: "email-attachment" },
- *     },
- *     audit:         b.audit,
- *     observability: b.observability,
- *   });
- *
- *   // Drop straight into the existing composition points.
- *   b.staticServe.create({
- *     contentSafety: b.guardAll.byExtension({ profile: "strict" }),
- *   });
- *   b.fileUpload.create({
- *     contentSafety: b.guardAll.gate({ profile: "strict" }),
- *   });
+ *   The framework thesis applied to content safety: every shipped
+ *   guard is ON by default; operators opt OUT explicitly with an
+ *   audited `reason` per guard. New guards added in future slices
+ *   auto-register through GUARDS / STANDALONE_GUARDS and operators
+ *   inherit the new coverage without re-wiring.
  *
- * Registry contract — every primitive registered into guard-all MUST
- * export:
- *   - NAME              — short string identifier ("csv", "html", ...)
- *   - MIME_TYPES        — array of canonical mime types it owns
- *   - EXTENSIONS        — array of file extensions it owns (.csv, ...)
- *   - PROFILES          — object map; must include the SHARED_PROFILES
- *                         vocabulary (strict / balanced / permissive)
- *   - COMPLIANCE_POSTURES — object map; must include the SHARED_POSTURES
- *                         vocabulary (hipaa / pci-dss / gdpr / soc2)
- *   - gate(opts)        — returns a b.gateContract-shaped gate
+ *   Registry contract — every primitive registered into guard-all
+ *   MUST export NAME / MIME_TYPES / EXTENSIONS (content guards only) /
+ *   PROFILES (must include strict / balanced / permissive) /
+ *   COMPLIANCE_POSTURES (must include hipaa / pci-dss / gdpr / soc2) /
+ *   gate(opts). A parity check at module load throws GuardAllError if
+ *   any member drifts from the contract — that's the registry gate
+ *   that keeps every future guard slice conformant.
  *
- * The parity check at module load throws GuardAllError if a registered
- * guard is missing any of the above — this is the registry gate that
- * keeps every future guard slice conformant.
+ *   Per-guard extension profiles (e.g. csv's "email-attachment") are
+ *   reached via the `override` map; the aggregator's `profile` opt
+ *   only takes the shared vocabulary so one string applies cleanly
+ *   across every member.
  *
- * Per-guard extension profiles (e.g. csv's "email-attachment") work
- * via direct b.guardCsv.gate({ profile: "email-attachment" }) but are
- * NOT accepted by b.guardAll.gate({ profile: ... }) — the aggregator
- * only takes the shared vocabulary so the same string applies cleanly
- * across every member. Operators reach for guard-specific profiles via
- * the override map.
+ * @card
+ *   Aggregate gate that dispatches to every registered b.guard* member by KIND.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -353,6 +332,53 @@ function _emitCreationAudit(opts, resolved) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive b.guardAll.gate
+ * @signature b.guardAll.gate(opts)
+ * @since     0.7.16
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.guardAll.byExtension, b.guardAll.byContentType, b.guardAll.list
+ *
+ * Build a single composite gate that dispatches by `Content-Type` to
+ * the active member of every registered content-bytes guard. Active
+ * set is the full GUARDS list minus any names listed in `exceptFor`
+ * (each requires a non-empty `reason` string — opting a guard out is
+ * auditable). A `guardAll.gate.created` audit row records the active +
+ * skipped roster so a security review can reconstruct what this deploy
+ * did and didn't defend against.
+ *
+ * @opts
+ *   profile:               "strict" | "balanced" | "permissive",
+ *   compliancePosture:     "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   mode:                  "enforce" | "audit-only",
+ *   exceptFor:             { [name]: { reason: string } },
+ *   override:              { [name]: object },          // per-guard opts merged in
+ *   audit:                 object,                      // b.audit handle
+ *   observability:         object,                      // b.observability handle
+ *   forensicEvidenceStore: object,
+ *   forensicSnippetBytes:  number,
+ *   cache:                 object,
+ *   cacheTtlMs:            number,
+ *   maxRuntimeMs:          number,
+ *   beforeCheck:           function,
+ *   afterCheck:            function,
+ *   onIssue:               function,
+ *   onSanitize:            function,
+ *   onRefuse:              function,
+ *   onAudit:               function,
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var safety = b.guardAll.gate({
+ *     profile: "strict",
+ *     exceptFor: {
+ *       html: { reason: "every HTML response is server-rendered + CSP-locked" },
+ *     },
+ *     override: { csv: { profile: "email-attachment" } },
+ *   });
+ *   // → contentTypeMux gate dispatching by Content-Type to each active member
+ */
 function gate(opts) {
   opts = opts || {};
   var resolved = _resolveActiveGuards(opts);
@@ -371,6 +397,33 @@ function gate(opts) {
   });
 }
 
+/**
+ * @primitive b.guardAll.byExtension
+ * @signature b.guardAll.byExtension(opts)
+ * @since     0.7.16
+ * @status    stable
+ * @related   b.guardAll.gate, b.guardAll.byContentType
+ *
+ * Return a map of file extension (".csv", ".svg", ...) to the gate of
+ * the guard that owns it. Drops directly into `b.staticServe.create
+ * ({ contentSafety })` so on-disk content is gated by extension match
+ * rather than served Content-Type. Honours the same `exceptFor` /
+ * `override` shape as `gate()`.
+ *
+ * @opts
+ *   profile:           "strict" | "balanced" | "permissive",
+ *   compliancePosture: "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   exceptFor:         { [name]: { reason: string } },
+ *   override:          { [name]: object },
+ *   audit:             object,
+ *   observability:     object,
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var byExt = b.guardAll.byExtension({ profile: "strict" });
+ *   var csvGate = byExt[".csv"];
+ *   // → b.gateContract gate for guard-csv at strict profile
+ */
 function byExtension(opts) {
   opts = opts || {};
   var resolved = _resolveActiveGuards(opts);
@@ -387,6 +440,32 @@ function byExtension(opts) {
   return map;
 }
 
+/**
+ * @primitive b.guardAll.byContentType
+ * @signature b.guardAll.byContentType(opts)
+ * @since     0.7.16
+ * @status    stable
+ * @related   b.guardAll.gate, b.guardAll.byExtension
+ *
+ * Return a map of canonical MIME type to the gate of the guard that
+ * owns it. Useful when the operator already has a non-mux dispatch
+ * shape (custom router / per-route content-safety) and wants the
+ * per-type gate keyed by MIME directly. `gate()` wraps this map in
+ * `gateContract.contentTypeMux`; this primitive surfaces the raw map.
+ *
+ * @opts
+ *   profile:           "strict" | "balanced" | "permissive",
+ *   compliancePosture: "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   exceptFor:         { [name]: { reason: string } },
+ *   override:          { [name]: object },
+ *   audit:             object,
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var byMime = b.guardAll.byContentType({ profile: "balanced" });
+ *   var jsonGate = byMime["application/json"];
+ *   // → b.gateContract gate for guard-json at balanced profile
+ */
 function byContentType(opts) {
   opts = opts || {};
   var resolved = _resolveActiveGuards(opts);
@@ -403,6 +482,25 @@ function byContentType(opts) {
   return map;
 }
 
+/**
+ * @primitive b.guardAll.list
+ * @signature b.guardAll.list()
+ * @since     0.7.16
+ * @status    stable
+ * @related   b.guardAll.allGuards, b.guardAll.gate
+ *
+ * Enumerate the registered content-bytes guards with their NAME, owned
+ * MIME types, owned extensions, and supported profile + posture
+ * vocabularies. Operators dump this at boot to surface "what is my
+ * deploy actually defending" in their audit attestation.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var rows = b.guardAll.list();
+ *   // → [{ name: "csv", mimeTypes: ["text/csv"], extensions: [".csv"],
+ *   //      profiles: ["strict","balanced","permissive","email-attachment"],
+ *   //      postures: ["hipaa","pci-dss","gdpr","soc2"] }, ...]
+ */
 function list() {
   return GUARDS.map(function (g) {
     return {
@@ -415,10 +513,29 @@ function list() {
   });
 }
 
-// allGuards — every guard primitive in the family, registered AND
-// standalone. Used by the adaptive integration harness to iterate
-// the full family without hardcoding the list. Future guards added
-// to either GUARDS or STANDALONE_GUARDS pick up automatically.
+/**
+ * @primitive b.guardAll.allGuards
+ * @signature b.guardAll.allGuards()
+ * @since     0.7.16
+ * @status    stable
+ * @related   b.guardAll.list, b.guardAll.gate
+ *
+ * Return every guard module in the family — registered (content-bytes)
+ * AND standalone (filename / domain / uuid / cidr / time / mime / jwt /
+ * oauth / graphql / shell / regex / jsonpath / template / image / pdf /
+ * auth). Used by the adaptive integration harness to iterate the full
+ * family without hardcoding the list, so future guards added to either
+ * registry pick up automatically.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var all = b.guardAll.allGuards();
+ *   var names = all.map(function (g) { return g.NAME; });
+ *   // → ["csv","html","svg","archive","json","yaml","xml","markdown",
+ *   //    "email","filename","domain","uuid","cidr","time","mime","jwt",
+ *   //    "oauth","graphql","shell","regex","jsonpath","template",
+ *   //    "image","pdf","auth"]
+ */
 function allGuards() {
   return GUARDS.concat(STANDALONE_GUARDS);
 }