@blamejs/core 0.8.43 → 0.8.49

package/lib/pagination.js

@@ -1,98 +1,49 @@
 "use strict";
 /**
- * pagination — cursor + offset helpers.
+ * @module b.pagination
+ * @nav    Tools
+ * @title  Pagination
  *
- * Every CRUD list endpoint reinvents pagination, usually wrong.
- * The two failure modes:
+ * @intro
+ *   Cursor-based pagination — opaque tokens that encode the last-row
+ *   sort key + direction, resilient to inserts and deletes between
+ *   pages.
  *
- *   - Offset pagination at depth: `LIMIT n OFFSET 50000` makes the DB
- *     scan-and-skip 50,000 rows. O(n). With concurrent writes, rows
- *     are also missed/duplicated as new inserts shift the offset.
- *   - Cursor pagination without a tie-breaker: `WHERE createdAt > ?`
- *     skips or duplicates rows when two records share createdAt.
+ *   Every CRUD list endpoint reinvents pagination, usually wrong. The
+ *   two failure modes: offset pagination at depth (`LIMIT n OFFSET
+ *   50000` scan-and-skips 50,000 rows; concurrent writes shift the
+ *   offset and rows get missed or duplicated), and cursor pagination
+ *   without a tie-breaker (`WHERE createdAt > ?` skips or duplicates
+ *   rows when two records share `createdAt`).
  *
- * This module ships both, done correctly, plus the encode/decode
- * primitives operators reach for when their SQL doesn't fit the
- * Query-builder shape.
+ *   This module ships both done correctly. `cursor()` uses composite
+ *   `(orderBy, _id)` ordering — `_id` is the implicit tie-breaker, so
+ *   two rows with identical `orderByVal` are still totally ordered.
+ *   Forward navigation: `WHERE (orderByVal > ?) OR (orderByVal = ? AND
+ *   _id > ?)`. Backward: same with `<`, then reverse the result set.
  *
- * Public API:
+ *   Cursors are HMAC-tagged with operator-supplied `secret`. A tampered
+ *   cursor is detected at decode time and rejected with
+ *   `PaginationError`. Cursor format: `<base64url state>.<base64url
+ *   tag>`, state is canonical JSON of `{ v, orderKey, vals, forward }`,
+ *   tag is `SHA3-512(secret || stateJson).slice(0, 16)`. Direction is
+ *   part of the cursor — operators don't round-trip it via query
+ *   string. Multi-column ordering accepted: a string, an array of
+ *   strings, or `[{ column, direction }, ...]`; `_id` is appended as a
+ *   tiebreaker if not already in the chain.
  *
- *   var p = b.pagination;
+ *   `offset()` is the legacy-client tool, not the recommended path.
+ *   It returns `total` (from `COUNT(*)`) and computes `totalPages` so
+ *   legacy clients can render numbered nav.
  *
- *   // Cursor: O(1) at any depth. Composite (orderBy, _id) ordering
- *   // so ties on the orderBy column are broken by _id and rows are
- *   // never skipped.
- *   var page = await p.cursor(b.db.from("users"), {
- *     cursor:    req.query.cursor,
- *     limit:     req.query.limit,
- *     max:       100,
- *     default:   25,
- *     orderBy:   "_id",         // default; use "createdAt" etc.
- *     direction: "asc",         // "asc" | "desc"
- *     secret:    pageSecret,    // Buffer or string; HMAC-tag the cursor
- *   });
- *   // → { items: [...], nextCursor, prevCursor, limit, hasMore }
- *
- *   // Offset: page-numbered. Ergonomic for legacy clients.
- *   var off = await p.offset(b.db.from("users"), {
- *     page:    req.query.page,
- *     perPage: req.query.perPage,
- *     max:     100,
- *     default: 25,
- *   });
- *   // → { items, total, page, perPage, totalPages, hasMore }
- *
- *   // Low-level — for raw SQL or custom row sources.
- *   var token = p.encodeCursor({ orderByVal: 12345, id: "abc" }, secret);
- *   var state = p.decodeCursor(token, secret);
- *
- * Cursor design:
- *   - Composite ordering: (orderBy column, _id). _id is the implicit
- *     tie-breaker, so two rows with identical orderByVal are still
- *     totally ordered. Forward navigation: WHERE
- *       (orderByVal > cur.orderByVal) OR
- *       (orderByVal = cur.orderByVal AND _id > cur.id)
- *     Backward: same with `<`, then reverse the result set.
- *   - Cursors are HMAC-tagged. A tampered cursor is detected at decode
- *     time and rejected with PaginationError. Operators MUST pass
- *     `secret` (Buffer or string) — there's no auto-derivation, since
- *     framework-derived secrets would produce surprises across deploys.
- *   - Cursor format: `<base64url state>.<base64url tag>`. State is
- *     canonical JSON of `{ v, dir, orderBy, orderByVal, id }`. Tag is
- *     SHA3-512(secret || stateJson).slice(0, 16).
- *   - direction is part of the cursor — operators don't need to round-
- *     trip it via query string. The cursor itself encodes whether it's
- *     a "next" or "prev" position so navigation stays consistent.
- *
- * Limit semantics:
- *   - Operator passes `default` and `max`. The effective limit is
- *     min(max, requestedLimit || default). Negative or non-integer
- *     limits are coerced to default.
- *   - The page query fetches limit+1 to detect hasMore without a
- *     second COUNT(*) trip.
+ *   Cursor TTL / expiry is operator-side: embed a timestamp in your own
+ *   state and check at decode-time before passing to `.cursor()`. The
+ *   framework's HMAC tag carries no notion of time. Search / filter
+ *   integration composes — chain `.where()` on the Query before handing
+ *   to `.cursor()`.
  *
- * Offset is the legacy-client tool, not the recommended path. The
- * module's offset() returns a `total` (from COUNT(*)) and computes
- * `totalPages` so legacy clients can render numbered nav.
- *
- * Multi-column ordering:
- *   - orderBy accepts a string (single column), an array of strings
- *     (multiple columns, all using opts.direction), or an array of
- *     { column, direction } objects (mixed directions per column).
- *     The keyset WHERE expands to the standard OR cascade
- *       (col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ...)
- *     so successive pages can't repeat or skip rows when ties on the
- *     leading columns are broken by trailing ones. _id is appended as
- *     a tiebreaker if not already in the orderBy chain.
- *
- * Out of scope (with structural reasons documented):
- *   - Cursor TTL / expiry. Operators who want time-limited cursors
- *     embed a timestamp in their own state and check at decode-time
- *     before passing to .cursor(). The framework's HMAC tag carries
- *     no notion of time.
- *   - Search / filter integration. Operators chain .where() on the
- *     Query before handing to .cursor() — pagination composes with
- *     whatever filtering the operator's already applied.
+ * @card
+ *   Cursor-based pagination — opaque tokens that encode the last-row sort key + direction, resilient to inserts and deletes between pages.
  */
 
 var nodeCrypto = require("node:crypto");
@@ -151,6 +102,29 @@ function _tag(secretBuf, stateJson) {
   return h.digest().slice(0, TAG_BYTES);
 }
 
+/**
+ * @primitive b.pagination.encodeCursor
+ * @signature b.pagination.encodeCursor(state, secret)
+ * @since     0.6.20
+ * @related   b.pagination.decodeCursor, b.pagination.cursor
+ *
+ * Low-level cursor encoder for raw-SQL or custom row-source paths.
+ * Wraps `state` with the framework version field, canonicalises via
+ * the shared canonical-JSON walker, then computes the SHA3-512 HMAC
+ * tag and emits `<base64url(stateJson)>.<base64url(tag)>`. State is
+ * any plain-data object — `Buffer` / `Map` / `Set` / `RegExp` /
+ * functions / circular references are rejected loudly. `secret` is a
+ * `Buffer` or non-empty string; an empty secret throws.
+ *
+ * @example
+ *   var token = b.pagination.encodeCursor(
+ *     { orderKey: ["createdAt:asc", "_id:asc"], vals: [1700000000000, "u-42"], forward: true },
+ *     "page-secret"
+ *   );
+ *   // token is `<base64url state>.<base64url tag>`, ready to round-trip via query string.
+ *   var state = b.pagination.decodeCursor(token, "page-secret");
+ *   state.forward;   // → true
+ */
 function encodeCursor(state, secret) {
   if (!state || typeof state !== "object") {
     throw new PaginationError("pagination/bad-state",
@@ -166,6 +140,32 @@ function encodeCursor(state, secret) {
   return _b64urlEncode(json) + "." + _b64urlEncode(tag);
 }
 
+/**
+ * @primitive b.pagination.decodeCursor
+ * @signature b.pagination.decodeCursor(token, secret)
+ * @since     0.6.20
+ * @related   b.pagination.encodeCursor, b.pagination.cursor
+ *
+ * Inverse of `encodeCursor`. Splits on the `.` separator, base64url-
+ * decodes both halves, recomputes the HMAC tag against `secret` and
+ * compares with `b.crypto.timingSafeEqual`. On mismatch (tamper or
+ * wrong secret) throws `PaginationError("pagination/cursor-tag-
+ * mismatch")`. State JSON is parsed via `b.safeJson.parse` with a
+ * 8-KiB byte cap. The framework version field (`v`) must match the
+ * current `CURSOR_VERSION`; older cursors throw `pagination/cursor-
+ * version` so operators can detect rolling-deploy mismatches.
+ *
+ * @example
+ *   try {
+ *     var state = b.pagination.decodeCursor(req.query.cursor, "page-secret");
+ *     state.vals;       // → [1700000000000, "u-42"]
+ *     state.forward;    // → true
+ *   } catch (e) {
+ *     // PaginationError — tamper, wrong secret, or stale cursor version.
+ *     res.statusCode = 400;
+ *     res.end("invalid cursor");
+ *   }
+ */
 function decodeCursor(token, secret) {
   if (typeof token !== "string" || token.length === 0) {
     throw new PaginationError("pagination/bad-cursor", "cursor must be a non-empty string");
@@ -300,6 +300,54 @@ function _buildKeysetWhere(orderEntries, cursorVals, forward) {
   return { sql: clauses.join(" OR "), params: params };
 }
 
+/**
+ * @primitive b.pagination.cursor
+ * @signature b.pagination.cursor(query, opts)
+ * @since     0.6.20
+ * @related   b.pagination.offset, b.pagination.encodeCursor
+ *
+ * Cursor pagination over a `b.db.from(...)` Query. O(1) at any depth.
+ * Builds the keyset `WHERE` from the previous page's column values,
+ * applies the operator's `orderBy` chain (with `_id` appended as
+ * tiebreaker), fetches `limit + 1` rows to detect `hasMore` without a
+ * second `COUNT(*)`, and returns `{ items, nextCursor, prevCursor,
+ * limit, hasMore }`. Cursors round-trip via opaque base64url strings
+ * — operators don't pick apart the encoded state.
+ *
+ * Operators MUST pass `opts.secret` (Buffer or non-empty string) for
+ * HMAC tagging. There's no auto-derivation — framework-derived
+ * secrets would surprise across deploys.
+ *
+ * @opts
+ *   cursor:    string,                    // opaque token from a previous response (omit for first page)
+ *   limit:     number,                    // requested page size; clamped to opts.max, defaults to opts.default
+ *   max:       number,                    // hard cap on limit (defaults to 100)
+ *   default:   number,                    // limit when none requested (defaults to 25)
+ *   orderBy:   string|array,              // column name, ["a","b"], or [{column,direction}]
+ *   direction: "asc"|"desc",              // default direction applied to string/array forms
+ *   secret:    Buffer|string,             // REQUIRED — HMAC key for cursor tag
+ *   forward:   boolean,                   // override cursor's encoded direction (rare)
+ *
+ * @example
+ *   var page = await b.pagination.cursor(b.db.from("users"), {
+ *     cursor:    req.query.cursor,
+ *     limit:     parseInt(req.query.limit, 10),
+ *     max:       100,
+ *     default:   25,
+ *     orderBy:   "createdAt",
+ *     direction: "desc",
+ *     secret:    "page-secret",
+ *   });
+ *   page.items;        // → array of rows (length <= limit)
+ *   page.nextCursor;   // → string token, or null when there's no next page
+ *   page.hasMore;      // → true when more rows exist beyond this page
+ *
+ *   // Multi-column ordering with mixed directions:
+ *   var mixed = await b.pagination.cursor(b.db.from("orders"), {
+ *     orderBy: [{ column: "priority", direction: "desc" }, { column: "createdAt", direction: "asc" }],
+ *     secret:  "page-secret",
+ *   });
+ */
 async function cursor(query, opts) {
   if (!query || typeof query.where !== "function" || typeof query.orderBy !== "function" ||
       typeof query.limit !== "function" || typeof query.all !== "function") {
@@ -405,6 +453,40 @@ async function cursor(query, opts) {
 
 // ---- Offset pagination ----
 
+/**
+ * @primitive b.pagination.offset
+ * @signature b.pagination.offset(query, opts)
+ * @since     0.6.20
+ * @related   b.pagination.cursor
+ *
+ * Offset pagination — page-numbered, ergonomic for legacy clients
+ * that render numbered nav. Issues `COUNT(*)` to compute `total` and
+ * `totalPages`. Use `cursor()` for new endpoints; `offset()` is only
+ * the right shape when the consumer's UI already binds to page
+ * numbers. Re-applies the operator's `where()` chain unmodified, then
+ * adds `ORDER BY orderBy direction LIMIT perPage OFFSET (page-1)*perPage`.
+ *
+ * @opts
+ *   page:      number,           // 1-based page number (defaults to 1; non-integer coerces to 1)
+ *   perPage:   number,           // rows per page (clamped to opts.max, defaults to opts.default)
+ *   max:       number,           // hard cap on perPage (defaults to 100)
+ *   default:   number,           // perPage when none requested (defaults to 25)
+ *   orderBy:   string,           // column name (defaults to "_id"); identifier-validated against safeSql
+ *   direction: "asc"|"desc",     // sort direction (defaults to "asc")
+ *
+ * @example
+ *   var page = await b.pagination.offset(b.db.from("users"), {
+ *     page:    parseInt(req.query.page, 10),
+ *     perPage: parseInt(req.query.perPage, 10),
+ *     max:     100,
+ *     default: 25,
+ *     orderBy: "createdAt",
+ *     direction: "desc",
+ *   });
+ *   page.total;        // → e.g. 1284
+ *   page.totalPages;   // → e.g. 52 (when perPage=25)
+ *   page.hasMore;      // → true when page < totalPages
+ */
 async function offset(query, opts) {
   if (!query || typeof query.limit !== "function" || typeof query.offset !== "function" ||
       typeof query.all !== "function" || typeof query.count !== "function") {

package/lib/parsers/index.js

@@ -70,11 +70,22 @@ var safeIni  = require("./safe-ini");
 var safeToml = require("./safe-toml");
 var safeXml  = require("./safe-xml");
 var safeYaml = require("./safe-yaml");
+var bodyParser = require("../middleware/body-parser");
 
+// Standalone async parsers for request bodies. Same parsing pipeline the
+// b.middleware.bodyParser uses — handlers that lazy-parse (route-shape
+// dispatch, streaming endpoints that bypass middleware) call these inline:
+//
+//   var body  = await b.parsers.json(req,      { maxBytes: C.BYTES.mib(2) });
+//   var parts = await b.parsers.multipart(req, { maxBytes: C.BYTES.mib(50), maxFiles: 5 });
+//
+// The middleware composes these — no parallel parser to drift.
 module.exports = {
-  xml:  safeXml,
-  toml: safeToml,
-  yaml: safeYaml,
-  env:  safeEnv,
-  ini:  safeIni,
+  xml:       safeXml,
+  toml:      safeToml,
+  yaml:      safeYaml,
+  env:       safeEnv,
+  ini:       safeIni,
+  json:      bodyParser.parseJson,
+  multipart: bodyParser.parseMultipart,
 };

package/lib/permissions.js

@@ -1,48 +1,27 @@
 "use strict";
 /**
- * b.permissions — RBAC primitive.
+ * @module b.permissions
+ * @nav    Identity
+ * @title  Permissions
  *
- *   var perms = b.permissions.create({
- *     roles: {
- *       admin:  { extends: ["editor"], permissions: ["users:delete"] },
- *       editor: ["users:read", "users:write", "posts:*"],
- *       viewer: ["*:read"],
- *     },
- *     audit: b.audit,                  // optional
- *   });
- *
- *   router.delete("/users/:id",
- *     authMiddleware,                  // populates req.user / req.apiKey
- *     perms.require("users:delete"),
- *     deleteUserHandler);
+ * @intro
+ *   RBAC / ABAC / scope-based access control — declare roles, resolve
+ *   user permissions, gate routes via middleware. Composes with
+ *   b.apiKey (scopes flow from req.apiKey) and b.middleware.attachUser
+ *   (roles flow from req.user). Wildcard scope syntax mirrors the
+ *   project-wide convention: `"users:*"` (trailing-greedy),
+ *   `"*:read"` (per-segment), `"*"` (root-greedy).
  *
- * The default resolver chain reads the actor from the request:
+ *   The middleware factory runs three layers per request: RBAC scope
+ *   match, optional MFA freshness gate (per-route or per-role), and
+ *   ABAC predicate evaluation when a policy is registered for the
+ *   requested scope. Failures emit `permissions.check.deny` /
+ *   `permissions.mfa.required` / `permissions.policy.deny` audit
+ *   events with the actor 5 W's so a compliance reviewer can
+ *   reconstruct exactly which layer refused the request.
  *
- *   req.apiKey.scopes  → { scopes: [...] }   (b.apiKey.verify output)
- *   req.user.scopes    → { scopes: [...] }   (operator-set)
- *   req.user.roles     → { roles:  [...] }   (operator-set)
- *
- * Operators with non-default request shapes pass `resolver` to create().
- *
- * Wildcard semantics (b.permissions.match):
- *   "*"             matches any scope (greedy)
- *   "users:*"       matches "users:read", "users:read:detail", etc. (trailing * is greedy)
- *   "*:read"        matches "users:read", "posts:read"
- *   "users:*:read"  matches "users:foo:read" (per-segment *)
- *   "users:read"    matches "users:read" only — no implicit sub-resource grant
- *
- * Validation policy:
- *
- *   - create() role table / scope formats → throw at app init
- *   - require(scope) registration arg     → throw at route declaration
- *   - check(actor, scope) bad actor       → return false (tolerant read)
- *   - resolver returns null in middleware → 401 (missingActorStatus)
- *   - actor lacks scope in middleware     → 403 (denyStatus)
- *   - audit/observability emit failures   → drop silent (hot-path sink)
- *
- * Audit defaults follow the framework's security-defaults stance
- * default: `auditFailures: true`
- * (deny is a security signal), `auditSuccess: false` (per-request noise).
+ * @card
+ *   RBAC / ABAC / scope-based access control — declare roles, resolve user permissions, gate routes via middleware.
  */
 
 var C = require("./constants");
@@ -82,6 +61,27 @@ var DEFAULTS = Object.freeze({
 
 // ---- Wildcard matcher ----
 
+/**
+ * @primitive b.permissions.match
+ * @signature b.permissions.match(granted, required)
+ * @since     0.4.9
+ * @status    stable
+ * @related   b.permissions.create
+ *
+ * Project-wide scope wildcard matcher. Returns `true` when `granted`
+ * (a scope held by the actor, possibly containing `*`) covers
+ * `required` (the scope a route demands, always concrete). Trailing
+ * `*` is greedy across remaining segments; mid-string `*` matches a
+ * single segment.
+ *
+ * @example
+ *   b.permissions.match("users:*", "users:read");          // → true
+ *   b.permissions.match("users:*", "users:read:detail");   // → true
+ *   b.permissions.match("*:read", "users:read");           // → true
+ *   b.permissions.match("users:*:read", "users:42:read");  // → true
+ *   b.permissions.match("users:read", "users:write");      // → false
+ *   b.permissions.match("users:read", "users:read:audit"); // → false (no implicit sub-resource grant)
+ */
 function match(granted, required) {
   if (typeof granted !== "string" || typeof required !== "string") return false;
   if (granted.length === 0 || required.length === 0) return false;
@@ -265,6 +265,59 @@ function _validateCreateOpts(opts) {
 
 // ---- Registry ----
 
+/**
+ * @primitive b.permissions.create
+ * @signature b.permissions.create(opts)
+ * @since     0.4.9
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.permissions.match, b.apiKey.create, b.middleware.attachUser
+ *
+ * Build a permissions registry from a role table. Returns a handle
+ * exposing `require(scope, mwOpts?)` / `requireAll(scopes, mwOpts?)`
+ * / `requireAny(scopes, mwOpts?)` middleware factories,
+ * `check(actor, scope)` / `checkAll` / `checkAny` synchronous
+ * predicates, `policy(scope, predicate)` for ABAC layering,
+ * `expand(roleNames)` to resolve inherited permissions, and
+ * `dbRoleFor(reqOrActor)` for declarative DB role binding. Role
+ * tables are validated at create-time — unknown extends targets,
+ * cycles, and bad scope shapes throw before the first request.
+ *
+ * @opts
+ *   roles:               object,                          // role-name → spec (required, ≥1 entry)
+ *   resolver:            function,                        // req → actor; default reads req.apiKey / req.user
+ *   audit:               b.audit,                         // optional audit sink
+ *   auditFailures:       boolean,                         // default true
+ *   auditSuccess:        boolean,                         // default true (compliance trail)
+ *   denyStatus:          number,                          // default 403
+ *   missingActorStatus:  number,                          // default 401
+ *   responder:           function,                        // (req, res, status, info) — custom error responder
+ *
+ * @example
+ *   var perms = b.permissions.create({
+ *     roles: {
+ *       admin:  { extends: ["editor"], permissions: ["users:delete"] },
+ *       editor: ["users:read", "users:write", "posts:*"],
+ *       viewer: ["*:read"],
+ *     },
+ *     audit: b.audit,
+ *   });
+ *
+ *   // Synchronous check (e.g. inside a handler that already has the actor):
+ *   perms.check({ roles: ["editor"] }, "posts:write");   // → true
+ *   perms.check({ scopes: ["users:read"] }, "users:delete"); // → false
+ *
+ *   // Middleware on a route — actor is read from req.user / req.apiKey:
+ *   router.delete("/users/:id",
+ *     attachUser,
+ *     perms.require("users:delete", { requireMfa: true, mfaWindowMs: b.constants.TIME.minutes(5) }),
+ *     deleteHandler);
+ *
+ *   // ABAC predicate stacked on top of RBAC:
+ *   perms.policy("orders:write", async function (actor, ctx) {
+ *     return ctx.order.tenantId === actor.tenantId;
+ *   });
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/pqc-agent.js

@@ -31,7 +31,47 @@
 var https = require("node:https");
 var http  = require("node:http");
 var C = require("./constants");
+var lazyRequire = require("./lazy-require");
 var networkTls = require("./network-tls");
+var safeBuffer = require("./safe-buffer");
+
+// audit imports crypto/handlers transitively — lazy to avoid load
+// cycles when pqc-agent is required during framework bootstrap.
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// IANA TLS Supported Groups Registry — every named-group identifier
+// the framework knows by name. Operators with `allowOperatorGroups:
+// true` may pass any entry from this registry; entries outside it
+// still throw (catches typos / smuggled-separator attempts).
+var KNOWN_TLS_GROUPS = Object.freeze([
+  // PQC hybrids
+  "SecP384r1MLKEM1024",   // draft-kwiatkowski-tls-ecdhe-mlkem 0x11ED
+  "X25519MLKEM768",       // RFC 9794 0x11EC
+  "SecP256r1MLKEM768",    // RFC 9794 0x11EB
+  // Classical groups (operator opt-in only)
+  "X25519",
+  "secp256r1",            // allow:raw-byte-literal — IANA TLS group name (P-256), not bytes
+  "secp384r1",            // allow:raw-byte-literal — IANA TLS group name (P-384), not bytes
+  "secp521r1",            // allow:raw-byte-literal — IANA TLS group name (P-521), not bytes
+  "X448",
+]);
+
+function _validateGroupName(name) {
+  // Same shape as network-tls._validateKeyShare: alphanumeric +
+  // underscore, bounded length. Refuses `:` so an operator can't
+  // smuggle a second group through one slot.
+  if (typeof name !== "string" || name.length === 0 || name.length > 64) { // allow:raw-byte-literal — string-length cap, not bytes
+    throw new TypeError(
+      "pqc-agent: ecdhCurve group entries must be non-empty strings up to 64 chars"
+    );
+  }
+  if (!safeBuffer.BASE64URL_RE.test(name)) {
+    throw new TypeError(
+      "pqc-agent: ecdhCurve group '" + name + "' has illegal characters " +
+      "(must match [A-Za-z0-9_-]+)"
+    );
+  }
+}
 
 // Defaults for connection pooling. These ARE overridable via opts —
 // only the cryptographic posture (ecdhCurve / minVersion) is locked.
@@ -47,24 +87,59 @@ var DEFAULT_OPTS = {
 
 function _buildAgentOpts(opts) {
   opts = opts || {};
+  // allowOperatorGroups gates operator-supplied groups outside the
+  // framework PQC preference. Default false: caller may only narrow
+  // (subset of) TLS_GROUP_PREFERENCE. Set true and any KNOWN_TLS_GROUPS
+  // entry is permitted, including classical groups (operator's call
+  // — security-defaults posture says default no, opt-in yes). Each
+  // accepted operator group emits an audit event so the choice is
+  // visible in the audit log.
+  var allowOperatorGroups = opts.allowOperatorGroups === true;
   var merged = Object.assign({}, DEFAULT_OPTS, opts);
+  delete merged.allowOperatorGroups;
   // Caller may narrow the framework's curve preference list (drop a
   // group, keep the remaining ones in framework-preferred order) but
-  // cannot widen it. A caller-supplied `ecdhCurve` string is parsed
-  // into groups and every group must appear in TLS_GROUP_PREFERENCE,
-  // otherwise the agent build refuses. The empty narrowing is a
-  // misconfig — TLS won't negotiate a key share — so reject too.
+  // cannot widen it unless allowOperatorGroups: true is set. A
+  // caller-supplied `ecdhCurve` string is parsed into groups and each
+  // group is validated; the empty narrowing is a misconfig — TLS
+  // won't negotiate a key share — so reject too.
   if (typeof opts.ecdhCurve === "string" && opts.ecdhCurve.length > 0) {
     var requested = opts.ecdhCurve.split(":");
+    if (requested.length === 0) {
+      throw new TypeError(
+        "pqc-agent: opts.ecdhCurve must contain at least one group"
+      );
+    }
     for (var rgi = 0; rgi < requested.length; rgi++) {
-      if (C.TLS_GROUP_PREFERENCE.indexOf(requested[rgi]) === -1) {
+      var group = requested[rgi];
+      _validateGroupName(group);
+      if (C.TLS_GROUP_PREFERENCE.indexOf(group) !== -1) continue;
+      if (!allowOperatorGroups) {
         throw new TypeError(
           "pqc-agent: opts.ecdhCurve='" + opts.ecdhCurve + "' includes '" +
-          requested[rgi] + "' which is not in the framework PQC-hybrid " +
-          "preference (" + C.TLS_GROUP_CURVE_STR + "); construct an " +
-          "https.Agent directly to negotiate weaker groups."
+          group + "' which is not in the framework PQC-hybrid " +
+          "preference (" + C.TLS_GROUP_CURVE_STR + "); pass " +
+          "{ allowOperatorGroups: true } to accept operator-supplied " +
+          "groups, or construct an https.Agent directly."
+        );
+      }
+      if (KNOWN_TLS_GROUPS.indexOf(group) === -1) {
+        throw new TypeError(
+          "pqc-agent: opts.ecdhCurve group '" + group + "' is not a " +
+          "known IANA TLS Supported Group identifier"
         );
       }
+      // Operator-supplied group accepted — audit-emit so the
+      // framework-default deviation is visible to operators reading
+      // the audit log. safeEmit is drop-silent on error (audit bus
+      // failures must not break TLS agent construction).
+      try {
+        audit().safeEmit({
+          action:   "pqcagent.operator_group.accepted",
+          outcome:  "success",
+          metadata: { group: group, ecdhCurve: opts.ecdhCurve },
+        });
+      } catch (_e) { /* drop-silent — audit is best-effort here */ }
     }
     merged.ecdhCurve = requested.join(":");
   } else {
@@ -104,5 +179,6 @@ module.exports = {
   create:      create,
   createHttp:  createHttp,
   DEFAULT_OPTS: DEFAULT_OPTS,
+  KNOWN_TLS_GROUPS: KNOWN_TLS_GROUPS,
   enforced:    true,
 };