@blamejs/core 0.8.43 → 0.8.50

package/lib/guard-graphql.js

@@ -1,38 +1,80 @@
 "use strict";
 /**
- * guard-graphql — GraphQL request-shape safety primitive
- * (b.guardGraphql).
+ * @module b.guardGraphql
+ * @nav    Guards
+ * @title  Guard Graphql
  *
- * Validates user-supplied GraphQL request bundles against the
- * canonical query-shape DoS catalog before the framework hands the
- * query to a schema-aware executor. KIND="graphql-request" — consumes
- * `ctx.graphqlRequest` shape: { query, operationName?, variables? }.
+ * @intro
+ *   GraphQL request-shape safety guard — validates user-supplied
+ *   request bundles against the canonical query-shape DoS catalog
+ *   BEFORE the framework hands the query to a schema-aware
+ *   executor. KIND is `graphql-request`; the gate consumes
+ *   `ctx.graphqlRequest` (or `ctx.gql`) shape `{ query,
+ *   operationName?, variables?, extensions? }`. Pair downstream
+ *   with the operator's schema-aware parser — this layer is the
+ *   shape / depth / breadth contract that runs before any
+ *   schema-resolution work.
  *
- * Threat catalog:
- *   - Query depth bombs — deeply-nested selection sets multiply N²
- *     against schema depth, bypassing field-level rate limits.
- *   - Query breadth / alias bombs — same field repeated under
- *     different aliases (`a:friend b:friend c:friend ...`) bypasses
- *     per-field limits.
- *   - Variable type confusion — variables passed as the wrong shape
- *     (string for ID expecting Int, object for scalar). Many
- *     executors coerce silently; the guard refuses non-shape-matching
- *     types when the operator declares variable shapes.
- *   - Introspection in production — `__schema` / `__type` queries
- *     leak schema details; refused unless operator opts in.
- *   - Batch query DoS — operators supporting [{},{}] batch arrays
- *     get N requests for one HTTP hit; the guard caps batch length.
- *   - Persisted-query opt-in — when operatorRequiresPersistedQuery,
- *     refuse free-form queries that don't carry a persisted-query
- *     hash extension.
- *   - Operation-name allowlist — operator may pin operationName to
- *     a whitelist of named operations (denylist for ad-hoc queries).
- *   - Excessive query / variable / total byte length — parser DoS.
- *   - BIDI / null / control / zero-width universal refuse on the
- *     query string.
+ *   Query depth caps: deeply-nested selection sets multiply
+ *   exponentially against schema depth, bypassing per-field rate
+ *   limits. The gate's `_measureQueryShape` walker counts
+ *   brace-depth without a full lex/parse (the operator's executor
+ *   handles full parsing); strict caps at 8, balanced 12,
+ *   permissive 24. The cap fires as `graphql.depth-exceeded` —
+ *   the canonical N²-amplification DoS class.
  *
- *   var rv = b.guardGraphql.validate(req, { profile: "strict" });
- *   var g  = b.guardGraphql.gate({ profile: "strict" });
+ *   Alias-amplification caps: the same field repeated under
+ *   different aliases (`a:friend b:friend c:friend ...`) bypasses
+ *   per-field limits because each alias is a separate selection.
+ *   Strict caps at 8 aliases per selection-set, balanced 16,
+ *   permissive 32. Fires as `graphql.alias-bomb` —
+ *   breadth-amplification DoS class.
+ *
+ *   Fragment-cycle defense: operator's executor handles cyclic
+ *   fragment refs at parse time; the guard's contribution is the
+ *   total-bytes cap (`maxBytes`) and per-query cap
+ *   (`maxQueryBytes`), which bound the worst-case parser-DoS
+ *   shape regardless of cycle structure.
+ *
+ *   Introspection toggle: `__schema` / `__type` queries leak
+ *   schema details and tooling expects them in development but
+ *   not production. Strict refuses (production posture); balanced
+ *   audits; permissive allows. Detection is substring-match on
+ *   the query string — fast and impossible to evade with
+ *   whitespace tricks.
+ *
+ *   Persisted-query allowlist: when the operator opts in via
+ *   `persistedQueryPolicy: "require"`, the request must carry
+ *   `extensions.persistedQuery.sha256Hash`. Free-form queries
+ *   are refused as `graphql.persisted-query-missing` — eliminates
+ *   ad-hoc query attack surface entirely (operator pre-approves
+ *   the catalog of permitted queries by hash).
+ *
+ *   Operation-name allowlist: when `opts.allowedOperations` is
+ *   set, the request `operationName` must be in the list.
+ *   Complements the persisted-query approach for operators that
+ *   keep free-form queries on but want a denylist for ad-hoc
+ *   shapes.
+ *
+ *   Variable shape validation: when `opts.variableShapes` declares
+ *   `{ varName: "string"|"number"|"boolean"|"object" }`, the gate
+ *   refuses any `variables` entry whose `typeof` doesn't match.
+ *   Catches type-confusion exploits where executors silently
+ *   coerce (string-for-ID-expecting-Int).
+ *
+ *   Batch defense: operators supporting `[{},{}]` batch arrays get
+ *   N requests for one HTTP hit. Strict refuses batches outright;
+ *   balanced caps at 10; permissive 50. Each batch entry is
+ *   validated with the same threat catalog applied recursively.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. BIDI / null /
+ *   control / zero-width universal-refuse applies on the query
+ *   string at every profile so trojan-source codepoints can't
+ *   ride inside a query identifier.
+ *
+ * @card
+ *   GraphQL request-shape safety guard — validates user-supplied request bundles against the canonical query-shape DoS catalog BEFORE the framework hands the query to a schema-aware executor.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -370,6 +412,59 @@ function _detectIssues(req, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardGraphql.validate
+ * @signature  b.guardGraphql.validate(input, opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardGraphql.sanitize, b.guardGraphql.gate
+ *
+ * Apply the full guard-graphql threat catalog to a request bundle
+ * (or batch array). Returns `{ ok, issues, refusal? }` per
+ * `gateContract.aggregateIssues`. Detected classes include
+ * `query-missing`, `query-cap`, `variables-cap`, `request-cap`,
+ * `batch-size`, `introspection`, `persisted-query-missing`,
+ * `operation-not-allowed`, `depth-exceeded`, `alias-bomb`,
+ * `variable-type-confusion`, plus codepoint-class issues on the
+ * query string. Operator-supplied opts are bounds-checked; bad
+ * opts throw `GuardGraphqlError("graphql.bad-opt")`.
+ *
+ * @opts
+ *   profile:                 "strict"|"balanced"|"permissive",
+ *   compliance:              "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   introspectionPolicy:     "reject"|"audit"|"allow",
+ *   persistedQueryPolicy:    "require"|"audit"|"allow",
+ *   operationNamePolicy:     "reject"|"audit"|"allow",
+ *   batchPolicy:             "reject"|"audit"|"allow",
+ *   aliasBombPolicy:         "reject"|"audit"|"allow",
+ *   depthPolicy:             "reject"|"audit"|"allow",
+ *   variableShapePolicy:     "reject"|"audit"|"allow",
+ *   allowedOperations:       string[],
+ *   variableShapes:          { [name: string]: "string"|"number"|"boolean"|"object" },
+ *   maxDepth:                number,
+ *   maxAliasesPerSelection:  number,
+ *   maxBatchSize:            number,
+ *   maxQueryBytes:           number,
+ *   maxVariableBytes:        number,
+ *   maxBytes:                number,
+ *
+ * @example
+ *   var hostile = {
+ *     query: "query Inspect { __schema { types { name } } }",
+ *     operationName: "Inspect",
+ *   };
+ *   var rv = b.guardGraphql.validate(hostile, { profile: "strict" });
+ *   rv.ok;                                              // → false
+ *   rv.issues[0].ruleId;                                // → "graphql.introspection"
+ *
+ *   var benign = {
+ *     query: "query GetMe { me { id name } }",
+ *     operationName: "GetMe",
+ *   };
+ *   var ok = b.guardGraphql.validate(benign, { profile: "strict" });
+ *   ok.ok;                                              // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -379,6 +474,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardGraphql.sanitize
+ * @signature  b.guardGraphql.sanitize(input, opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardGraphql.validate, b.guardGraphql.gate
+ *
+ * Pass-through-or-throw form of `validate`. GraphQL request
+ * bundles can't be partially repaired — depth bombs, alias
+ * amplification, and introspection leaks are refuse-class
+ * outcomes, not something the guard can patch up safely.
+ * Returns the input unchanged when the issue list contains no
+ * `critical` / `high` entries; throws `GuardGraphqlError`
+ * carrying the offending `ruleId` otherwise.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:        every guardGraphql.validate opt is honored,
+ *
+ * @example
+ *   try {
+ *     b.guardGraphql.sanitize({
+ *       query: "query Inspect { __schema { types { name } } }",
+ *       operationName: "Inspect",
+ *     }, { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                           // → "graphql.introspection"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   var issues = _detectIssues(input, opts);
@@ -391,6 +516,42 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardGraphql.gate
+ * @signature  b.guardGraphql.gate(opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardGraphql.validate, b.guardGraphql.sanitize
+ *
+ * Build a `gateContract.buildGuardGate`-shaped gate that pulls
+ * `ctx.graphqlRequest` (or `ctx.gql`) and dispatches to
+ * `validate`. Returns `{ ok: true, action: "serve" }` when the
+ * issue list is empty, `{ ok: true, action: "audit-only", issues }`
+ * when only low-severity issues fire, and `{ ok: false, action:
+ * "refuse", issues }` on any `critical` / `high` issue. Compose
+ * into the GraphQL request handler before any schema-resolution
+ * work — refusal short-circuits hostile depth / alias / batch
+ * shapes before they reach the executor.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,            // gate label for audit trails
+ *   ...:        every guardGraphql.validate opt is honored,
+ *
+ * @example
+ *   var gqlGate = b.guardGraphql.gate({ profile: "strict" });
+ *   var rv = await gqlGate.run({
+ *     graphqlRequest: {
+ *       query: "{ a:me { id } b:me { id } c:me { id } d:me { id } " +
+ *              "e:me { id } f:me { id } g:me { id } h:me { id } " +
+ *              "i:me { id } }",
+ *     },
+ *   });
+ *   rv.action;                                          // → "refuse"
+ *   rv.issues[0].ruleId;                                // → "graphql.alias-bomb"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -414,14 +575,86 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardGraphql.buildProfile
+ * @signature  b.guardGraphql.buildProfile(opts)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardGraphql.gate, b.guardGraphql.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus
+ * inline overrides. `opts.extends` is a profile name (`"strict"` /
+ * `"balanced"` / `"permissive"`) or an array of names; later
+ * entries shadow earlier ones, and inline `opts` keys win last.
+ * Operators stage profile overlays here so the final shape is
+ * traceable to a baseline rather than a hand-typed dictionary.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guardGraphql key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardGraphql.buildProfile({
+ *     extends: "balanced",
+ *     introspectionPolicy: "reject",
+ *     maxDepth: 6,
+ *   });
+ *   custom.introspectionPolicy;                         // → "reject"
+ *   custom.maxDepth;                                    // → 6
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardGraphql.compliancePosture
+ * @signature  b.guardGraphql.compliancePosture(name)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardGraphql.gate, b.guardGraphql.buildProfile
+ *
+ * Look up a compliance-posture overlay by name (`"hipaa"` /
+ * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of
+ * the posture object — the caller may mutate freely. Throws
+ * `GuardGraphqlError("graphql.bad-posture")` on unknown name.
+ * Postures extend the strict profile (or balanced for `gdpr`)
+ * with a `forensicSnippetBytes` cap appropriate to the regime.
+ *
+ * @example
+ *   var posture = b.guardGraphql.compliancePosture("soc2");
+ *   posture.introspectionPolicy;                        // → "reject"
+ *   posture.forensicSnippetBytes;                       // → 1024
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "graphql");
 }
 
 var _gqlRulePacks = gateContract.makeRulePackLoader(GuardGraphqlError, "graphql");
+/**
+ * @primitive  b.guardGraphql.loadRulePack
+ * @signature  b.guardGraphql.loadRulePack(pack)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardGraphql.gate
+ *
+ * Register an operator-supplied rule pack with the guard-graphql
+ * registry. The pack is identified by `pack.id` (non-empty
+ * string) and stored for later inspection / dispatch by gates
+ * that opt in via `opts.rulePackId`. Returns the pack object
+ * unchanged on success; throws `GuardGraphqlError("graphql.bad-opt")`
+ * when `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardGraphql.loadRulePack({
+ *     id: "no-mutation-on-read-replica",
+ *     rules: [
+ *       { id: "no-mutation", severity: "high",
+ *         detect: function (req) { return /^\s*mutation\b/.test(req.query || ""); },
+ *         reason: "read-replica refuses mutation operations" },
+ *     ],
+ *   });
+ *   pack.id;                                            // → "no-mutation-on-read-replica"
+ */
 var loadRulePack = _gqlRulePacks.load;
 
 module.exports = {