@blamejs/core 0.8.43 → 0.8.50

package/lib/storage.js

@@ -1,61 +1,41 @@
 "use strict";
 /**
- * Storage abstraction — multi-backend, classification-routed, residency-
- * enforced file storage with per-file vault-sealed encryption.
- *
- * Two configuration shapes (both supported, internally normalized to
- * the multi-backend form):
- *
- *   1. Single-backend (legacy shape — preserved):
- *        storage.init({ backend: 'local', uploadDir: './data/uploads' })
- *
- *   2. Multi-backend:
- *        storage.init({
- *          backends: {
- *            'eu-private': { protocol: 'http-put', baseUrl: '...',
- *                            classifications: ['personal'], residencyTag: 'EU' },
- *            'us-ops':     { protocol: 'local', rootDir: '/data/ops',
- *                            classifications: ['operational', 'public'],
- *                            residencyTag: 'US' },
- *          },
- *          defaultClassification: 'personal',
- *          refuseUnclassified:    true,
- *        });
- *
- * Classification routing (per-call):
- *   storage.saveFile(buf, 'invoice.pdf', { classification: 'personal' })
- *     → routes to a backend whose `classifications` includes 'personal'.
- *   storage.saveFile(buf, 'logo.png', { backend: 'us-ops' })
- *     → explicit backend; framework still validates the backend serves
- *        the classification.
- *
- * Residency enforcement (boot-time):
- *   - If db.getDataResidency() declares a region, every backend serving the
- *     'personal' classification must have residencyTag === region (or be
- *     listed in dataResidency.allowedStorageRegions).
- *   - Refuses to boot otherwise — catches operator misconfiguration where
- *     a US-region backend was configured for personal data in an EU app.
- *
- * Audit hooks:
- *   - Every saveFile records a 'system.storage.write' event with metadata
- *     { backend, classification, residencyTag, sizeBytes }.
- *   - getFile records 'system.storage.read'.
- *   - delete records 'system.storage.delete'.
- *
- * Public API (sync entry, async ops since backends may be remote):
- *   storage.init(opts)                                            (sync)
- *   storage.saveFile(buffer, key, opts?)        async →  { storedPath, encryptionKey, backend, classification }
- *   storage.getFileBuffer(storedPath, sealedKey, opts?) async → Buffer
- *   storage.getFileStream(storedPath, sealedKey, opts?) async → Readable
- *   storage.saveRaw(buffer, key, opts?)         async → { storedPath, backend }
- *   storage.getRawBuffer(storedPath, opts?)     async → Buffer
- *   storage.deleteFile(storedPath, opts?)       async → boolean
- *   storage.exists(storedPath, opts?)           async → boolean
- *   storage.presignedUploadUrl(key, opts?)              → { url, method, headers, expiresAt }
- *   storage.presignedDownloadUrl(key, opts?)            → { url, method, headers, expiresAt }
- *   storage.presignedUploadPolicy(key, opts)            → { url, method, fields, expiresAt, maxBytes, enforcement }
- *   storage.listBackends()                              → [{ name, protocol, classifications, residencyTag }]
- *   storage.getBackend(name)                            → backend instance (or null)
+ * @module b.storage
+ * @featured true
+ * @nav    Data
+ * @title  Storage
+ *
+ * @intro
+ *   Filesystem-and-cloud-backed object storage with sealed per-file
+ *   encryption keys, classification routing, and residency enforcement.
+ *
+ *   `b.storage` sits one layer above `b.objectStore`: the lower
+ *   primitive abstracts the byte-level adapter (local FS, sigv4-style
+ *   S3-compatible, GCS, Azure Blob, generic HTTP-PUT); this module
+ *   adds the framework-shaped policy on top — multi-backend
+ *   registration, per-call classification → backend dispatch,
+ *   boot-time residency validation against `b.db.getDataResidency()`,
+ *   per-file XChaCha20-Poly1305 encryption with the data key sealed
+ *   into the framework's vault, and audit-chain emission for every
+ *   read / write / delete / presign.
+ *
+ *   Configuration accepts either the legacy single-backend shape
+ *   (`{ backend, uploadDir }`) or the multi-backend shape
+ *   (`{ backends: { name: cfg, ... }, defaultClassification,
+ *   refuseUnclassified }`). Both normalize internally to the
+ *   multi-backend form. `refuseUnclassified: true` forces every call
+ *   to declare its `classification` explicitly, which is the right
+ *   posture for apps mixing personal / operational / public data
+ *   across different residency zones.
+ *
+ *   Encrypted save/get is the default surface (`saveFile` /
+ *   `getFileBuffer` / `getFileStream`); `saveRaw` / `getRawBuffer`
+ *   skip the per-file encryption envelope for content that is
+ *   already-public or already-encrypted (e.g. signed image assets,
+ *   pre-encrypted backup bundles).
+ *
+ * @card
+ *   Filesystem-and-cloud-backed object storage with sealed per-file encryption keys, classification routing, and residency enforcement.
  */
 var C = require("./constants");
 var { generateBytes, encryptPacked, decryptPacked } = require("./crypto");
@@ -76,6 +56,52 @@ var _err = StorageError.factory;
 
 // ---- Init ----
 
+/**
+ * @primitive b.storage.init
+ * @signature b.storage.init(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.saveFile, b.storage.listBackends, b.objectStore.buildBackend
+ *
+ * Register one or more storage backends and lock the framework into
+ * the configured policy. Idempotent — a second call after the first
+ * succeeds is a no-op (operators rebuild via `_resetForTest` only).
+ * Validates classification → residency mapping at boot so a
+ * misconfigured deployment (US backend serving EU personal data)
+ * fails fast instead of leaking on first write.
+ *
+ * @opts
+ *   backend:                "local" | "sigv4" | "gcs" | "azure-blob" | "http-put",  // single-backend shorthand
+ *   uploadDir:              string,             // local backend root (single-backend shorthand)
+ *   backends:               object,             // multi-backend map: name -> backend cfg
+ *   defaultClassification:  string,             // applied when a call omits { classification }
+ *   refuseUnclassified:     boolean,            // refuse calls without explicit classification
+ *
+ * @example
+ *   // Single-backend, local FS — typical small-app shape.
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *
+ * @example
+ *   // Multi-backend with classification routing + residency tags.
+ *   b.storage.init({
+ *     backends: {
+ *       "eu-private": {
+ *         protocol:        "local",
+ *         rootDir:         "/srv/eu/private",
+ *         classifications: ["personal"],
+ *         residencyTag:    "EU",
+ *       },
+ *       "us-ops": {
+ *         protocol:        "local",
+ *         rootDir:         "/srv/us/ops",
+ *         classifications: ["operational", "public"],
+ *         residencyTag:    "US",
+ *       },
+ *     },
+ *     defaultClassification: "operational",
+ *     refuseUnclassified:    true,
+ *   });
+ */
 function init(opts) {
   if (initialized) return;
   if (!opts) throw _err("INVALID_CONFIG", "storage.init() requires options", true);
@@ -244,6 +270,37 @@ function _emit(action, info) {
 
 // ---- Public API ----
 
+/**
+ * @primitive b.storage.saveFile
+ * @signature b.storage.saveFile(buffer, key, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @compliance gdpr, hipaa, pci-dss, soc2
+ * @related   b.storage.getFileBuffer, b.storage.deleteFile, b.storage.saveRaw
+ *
+ * Encrypt `buffer` under a fresh XChaCha20-Poly1305 data key, seal
+ * the data key into the framework vault, and write the ciphertext to
+ * the backend selected by `opts.classification` (or `opts.backend`
+ * for explicit pinning). Returns the storage path plus the sealed
+ * key the caller MUST persist alongside the row that references the
+ * blob — without it, the bytes are unrecoverable. Emits a
+ * `system.storage.write` audit event with `{ backend, classification,
+ * residencyTag, sizeBytes }`.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name (still validates classification serve)
+ *
+ * @example
+ *   var buf = Buffer.from("invoice pdf bytes");
+ *   var saved = await b.storage.saveFile(buf, "invoices/2026/001.pdf", {
+ *     classification: "personal",
+ *   });
+ *   // → { storedPath: "invoices/2026/001.pdf",
+ *   //     encryptionKey: "v1:...",   // sealed; persist with the row
+ *   //     backend: "eu-private",
+ *   //     classification: "personal" }
+ */
 async function saveFile(buffer, key, opts) {
   _requireInit();
   if (!Buffer.isBuffer(buffer)) throw _err("INVALID_BODY", "saveFile body must be a Buffer", true);
@@ -268,6 +325,31 @@ async function saveFile(buffer, key, opts) {
   };
 }
 
+/**
+ * @primitive b.storage.getFileBuffer
+ * @signature b.storage.getFileBuffer(key, sealedKey, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.saveFile, b.storage.getFileStream
+ *
+ * Fetch the ciphertext at `key` from the routed backend, unseal the
+ * per-file data key via the framework vault, and return the
+ * decrypted plaintext as a Buffer. The AEAD tag is verified before
+ * any plaintext is released — a tampered ciphertext throws
+ * `crypto/decrypt-failed`, never returns partial bytes. Emits
+ * `system.storage.read` with `{ backend, key, sizeBytes }`.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *
+ * @example
+ *   // Round-trip a small text payload through saveFile/getFileBuffer.
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   var saved = await b.storage.saveFile(Buffer.from("hello"), "greet.txt");
+ *   var roundTrip = await b.storage.getFileBuffer("greet.txt", saved.encryptionKey);
+ *   roundTrip.toString("utf8");   // → "hello"
+ */
 async function getFileBuffer(key, sealedKey, opts) {
   _requireInit();
   opts = opts || {};
@@ -284,6 +366,33 @@ async function getFileBuffer(key, sealedKey, opts) {
   return decrypted;
 }
 
+/**
+ * @primitive b.storage.getFileStream
+ * @signature b.storage.getFileStream(key, sealedKey, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.getFileBuffer, b.storage.saveFile
+ *
+ * Buffer-then-stream variant of `getFileBuffer` — returns a
+ * `stream.Readable` once the AEAD tag has verified the entire
+ * ciphertext. Per-file XChaCha20-Poly1305 needs the whole frame
+ * before it can release the first byte; chunked AEAD with
+ * per-chunk tags would let us stream end-to-end at the cost of
+ * finer-grained tampering windows, so the framework defaults to
+ * the safe variant.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   var saved = await b.storage.saveFile(Buffer.from("stream-me"), "blob.bin");
+ *   var stream = await b.storage.getFileStream("blob.bin", saved.encryptionKey);
+ *   var chunks = [];
+ *   for await (var chunk of stream) chunks.push(chunk);
+ *   Buffer.concat(chunks).toString("utf8");   // → "stream-me"
+ */
 async function getFileStream(key, sealedKey, opts) {
   // Buffer-then-stream: per-file XChaCha20 encryption needs the whole
   // ciphertext to verify the AEAD tag before any plaintext can be released
@@ -293,6 +402,29 @@ async function getFileStream(key, sealedKey, opts) {
   return require("stream").Readable.from(buf);
 }
 
+/**
+ * @primitive b.storage.saveRaw
+ * @signature b.storage.saveRaw(buffer, key, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.saveFile, b.storage.getRawBuffer
+ *
+ * Write `buffer` to the routed backend as-is, skipping the per-file
+ * encryption envelope. Use for content that is already public
+ * (signed CDN assets, image thumbnails) or already encrypted
+ * (pre-sealed backup bundles); use `saveFile` for everything else.
+ * Audit metadata records `raw: true` so storage reads in the audit
+ * chain can be distinguished from encrypted reads.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   var saved = await b.storage.saveRaw(Buffer.from("public-bytes"), "logo.png");
+ *   // → { storedPath: "logo.png", backend: "default" }
+ */
 async function saveRaw(buffer, key, opts) {
   _requireInit();
   if (!Buffer.isBuffer(buffer)) throw _err("INVALID_BODY", "saveRaw body must be a Buffer", true);
@@ -312,6 +444,28 @@ async function saveRaw(buffer, key, opts) {
   return { storedPath: key, backend: picked.backend.name };
 }
 
+/**
+ * @primitive b.storage.getRawBuffer
+ * @signature b.storage.getRawBuffer(key, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.saveRaw, b.storage.getFileBuffer
+ *
+ * Fetch the raw bytes at `key` from the routed backend. No
+ * decryption layer is applied — the caller receives whatever was
+ * stored, byte-for-byte. Pair with `saveRaw`; for encrypted blobs
+ * use `getFileBuffer` instead so the AEAD tag is verified.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   await b.storage.saveRaw(Buffer.from("raw-payload"), "asset.bin");
+ *   var bytes = await b.storage.getRawBuffer("asset.bin");
+ *   bytes.toString("utf8");   // → "raw-payload"
+ */
 async function getRawBuffer(key, opts) {
   _requireInit();
   opts = opts || {};
@@ -319,6 +473,34 @@ async function getRawBuffer(key, opts) {
   return picked.backend.get(key);
 }
 
+/**
+ * @primitive b.storage.deleteFile
+ * @signature b.storage.deleteFile(key, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @compliance gdpr
+ * @related   b.storage.saveFile, b.storage.exists
+ *
+ * Remove `key` from the routed backend. Returns `true` when the
+ * object existed and was removed, `false` when it was already
+ * absent. Emits `system.storage.delete` with `{ backend, key,
+ * existed }` so the audit chain records GDPR right-to-erasure
+ * flows. The sealed encryption key the caller persisted alongside
+ * the row should be discarded by the caller after a successful
+ * delete — without the bytes, the key has no recovery value.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   await b.storage.saveRaw(Buffer.from("doomed"), "tmp/x.bin");
+ *   var existed = await b.storage.deleteFile("tmp/x.bin");
+ *   // → true
+ *   var second = await b.storage.deleteFile("tmp/x.bin");
+ *   // → false
+ */
 async function deleteFile(key, opts) {
   _requireInit();
   opts = opts || {};
@@ -334,6 +516,31 @@ async function deleteFile(key, opts) {
   return result;
 }
 
+/**
+ * @primitive b.storage.exists
+ * @signature b.storage.exists(key, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.deleteFile, b.storage.getFileBuffer
+ *
+ * HEAD-style existence check — returns `true` when the routed
+ * backend reports the key present, `false` on `NOT_FOUND`. Other
+ * backend errors propagate so transient outages aren't swallowed
+ * as "doesn't exist." Cheaper than a full GET when the caller only
+ * needs to gate a downstream operation on presence.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   await b.storage.saveRaw(Buffer.from("here"), "probe.bin");
+ *   var present = await b.storage.exists("probe.bin");
+ *   // → true
+ *   var missing = await b.storage.exists("nope.bin");
+ *   // → false
+ */
 async function exists(key, opts) {
   _requireInit();
   opts = opts || {};
@@ -347,6 +554,25 @@ async function exists(key, opts) {
   }
 }
 
+/**
+ * @primitive b.storage.listBackends
+ * @signature b.storage.listBackends()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.storage.getBackend, b.storage.init
+ *
+ * Snapshot every registered backend with `{ name, protocol,
+ * classifications, residencyTag, breakerState }`. The
+ * `breakerState` is the live circuit-breaker state from the
+ * underlying `b.objectStore` adapter — handy for ops dashboards
+ * surfacing a degraded backend before it cascades.
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   var info = b.storage.listBackends();
+ *   info[0].name;       // → "default"
+ *   info[0].protocol;   // → "local"
+ */
 function listBackends() {
   _requireInit();
   var out = [];
@@ -389,23 +615,138 @@ function _presign(direction, key, opts) {
   return result;
 }
 
+/**
+ * @primitive b.storage.presignedUploadUrl
+ * @signature b.storage.presignedUploadUrl(key, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.storage.presignedDownloadUrl, b.storage.presignedUploadPolicy
+ *
+ * Issue a short-lived signed URL the client uses to PUT bytes
+ * directly to the object store, bypassing the framework process
+ * for the upload bytes. Backend-dependent: sigv4 / gcs / azure-blob
+ * support it natively; local / http-put backends throw
+ * `PRESIGN_NOT_SUPPORTED`. Emits `system.storage.presign` with
+ * `direction: "upload"`.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *   expiresInSec:    number,    // URL lifetime; backend-defaulted when omitted
+ *   contentType:     string,    // pin the upload Content-Type into the signature
+ *
+ * @example
+ *   b.storage.init({
+ *     backends: {
+ *       "us-ops": {
+ *         protocol:        "sigv4",
+ *         endpoint:        "https://s3.us-east-1.amazonaws.com",
+ *         region:          "us-east-1",
+ *         bucket:          "uploads",
+ *         accessKeyId:     "AKIAEXAMPLE",
+ *         secretAccessKey: "secret",
+ *         classifications: ["operational"],
+ *         residencyTag:    "US",
+ *       },
+ *     },
+ *   });
+ *   var presigned = b.storage.presignedUploadUrl("incoming/x.bin", {
+ *     backend:      "us-ops",
+ *     expiresInSec: 300,
+ *   });
+ *   presigned.method;   // → "PUT"
+ */
 function presignedUploadUrl(key, opts)   { return _presign("Upload", key, opts); }
+
+/**
+ * @primitive b.storage.presignedDownloadUrl
+ * @signature b.storage.presignedDownloadUrl(key, opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.storage.presignedUploadUrl, b.storage.getFileBuffer
+ *
+ * Issue a short-lived signed URL the client uses to GET bytes
+ * directly from the object store. Same backend-support matrix as
+ * the upload variant. Use this only with `saveRaw` content —
+ * encrypted blobs (`saveFile`) need the per-file sealed key, which
+ * the framework does not expose to the client.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *   expiresInSec:    number,    // URL lifetime; backend-defaulted when omitted
+ *
+ * @example
+ *   b.storage.init({
+ *     backends: {
+ *       "us-ops": {
+ *         protocol:        "sigv4",
+ *         endpoint:        "https://s3.us-east-1.amazonaws.com",
+ *         region:          "us-east-1",
+ *         bucket:          "uploads",
+ *         accessKeyId:     "AKIAEXAMPLE",
+ *         secretAccessKey: "secret",
+ *         classifications: ["public"],
+ *         residencyTag:    "US",
+ *       },
+ *     },
+ *   });
+ *   var presigned = b.storage.presignedDownloadUrl("public/logo.png", {
+ *     backend:      "us-ops",
+ *     expiresInSec: 60,
+ *   });
+ *   presigned.method;   // → "GET"
+ */
 function presignedDownloadUrl(key, opts) { return _presign("Download", key, opts); }
 
-// presignedUploadPolicy — issues a POST-form policy (or vendor-equivalent
-// PUT) that the client uses to upload directly to the object store with
-// server-side body-size enforcement. Distinct from presignedUploadUrl
-// because that signs only the URL; this signs a full policy document
-// that includes a content-length-range condition.
-//
-// Vendor enforcement:
-//   sigv4    — content-length-range condition; S3 rejects bodies outside
-//   gcs      — content-length-range condition; GCS rejects bodies outside
-//   azure    — SAS doesn't natively cap body size; returns SAS PUT URL
-//              with enforcement: "client-only" — operator must HEAD the
-//              blob post-upload and reject if oversize
-//   local    — NOT_SUPPORTED (use saveFile directly)
-//   http-put — NOT_SUPPORTED (no signing convention)
+/**
+ * @primitive b.storage.presignedUploadPolicy
+ * @signature b.storage.presignedUploadPolicy(key, opts)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.storage.presignedUploadUrl, b.fileUpload
+ *
+ * Issue a signed POST-form policy (sigv4 / gcs) or vendor-equivalent
+ * PUT (azure-blob) that the client uploads against, with the body-
+ * size cap baked into the signature so an oversize upload is
+ * rejected by the object store, not by the framework process. Use
+ * this — not `presignedUploadUrl` — when the upload size matters
+ * and you can't trust the client. `result.enforcement` indicates
+ * whether the cap is server-side (`"server"`) or client-only
+ * (`"client-only"` — Azure SAS, where the operator must HEAD the
+ * blob post-upload to reject oversize). `local` and `http-put`
+ * backends throw `PRESIGN_NOT_SUPPORTED`.
+ *
+ * @opts
+ *   classification:  string,    // route to a backend serving this classification
+ *   backend:         string,    // explicit backend by name
+ *   maxBytes:        number,    // body-size cap (required for size enforcement)
+ *   expiresInSec:    number,    // policy lifetime; backend-defaulted when omitted
+ *   contentType:     string,    // pin the upload Content-Type into the policy
+ *
+ * @example
+ *   b.storage.init({
+ *     backends: {
+ *       "us-ops": {
+ *         protocol:        "sigv4",
+ *         endpoint:        "https://s3.us-east-1.amazonaws.com",
+ *         region:          "us-east-1",
+ *         bucket:          "uploads",
+ *         accessKeyId:     "AKIAEXAMPLE",
+ *         secretAccessKey: "secret",
+ *         classifications: ["operational"],
+ *         residencyTag:    "US",
+ *       },
+ *     },
+ *   });
+ *   var policy = b.storage.presignedUploadPolicy("user/avatar.png", {
+ *     backend:      "us-ops",
+ *     maxBytes:     5 * 1024 * 1024,   // 5 MiB cap, server-enforced
+ *     expiresInSec: 300,
+ *     contentType:  "image/png",
+ *   });
+ *   policy.enforcement;   // → "server"
+ */
 function presignedUploadPolicy(key, opts) {
   _requireInit();
   if (typeof key !== "string" || key.length === 0) {
@@ -434,6 +775,28 @@ function presignedUploadPolicy(key, opts) {
   return result;
 }
 
+/**
+ * @primitive b.storage.getBackend
+ * @signature b.storage.getBackend(name)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.storage.listBackends, b.storage.init
+ *
+ * Return the named backend instance from the underlying
+ * `b.objectStore` adapter, or `null` when no backend with that
+ * name is registered. Most operator code routes through the
+ * dispatching primitives (`saveFile` / `getFileBuffer` / ...);
+ * `getBackend` is the escape hatch for adapter-specific operations
+ * (lifecycle policy ops, vendor-specific HEAD probes) the
+ * framework does not abstract.
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   var backend = b.storage.getBackend("default");
+ *   backend.protocol;   // → "local"
+ *   var missing = b.storage.getBackend("does-not-exist");
+ *   // → null
+ */
 function getBackend(name) {
   _requireInit();
   return backends[name] || null;