@blamejs/core 0.8.43 → 0.8.50

package/lib/guard-mime.js

@@ -1,34 +1,39 @@
 "use strict";
 /**
- * guard-mime — Media-type identifier-safety primitive (b.guardMime).
+ * @module b.guardMime
+ * @nav    Guards
+ * @title  Guard Mime
  *
- * Validates user-supplied RFC 6838 media type strings destined for
- * Accept-shape comparison, content-type allowlists, and dispatch
- * routing. KIND="identifier" — consumes ctx.identifier (or ctx.mime).
+ * @intro
+ *   Media-type identifier-safety guard. Validates user-supplied
+ *   RFC 6838 media-type strings destined for Accept-shape comparison,
+ *   content-type allowlists, and dispatch routing. KIND="identifier"
+ *   — the gate consumes `ctx.identifier` (or `ctx.mime`).
  *
- * Threat catalog:
- *   - Shape malformation — not RFC 6838 type/subtype grammar.
- *   - Bad token characters — RFC 6838 §4.2 restricts type and subtype
- *     to ALPHA / DIGIT / `!#$&-^_.+`. Spaces / quotes / Unicode reject.
- *   - Parameter injection — operators sometimes pass through user-
- *     supplied parameters (`text/plain; charset=...`); the grammar is
- *     permissive enough to smuggle multiple parameters or bare values.
- *   - Wildcard `* / *` and `type / *` — only valid in Accept-header
- *     context; refused as a content-type at strict.
- *   - Vendor tree without operator opt-in (`application/vnd.<vendor>`)
- *     — flag at strict so operators audit the vendor namespace.
- *   - Personal tree (`application/prs.*`) and unregistered (`x.*`) —
- *     same flag class.
- *   - Risky types refuse list — `application/x-msdownload`, `.x-bat`,
- *     `.x-msdos-program`, `.x-sh`, `.x-csh`, `.javascript`,
- *     `.x-javascript` (when handed off to a script-host).
- *   - BIDI / zero-width / control / null-byte universal refuse.
+ *   Threat catalog: shape malformation (not RFC 6838 type/subtype
+ *   grammar); bad token characters (RFC 6838 §4.2 restricts type and
+ *   subtype to ALPHA / DIGIT / `!#$&-^_.+` — spaces / quotes /
+ *   Unicode reject); parameter injection through pass-through
+ *   `text/plain; charset=...` shapes; wildcard `*‍/‍*` / `type/*`
+ *   (Accept-only — refused as content-type at strict); vendor tree
+ *   `application/vnd.<vendor>` and personal tree `application/prs.*`
+ *   plus unregistered `x.*` flagged so operators audit the namespace;
+ *   risky types refuse list (`application/x-msdownload`,
+ *   `.x-msdos-program`, `.x-sh`, `.x-csh`, `application/javascript`,
+ *   `text/javascript`) when handed off to a script-host;
+ *   BIDI / zero-width / C0-control / null-byte universal-refuse.
  *
- *   var rv = b.guardMime.validate("application/json",
- *                                 { profile: "strict" });
- *   var safe = b.guardMime.sanitize("Application/JSON; charset=UTF-8",
- *                                   { profile: "balanced" });
- *   var g = b.guardMime.gate({ profile: "strict" });
+ *   Magic-byte verification and polyglot rejection are performed by
+ *   the operator-side fixture pipeline: the gate emits the asserted
+ *   identifier; downstream content guards (`b.guardSvg` / `b.guardPdf`
+ *   / `b.guardImage`) compare it against `inspectMagic(buffer)` and
+ *   refuse mismatches.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`.
+ *
+ * @card
+ *   Media-type identifier-safety guard.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -347,6 +352,45 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardMime.validate
+ * @signature  b.guardMime.validate(input, opts?)
+ * @since      0.7.47
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardMime.sanitize, b.guardMime.gate
+ *
+ * Inspect a media-type string against the resolved profile and
+ * return `{ ok, issues }`. Each issue carries `kind` / `severity`
+ * (`critical` | `high` | `medium` | `low`) / `ruleId` / `snippet`.
+ * Non-string input returns a single `mime.bad-input` issue rather
+ * than throwing — callers that prefer an exception use
+ * `b.guardMime.sanitize`.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:             "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:          "reject"|"strip"|"allow",
+ *   nullBytePolicy:         "reject"|"strip"|"allow",
+ *   zeroWidthPolicy:        "reject"|"strip"|"allow",
+ *   wildcardPolicy:         "reject"|"audit"|"allow",
+ *   vendorTreePolicy:       "reject"|"audit"|"allow",
+ *   personalTreePolicy:     "reject"|"audit"|"allow",
+ *   unregisteredTreePolicy: "reject"|"audit"|"allow",
+ *   riskyTypesPolicy:       "reject"|"audit"|"allow",
+ *   parameterPolicy:        "reject"|"audit"|"allow",
+ *   maxBytes:               number,    // default 256 (RFC-recommended cap)
+ *
+ * @example
+ *   var rv = b.guardMime.validate("application/json", { profile: "strict" });
+ *   rv.ok;                                             // → true
+ *   rv.issues.length;                                  // → 0
+ *
+ *   var bad = b.guardMime.validate("application/x-msdownload", { profile: "strict" });
+ *   bad.ok;                                            // → false
+ *   bad.issues[0].ruleId;                              // → "mime.risky-type"
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -363,6 +407,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardMime.sanitize
+ * @signature  b.guardMime.sanitize(input, opts?)
+ * @since      0.7.47
+ * @status     stable
+ * @related    b.guardMime.validate, b.guardMime.gate
+ *
+ * Lower-case the canonical type/subtype while preserving
+ * parameter-value case (some parameter values are case-significant —
+ * e.g. multipart `boundary` tokens). Throws `GuardMimeError` when any
+ * `critical` or `high` issue fires (risky-type, parameter-injection,
+ * BIDI / null-byte / control). Use `validate` to inspect issues
+ * without throwing.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardMime.validate opts,
+ *
+ * @example
+ *   var safe = b.guardMime.sanitize("Application/JSON; charset=UTF-8",
+ *                                   { profile: "balanced" });
+ *   safe;                                              // → "application/json; charset=UTF-8"
+ *
+ *   try {
+ *     b.guardMime.sanitize("application/javascript", { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "mime.risky-type"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -385,6 +459,35 @@ function sanitize(input, opts) {
   }, canonical);
 }
 
+/**
+ * @primitive  b.guardMime.gate
+ * @signature  b.guardMime.gate(opts?)
+ * @since      0.7.47
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardMime.validate, b.guardMime.sanitize, b.guardAll.gate
+ *
+ * Build an async gate `(ctx) -> { ok, action, issues }` consumable
+ * by `b.guardAll`, `b.staticServe`, `b.fileUpload`, and any other
+ * host that integrates the guard contract. The gate reads
+ * `ctx.identifier` (or `ctx.mime`), runs `validate`, and maps
+ * severity to action: zero issues `serve`; only low/medium
+ * `audit-only`; any high/critical `refuse`.
+ *
+ * @opts
+ *   name:                   string,    // gate label for audit / observability
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardMime.validate opts,
+ *
+ * @example
+ *   var g = b.guardMime.gate({ profile: "strict" });
+ *   var rv = await g({ identifier: "application/json" });
+ *   rv.action;                                         // → "serve"
+ *
+ *   var bad = await g({ identifier: "application/x-msdownload" });
+ *   bad.action;                                        // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -408,14 +511,75 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardMime.buildProfile
+ * @signature  b.guardMime.buildProfile(opts)
+ * @since      0.7.47
+ * @status     stable
+ * @related    b.guardMime.gate, b.guardMime.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus
+ * inline overrides. `opts.extends` is a profile name or array of
+ * names (later entries shadow earlier ones); inline keys win last.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guard-mime key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardMime.buildProfile({
+ *     extends: "balanced",
+ *     vendorTreePolicy: "audit",
+ *   });
+ *   custom.bidiPolicy;                                 // → "reject"
+ *   custom.vendorTreePolicy;                           // → "audit"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardMime.compliancePosture
+ * @signature  b.guardMime.compliancePosture(name)
+ * @since      0.7.47
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardMime.gate, b.guardMime.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
+ * `GuardMimeError("mime.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardMime.compliancePosture("pci-dss");
+ *   posture.riskyTypesPolicy;                          // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "mime");
 }
 
 var _mimeRulePacks = gateContract.makeRulePackLoader(GuardMimeError, "mime");
+/**
+ * @primitive  b.guardMime.loadRulePack
+ * @signature  b.guardMime.loadRulePack(pack)
+ * @since      0.7.47
+ * @status     stable
+ * @related    b.guardMime.gate
+ *
+ * Register an operator-supplied rule pack with the guard-mime
+ * 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 `GuardMimeError("mime.bad-opt")`
+ * when `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardMime.loadRulePack({
+ *     id: "operator-deny-flash",
+ *     deny: ["application/x-shockwave-flash"],
+ *   });
+ *   pack.id;                                           // → "operator-deny-flash"
+ */
 var loadRulePack = _mimeRulePacks.load;
 
 module.exports = {

package/lib/guard-oauth.js

@@ -1,36 +1,82 @@
 "use strict";
 /**
- * guard-oauth — OAuth flow-shape safety primitive (b.guardOauth).
+ * @module b.guardOauth
+ * @nav    Guards
+ * @title  Guard Oauth
  *
- * Validates user-supplied OAuth 2.x / OIDC authorization-code-flow
- * parameter bundles before the framework's b.auth.oauth client
- * exchanges them. KIND="oauth-flow" — consumes ctx.oauthFlow.
+ * @intro
+ *   OAuth 2.x / OIDC authorization-code-flow shape guard —
+ *   validates user-supplied parameter bundles BEFORE the
+ *   framework's `b.auth.oauth` client exchanges them with the IdP.
+ *   KIND is `oauth-flow`; the gate consumes `ctx.oauthFlow` (or
+ *   `ctx.flow`) shape `{ response_type, redirect_uri, state,
+ *   code_challenge, code_challenge_method, scope, code, iss,
+ *   _isCallback }`. The guard runs the spec-mandated refuse list
+ *   so misconfigured callers can't downgrade the flow.
  *
- * Threat catalog:
- *   - PKCE missing or non-S256 — RFC 7636 mandates code_verifier;
- *     OAuth 2.1 mandates S256 (no plain). The plaintext "plain"
- *     method is downgrade-attack class.
- *   - state missing / replayed — RFC 6749 §10.12 + §10.14; without
- *     state-binding the flow is open to CSRF.
- *   - redirect_uri not in allowlist — RFC 6749 §3.1.2 + OAuth 2.1
- *     mandate exact-match (no prefix / wildcard / scheme drift).
- *   - response_type not in allowlist — refuse "token" implicit flow
- *     (deprecated in OAuth 2.1) and "id_token" outside OIDC; require
- *     operator-allowed types.
- *   - scope tampering — refuse scope values containing whitespace
- *     other than space (RFC 6749 §3.3) or non-printable bytes.
- *   - issuer (iss) missing on callback — RFC 9207 mandates iss
- *     parameter on authorization response to defeat the IdP-mix-up
- *     attack.
- *   - code reuse — operator-supplied seenCodeStore detects
- *     authorization-code replay (RFC 6749 §10.5).
- *   - excessive parameter / value length — defense against parser
- *     DoS and decompression-bomb-shaped clients.
- *   - BIDI / null / control / zero-width universal refuse.
+ *   PKCE enforcement: `strict` requires `S256` (RFC 7636 + OAuth
+ *   2.1; the `plain` method is a downgrade-attack class). `balanced`
+ *   accepts S256 or plain. `permissive` audits without enforcing.
+ *   Missing `code_verifier` AND missing `code_challenge` always
+ *   surfaces as `oauth.pkce-missing` because OAuth 2.1 mandates
+ *   PKCE for every client class.
  *
- *   var rv = b.guardOauth.validate({ redirect_uri, state, ... },
- *                                  { profile: "strict" });
- *   var g  = b.guardOauth.gate({ profile: "strict" });
+ *   `state` enforcement: required at strict / balanced. Without
+ *   state-binding the authorization callback is open to CSRF (RFC
+ *   6749 §10.12). The guard refuses missing `state`; operator-side
+ *   replay defense (rotating + comparing) is the responsibility of
+ *   the caller's session layer.
+ *
+ *   `nonce` is OIDC-specific replay defense — the guard's required-
+ *   claims parity is enforced via the operator's
+ *   `b.auth.jwt.verifyExternal` config, not in the flow shape, so
+ *   nonce is documented here but checked by the verifier.
+ *
+ *   `redirect_uri` exact-match: when the operator supplies
+ *   `allowedRedirectUris`, every callback must be a byte-for-byte
+ *   match. RFC 6749 §3.1.2 + OAuth 2.1 forbid prefix, wildcard, or
+ *   scheme drift — the canonical CVE-class for this is the
+ *   "redirect_uri loose-match" account-takeover bug. When no
+ *   allowlist is configured the gate skips the check (operator-side
+ *   misconfiguration warning lives in the startup audit, not in
+ *   per-request issue lists).
+ *
+ *   `response_type` allowlist: `strict` allows only `code`.
+ *   `balanced` adds `code id_token`. `permissive` skips. Implicit-
+ *   flow `token` and `id_token` outside OIDC are deprecated in
+ *   OAuth 2.1 and refused under the strict / balanced allowlists.
+ *
+ *   Scope-token discipline: every space-separated scope must
+ *   conform to the RFC 6749 §3.3 charset (`%x21 / %x23-5B /
+ *   %x5D-7E`). Whitespace-other-than-space, control bytes, and
+ *   non-printable bytes in scope tokens are refused under strict
+ *   / balanced and audited under permissive.
+ *
+ *   RFC 9207 issuer-on-callback: when the request bundle is
+ *   marked `_isCallback: true`, the `iss` parameter MUST be
+ *   present at strict — defeats the IdP-mix-up attack class.
+ *   `balanced` audits, `permissive` skips.
+ *
+ *   Token-introspection bounds: `maxParamBytes` (default 2 KiB at
+ *   strict / balanced) and `maxBytes` (default 8 KiB) cap each
+ *   parameter and the total flow JSON. Decompression-bomb-shaped
+ *   clients can't push the introspection / metadata layer past
+ *   these bounds.
+ *
+ *   Code-reuse defense: when the operator wires a `seenCodeStore`
+ *   with `hasSeen(code)`, the guard refuses any authorization code
+ *   already exchanged (RFC 6749 §10.5). The store implementation
+ *   is the operator's responsibility — typically a short-TTL
+ *   `b.cache` entry.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. BIDI / null /
+ *   control / zero-width universal-refuse applies on every string-
+ *   valued top-level parameter at every profile so trojan-source
+ *   codepoints can't ride a state or scope value.
+ *
+ * @card
+ *   OAuth 2.x / OIDC authorization-code-flow shape guard — validates user-supplied parameter bundles BEFORE the framework's `b.auth.oauth` client exchanges them with the IdP.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -297,6 +343,66 @@ function _detectIssues(flow, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardOauth.validate
+ * @signature  b.guardOauth.validate(input, opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardOauth.sanitize, b.guardOauth.gate, b.auth.oauth
+ *
+ * Apply the full guard-oauth threat catalog to a flow bundle.
+ * Returns `{ ok, issues, refusal? }` per
+ * `gateContract.aggregateIssues`. Detected classes include
+ * `pkce-missing`, `pkce-method` (e.g. plain under require-s256),
+ * `state-missing`, `redirect-uri-not-allowed`,
+ * `response-type-not-allowed`, `scope-token-shape`,
+ * `issuer-missing`, `code-reused` (always critical), plus per-
+ * parameter `param-cap` and total-flow `flow-cap` bounds and
+ * codepoint-class issues on every string parameter. Operator-
+ * supplied opts are bounds-checked; bad opts throw
+ * `GuardOauthError("oauth.bad-opt")`.
+ *
+ * @opts
+ *   profile:                 "strict"|"balanced"|"permissive",
+ *   compliance:              "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   pkcePolicy:              "require-s256"|"require-any"|"audit"|"allow",
+ *   statePolicy:             "require"|"audit"|"allow",
+ *   redirectUriPolicy:       "require-exact-allowlist"|"audit"|"allow",
+ *   responseTypePolicy:      "require-allowlist"|"audit"|"allow",
+ *   scopeTamperingPolicy:    "reject"|"audit"|"allow",
+ *   issuerOnCallbackPolicy:  "require"|"audit"|"allow",
+ *   codeReusePolicy:         "reject"|"allow",
+ *   allowedRedirectUris:     string[],
+ *   allowedResponseTypes:    string[],
+ *   seenCodeStore:           { hasSeen: function(code): boolean },
+ *   maxParamBytes:           number,
+ *   maxBytes:                number,
+ *
+ * @example
+ *   var hostile = {
+ *     response_type: "code",
+ *     redirect_uri:  "https://attacker.example/callback",
+ *     scope:         "openid",
+ *   };
+ *   var rv = b.guardOauth.validate(hostile, { profile: "strict" });
+ *   rv.ok;                                              // → false
+ *   rv.issues[0].ruleId;                                // → "oauth.pkce-missing"
+ *
+ *   var benign = {
+ *     response_type: "code",
+ *     redirect_uri:  "https://app.example.com/callback",
+ *     state:         "csrf-rand-1",
+ *     scope:         "openid profile",
+ *     code_challenge: "abc123def456ghi789jkl012mno345pqr678",
+ *     code_challenge_method: "S256",
+ *   };
+ *   var ok = b.guardOauth.validate(benign, {
+ *     profile: "strict",
+ *     allowedRedirectUris: ["https://app.example.com/callback"],
+ *   });
+ *   ok.ok;                                              // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -305,6 +411,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardOauth.sanitize
+ * @signature  b.guardOauth.sanitize(input, opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardOauth.validate, b.guardOauth.gate
+ *
+ * Pass-through-or-throw form of `validate`. OAuth flow bundles
+ * can't be partially repaired — a missing `state` or wrong
+ * `redirect_uri` is a refuse-class outcome, not something the
+ * guard can patch up safely. Returns the input unchanged when
+ * the issue list contains no `critical` / `high` entries; throws
+ * `GuardOauthError` carrying the offending `ruleId` otherwise.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:        every guardOauth.validate opt is honored,
+ *
+ * @example
+ *   try {
+ *     b.guardOauth.sanitize({
+ *       response_type: "code",
+ *       redirect_uri:  "https://app.example.com/callback",
+ *       scope:         "openid",
+ *     }, { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                           // → "oauth.pkce-missing"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   // OAuth flows can't be repaired — sanitize either passes through
@@ -319,6 +455,47 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardOauth.gate
+ * @signature  b.guardOauth.gate(opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardOauth.validate, b.guardOauth.sanitize, b.auth.oauth
+ *
+ * Build a `gateContract.buildGuardGate`-shaped gate that pulls
+ * `ctx.oauthFlow` (or `ctx.flow`) 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
+ * authorization-callback handler before exchanging the code with
+ * the IdP — refusal on a hostile callback prevents the token
+ * exchange entirely.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,            // gate label for audit trails
+ *   ...:        every guardOauth.validate opt is honored,
+ *
+ * @example
+ *   var oauthGate = b.guardOauth.gate({
+ *     profile: "strict",
+ *     allowedRedirectUris: ["https://app.example.com/callback"],
+ *   });
+ *   var rv = await oauthGate.run({
+ *     oauthFlow: {
+ *       response_type: "code",
+ *       redirect_uri:  "https://attacker.example/callback",
+ *       state:         "csrf-rand-1",
+ *       scope:         "openid",
+ *       code_challenge: "abc123def456ghi789jkl012mno345pqr678",
+ *       code_challenge_method: "S256",
+ *     },
+ *   });
+ *   rv.action;                                          // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -342,14 +519,86 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardOauth.buildProfile
+ * @signature  b.guardOauth.buildProfile(opts)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardOauth.gate, b.guardOauth.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 guardOauth key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardOauth.buildProfile({
+ *     extends: "balanced",
+ *     pkcePolicy: "require-s256",
+ *     allowedResponseTypes: ["code"],
+ *   });
+ *   custom.pkcePolicy;                                  // → "require-s256"
+ *   custom.allowedResponseTypes.length;                 // → 1
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardOauth.compliancePosture
+ * @signature  b.guardOauth.compliancePosture(name)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardOauth.gate, b.guardOauth.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
+ * `GuardOauthError("oauth.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.guardOauth.compliancePosture("pci-dss");
+ *   posture.pkcePolicy;                                 // → "require-s256"
+ *   posture.forensicSnippetBytes;                       // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "oauth");
 }
 
 var _oauthRulePacks = gateContract.makeRulePackLoader(GuardOauthError, "oauth");
+/**
+ * @primitive  b.guardOauth.loadRulePack
+ * @signature  b.guardOauth.loadRulePack(pack)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardOauth.gate
+ *
+ * Register an operator-supplied rule pack with the guard-oauth
+ * 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 `GuardOauthError("oauth.bad-opt")`
+ * when `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardOauth.loadRulePack({
+ *     id: "scope-narrow",
+ *     rules: [
+ *       { id: "no-admin", severity: "high",
+ *         detect: function (flow) { return /\badmin\b/.test(flow.scope || ""); },
+ *         reason: "tenant forbids admin scope on user-flow callbacks" },
+ *     ],
+ *   });
+ *   pack.id;                                            // → "scope-narrow"
+ */
 var loadRulePack = _oauthRulePacks.load;
 
 module.exports = {