@blamejs/core 0.10.15 → 0.11.0

package/lib/importmap-integrity.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * @module b.importmapIntegrity
+ * @nav    HTTP
+ * @title  Import-Map Integrity
+ * @order  175
+ *
+ * @intro
+ *   WICG Import Maps + Subresource Integrity (SRI) extension. When
+ *   a page declares `<script type="importmap">`, each mapped module
+ *   SHOULD carry an `integrity` hash so the browser refuses to
+ *   execute the module if the bytes don't match.
+ *
+ *   `b.importmapIntegrity.build({ specifiers, sha256, sha384,
+ *   sha512 })` hashes each operator-supplied module body and emits
+ *   the `<script type="importmap">` JSON with an `integrity` map
+ *   alongside the `imports` map. Composes existing `b.crypto.sri`.
+ *
+ * @card
+ *   WICG Import Maps + SRI integrity builder. Emits importmap JSON with module-body SHA-384 hashes so browsers refuse unauthenticated module bytes.
+ */
+
+var validateOpts = require("./validate-opts");
+var bCrypto      = require("./crypto");
+var { defineClass } = require("./framework-error");
+
+var ImportmapError = defineClass("ImportmapError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.importmapIntegrity.build
+ * @signature b.importmapIntegrity.build(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build an import-map JSON shape `{ imports, integrity }` per WICG
+ * Import-Maps-SRI. Each module body is hashed with `opts.hash`
+ * (default sha384 per current SRI convention).
+ *
+ * @opts
+ *   modules:    { "<specifier>": { url, body: Buffer|string } },
+ *   hash:       "sha256"|"sha384"|"sha512",   // default sha384
+ *
+ * @example
+ *   var im = b.importmapIntegrity.build({
+ *     modules: {
+ *       "@org/lib": { url: "/static/lib.js", body: fileBytes },
+ *     },
+ *   });
+ *   res.end("<script type=\"importmap\">" + JSON.stringify(im) + "</script>");
+ */
+function build(opts) {
+  opts = validateOpts.requireObject(opts, "importmapIntegrity.build",
+    ImportmapError, "importmap/bad-opts");
+  validateOpts(opts, ["modules", "hash"], "importmapIntegrity.build");
+  if (!opts.modules || typeof opts.modules !== "object" || Array.isArray(opts.modules)) {
+    throw new ImportmapError("importmap/no-modules",
+      "build: opts.modules must be a non-array object");
+  }
+  var hash = opts.hash || "sha384";
+  if (hash !== "sha256" && hash !== "sha384" && hash !== "sha512") {
+    throw new ImportmapError("importmap/bad-hash",
+      "build: hash must be sha256 / sha384 / sha512");
+  }
+  var imports = {};
+  var integrity = {};
+  var keys = Object.keys(opts.modules);
+  for (var i = 0; i < keys.length; i += 1) {
+    var spec = keys[i];
+    var mod = opts.modules[spec];
+    if (!mod || typeof mod.url !== "string") {
+      throw new ImportmapError("importmap/bad-module",
+        "build: modules['" + spec + "'].url must be a string");
+    }
+    if (!Buffer.isBuffer(mod.body) && typeof mod.body !== "string") {
+      throw new ImportmapError("importmap/bad-module",
+        "build: modules['" + spec + "'].body must be a Buffer or string");
+    }
+    imports[spec] = mod.url;
+    // Compose b.crypto.sri — returns the canonical SRI string
+    // (e.g. `sha384-<base64>`). b.crypto.sri takes its hash from
+    // `opts.algorithm`, not a positional arg.
+    integrity[mod.url] = bCrypto.sri(mod.body, { algorithm: hash });
+  }
+  return { imports: imports, integrity: integrity };
+}
+
+module.exports = {
+  build:           build,
+  ImportmapError:  ImportmapError,
+};

package/lib/jsonapi.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * @module b.jsonApi
+ * @nav    HTTP
+ * @title  JSON:API
+ * @order  172
+ *
+ * @intro
+ *   JSON:API v1.1 (jsonapi.org/format/1.1/) response-shape helpers.
+ *   The framework's wire-format primitives compose this so operators
+ *   building JSON:API services get the right top-level shape + the
+ *   right Content-Type without re-implementing the spec each time.
+ *
+ *   Content-Type: `application/vnd.api+json`
+ *
+ *   Top-level shapes:
+ *     - `dataResponse(data, opts?)` — `{ data: [...] | {...}, included?, links?, meta? }`
+ *     - `errorResponse(errors)`     — `{ errors: [...] }`
+ *     - `linkObject(url, opts?)`    — string href OR `{ href, rel, meta }`
+ *
+ * @card
+ *   JSON:API v1.1 response shape builders. Content-Type negotiation, top-level data/errors/included/links/meta wrappers, error-object shape per §7.
+ */
+
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+
+var JsonApiError = defineClass("JsonApiError", { alwaysPermanent: true });
+
+var CONTENT_TYPE = "application/vnd.api+json";
+
+/**
+ * @primitive b.jsonApi.dataResponse
+ * @signature b.jsonApi.dataResponse(data, opts?)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build a JSON:API v1.1 success response. `data` can be a Resource
+ * Object, an array of Resource Objects, or null (for single-resource
+ * 404 / empty-collection responses). Each Resource Object must carry
+ * `type` + `id` (§7.2).
+ *
+ * @opts
+ *   included: ResourceObject[],   // compound documents §7.7
+ *   links:    object,             // top-level links §7.5
+ *   meta:     object,             // non-standard top-level meta §7.4
+ *   jsonapi:  object,             // jsonapi-object §7.3 (version etc.)
+ *
+ * @example
+ *   res.setHeader("Content-Type", "application/vnd.api+json");
+ *   res.end(JSON.stringify(b.jsonApi.dataResponse(
+ *     { type: "articles", id: "1", attributes: { title: "Hello" } },
+ *     { links: { self: "/articles/1" } }
+ *   )));
+ */
+function dataResponse(data, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["included", "links", "meta", "jsonapi"], "jsonApi.dataResponse");
+  if (data !== null && data !== undefined) {
+    if (Array.isArray(data)) {
+      for (var i = 0; i < data.length; i += 1) _assertResource(data[i], i);
+    } else {
+      _assertResource(data, null);
+    }
+  }
+  var out = { data: data === undefined ? null : data };
+  if (opts.included) {
+    if (!Array.isArray(opts.included)) {
+      throw new JsonApiError("json-api/bad-included",
+        "dataResponse: opts.included must be an array");
+    }
+    for (var j = 0; j < opts.included.length; j += 1) _assertResource(opts.included[j], j);
+    out.included = opts.included;
+  }
+  if (opts.links)   out.links   = opts.links;
+  if (opts.meta)    out.meta    = opts.meta;
+  if (opts.jsonapi) out.jsonapi = opts.jsonapi;
+  return out;
+}
+
+/**
+ * @primitive b.jsonApi.errorResponse
+ * @signature b.jsonApi.errorResponse(errors, opts?)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build a JSON:API v1.1 error response per §7.6. Each error object
+ * can carry `id` / `status` / `code` / `title` / `detail` / `source` /
+ * `links` / `meta`. The framework refuses errors lacking BOTH
+ * `status` and `title` (most JSON:API consumers need at least one).
+ *
+ * @opts
+ *   meta:     object,    // optional top-level `meta` block (JSON:API §5.3)
+ *   jsonapi:  object,    // optional top-level `jsonapi` member (JSON:API §5.2 — version / ext / profile)
+ *   links:    object,    // optional top-level `links` (JSON:API §5.4 — self / related / pagination)
+ *
+ * @example
+ *   res.statusCode = 422;
+ *   res.end(JSON.stringify(b.jsonApi.errorResponse([
+ *     { status: "422", code: "INVALID", title: "Invalid email",
+ *       source: { pointer: "/data/attributes/email" } },
+ *   ])));
+ */
+function errorResponse(errors, opts) {
+  opts = opts || {};
+  if (!Array.isArray(errors) || errors.length === 0) {
+    throw new JsonApiError("json-api/no-errors",
+      "errorResponse: errors must be a non-empty array");
+  }
+  var checked = errors.map(function (e, idx) {
+    if (!e || typeof e !== "object") {
+      throw new JsonApiError("json-api/bad-error",
+        "errorResponse: errors[" + idx + "] must be an object");
+    }
+    if (typeof e.status !== "string" && typeof e.title !== "string") {
+      throw new JsonApiError("json-api/empty-error",
+        "errorResponse: errors[" + idx + "] must have at least 'status' or 'title' (string)");
+    }
+    return e;
+  });
+  var out = { errors: checked };
+  if (opts.meta)    out.meta    = opts.meta;
+  if (opts.jsonapi) out.jsonapi = opts.jsonapi;
+  if (opts.links)   out.links   = opts.links;
+  return out;
+}
+
+function _assertResource(r, idx) {
+  if (!r || typeof r !== "object") {
+    throw new JsonApiError("json-api/bad-resource",
+      "Resource at " + (idx === null ? "<root>" : "index " + idx) + " must be an object");
+  }
+  if (typeof r.type !== "string" || r.type.length === 0) {
+    throw new JsonApiError("json-api/missing-type",
+      "Resource at " + (idx === null ? "<root>" : "index " + idx) + " missing 'type'");
+  }
+  // id is OPTIONAL only on client-side create requests; we don't have
+  // a way to distinguish, so we accept missing id (the operator's
+  // responsibility to set it for non-create paths).
+}
+
+/**
+ * @primitive b.jsonApi.parseQuery
+ * @signature b.jsonApi.parseQuery(queryString, opts?)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Parse a JSON:API v1.1 query string per §5 (Fetching Data). Returns
+ * `{ include, fields, filter, sort, page }`:
+ *   - `include` — array of relationship paths from `include=` (comma-split)
+ *   - `fields[type]` — array of sparse-fieldset selectors per type
+ *   - `filter` — pass-through object (spec defers filter shape to operators)
+ *   - `sort` — array of `{ field, asc }` per RFC 7159-style direction
+ *   - `page` — pass-through object (operator picks page-strategy)
+ *
+ * Refuses missing required `include` paths when opts.includeAllowlist is
+ * supplied and an unrecognized path appears.
+ *
+ * @opts
+ *   includeAllowlist:    string[],
+ *   sortAllowlist:       string[],
+ *   maxIncludeDepth:     number,    // default 5
+ *
+ * @example
+ *   var q = b.jsonApi.parseQuery(req.url.split("?")[1]);
+ *   q.include;         // → ["author", "comments.author"]
+ *   q.fields.articles; // → ["title", "body"]
+ *   q.sort;            // → [{ field: "createdAt", asc: false }]
+ */
+function parseQuery(queryString, opts) {
+  opts = opts || {};
+  if (typeof queryString !== "string") {
+    throw new JsonApiError("json-api/bad-query",
+      "parseQuery: queryString must be a string");
+  }
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxIncludeDepth, "maxIncludeDepth",
+    JsonApiError, "json-api/bad-max-include-depth");
+  var maxDepth = typeof opts.maxIncludeDepth === "number" ? opts.maxIncludeDepth : 5;
+  var out = { include: [], fields: {}, filter: {}, sort: [], page: {} };
+  if (queryString.length === 0) return out;
+  var pairs = queryString.split("&");
+  for (var i = 0; i < pairs.length; i += 1) {
+    var eq = pairs[i].indexOf("=");
+    if (eq === -1) continue;
+    var rawKey = decodeURIComponent(pairs[i].slice(0, eq));
+    var rawVal = decodeURIComponent(pairs[i].slice(eq + 1));
+    if (rawKey === "include") {
+      out.include = rawVal.split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+      for (var ii = 0; ii < out.include.length; ii += 1) {
+        var depth = out.include[ii].split(".").length;
+        if (depth > maxDepth) {
+          throw new JsonApiError("json-api/include-too-deep",
+            "parseQuery: include path '" + out.include[ii] + "' exceeds maxIncludeDepth=" + maxDepth);
+        }
+        if (Array.isArray(opts.includeAllowlist) &&
+            opts.includeAllowlist.indexOf(out.include[ii]) === -1) {
+          throw new JsonApiError("json-api/include-not-allowed",
+            "parseQuery: include path '" + out.include[ii] + "' not in allowlist");
+        }
+      }
+    } else if (rawKey === "sort") {
+      out.sort = rawVal.split(",").map(function (s) { return s.trim(); }).filter(Boolean).map(function (s) {
+        var asc = true;
+        if (s.charAt(0) === "-") { asc = false; s = s.slice(1); }
+        if (Array.isArray(opts.sortAllowlist) && opts.sortAllowlist.indexOf(s) === -1) {
+          throw new JsonApiError("json-api/sort-not-allowed",
+            "parseQuery: sort field '" + s + "' not in allowlist");
+        }
+        return { field: s, asc: asc };
+      });
+    } else if (rawKey.indexOf("fields[") === 0 && rawKey.charAt(rawKey.length - 1) === "]") {
+      var type = rawKey.slice(7, -1);                                                                 // allow:raw-byte-literal — `fields[` length
+      out.fields[type] = rawVal.split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    } else if (rawKey.indexOf("filter[") === 0 && rawKey.charAt(rawKey.length - 1) === "]") {
+      out.filter[rawKey.slice(7, -1)] = rawVal;                                                       // allow:raw-byte-literal — `filter[` length
+    } else if (rawKey.indexOf("page[") === 0 && rawKey.charAt(rawKey.length - 1) === "]") {
+      out.page[rawKey.slice(5, -1)] = rawVal;                                                         // allow:raw-byte-literal — `page[` length
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  dataResponse:  dataResponse,
+  errorResponse: errorResponse,
+  parseQuery:    parseQuery,
+  CONTENT_TYPE:  CONTENT_TYPE,
+  JsonApiError:  JsonApiError,
+};

package/lib/lro.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * @module b.lro
+ * @nav    HTTP
+ * @title  Long-Running Operations
+ * @order  178
+ *
+ * @intro
+ *   Google API Improvement Proposals AIP-151 (Long-Running Operations)
+ *   — a uniform shape for async APIs where the response can't be
+ *   computed within the request lifetime. The operator's POST
+ *   endpoint returns an Operation resource (`name` / `done` /
+ *   `metadata` / `response` | `error`) which the client polls at
+ *   `/operations/<name>` until `done: true`. Composes existing
+ *   `b.queue` / `b.jobs` for the actual work; this module just
+ *   ships the wire-shape + status-poll endpoint helpers.
+ *
+ *   `b.lro.create(opts)` returns `{ submit, status, list, cancel }`
+ *   wired to operator-supplied storage (in-memory by default for
+ *   single-process; ops with multiple workers wire `b.cache` /
+ *   `b.db` storage via `opts.store`).
+ *
+ * @card
+ *   AIP-151 Long-Running Operations — uniform Operation resource shape + submit / status / cancel endpoints. Composes b.queue / b.jobs for the actual work.
+ */
+
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var bCrypto      = require("./crypto");
+var C            = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var LroError = defineClass("LroError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.lro.create
+ * @signature b.lro.create(opts?)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Create an LRO registry. Returns `{ submit, status, list, cancel }`.
+ * Operations are tracked in `opts.store` (a Map-shaped object) or an
+ * in-memory Map when omitted. `submit({ work, metadata?, name? })`
+ * runs `work` async + returns the initial Operation resource;
+ * `status(name)` returns the current Operation (with `done: true`
+ * + `response` or `error` set when finished); `cancel(name)`
+ * surfaces cancellation back to the work function via the supplied
+ * AbortSignal.
+ *
+ * @opts
+ *   store:        Map-like { get, set, delete, keys },
+ *   namePrefix:   string, // default "operations/"
+ *   maxConcurrent: number, // soft cap; overflow refuses with lro/too-many
+ *
+ * @example
+ *   var lro = b.lro.create();
+ *   var op = await lro.submit({
+ *     work: async function (signal) { return await heavyJob(signal); },
+ *   });
+ *   res.statusCode = 202;
+ *   res.end(JSON.stringify(op));
+ *
+ *   // Later, on GET /operations/<name>:
+ *   res.end(JSON.stringify(lro.status(op.name)));
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["store", "namePrefix", "maxConcurrent"],
+    "lro.create");
+  var store = opts.store || new Map();
+  var prefix = opts.namePrefix || "operations/";
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxConcurrent, "maxConcurrent",
+    LroError, "lro/bad-max-concurrent");
+  var maxConcurrent = typeof opts.maxConcurrent === "number" ? opts.maxConcurrent : 1024;             // allow:raw-byte-literal — default in-flight cap
+
+  function _newName() { return prefix + bCrypto.generateToken(32); }                                  // allow:raw-byte-literal — 32-char name token
+
+  function submit(submitOpts) {
+    submitOpts = validateOpts.requireObject(submitOpts, "lro.submit",
+      LroError, "lro/bad-opts");
+    if (typeof submitOpts.work !== "function") {
+      throw new LroError("lro/no-work",
+        "submit: opts.work must be a function (signal) => Promise<result>");
+    }
+    var inFlight = 0;
+    var keys = store.keys ? Array.from(store.keys()) : [];
+    for (var i = 0; i < keys.length; i += 1) {
+      var op = store.get(keys[i]);
+      if (op && !op.done) inFlight += 1;
+    }
+    if (inFlight >= maxConcurrent) {
+      throw new LroError("lro/too-many",
+        "submit: " + inFlight + " operations in flight (cap " + maxConcurrent + ")");
+    }
+    var name = submitOpts.name || _newName();
+    var controller = (typeof AbortController === "function") ? new AbortController() : null;
+    var operation = {
+      name:     name,
+      done:     false,
+      metadata: submitOpts.metadata || {},
+      createdAt: new Date().toISOString(),
+    };
+    store.set(name, operation);
+    // Kick off the work async. Operator-supplied function MUST accept
+    // an AbortSignal (or ignore it). Errors land on operation.error;
+    // successful results land on operation.response per AIP-151 shape.
+    Promise.resolve()
+      .then(function () { return submitOpts.work(controller ? controller.signal : null); })
+      .then(function (response) {
+        var stored = store.get(name);
+        if (!stored) return;
+        // Cancellation precedes resolve — if `cancel()` flipped the
+        // operation to CANCELLED first AND the work function ignored
+        // the AbortSignal, do NOT overwrite the cancelled terminal
+        // state. AIP-151 §6.x: once an operation is `done: true`, it
+        // stays done with the first terminal state it landed in.
+        if (stored.done) return;
+        stored.done = true;
+        stored.response = (response === undefined) ? null : response;
+        stored.completedAt = new Date().toISOString();
+      }, function (err) {
+        var stored = store.get(name);
+        if (!stored) return;
+        // Same guard as the resolve path — once terminal, stay terminal.
+        if (stored.done) return;
+        stored.done = true;
+        // AIP-151 error: { code, message, details? } shape.
+        var msg = (err && err.message) || String(err);
+        stored.error = { code: 13, message: msg };                                                    // allow:raw-byte-literal — google.rpc.Code.INTERNAL = 13
+        if (err && err.code) stored.error.errorCode = err.code;
+        stored.completedAt = new Date().toISOString();
+      });
+    // Store the controller against the operation (off-resource, so
+    // serialisation doesn't accidentally export it).
+    operation._controller = controller;
+    return _stripPrivate(operation);
+  }
+
+  function status(name) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new LroError("lro/bad-name", "status: name must be a non-empty string");
+    }
+    var op = store.get(name);
+    if (!op) {
+      throw new LroError("lro/not-found", "status: no operation named '" + name + "'");
+    }
+    return _stripPrivate(op);
+  }
+
+  function list(filter) {
+    filter = filter || {};
+    var out = [];
+    var keys = store.keys ? Array.from(store.keys()) : [];
+    for (var i = 0; i < keys.length; i += 1) {
+      var op = store.get(keys[i]);
+      if (!op) continue;
+      if (filter.doneOnly && !op.done) continue;
+      if (filter.pendingOnly && op.done) continue;
+      out.push(_stripPrivate(op));
+    }
+    return out;
+  }
+
+  function cancel(name) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new LroError("lro/bad-name", "cancel: name must be a non-empty string");
+    }
+    var op = store.get(name);
+    if (!op) {
+      throw new LroError("lro/not-found", "cancel: no operation named '" + name + "'");
+    }
+    if (op.done) return _stripPrivate(op);
+    if (op._controller) {
+      try { op._controller.abort(); } catch (_e) { /* best-effort */ }
+    }
+    // Mark cancelled per AIP-151 — error.code 1 = CANCELLED.
+    op.done = true;
+    op.error = { code: 1, message: "operation cancelled" };                                           // allow:raw-byte-literal — google.rpc.Code.CANCELLED = 1
+    op.completedAt = new Date().toISOString();
+    return _stripPrivate(op);
+  }
+
+  void C;
+  return { submit: submit, status: status, list: list, cancel: cancel };
+}
+
+function _stripPrivate(op) {
+  var out = {};
+  var keys = Object.keys(op);
+  for (var i = 0; i < keys.length; i += 1) {
+    if (keys[i].charAt(0) === "_") continue;
+    out[keys[i]] = op[keys[i]];
+  }
+  return out;
+}
+
+module.exports = {
+  create:    create,
+  LroError:  LroError,
+};