@blamejs/core 0.6.36 → 0.6.37

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.37** (2026-05-02) — Azure + GCS bucket-ops parity. **`b.objectStore.bucketOps`** is now a protocol-dispatching factory: pass `{ protocol: 'sigv4' | 'azure-blob' | 'gcs', ... }` to get a service-scoped client for the matching cloud. Previously SigV4 only. **`lib/object-store/azure-blob-bucket-ops.js`** (new) — Azure Storage container lifecycle via Shared Key auth (reuses `azure-blob.js`'s `signRequest`): `create(name, {publicAccess?})` (PUT `/{container}?restype=container`), `delete(name)` (DELETE), `list({prefix?, maxResults?})` (GET `/?comp=list` with XML response parsed into `[{ name, lastModified, etag, leaseStatus, leaseState, publicAccess }]`), `setCorsRules(rules)` (PUT `/?restype=service&comp=properties` — Azure CORS is account-level, not per-container). `setLifecycle` is intentionally not implemented because Azure Storage lifecycle management policies live on Azure Resource Manager (`management.azure.com`) and require Azure AD bearer-token auth — a different scheme entirely; calling it throws `NOT_SUPPORTED` with operator guidance pointing at Terraform / Bicep / az CLI. **`lib/object-store/gcs-bucket-ops.js`** (new) — GCS bucket lifecycle via service-account JWT exchanged for an OAuth2 access token (reuses `gcs.js`'s `_signJwt`); admin-scoped (`devstorage.full_control`) so list-buckets + create + delete + lifecycle + CORS all succeed: `create(name, {location?, storageClass?, iamConfiguration?})` (POST `/storage/v1/b?project=`), `delete(name)`, `list({prefix?, maxResults?, pageToken?})`, `setLifecycle(name, rules)` (PATCH bucket with `lifecycle: { rule: [{ action, condition }] }`; rules support `Delete` / `SetStorageClass` / `AbortIncompleteMultipartUpload` actions), `setCorsRules(name, rules)` (PATCH bucket with `cors: [{ origin, method, responseHeader, maxAgeSeconds }]`). **Bucket-name validation** matches each cloud's spec: Azure containers (3-63 lowercase alphanumeric + hyphens, no consecutive hyphens, must start/end with alphanumeric); GCS buckets (3-63 lowercase + digits + hyphens + underscores + dots, no consecutive dots, no `goog` prefix). Bad names are rejected at the call site before the request leaves the process. **404 / 409 semantic mapping** — both modules treat 404 on delete as "already gone" (returns false), 409 on create as `BUCKET_ALREADY_OWNED`; everything else surfaces with the original HTTP status preserved on the thrown ObjectStoreError. **Tests**: 47 layer-0 mock-based assertions for Azure (surface, factory validation, container-name validation, create/delete/list wire shape including XML response parsing, CORS validation + wire shape, setLifecycle NOT_SUPPORTED guidance) + 50 layer-0 mock-based assertions for GCS (surface, factory validation including missing service-account / project, bucket-name validation, create/delete/list wire shape including JWT bearer auth, lifecycle validation + JSON body shape, CORS shape). HTTP mock servers record every request shape so signing, URL params, headers, and body-format are all asserted. **Wiki page** `examples/wiki/seeders/prod/pages/object-store.js` updated end-to-end with all three clouds' bucket-ops examples and the Azure-vs-Resource-Manager lifecycle gap documented. Smoke 6951 / wiki e2e 178 / per-primitive integration 16 files / wiki integration 32 / shellcheck clean / eslint clean.
 - **0.6.36** (2026-05-02) — `b.db.from("schema.table")` cross-schema chain. **`b.db.from("audit.events")`** — the chainable Query builder now accepts a two-part `schema.table` identifier. Both halves validated separately as SQL identifiers (rejects three-part names, empty parts, identifiers with embedded quotes / SQL keywords); both halves wrapped in `"..."` when interpolated so the generated SQL is `SELECT * FROM "audit"."events" WHERE ...` etc. The bare `b.db.from("users")` form still works unchanged. Sealed-field registry lookup tries the qualified name (`audit.users`) first when schema is set, falls back to the bare table — operators registering `cryptoField.registerTable("audit.users", { sealedFields: ... })` get per-schema sealed columns; existing table-name-only registrations keep working. Use cases: cross-schema joins on Postgres external-db (`public.users` vs `audit.events` from one app), SQLite `ATTACH DATABASE` (per-classification audit / archive databases mounted on the side and queried through the same Query API). **Tests**: 14 layer-0 SQL-shape assertions against a fake DB (verify schema-qualified SELECT / INSERT / UPDATE / DELETE / count / sub-select-on-rowid all emit `"schema"."table"`; reject three-part / empty / invalid identifiers; bare table name preserved unqualified) + 7 layer-2 end-to-end assertions against a real `ATTACH DATABASE` schema (insert / select / count / update / delete round-trip via `b.db.from("audit.events")`). Smoke 6854 / wiki e2e 178 / per-primitive integration 16 files / wiki integration 32 / shellcheck clean / eslint clean.
 - **0.6.35** (2026-05-02) — `cluster-provider-db` MySQL dialect. **`b.cluster.create({ provider: clusterProviderDb.create({ dialect: "mysql", ... }) })`** — operators on MySQL no longer have to supply their own provider; the framework's default DB-row leader-election provider now speaks all three of postgres / sqlite / mysql. The MySQL acquireLease shape uses `INSERT INTO _blamejs_leader (...) VALUES (...) ON DUPLICATE KEY UPDATE col = IF(expiresAt < ?, VALUES(col), col), ..., expiresAt = IF(expiresAt < ?, VALUES(expiresAt), expiresAt)` so a still-valid lease is preserved untouched and an expired one is overwritten — atomic at the row level — followed by a `SELECT FROM _blamejs_leader WHERE scope='leader'` to read who holds (MySQL has no `RETURNING`). The expiresAt assignment runs LAST so per-column IF() predicates evaluate against pre-update row state. Renew uses `UPDATE ... SET expiresAt=?, endpoint=? WHERE scope='leader' AND nodeId=? AND leaseId=?` followed by a check-SELECT to surface takeover races as `LEASE_LOST`. Schema generation: `BIGINT` int columns (was `INTEGER` for SQLite), `VARCHAR(64)` for primary-key text columns and `VARCHAR(255)` for body text (MySQL needs explicit lengths on PRIMARY KEY columns), `CHECK (scope = 'leader' / 'state')` constraint dropped on MySQL because some MariaDB / MySQL 5.x versions parse-then-silently-drop CHECK clauses (would surface as version drift); the constant-scope invariant is enforced by application code anyway. Placeholder style auto-flips to `?` for MySQL (Postgres / SQLite continue to use `$1..$N`). **Tests**: 16 layer-1 assertions exercising the MySQL dialect path against a fake mysql-shaped driver (`_makeFakeMysqlDriver` in `test/helpers/drivers.js`) that emulates `INSERT ... ON DUPLICATE KEY UPDATE` with the per-column `IF()` semantics; covers acquire-empty, blocked-while-held, renew-no-fencing-bump, takeover-with-fencing-bump, old-leader-renew-throws-LEASE_LOST, currentLeader, releaseLease — plus a SQL-shape audit (validates VARCHAR primary keys, ON DUPLICATE KEY syntax, ?-placeholders, IF() gating). 14 live integration assertions against the docker MySQL 8.4 container via a docker-exec-based external-db driver shim (no npm mysql client; the framework already requires operator-supplied driver wiring, the shim demonstrates one path) covering ensureSchema, acquireLease, blocked-second-node, currentLeader, renewLease, release, takeover-after-expiry, fencingToken bump, old-leader LEASE_LOST. Smoke 6833 / wiki e2e 178 / per-primitive integration 16 files / wiki integration 32 / shellcheck clean / eslint clean.
 - **0.6.34** (2026-05-02) — distributed pub/sub primitive. **`b.pubsub`** — single API for cross-node fan-out across the framework, with three backends. `local` dispatches in-process to registered handlers (zero coordination overhead for single-node deploys); `cluster` polls a shared `_blamejs_pubsub_messages` table at `pollIntervalMs` (default 100ms) and dispatches new rows past `lastSeenId` from other nodes (publishedBy=self filter prevents loopback); `redis` opens a SUBSCRIBE-mode connection on `lib/redis-client.js` (now with new push-message demultiplexing — server-pushed `["message", channel, payload]` and `["pmessage", pattern, channel, payload]` arrays route through `setOnPushMessage` instead of consuming a pending request slot, while SUBSCRIBE / UNSUBSCRIBE acks still flow through the normal command pipeline). Per-instance nonce stamped on outgoing redis payloads so the SUBSCRIBE socket recognizes its own publishes and skips the loopback (without it every same-instance publish would fire local handlers twice). Operator API: `ps.subscribe(channel, handler) → token`, `ps.subscribePattern(pattern, handler) → token` (glob-style on local + cluster, native PSUBSCRIBE on redis), `ps.unsubscribe(token)`, `await ps.publish(channel, payload) → { local, remote }`, `await ps.close()`. `topicPrefix` opt scopes channel names so independent pubsub instances sharing a backend (cache invalidation + websocket channels + custom) don't collide. Handler errors are caught + logged via the framework's boot logger; they never abort dispatch to other handlers on the same channel. **`lib/websocket-channels.js`** — replaces the inline cluster-poll-and-fan-out logic with `b.pubsub` consumption. The hub now owns one pubsub instance per primitive; cross-node delivery is `pubsub.subscribe` per channel the hub joins, with the hub's `_localDispatch` as the handler. Per-channel pubsub subscription is refcounted by local conn count (subscribe on first conn, unsubscribe on last). The `_blamejs_ws_messages` table is renamed to `_blamejs_pubsub_messages` (column `channel` → `topic`) reflecting the generalization; pre-v1, no compat shim — operators upgrading wipe the previous table (which carried only ephemeral fan-out rows with default 60s retention). **`b.cache.create({ invalidationPubsub })`** — passing a `b.pubsub.create()` instance auto-publishes on every successful `del` / `clear` / `invalidateTag`, and subscribes for the same events so other cache instances on other nodes (or processes sharing the pubsub backend) react locally — primarily useful for the memory backend so stale per-node entries don't survive a global tag wipe. Re-entrancy guard prevents inbound invalidation events from re-publishing (no fan-out loops). Tests: 29 layer-0 assertions covering local + cluster behavior, topicPrefix isolation, pattern subscribe, handler error isolation, post-close error path, end-to-end cache invalidationPubsub fan-out via local pubsub. 10 live integration assertions against the docker redis container covering single-instance round-trip, PSUBSCRIBE pattern, cross-instance fan-out, and cache invalidation through redis PUB/SUB. Smoke 6817 / wiki e2e 178 / per-primitive integration 15 files / wiki integration 32 / shellcheck clean / eslint clean.

package/README.md

@@ -41,7 +41,7 @@ var b = require("@blamejs/core");
 
 The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
 
-- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows on the local SQLite backend OR a shared Redis backend for multi-replica deploys (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
+- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket-ops (create / delete / list / lifecycle / CORS) across all three clouds (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows on the local SQLite backend OR a shared Redis backend for multi-replica deploys (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
 - **Identity & access** — passwords (Argon2id) + policy primitive (NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles, HaveIBeenPwned k-anonymity breach check, length / context / dictionary / complexity rules, rotation + history) (`b.auth.password`); passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions with optional IP / UA fingerprint drift detection + anomaly scoring, brute-force lockout (`b.auth.*`, `b.session`); RBAC + optional per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule approval workflow with m-of-n quorum + cooling-off lock + approver-role gate + cancellation (`b.dualControl`).
 - **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA that issues clientAuth / serverAuth / dual-EKU certs with SAN entries and auto-detects the highest-PQC signature algorithm the vendored x509 library accepts (today: ECDSA-P384-SHA384 bridge; self-upgrades to SLH-DSA / ML-DSA when the X.509 ecosystem catches up), PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
 - **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate (cloud-metadata IPs hard-denied unconditionally; private / loopback / link-local overridable per call), scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), IPv4-or-IPv6 NTP servers, DNS with IPv6 / DoH / DoT (private-CA trust pinning via `opts.ca`) / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).

package/lib/object-store/azure-blob-bucket-ops.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * azure-blob-bucket-ops — container-level operations for Azure Blob.
+ *
+ * Per-blob ops (put / get / list / delete) live in
+ * `lib/object-store/azure-blob.js` and are bound to a single container
+ * at create() time. Container lifecycle ops are at a different level —
+ * a service-scoped client that addresses arbitrary containers — so
+ * they get their own factory.
+ *
+ *   create(name, opts?)        async; PUT  /{container}?restype=container
+ *   delete(name)               async; DELETE /{container}?restype=container
+ *   list(opts?)                async; GET  /?comp=list
+ *                              -> [{ name, lastModified, etag,
+ *                                    leaseStatus, leaseState, publicAccess }]
+ *   setCorsRules(rules)        async; PUT  /?restype=service&comp=properties
+ *                              account-level CORS — Azure has no
+ *                              per-container CORS.
+ *
+ * Shared Key auth via `lib/object-store/azure-blob.js`'s `signRequest`
+ * helper. Not implemented here:
+ *
+ *   setLifecycle(name, rules) — Azure Storage lifecycle management
+ *     policies live on Azure Resource Manager
+ *     (`management.azure.com`), not the Blob service endpoint. ARM
+ *     requires an Azure AD bearer token (Service Principal flow), a
+ *     different auth scheme entirely. Operators wiring lifecycle do
+ *     so via Terraform / Bicep / az CLI; the framework documents the
+ *     gap rather than half-implementing one auth path.
+ */
+var azureBlob = require("./azure-blob");
+var httpClient = require("../http-client");
+var safeUrl = require("../safe-url");
+var { ObjectStoreError } = require("../framework-error");
+
+var _err = ObjectStoreError.factory;
+
+// Azure container names: 3-63 chars, lowercase alphanumeric + hyphens,
+// no consecutive hyphens, must start and end with letter or digit.
+var CONTAINER_NAME_RE = /^[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$/;
+
+function _validateContainerName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw _err("BUCKET_INVALID_NAME",
+      "azure-blob bucketOps: container name must be a non-empty string", true);
+  }
+  if (name.length < 3 || name.length > 63) {
+    throw _err("BUCKET_INVALID_NAME",
+      "azure-blob bucketOps: container name must be 3-63 chars (got " +
+      name.length + ")", true);
+  }
+  if (!CONTAINER_NAME_RE.test(name)) {
+    throw _err("BUCKET_INVALID_NAME",
+      "azure-blob bucketOps: container name '" + name + "' is invalid; " +
+      "lowercase letters / digits / hyphens only, no consecutive hyphens, " +
+      "must start and end with letter or digit", true);
+  }
+}
+
+function _validateCorsRule(rule, idx) {
+  function bad(msg) {
+    throw _err("INVALID_CORS_RULE",
+      "azure-blob bucketOps: setCorsRules: rule[" + idx + "]: " + msg, true);
+  }
+  if (!rule || typeof rule !== "object") bad("must be an object");
+  if (!Array.isArray(rule.allowedOrigins) || rule.allowedOrigins.length === 0) {
+    bad("allowedOrigins must be a non-empty array");
+  }
+  if (!Array.isArray(rule.allowedMethods) || rule.allowedMethods.length === 0) {
+    bad("allowedMethods must be a non-empty array");
+  }
+  for (var i = 0; i < rule.allowedMethods.length; i++) {
+    var m = rule.allowedMethods[i];
+    if (["GET", "PUT", "POST", "DELETE", "HEAD", "MERGE", "OPTIONS"].indexOf(m) === -1) {
+      bad("allowedMethods[" + i + "] = " + JSON.stringify(m) +
+          " (must be one of GET/PUT/POST/DELETE/HEAD/MERGE/OPTIONS)");
+    }
+  }
+  if (rule.allowedHeaders !== undefined && !Array.isArray(rule.allowedHeaders)) {
+    bad("allowedHeaders, if present, must be an array");
+  }
+  if (rule.exposedHeaders !== undefined && !Array.isArray(rule.exposedHeaders)) {
+    bad("exposedHeaders, if present, must be an array");
+  }
+  if (rule.maxAgeInSeconds !== undefined &&
+      (typeof rule.maxAgeInSeconds !== "number" || rule.maxAgeInSeconds < 0 ||
+       !Number.isFinite(rule.maxAgeInSeconds))) {
+    bad("maxAgeInSeconds, if present, must be a non-negative finite number");
+  }
+}
+
+function _xmlEscape(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function _buildCorsXml(rules) {
+  var inner = rules.map(function (rule) {
+    var parts = [
+      "<CorsRule>",
+      "<AllowedOrigins>" + _xmlEscape(rule.allowedOrigins.join(",")) + "</AllowedOrigins>",
+      "<AllowedMethods>" + rule.allowedMethods.join(",") + "</AllowedMethods>",
+      "<AllowedHeaders>" + _xmlEscape((rule.allowedHeaders || []).join(",")) + "</AllowedHeaders>",
+      "<ExposedHeaders>" + _xmlEscape((rule.exposedHeaders || []).join(",")) + "</ExposedHeaders>",
+      "<MaxAgeInSeconds>" +
+        (rule.maxAgeInSeconds == null ? 0 : Math.floor(rule.maxAgeInSeconds)) +
+        "</MaxAgeInSeconds>",
+      "</CorsRule>",
+    ];
+    return parts.join("");
+  }).join("");
+  return '<?xml version="1.0" encoding="utf-8"?>' +
+         "<StorageServiceProperties><Cors>" + inner + "</Cors></StorageServiceProperties>";
+}
+
+// Tiny XML extractor — pulls every occurrence of <Tag>value</Tag>
+// and returns an array of value strings. Sufficient for the limited
+// shapes we read (Containers list, container metadata).
+function _extractAll(xml, tag) {
+  var out = [];
+  var re = new RegExp("<" + tag + ">([\\s\\S]*?)</" + tag + ">", "g");
+  var m;
+  while ((m = re.exec(xml)) !== null) out.push(m[1]);
+  return out;
+}
+
+function _extractBlocks(xml, tag) {
+  var open = "<" + tag + ">";
+  var close = "</" + tag + ">";
+  var blocks = [];
+  var i = 0;
+  while (true) {
+    var s = xml.indexOf(open, i);
+    if (s === -1) break;
+    var e = xml.indexOf(close, s + open.length);
+    if (e === -1) break;
+    blocks.push(xml.slice(s + open.length, e));
+    i = e + close.length;
+  }
+  return blocks;
+}
+
+function create(config) {
+  if (!config) throw _err("BAD_OPT", "azure-blob bucketOps: config required", true);
+  if (!config.accountName) throw _err("BAD_OPT", "azure-blob bucketOps: accountName required", true);
+  if (!config.accountKey)  throw _err("BAD_OPT", "azure-blob bucketOps: accountKey required", true);
+
+  var endpoint = config.endpoint ||
+                 ("https://" + config.accountName + ".blob.core.windows.net");
+  if (endpoint.endsWith("/")) endpoint = endpoint.slice(0, -1);
+  var apiVersion = config.apiVersion || azureBlob.DEFAULT_API_VERSION;
+  var timeoutMs = config.timeoutMs;
+  var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal = config.allowInternal != null ? config.allowInternal : null;
+
+  function _sign(method, url, headers) {
+    return azureBlob.signRequest({
+      method:      method,
+      url:         url,
+      headers:     headers || {},
+      accountName: config.accountName,
+      accountKey:  config.accountKey,
+      apiVersion:  apiVersion,
+    }).headers;
+  }
+
+  function _request(method, url, headers, body, expectStatus) {
+    var reqOpts = {
+      method:           method,
+      url:              url,
+      headers:          headers,
+      body:             body,
+      idleTimeoutMs:    timeoutMs,
+      allowedProtocols: allowedProtocols,
+      errorClass:       ObjectStoreError,
+    };
+    if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
+    // http-client rejects on any 4xx/5xx by default. The bucket-ops API
+    // semantically accepts certain non-2xx codes (404 for "missing on
+    // delete", 409 for "container already exists"), so we catch those
+    // and surface them as the wrapped response object instead.
+    return httpClient.request(reqOpts).then(function (res) {
+      if (expectStatus && expectStatus.indexOf(res.statusCode) === -1) {
+        throw _err("UNEXPECTED_STATUS",
+          "azure-blob bucketOps: " + method + " " + url +
+          " returned HTTP " + res.statusCode, true);
+      }
+      return res;
+    }, function (e) {
+      var sc = e && e.statusCode;
+      if (sc && expectStatus && expectStatus.indexOf(sc) !== -1) {
+        return { statusCode: sc, headers: {}, body: Buffer.alloc(0) };
+      }
+      throw e;
+    });
+  }
+
+  async function createContainer(name, opts) {
+    _validateContainerName(name);
+    opts = opts || {};
+    var url = new URL(endpoint + "/" + name + "?restype=container");
+    var headers = { "Content-Length": "0" };
+    if (opts.publicAccess) {
+      if (opts.publicAccess !== "blob" && opts.publicAccess !== "container") {
+        throw _err("BAD_OPT",
+          "azure-blob bucketOps: createContainer: publicAccess must be " +
+          "'blob' or 'container' (got " + JSON.stringify(opts.publicAccess) + ")", true);
+      }
+      headers["x-ms-blob-public-access"] = opts.publicAccess;
+    }
+    var signed = _sign("PUT", url, headers);
+    var res = await _request("PUT", url, signed, null, [201, 409]);
+    if (res.statusCode === 409) {
+      throw _err("BUCKET_ALREADY_OWNED",
+        "azure-blob bucketOps: container '" + name +
+        "' already exists or was recently deleted", true);
+    }
+    return { name: name };
+  }
+
+  async function deleteContainer(name) {
+    _validateContainerName(name);
+    var url = new URL(endpoint + "/" + name + "?restype=container");
+    var signed = _sign("DELETE", url, {});
+    var res = await _request("DELETE", url, signed, null, [202, 404]);
+    return res.statusCode === 202;
+  }
+
+  async function listContainers(opts) {
+    opts = opts || {};
+    var url = new URL(endpoint + "/?comp=list");
+    if (opts.prefix)  url.searchParams.set("prefix", opts.prefix);
+    if (opts.maxResults != null) url.searchParams.set("maxresults", String(opts.maxResults));
+    var signed = _sign("GET", url, {});
+    var res = await _request("GET", url, signed, null, [200]);
+    var xml = Buffer.isBuffer(res.body) ? res.body.toString("utf8") :
+              typeof res.body === "string" ? res.body :
+              "";
+    var blocks = _extractBlocks(xml, "Container");
+    return blocks.map(function (block) {
+      return {
+        name:          (_extractAll(block, "Name")[0] || "").trim(),
+        lastModified:  (_extractAll(block, "Last-Modified")[0] || null),
+        etag:          (_extractAll(block, "Etag")[0] || null),
+        leaseStatus:   (_extractAll(block, "LeaseStatus")[0] || null),
+        leaseState:    (_extractAll(block, "LeaseState")[0] || null),
+        publicAccess:  (_extractAll(block, "PublicAccess")[0] || null),
+      };
+    });
+  }
+
+  async function setCorsRules(rules) {
+    if (!Array.isArray(rules)) {
+      throw _err("INVALID_CORS_RULE",
+        "azure-blob bucketOps: setCorsRules: rules must be an array", true);
+    }
+    rules.forEach(_validateCorsRule);
+    var xml = _buildCorsXml(rules);
+    var bodyBuf = Buffer.from(xml, "utf8");
+    var url = new URL(endpoint + "/?restype=service&comp=properties");
+    var headers = {
+      "Content-Type":   "application/xml",
+      "Content-Length": String(bodyBuf.length),
+    };
+    var signed = _sign("PUT", url, headers);
+    await _request("PUT", url, signed, bodyBuf, [202]);
+    return { rulesApplied: rules.length };
+  }
+
+  return {
+    protocol:     "azure-blob",
+    create:       createContainer,
+    delete:       deleteContainer,
+    list:         listContainers,
+    setCorsRules: setCorsRules,
+    setLifecycle: function () {
+      throw _err("NOT_SUPPORTED",
+        "azure-blob bucketOps: setLifecycle is not implemented because " +
+        "Azure Storage lifecycle management policies live on Azure Resource " +
+        "Manager (management.azure.com) and require Azure AD bearer token " +
+        "auth, not Shared Key. Configure lifecycle via Terraform / Bicep / " +
+        "az CLI.", true);
+    },
+  };
+}
+
+module.exports = { create: create };

package/lib/object-store/gcs-bucket-ops.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * gcs-bucket-ops — bucket-level operations for Google Cloud Storage.
+ *
+ * Per-object ops (put / get / list / delete) live in
+ * `lib/object-store/gcs.js` and are bound to a single bucket at
+ * create() time. Bucket lifecycle ops are at a different level — a
+ * project-scoped client that addresses arbitrary buckets — so they
+ * get their own factory.
+ *
+ *   create(name, opts?)         async; POST /storage/v1/b?project={projectId}
+ *                               opts: location ('US' / 'EU' / region) +
+ *                                     storageClass + iamConfiguration
+ *   delete(name)                async; DELETE /storage/v1/b/{name}
+ *   list()                      async; GET  /storage/v1/b?project={projectId}
+ *                               -> [{ name, location, storageClass,
+ *                                     timeCreated, updated }]
+ *   setLifecycle(name, rules)   async; PATCH /storage/v1/b/{name}
+ *                               -> body { lifecycle: { rule: [...] } }
+ *   setCorsRules(name, rules)   async; PATCH /storage/v1/b/{name}
+ *                               -> body { cors: [...] }
+ *
+ * Auth: same service-account JSON / RSA-SHA256-signed JWT exchanged
+ * for an OAuth2 access token as `lib/object-store/gcs.js`.
+ */
+var fs = require("node:fs");
+var gcs = require("./gcs");
+var authHeader = require("../auth-header");
+var httpClient = require("../http-client");
+var safeJson = require("../safe-json");
+var safeUrl = require("../safe-url");
+var C = require("../constants");
+var { ObjectStoreError } = require("../framework-error");
+
+var _err = ObjectStoreError.factory;
+
+// GCS bucket names: 3-63 chars, lowercase letters / digits / hyphens /
+// underscores / dots; can't start or end with hyphen; can't contain '..'
+// or 'goog' prefix; can't be IP address. Most violations the API will
+// reject for us — we sanity-check the basics.
+var BUCKET_NAME_RE = /^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$/;
+
+function _validateBucketName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw _err("BUCKET_INVALID_NAME",
+      "gcs bucketOps: bucket name must be a non-empty string", true);
+  }
+  if (name.length < 3 || name.length > 63) {
+    throw _err("BUCKET_INVALID_NAME",
+      "gcs bucketOps: bucket name must be 3-63 chars (got " + name.length + ")", true);
+  }
+  if (!BUCKET_NAME_RE.test(name)) {
+    throw _err("BUCKET_INVALID_NAME",
+      "gcs bucketOps: bucket name '" + name + "' is invalid; lowercase " +
+      "letters / digits / hyphens / underscores / dots only, must start " +
+      "and end with letter or digit", true);
+  }
+  if (name.indexOf("..") !== -1) {
+    throw _err("BUCKET_INVALID_NAME",
+      "gcs bucketOps: bucket name '" + name + "' contains '..'", true);
+  }
+  if (name.indexOf("goog") === 0) {
+    throw _err("BUCKET_INVALID_NAME",
+      "gcs bucketOps: bucket name '" + name + "' starts with 'goog' " +
+      "(reserved by Google)", true);
+  }
+}
+
+// GCS lifecycle rules: { action: { type: "Delete"|"SetStorageClass", storageClass? },
+//                        condition: { age, createdBefore, ...} }
+function _validateLifecycleRule(rule, idx) {
+  function bad(msg) {
+    throw _err("INVALID_LIFECYCLE",
+      "gcs bucketOps: setLifecycle: rule[" + idx + "]: " + msg, true);
+  }
+  if (!rule || typeof rule !== "object") bad("must be an object");
+  if (!rule.action || typeof rule.action !== "object") {
+    bad("action object is required");
+  }
+  if (!rule.action.type) bad("action.type is required");
+  if (rule.action.type !== "Delete" && rule.action.type !== "SetStorageClass" &&
+      rule.action.type !== "AbortIncompleteMultipartUpload") {
+    bad("action.type must be 'Delete' / 'SetStorageClass' / " +
+        "'AbortIncompleteMultipartUpload' (got " +
+        JSON.stringify(rule.action.type) + ")");
+  }
+  if (rule.action.type === "SetStorageClass" && !rule.action.storageClass) {
+    bad("action.storageClass required when action.type='SetStorageClass'");
+  }
+  if (!rule.condition || typeof rule.condition !== "object") {
+    bad("condition object is required");
+  }
+}
+
+function _validateCorsRule(rule, idx) {
+  function bad(msg) {
+    throw _err("INVALID_CORS_RULE",
+      "gcs bucketOps: setCorsRules: rule[" + idx + "]: " + msg, true);
+  }
+  if (!rule || typeof rule !== "object") bad("must be an object");
+  if (!Array.isArray(rule.origin) || rule.origin.length === 0) {
+    bad("origin must be a non-empty array");
+  }
+  if (rule.method !== undefined && !Array.isArray(rule.method)) {
+    bad("method, if present, must be an array");
+  }
+  if (rule.responseHeader !== undefined && !Array.isArray(rule.responseHeader)) {
+    bad("responseHeader, if present, must be an array");
+  }
+  if (rule.maxAgeSeconds !== undefined &&
+      (typeof rule.maxAgeSeconds !== "number" || rule.maxAgeSeconds < 0)) {
+    bad("maxAgeSeconds, if present, must be a non-negative number");
+  }
+}
+
+function create(config) {
+  if (!config) throw _err("BAD_OPT", "gcs bucketOps: config required", true);
+
+  var serviceAccount = config.serviceAccount;
+  if (!serviceAccount && config.serviceAccountFile) {
+    try {
+      serviceAccount = safeJson.parse(fs.readFileSync(config.serviceAccountFile));
+    } catch (e) {
+      throw _err("BAD_OPT", "gcs bucketOps: failed to read serviceAccountFile '" +
+        config.serviceAccountFile + "': " + ((e && e.message) || String(e)), true);
+    }
+  }
+  if (!serviceAccount || !serviceAccount.client_email || !serviceAccount.private_key) {
+    throw _err("BAD_OPT",
+      "gcs bucketOps: serviceAccount with { client_email, private_key } required " +
+      "(or serviceAccountFile pointing to one)", true);
+  }
+  var projectId = config.projectId || serviceAccount.project_id;
+  if (!projectId) {
+    throw _err("BAD_OPT",
+      "gcs bucketOps: projectId required (either config.projectId or " +
+      "serviceAccount.project_id)", true);
+  }
+
+  var endpoint = config.endpoint || gcs.DEFAULT_ENDPOINT;
+  if (endpoint.endsWith("/")) endpoint = endpoint.slice(0, -1);
+  var tokenEndpoint = config.tokenEndpoint || "https://oauth2.googleapis.com/token";
+  // Bucket-level admin needs the full-control scope — list-buckets +
+  // create + delete + lifecycle + CORS are all admin operations beyond
+  // the per-object read_write scope used by gcs.js's per-blob client.
+  var scope = config.scope || "https://www.googleapis.com/auth/devstorage.full_control";
+  var timeoutMs = config.timeoutMs;
+  var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal = config.allowInternal != null ? config.allowInternal : null;
+
+  // Token cache — same shape as gcs.js's per-blob client, scoped to
+  // this factory instance so a parallel per-blob client doesn't share
+  // the admin-scoped token (different scope).
+  var cachedToken = null;
+  var TOKEN_REFRESH_BUFFER = C.TIME.minutes(5);
+
+  function _request(method, url, headers, body, expectStatus) {
+    var reqOpts = {
+      method:           method,
+      url:              url,
+      headers:          headers,
+      body:             body,
+      idleTimeoutMs:    timeoutMs,
+      allowedProtocols: allowedProtocols,
+      errorClass:       ObjectStoreError,
+    };
+    if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
+    return httpClient.request(reqOpts).then(function (res) {
+      if (expectStatus && expectStatus.indexOf(res.statusCode) === -1) {
+        var bodyText = res.body ?
+          (Buffer.isBuffer(res.body) ? res.body.toString("utf8") : String(res.body)) : "";
+        throw _err("UNEXPECTED_STATUS",
+          "gcs bucketOps: " + method + " " + url + " returned HTTP " +
+          res.statusCode + (bodyText ? " — " + bodyText.slice(0, 500) : ""), true);
+      }
+      return res;
+    }, function (e) {
+      // http-client rejects on 4xx/5xx; if the caller marked the
+      // status as semantically acceptable (404 on delete, 409 on
+      // create) surface it as a normal response.
+      var sc = e && e.statusCode;
+      if (sc && expectStatus && expectStatus.indexOf(sc) !== -1) {
+        return { statusCode: sc, headers: {}, body: Buffer.alloc(0) };
+      }
+      throw e;
+    });
+  }
+
+  async function _ensureToken() {
+    if (cachedToken && Date.now() < cachedToken.expiresAt - TOKEN_REFRESH_BUFFER) {
+      return cachedToken.accessToken;
+    }
+    var assertion = gcs._signJwt(serviceAccount, scope, tokenEndpoint);
+    var bodyStr = "grant_type=" + encodeURIComponent("urn:ietf:params:oauth:grant-type:jwt-bearer") +
+                  "&assertion=" + encodeURIComponent(assertion);
+    var bodyBuf = Buffer.from(bodyStr, "utf8");
+    var res = await _request("POST", new URL(tokenEndpoint), {
+      "Content-Type":   "application/x-www-form-urlencoded",
+      "Content-Length": String(bodyBuf.length),
+    }, bodyBuf, [200]);
+    var tokenResp = safeJson.parse(res.body);
+    if (!tokenResp.access_token) {
+      throw _err("AUTH_FAILED",
+        "gcs bucketOps: token endpoint returned no access_token: " +
+        (res.body ? res.body.toString("utf8") : ""), true);
+    }
+    var expiresInMs = C.TIME.seconds(tokenResp.expires_in || 3600);
+    cachedToken = {
+      accessToken: tokenResp.access_token,
+      expiresAt:   Date.now() + expiresInMs,
+    };
+    return cachedToken.accessToken;
+  }
+
+  function _bucketBaseUrl() {
+    return endpoint + "/storage/v1/b";
+  }
+
+  async function createBucket(name, opts) {
+    _validateBucketName(name);
+    opts = opts || {};
+    var token = await _ensureToken();
+    var url = new URL(_bucketBaseUrl());
+    url.searchParams.set("project", projectId);
+    var bodyObj = { name: name };
+    if (opts.location)     bodyObj.location     = opts.location;
+    if (opts.storageClass) bodyObj.storageClass = opts.storageClass;
+    if (opts.iamConfiguration) bodyObj.iamConfiguration = opts.iamConfiguration;
+    var bodyBuf = Buffer.from(JSON.stringify(bodyObj), "utf8");
+    var headers = Object.assign(authHeader.bearer(token), {
+      "Content-Type":   "application/json",
+      "Content-Length": String(bodyBuf.length),
+    });
+    var res = await _request("POST", url, headers, bodyBuf, [200, 409]);
+    if (res.statusCode === 409) {
+      throw _err("BUCKET_ALREADY_OWNED",
+        "gcs bucketOps: bucket '" + name + "' already exists", true);
+    }
+    var parsed = safeJson.parse(res.body);
+    return {
+      name:         parsed.name,
+      location:     parsed.location || null,
+      storageClass: parsed.storageClass || null,
+    };
+  }
+
+  async function deleteBucket(name) {
+    _validateBucketName(name);
+    var token = await _ensureToken();
+    var url = new URL(_bucketBaseUrl() + "/" + encodeURIComponent(name));
+    var headers = authHeader.bearer(token);
+    var res = await _request("DELETE", url, headers, null, [204, 404]);
+    return res.statusCode === 204;
+  }
+
+  async function listBuckets(opts) {
+    opts = opts || {};
+    var token = await _ensureToken();
+    var url = new URL(_bucketBaseUrl());
+    url.searchParams.set("project", projectId);
+    if (opts.prefix)     url.searchParams.set("prefix", opts.prefix);
+    if (opts.maxResults) url.searchParams.set("maxResults", String(opts.maxResults));
+    if (opts.pageToken)  url.searchParams.set("pageToken", opts.pageToken);
+    var headers = authHeader.bearer(token);
+    var res = await _request("GET", url, headers, null, [200]);
+    var parsed = safeJson.parse(res.body);
+    var items = Array.isArray(parsed.items) ? parsed.items : [];
+    return items.map(function (item) {
+      return {
+        name:         item.name,
+        location:     item.location || null,
+        storageClass: item.storageClass || null,
+        timeCreated:  item.timeCreated || null,
+        updated:      item.updated || null,
+      };
+    });
+  }
+
+  async function setLifecycle(name, rules) {
+    _validateBucketName(name);
+    if (!Array.isArray(rules)) {
+      throw _err("INVALID_LIFECYCLE",
+        "gcs bucketOps: setLifecycle: rules must be an array", true);
+    }
+    rules.forEach(_validateLifecycleRule);
+    var token = await _ensureToken();
+    var url = new URL(_bucketBaseUrl() + "/" + encodeURIComponent(name));
+    var bodyObj = { lifecycle: { rule: rules } };
+    var bodyBuf = Buffer.from(JSON.stringify(bodyObj), "utf8");
+    var headers = Object.assign(authHeader.bearer(token), {
+      "Content-Type":   "application/json",
+      "Content-Length": String(bodyBuf.length),
+    });
+    await _request("PATCH", url, headers, bodyBuf, [200]);
+    return { rulesApplied: rules.length };
+  }
+
+  async function setCorsRules(name, rules) {
+    _validateBucketName(name);
+    if (!Array.isArray(rules)) {
+      throw _err("INVALID_CORS_RULE",
+        "gcs bucketOps: setCorsRules: rules must be an array", true);
+    }
+    rules.forEach(_validateCorsRule);
+    var token = await _ensureToken();
+    var url = new URL(_bucketBaseUrl() + "/" + encodeURIComponent(name));
+    var bodyObj = { cors: rules };
+    var bodyBuf = Buffer.from(JSON.stringify(bodyObj), "utf8");
+    var headers = Object.assign(authHeader.bearer(token), {
+      "Content-Type":   "application/json",
+      "Content-Length": String(bodyBuf.length),
+    });
+    await _request("PATCH", url, headers, bodyBuf, [200]);
+    return { rulesApplied: rules.length };
+  }
+
+  return {
+    protocol:     "gcs",
+    create:       createBucket,
+    delete:       deleteBucket,
+    list:         listBuckets,
+    setLifecycle: setLifecycle,
+    setCorsRules: setCorsRules,
+  };
+}
+
+module.exports = { create: create };

package/lib/object-store/index.js

@@ -27,15 +27,17 @@
  *   delete(key)                 → boolean (true if deleted, false if missing)
  *   list(prefix, opts?)         → { items: [{ key, size, lastModified }], truncated }
  */
-var localProto      = require("./local");
-var httpPutProto    = require("./http-put");
-var sigv4Proto      = require("./sigv4");
-var sigv4BucketOps  = require("./sigv4-bucket-ops");
-var gcsProto        = require("./gcs");
-var azureBlobProto  = require("./azure-blob");
-var retryHelper     = require("./retry");
-var protocolDispatcher = require("../protocol-dispatcher");
-var { ObjectStoreError } = require("../framework-error");
+var localProto             = require("./local");
+var httpPutProto           = require("./http-put");
+var sigv4Proto             = require("./sigv4");
+var sigv4BucketOps         = require("./sigv4-bucket-ops");
+var gcsProto               = require("./gcs");
+var gcsBucketOps           = require("./gcs-bucket-ops");
+var azureBlobProto         = require("./azure-blob");
+var azureBlobBucketOps     = require("./azure-blob-bucket-ops");
+var retryHelper            = require("./retry");
+var protocolDispatcher     = require("../protocol-dispatcher");
+var { ObjectStoreError }   = require("../framework-error");
 
 // All currently advertised protocols are bundled. The dispatcher's
 // `deferred` slot is the hook for adding deferred ones later.
@@ -134,13 +136,62 @@ function buildBackend(config) {
   };
 }
 
+// ---- Bucket-level ops dispatcher ----
+//
+// Bucket lifecycle (create / delete / list) + lifecycle / CORS rules
+// are service-scoped, not bucket-scoped — `b.objectStore.bucketOps`
+// resolves a per-cloud factory by protocol. Each cloud's ops shape
+// differs (S3 sigv4 vs Azure Shared Key vs GCS OAuth) so the
+// per-protocol modules each own their own validation, signing, and
+// REST-API translation; this dispatcher just routes.
+//
+// Operator entry point — unchanged from v0.6.x:
+//
+//   var ops = b.objectStore.bucketOps.create({
+//     protocol: 'sigv4' | 'azure-blob' | 'gcs',
+//     // ... protocol-specific creds ...
+//   });
+//
+// Each returned ops object exposes (where supported per-cloud):
+//   ops.create(name, opts?)
+//   ops.delete(name)
+//   ops.list(opts?)
+//   ops.setLifecycle(name, rules)
+//   ops.setCorsRules(name, rules)   // sigv4 + gcs accept (name, rules);
+//                                    // azure-blob accepts (rules) — its
+//                                    // CORS is account-level.
+var BUCKET_OPS_BY_PROTOCOL = {
+  "sigv4":      sigv4BucketOps,
+  "gcs":        gcsBucketOps,
+  "azure-blob": azureBlobBucketOps,
+};
+function _bucketOpsCreate(config) {
+  if (!config) {
+    throw _err("BAD_OPT",
+      "objectStore.bucketOps.create: config required (must include " +
+      "{ protocol })", true);
+  }
+  var protoMod = BUCKET_OPS_BY_PROTOCOL[config.protocol];
+  if (!protoMod) {
+    throw _err("UNKNOWN_PROTOCOL",
+      "objectStore.bucketOps.create: unknown protocol '" + config.protocol +
+      "' (supported: " + Object.keys(BUCKET_OPS_BY_PROTOCOL).join(", ") +
+      ")", true);
+  }
+  return protoMod.create(config);
+}
+
 module.exports = {
   buildBackend:        buildBackend,
   PROTOCOLS:           dispatcher.protocols,
   DEFERRED_PROTOCOLS:  dispatcher.deferred,
-  // Bucket-level (lifecycle / CORS / create / delete / list) ops are
-  // service-scoped, not bucket-scoped — they get their own factory.
-  // SigV4 only; GCS / Azure bucket lifecycle differs substantially per
-  // cloud and is operator-managed (Terraform / CDK / Pulumi).
-  bucketOps:           sigv4BucketOps,
+  bucketOps:           {
+    create:                  _bucketOpsCreate,
+    PROTOCOLS:               Object.keys(BUCKET_OPS_BY_PROTOCOL),
+    // Per-protocol modules exposed for advanced operators wiring
+    // their own dispatch / testing harnesses against a specific cloud.
+    sigv4:      sigv4BucketOps,
+    gcs:        gcsBucketOps,
+    "azure-blob": azureBlobBucketOps,
+  },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:7c9d3ad1-2719-437a-80c6-0d18fefad8b9",
+  "serialNumber": "urn:uuid:a13cf9c3-cc15-4fc1-bff7-03071923ae8d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T20:34:17.304Z",
+    "timestamp": "2026-05-02T21:50:09.461Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.36",
+      "bom-ref": "@blamejs/core@0.6.37",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.36",
+      "version": "0.6.37",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.36",
+      "purl": "pkg:npm/%40blamejs/core@0.6.37",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.36",
+      "ref": "@blamejs/core@0.6.37",
       "dependsOn": []
     }
   ]