@blamejs/core 0.8.42 → 0.8.49

package/lib/fdx.js

@@ -1,7 +1,36 @@
 "use strict";
 /**
- * b.fdx — CFPB §1033 / Financial Data Exchange (FDX) consumer-
- * financial-data sharing wrapper.
+ * @module b.fdx
+ * @nav    Compliance
+ * @title  FDX
+ *
+ * @intro
+ *   Financial Data Exchange (FDX) US open-banking standard —
+ *   consent records, SHA3 transaction hashes, data-recipient
+ *   registry.
+ *
+ *   CFPB §1033 (12 CFR §1033.121-461, final rule 2024-10-22) gives
+ *   US consumers the right to authorize a third party to access
+ *   their financial data through a covered data provider's
+ *   developer interface. FDX (https://financialdataexchange.org)
+ *   is the industry-standard schema + protocol the CFPB rule
+ *   effectively codifies (FDX 6.0+ aligns with the §1033 final
+ *   rule). Compliance deadline 2026-04-01 already past for $250B+
+ *   asset-size banks.
+ *
+ *   The framework can't be the operator's authorization server,
+ *   resource server, or FDX-data origin — those are the operator's
+ *   core banking system. What it can do: bind the operator's auth
+ *   server to the FAPI 2.0 profile (which §1033.351 effectively
+ *   requires), validate FDX response shapes, emit §1033-shape
+ *   audit events on every authorized data access, and generate
+ *   the §1033.401(b) consent receipt.
+ *
+ * @card
+ *   Financial Data Exchange (FDX) US open-banking standard — consent records, SHA3 transaction hashes, data-recipient registry.
+ */
+/*
+ * Original prose retained:
  *
  * CFPB §1033 (12 CFR §1033.121-461, final rule 2024-10-22) gives US
  * consumers the right to authorize a third party to access their
@@ -95,6 +124,42 @@ var FDX_SCHEMAS = {
   },
 };
 
+/**
+ * @primitive b.fdx.bind
+ * @signature b.fdx.bind(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance fdx, fapi2
+ * @related   b.fdx.validateResponse, b.fdx.consentReceipt, b.fapi2.assertOAuthConfig
+ *
+ * Bind an operator's authorization-server config to the FDX 6.0
+ * data-sharing surface and the FAPI 2.0 security profile. Refuses
+ * unknown FDX resources, refuses missing issuer/jwksUri, and runs
+ * `b.fapi2.assertOAuthConfig` on the supplied FAPI opts so a
+ * non-conformant deployment fails at boot. Returns a handle with
+ * `schemaValidator(resource, body)` and `consent.receipt(opts)`.
+ *
+ * @opts
+ *   authServer: {
+ *     issuer:  string,        // required, non-empty
+ *     jwksUri: string,        // required, non-empty
+ *     fapi2:   { pkce, dpop?, mtls?, par },
+ *   },
+ *   resources: ["accounts" | "transactions" | "statements" |
+ *               "payment-networks" | "rewards" | "tax-forms"],
+ *
+ * @example
+ *   var fdx = b.fdx.bind({
+ *     authServer: {
+ *       issuer:  "https://auth.example-bank.com",
+ *       jwksUri: "https://auth.example-bank.com/.well-known/jwks.json",
+ *       fapi2:   { pkce: true, mtls: true, par: true },
+ *     },
+ *     resources: ["accounts", "transactions"],
+ *   });
+ *   fdx.fapi2Posture;
+ *   // → "fapi-2.0"
+ */
 function bind(opts) {
   if (!opts || typeof opts !== "object") {
     throw FdxError.factory("BAD_OPTS", "fdx.bind: opts required");
@@ -150,6 +215,36 @@ function bind(opts) {
   };
 }
 
+/**
+ * @primitive b.fdx.validateResponse
+ * @signature b.fdx.validateResponse(resourceType, body)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance fdx
+ * @related   b.fdx.bind
+ *
+ * Validate an FDX response payload against the framework's FDX 6.0
+ * minimum-required-field schema. Accepts both envelope form
+ * (`{ accounts: [...] }`) and bare-array / single-record form.
+ * Returns `{ valid, errors }` so the operator can decide whether
+ * to refuse, redact, or pass through. Throws `FdxError` only when
+ * `resourceType` is unknown.
+ *
+ * @example
+ *   var result = b.fdx.validateResponse("accounts", {
+ *     accounts: [{
+ *       accountId:            "acct-1",
+ *       accountType:          "DEPOSIT",
+ *       accountNumberDisplay: "****1234",
+ *       currency:             "USD",
+ *       currentBalance:       1234.56,
+ *     }],
+ *   });
+ *   result.valid;
+ *   // → true
+ *   result.errors.length;
+ *   // → 0
+ */
 function validateResponse(resourceType, body) {
   var schema = FDX_SCHEMAS[resourceType];
   if (!schema) {
@@ -181,6 +276,41 @@ function validateResponse(resourceType, body) {
   return { valid: errors.length === 0, errors: errors };
 }
 
+/**
+ * @primitive b.fdx.consentReceipt
+ * @signature b.fdx.consentReceipt(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance fdx
+ * @related   b.fdx.bind
+ *
+ * Mint the §1033.401(b) consent receipt the authorization server
+ * gives the consumer at authorization time. Required fields:
+ * dataProvider, consumerRef, thirdParty, revocationUrl, scopes.
+ * Optional `durationMs` defaults to 52 weeks. Emits
+ * `fdx.consent_receipt_issued` to the audit chain so the regulator
+ * sees a record per receipt.
+ *
+ * @opts
+ *   dataProvider:  string,         // issuer / data provider name
+ *   consumerRef:   string,         // operator-side consumer identifier
+ *   thirdParty:    string,         // recipient name
+ *   revocationUrl: string,         // public revocation endpoint
+ *   scopes:        [string, ...],  // data scopes (account ids, resources)
+ *   durationMs:    number,         // optional; defaults to 52 weeks
+ *
+ * @example
+ *   var receipt = b.fdx.consentReceipt({
+ *     dataProvider:  "https://auth.example-bank.com",
+ *     consumerRef:   "consumer-42",
+ *     thirdParty:    "Aggregator Inc.",
+ *     revocationUrl: "https://example-bank.com/consent/revoke/abc",
+ *     scopes:        ["accounts", "transactions"],
+ *     durationMs:    365 * 86400 * 1000,
+ *   });
+ *   receipt.type;
+ *   // → "fdx.consent-receipt"
+ */
 function consentReceipt(opts) {
   if (!opts || typeof opts !== "object") {
     throw FdxError.factory("BAD_OPTS", "fdx.consentReceipt: opts required");

package/lib/file-type.js

@@ -1,4 +1,37 @@
 "use strict";
+/**
+ * @module b.fileType
+ * @nav    Validation
+ * @title  File Type
+ *
+ * @intro
+ *   Magic-byte content-type detection independent of the declared
+ *   MIME. The Content-Type header on a multipart upload is supplied
+ *   by the client; a hostile uploader can label a polyglot HTML
+ *   payload as `image/png` and the header alone won't catch it.
+ *   This primitive inspects the leading bytes against a hardcoded
+ *   signature registry (PNG / JPEG / GIF / WEBP / AVIF / HEIC / PDF /
+ *   OOXML / CFB / ZIP / RAR / 7Z / TAR / GZIP / BZ2 / XZ / MP3 / MP4
+ *   / WEBM / PE / ELF / Mach-O) and returns the actual format.
+ *
+ *   `detect(buf)` returns `null` rather than throwing on bad input
+ *   (saved-for-later analysis often runs against partial reads);
+ *   `assertOneOf(buf, allowlist)` throws `FileTypeError` when the
+ *   detected format is not in the operator-supplied allowlist.
+ *   Allowlist entries match against `mime` ("image/png"), short
+ *   `name` ("png"), or `category` ("image") — operators pin the
+ *   tightest level the use case allows.
+ *
+ *   Out of scope: content disarm (CDR), polyglot detection, and
+ *   filename-extension validation. Operators with disarm requirements
+ *   reach for a sandbox like dangerzone or vmray; filename extensions
+ *   live behind `b.guardFilename`. Operators extending the registry
+ *   pass `opts.extra` to `detect` — extras come first, letting an
+ *   operator override a built-in entry without forking.
+ *
+ * @card
+ *   Magic-byte content-type detection independent of the declared MIME.
+ */
 /**
  * file-type — magic-byte content detection.
  *
@@ -206,6 +239,32 @@ function _entryMatches(entry, buf) {
   return true;
 }
 
+/**
+ * @primitive b.fileType.detect
+ * @signature b.fileType.detect(buf, opts?)
+ * @since     0.1.0
+ * @related   b.fileType.assertOneOf, b.fileUpload.create
+ *
+ * Inspects the leading bytes of `buf` against the signature registry
+ * and returns `{ mime, extension, category, name }` for the first
+ * matching entry, or `null` when no signature matches (or `buf` is
+ * empty, or not a Buffer/Uint8Array). OOXML entries (`docx`/`xlsx`/
+ * `pptx`) sit before generic ZIP so well-formed Office files win
+ * before the bare ZIP shape; operators extending the registry via
+ * `opts.extra` get their entries scanned first so they can override
+ * built-ins without forking.
+ *
+ * @opts
+ *   extra: Array<{ name, mime, extension, category, offset, magic, extra? }>,
+ *
+ * @example
+ *   var fs = require("node:fs");
+ *   var buf = fs.readFileSync("photo.png");
+ *   b.fileType.detect(buf);
+ *   // → { mime: "image/png", extension: "png", category: "image", name: "png" }
+ *
+ *   b.fileType.detect(Buffer.from(""));   // → null
+ */
 function detect(buf, opts) {
   if (!Buffer.isBuffer(buf)) {
     if (buf instanceof Uint8Array) buf = Buffer.from(buf);
@@ -227,6 +286,34 @@ function detect(buf, opts) {
   return null;
 }
 
+/**
+ * @primitive b.fileType.assertOneOf
+ * @signature b.fileType.assertOneOf(buf, allowlist, opts?)
+ * @since     0.1.0
+ * @related   b.fileType.detect, b.fileUpload.create
+ *
+ * Detects the format of `buf` and throws `FileTypeError` when the
+ * result is not in `allowlist`. Allowlist entries match by `mime`
+ * ("image/png"), short `name` ("png"), or `category` ("image") so
+ * operators pin the tightest level the use case allows. Empty
+ * buffers throw `EMPTY` unless `opts.allowEmpty: true`. Unrecognized
+ * magic bytes throw `UNKNOWN_TYPE` — the framework refuses to fall
+ * back to the advertised header MIME because the entire purpose of
+ * this primitive is mistrusting that header.
+ *
+ * @opts
+ *   allowEmpty: boolean,                                                // default false
+ *   extra:      Array<{ name, mime, extension, category, offset, magic, extra? }>,
+ *
+ * @example
+ *   var fs = require("node:fs");
+ *   var buf = fs.readFileSync("photo.png");
+ *   var detected = b.fileType.assertOneOf(buf, ["image/png", "image/jpeg"]);
+ *   // → { mime: "image/png", extension: "png", category: "image", name: "png" }
+ *
+ *   // Category-level allowlist (any image format)
+ *   b.fileType.assertOneOf(buf, ["image"]);
+ */
 function assertOneOf(buf, allowlist, opts) {
   opts = opts || {};
   if (!Buffer.isBuffer(buf) && !(buf instanceof Uint8Array)) {

package/lib/file-upload.js

@@ -1,4 +1,39 @@
 "use strict";
+/**
+ * @module b.fileUpload
+ * @nav    HTTP
+ * @title  File Upload
+ *
+ * @intro
+ *   Streaming multipart upload with content-safety guards wired on
+ *   by default. Init / acceptChunk / finalize lifecycle: operator
+ *   calls `init` to allocate per-upload staging, streams chunks via
+ *   `acceptChunk` (each carrying its own SHA3-512 hex), then calls
+ *   `finalize` with a manifest so the framework can verify per-chunk
+ *   + total hash, sniff magic bytes against an `allowedFileTypes`
+ *   allowlist, and hand off to the operator's `onFinalize` (buffer
+ *   for small uploads, Readable stream above `maxStreamReassemblyBytes`).
+ *
+ *   Default-on safety: `b.guardAll.byExtension({ profile: "strict" })`
+ *   for content gating and `b.guardFilename.gate({ profile: "strict" })`
+ *   for filename gating. Operators opt out via `contentSafety: null`
+ *   / `filenameSafety: null` (audited at create time so a security
+ *   review can find the disabled-on-deploy rows). Per-chunk hooks
+ *   (`onChunk`) are the integration point for virus scanners and
+ *   schema-shape checks; rejecting from the hook surfaces as a
+ *   permanent `FileUploadError`.
+ *
+ *   Quotas: `maxFileBytes`, `maxChunkBytes`, `maxStagingBytes`,
+ *   `maxActiveUploadsPerActor`, `maxChunks`, `incompleteTtlMs`,
+ *   `maxIdleMs`. `purgeIncomplete()` reclaims TTL'd / idle staging
+ *   directories — operators wire it to `b.scheduler` for a cron-shaped
+ *   sweep. Permission scopes (`fileUpload.init` / `accept` / `finalize`
+ *   / `status` / `list` / `cancel`) are checked through `b.permissions`
+ *   when wired.
+ *
+ * @card
+ *   Streaming multipart upload with content-safety guards wired on by default.
+ */
 /**
  * b.fileUpload — chunked file upload primitive.
  *
@@ -282,6 +317,64 @@ function _validateCreateOpts(opts) {
   }
 }
 
+/**
+ * @primitive b.fileUpload.create
+ * @signature b.fileUpload.create(opts)
+ * @since     0.7.2
+ * @related   b.fileType.detect, b.fileType.assertOneOf
+ *
+ * Builds an upload manager bound to `opts.stagingDir`. The returned
+ * object exposes `init`, `acceptChunk`, `finalize`, `status`, `list`,
+ * `cancelUpload`, `purgeIncomplete`, and `close`. Uploads are written
+ * chunk-per-file under a per-upload directory (mode 0o700); finalize
+ * walks the manifest in order, verifies per-chunk + total SHA3-512,
+ * runs the magic-byte allowlist (when `allowedFileTypes` is set), and
+ * hands the assembled buffer (or a stream above `maxStreamReassemblyBytes`)
+ * to the operator's `onFinalize`.
+ *
+ * Per-chunk and per-upload audits flow through the wired `audit` and
+ * `observability` instances. Quota refusals, hash mismatches, MIME-claim
+ * disagreement, filename-safety refusal, and content-safety refusal all
+ * throw `FileUploadError` with `permanent: true` — no retry succeeds.
+ *
+ * @opts
+ *   stagingDir:                string,                 // absolute path; created mode 0o700 if missing
+ *   maxFileBytes:              number,                 // default 2 GiB
+ *   maxChunkBytes:             number,                 // default 8 MiB
+ *   maxStreamReassemblyBytes:  number,                 // above this finalize streams; default 64 MiB
+ *   maxStagingBytes:           number,                 // default 50 GiB
+ *   maxActiveUploadsPerActor:  number,                 // default 16
+ *   maxChunks:                 number,                 // default 16384
+ *   incompleteTtlMs:           number,                 // since createdAt; default 24h
+ *   maxIdleMs:                 number,                 // since lastChunkAt; default 30m
+ *   allowedFileTypes:          string[],               // MIME allowlist; "image/*" wildcard supported
+ *   audit:                     b.audit,
+ *   observability:             b.observability,
+ *   permissions:               b.permissions,          // optional; gates init/accept/finalize/status/list/cancel
+ *   fileType:                  b.fileType,             // required when allowedFileTypes is non-empty
+ *   contentSafety:             Object | null,          // ext→gate map; null = audited opt-out; undefined = b.guardAll.byExtension({ profile: "strict" })
+ *   filenameSafety:            Object | null,          // gate; null = audited opt-out; undefined = b.guardFilename.gate({ profile: "strict" })
+ *   onChunk:                   async function (info),  // optional per-chunk hook
+ *   onFinalize:                async function (info),  // operator decides final storage
+ *   clock:                     function () → number,    // test-fixture clock; default Date.now
+ *
+ * @example
+ *   var uploads = b.fileUpload.create({
+ *     stagingDir:        "/var/lib/myapp/uploads",
+ *     maxFileBytes:      C.BYTES.gib(2),
+ *     allowedFileTypes:  ["image/png", "image/jpeg", "application/pdf"],
+ *     fileType:          b.fileType,
+ *     audit:             b.audit,
+ *     observability:     b.observability,
+ *     onFinalize:        async function (info) {
+ *       // → info.body / info.stream → operator's storage layer
+ *       return { ok: true, sha3: info.sha3, size: info.size };
+ *     },
+ *   });
+ *
+ *   await uploads.init({ uploadId: "u-1", actor: { id: "ada" }, metadata: { filename: "photo.png" } });
+ *   // → { uploadId: "u-1", createdAt: 1762560000000, expiresAt: 1762646400000 }
+ */
 function create(opts) {
   _validateCreateOpts(opts);
   var cfg = validateOpts.applyDefaults(opts, DEFAULTS);

package/lib/flag.js

@@ -1,29 +1,40 @@
 "use strict";
 /**
- * b.flag — feature-flag client per the OpenFeature specification
- * (https://openfeature.dev/specification/).
+ * @module b.flag
+ * @nav    Tools
+ * @title  Flag
  *
- *   var flag = b.flag.create({
- *     provider: b.flag.providers.localFile({ path: "./flags.json" }),
- *     defaultEvaluationContext: { environment: "production" },
- *   });
- *
- *   var enabled = flag.getBoolean("new-checkout-flow", { targetingKey: req.user.id });
- *   var sample  = flag.getString ("greeting-banner", { targetingKey: req.user.id }, "default-text");
- *   var rate    = flag.getNumber ("upsell-rate",     { targetingKey: req.user.id }, 0);
- *   var cfg     = flag.getObject ("checkout-config", { targetingKey: req.user.id }, {});
+ * @intro
+ *   Feature-flag primitive shaped to the OpenFeature specification
+ *   (https://openfeature.dev/specification/). Per-tenant overrides
+ *   ride on the targeting context (`{ targetingKey, environment,
+ *   ...attrs }`); every flip of a flag value at the provider layer
+ *   audits via `flag.evaluated` / `flag.evaluation.error` on the
+ *   framework audit chain so operators see the change without scraping
+ *   provider state. Kill-switch semantics fall out of the same
+ *   resolution chain: a provider that returns `value: false` for a
+ *   targeting key disables the gated path immediately — no client
+ *   restart, no cache flush.
  *
- *   var details = flag.getDetails("new-checkout-flow", ctx);
- *   //  → { value, variant, reason, metadata }
+ *   Validation policy:
+ *     - `create()` throws on bad opts (provider missing
+ *       `.evaluate(flagKey, ctx)`, hooks not function-shaped, etc.).
+ *     - The hot path (`getBoolean` / `getString` / `getNumber` /
+ *       `getObject` / `getValue`) NEVER throws — a provider that
+ *       errors emits `flag.evaluation.error` and the call returns
+ *       the operator-supplied default. A request can't be taken down
+ *       by a misconfigured flag.
  *
- *   flag.middleware()  → request-time middleware that attaches a
- *                         per-request `flag` accessor onto req.
+ *   Composability: `flag.middleware({ userKey })` attaches a
+ *   per-request `req.flag` accessor that bakes the request's
+ *   targeting context in, so handlers call `req.flag.getBoolean(key)`
+ *   without threading context through every site. Multiple providers
+ *   can be stacked via `opts.providers` or `addProvider`/`removeProvider`
+ *   — first non-`flag_not_found` response wins, so a local-file
+ *   override beats the central provider for break-glass scenarios.
  *
- * Per the validation-tier policy: create() throws on bad opts; the
- * hot-path getValue / getBoolean / etc. NEVER throw — they return the
- * operator-supplied default + emit `flag.evaluation.error` on the
- * audit chain so the operator sees the problem without taking down
- * the request.
+ * @card
+ *   Feature-flag primitive shaped to the OpenFeature specification (https://openfeature.dev/specification/).
  */
 
 var validateOpts   = require("./validate-opts");
@@ -60,6 +71,57 @@ function _validateHooks(rawHooks) {
   return out;
 }
 
+/**
+ * @primitive b.flag.create
+ * @signature b.flag.create(opts)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.audit.safeEmit
+ *
+ * Build an OpenFeature-shaped flag client backed by one or more
+ * providers. The returned object exposes typed getters
+ * (`getBoolean` / `getString` / `getNumber` / `getObject` / `getValue`),
+ * a richer `getDetails(flagKey, ctx)` (returns
+ * `{ value, variant, reason, metadata }`), batch helpers (`getValues` /
+ * `getDetailsAll`), provider mutation (`addProvider` / `removeProvider`),
+ * and `middleware({ userKey })` for per-request binding.
+ *
+ * Throws `FlagError` at config time on a missing provider, hooks not
+ * shaped as `{ before?, after?, error?, finally? }` functions, or a
+ * provider lacking `.evaluate(flagKey, ctx)`.
+ *
+ * @opts
+ *   provider:                  { evaluate: (flagKey, ctx) => result, kind?: string, list?: () => [string] },
+ *   providers:                 [provider],                    // additional providers (first non-not-found wins)
+ *   defaultEvaluationContext:  { targetingKey?: string, [attr: string]: any },
+ *   audit:                     boolean,                        // emit flag.evaluated / flag.evaluation.error; default true
+ *   errorHandler:              ({ flagKey, err, ctx }) => void,
+ *   hooks:                     { before?: fn, after?: fn, error?: fn, finally?: fn }, // OpenFeature hook stages
+ *
+ * @example
+ *   var provider = {
+ *     kind: "memory",
+ *     evaluate: function (flagKey, ctx) {
+ *       if (flagKey === "new-checkout-flow") {
+ *         return { value: ctx.targetingKey === "user-42", variant: "on", reason: "TARGETING_MATCH" };
+ *       }
+ *       return { reason: "flag_not_found" };
+ *     },
+ *   };
+ *
+ *   var flag = b.flag.create({
+ *     provider: provider,
+ *     defaultEvaluationContext: { environment: "production" },
+ *   });
+ *
+ *   flag.getBoolean("new-checkout-flow", { targetingKey: "user-42" });   // → true
+ *   flag.getBoolean("new-checkout-flow", { targetingKey: "user-99" });   // → false
+ *   flag.getString ("missing-key",       { targetingKey: "u" }, "fallback");   // → "fallback"
+ *
+ *   // Per-request binding via middleware:
+ *   //   app.use(flag.middleware({ userKey: "id" }));
+ *   //   // handler: if (req.flag.getBoolean("new-checkout-flow")) { ... }
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [