@blamejs/core 0.6.24 → 0.6.26

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.26** (2026-05-02) — `blamejs restore` and `blamejs audit verify-chain` subcommands wrap the existing `b.restore` and `b.audit.verifyChain` primitives so operators can drive them from runbooks without writing app code. **`blamejs restore`**: `list` (enumerate bundles in storage), `inspect` (manifest summary without touching live data), `apply` (live in-place restore with rollback preserved), `rollback` (revert to most-recent OR named restore point), `list-rollbacks` (enumerate preserved rollback points). Two ways to identify a bundle — `--bundle <dir>` matches the shape `blamejs backup extract` produces (parent dir is treated as storage root, basename as bundle id), or `--storage-root <root> --bundle-id <id>` for multi-bundle stores. `apply` honors `--max-pulled-bytes` / `--max-pulled-files` (defaults 4 GiB / 100K), `--rollback-root` (default `<data-dir>.rollbacks`), `--no-audit`, and `BLAMEJS_BACKUP_PASSPHRASE` env. **`blamejs audit verify-chain`**: walks the live audit chain end-to-end, reports tampering with `breakAt` / `breakRowId` / expected-vs-actual prevHash; honours `--max-rows` to bound long walks; default table is `audit_log`. **Wiki CLI snapshot test now validates subcommand pairs**, not just top commands. Walks every wiki + README invocation of the form `blamejs <cmd> <sub>` and verifies that <sub> exists in the perCommand[<cmd>].subcommands list parsed from `lib/cli.js`. Surfaced one real drift on first run: `examples/wiki/seeders/prod/pages/backup-restore.js` documented `blamejs audit verify-signing` after vault rotation, but no such subcommand existed (only `verify-bundle`); fixed by shipping the new `verify-chain` subcommand and updating the wiki to reference it. Two top-level command gaps surfaced and fixed: `blamejs restore` (now real) and `blamejs network status` (was prose-promised in `network-config.js`; reworded to point at `b.network.snapshot()` for /healthz / custom diagnostics routes since wiring a CLI command for it is operator-side work). README CLI table updated with `restore` row and the two new audit subcommands.
+- **0.6.25** (2026-05-02) — `b.logStream` gains an AWS CloudWatch Logs sink AND framework-level env wiring. **CloudWatch sink**: `protocol: "cloudwatch"` POSTs `PutLogEvents` over HTTPS with SigV4 signing (service `logs`); operator pre-creates the log group + log stream (the framework does NOT auto-create). Honors IAM role + STS session-token credentials. Respects all three CloudWatch caps automatically: 10,000 events / 1 MiB total payload / 256 KiB-per-event. Per-event oversize dropped at `emit()`-time with `onDrop` fired (truncated message in the drop notification). Per-batch oversize split mid-flush. Permanent AWS errors (`ResourceNotFoundException` / `AccessDeniedException` / `InvalidParameterException` / `UnrecognizedClientException` / `SerializationException`) skip the retry budget. `InvalidSequenceTokenException` (legacy CW accounts) extracts the expected token from the error message and retries with it once. `lib/object-store/sigv4.js` `signRequest()` is now service-agnostic — accepts `opts.service` (default still `"s3"` for back-compat). Removed `cloudwatch` from `DEFERRED_PROTOCOLS`. **`b.logStream.bootFromEnv({ env })`**: framework-level env-driven init mirroring `b.network.bootFromEnv`. Reads `BLAMEJS_LOG_STREAM_PROTOCOL` (`local`/`webhook`/`otlp`/`cloudwatch`), `BLAMEJS_LOG_STREAM_URL`, `BLAMEJS_LOG_STREAM_TOKEN`, `BLAMEJS_LOG_STREAM_SERVICE_NAME`, `BLAMEJS_LOG_STREAM_SERVICE_VERSION`, `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_GROUP`, `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_STREAM`, `BLAMEJS_LOG_STREAM_PATH`, plus standard AWS_*. Operators get a working log-stream sink without writing build-app code. Wiki app's `build-app.js` replaced its inline env-reading with one `b.logStream.bootFromEnv()` call; both docker-compose configs declare the new env knobs. **Wiki env-snapshot test**: parallel to api-snapshot.json — walks `process.env.X` / `env.X` / `safeEnv.readVar("X")` reads in the wiki app + framework `lib/`, walks docker-compose env declarations, captures the union as `examples/wiki/env-snapshot.json`, fails the e2e gate when env vars are added/removed without updating the snapshot OR when source-only / compose-only gaps appear (env knob declared but unread, env read but undocumented). The validator immediately surfaced 13 real gaps in the wiki app: 5 `WIKI_*` env vars read by source but missing from docker-compose (`WIKI_VAULT_MODE`, `WIKI_DB_AT_REST`, `WIKI_AUDIT_SIGNING_MODE`, `WIKI_BIND`, `WIKI_SITE_URL`), 2 framework env vars (`BLAMEJS_AUDIT_SIGNING_MODE`, `BLAMEJS_TMPDIR`) read by `lib/db.js` via `safeEnv.readVar` but never declared in the wiki's compose configs, and 6 dead env knobs in compose that nothing read. All 13 fixed. Update workflow: `BLAMEJS_UPDATE_ENV_SNAPSHOT=1 node examples/wiki/test/validate-env-snapshot.js` (mirrors the api-snapshot UX). Wiki observability page documents the new sink alongside webhook + otlp; README "What ships in the box" calls out all four log-stream sinks. Tests cover endpoint resolution, event-byte accounting, batch sorting + sequence-token round-trip, permanent-error classifier, validation, round-trip via mock CloudWatch, STS session-token propagation, ResourceNotFoundException no-retry path, 256 KiB per-event hard cap, dispatcher integration, AND batch splitting on the 1-MiB cap (5 quarter-MB events POST as 4 + 1 batches).
 - **0.6.24** (2026-05-02) — `b.logStream` gains an OTLP/HTTP-JSON sink. `protocol: "otlp"` now forwards log records to any OpenTelemetry collector via the OTel Logs Data Model — `resourceLogs` → `scopeLogs` → `logRecords` envelope with `severityNumber` (debug=5/info=9/warn=13/error=17), `severityText`, `timeUnixNano` (string-encoded for JSON-safe 64-bit), `body.stringValue`, and OTel-typed attributes. Operator config: `{ url, serviceName, serviceVersion, resourceAttributes, auth, headers, batchSize, retry, onDrop, ... }` — same back-pressure semantics as the webhook sink (per-sink ring buffer, batched flush on size or maxBatchAgeMs, exponential-backoff retry, drop-on-overflow with operator-supplied onDrop callback). URL convention: `/v1/logs` is auto-appended when the operator passes the collector root. JSON not protobuf — operators benchmarking >100K logs/s ship the OTel Collector locally so the framework hands JSON to a sidecar that forwards via gRPC. Removed `otlp` from `DEFERRED_PROTOCOLS`. Wiki observability page documents the new sink with a `b.logStream.init` example pointing at an OTel collector. Tests cover URL resolution, attribute encoding (string / int / float / bool / array / nested object), severity mapping, round-trip via mock collector, auth header pass-through, retry on 5xx + drop on retry-exhaustion, buffer overflow, dispatcher integration. Verified 0 leaks across 291 commits via `gitleaks`.
 - **0.6.23** (2026-05-02) — v0.6.22 follow-up cleanup. The cron-repeat call site in queue-local.js was passing both `availableAt` AND `delaySeconds` (the former was the precise next-fire ms; the latter was a redundant `Math.floor((nextMs - nowMs) / 1000)` computation that only existed to work around the bug v0.6.22 fixed). Dropped — the cron repeat now passes `availableAt` alone, matching the queue's documented precedence rule. The enqueue() docstring gains a 20-line "SCHEDULING PRECEDENCE" header documenting that `opts.availableAt` wins over `opts.delaySeconds` when both are passed, why the framework chose that direction, and which callers should use which form. New round-trip preservation regression test (`testEnqueueRoundTripsAvailableAt`) covers three precise targets, the delaySeconds-only path, and the both-opts-set case — gates against any future "I'll just rederive it from the floored seconds" mistake. Audited the rest of the framework for the same `(absolute-time, relative-time)` opt-overlap shape (cache.set, session.rotate, apiKey, dualControl): queue is the only primitive carrying both forms, so a generalized `b.time.resolveTimePoint` primitive would be premature with one call site.
 - **0.6.22** (2026-05-02) — `b.queue.enqueue({ availableAt })` is now honoured. Previously the local-protocol enqueue() ignored opts.availableAt entirely, recomputing from `Date.now() + delaySeconds*1000`. The cron-repeat path passes both fields (the exact next-fire ms in availableAt + the floored seconds in delaySeconds), and the enqueue's recomputation lost sub-second precision plus drifted on the internal clock-vs-caller delta. Symptoms: cron-scheduled jobs landed up to 999ms off the intended boundary; the queue-flow-repeat smoke test was intermittently flaky on slow CI runners (caught by ubuntu-latest on the v0.6.21 commit). Fix: enqueue() honours opts.availableAt directly when finite; falls back to delaySeconds-based shorthand otherwise. Operators relying on `enqueue({ availableAt: T })` for non-cron scheduled jobs (e.g. "deliver this notification at exactly 09:00 tomorrow") now get the requested time instead of nowMs+0.

package/README.md

@@ -47,7 +47,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **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, 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), DNS with IPv6 / DoH / DoT / 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`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
-- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
+- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector, AWS CloudWatch Logs via SigV4), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`).
 - **Format helpers** — RFC 4180 CSV with Excel formula-injection prevention (`b.csv`), RFC 9562 UUID v4 + v7 (`b.uuid`), URL-safe slugs (`b.slug`), TZ-aware datetime (`b.time`), ZIP creation (`b.archive`), HMAC-signed cursor pagination (`b.pagination`), HTML form rendering + validation + CSRF (`b.forms`).
 - **Production** — cluster leader election with fenced leases over Postgres/SQLite (`b.cluster`); cron + interval scheduler that runs exactly-once globally (`b.scheduler`); retry with full-jitter backoff + circuit breaker (`b.retry`); graceful shutdown (`b.appShutdown`); NTP boot check (`b.ntpCheck`); end-to-end-encrypted backup bundles with pre-flush fail-closed mode (`b.backup`); restore with pulled-bundle footprint preflight (`b.restore`); GDPR / PCI / HIPAA-shaped retention rules with multi-stage warn → archive → erase, legal-hold exemptions, dry-run preview, cross-table cascade (`b.retention`).
@@ -76,8 +76,9 @@ blamejs seed          run | status                                --db <path> --
 blamejs dev           --command <cmd> [--watch <dir>...]
 blamejs api-snapshot  capture | compare                           --file <path>
 blamejs api-key       issue | revoke | list | rotate | verify     --data-dir <path> --namespace <ns>
-blamejs audit         archive | export | verify | purge           --data-dir <path>
+blamejs audit         archive | export | verify-bundle | verify-chain | purge   --data-dir <path>
 blamejs backup        inspect | verify | extract                  --bundle <path>
+blamejs restore       list | inspect | apply | rollback | list-rollbacks         --data-dir <path> --bundle <dir>
 blamejs mtls          status | show-cert | init | issue | issue-p12  --data-dir <path>
 blamejs vault         status | seal | unseal | rotate             --data-dir <path>
 blamejs security      assert                                      --data-dir <path>

package/lib/cli.js

@@ -38,14 +38,18 @@ var fs = require("node:fs");
 var os = require("node:os");
 var path = require("path");
 var apiSnapshot = require("./api-snapshot");
+var auditChain = require("./audit-chain");
 var auditTools = require("./audit-tools");
+var backup = require("./backup");
 var cliHelpers = require("./cli-helpers");
 var constants = require("./constants");
 var crypto = require("./crypto");
 var dev = require("./dev");
 var migrations = require("./migrations");
 var requestHelpers = require("./request-helpers");
+var restore = require("./restore");
 var restoreBundle = require("./restore-bundle");
+var restoreRollback = require("./restore-rollback");
 var seeders = require("./seeders");
 var vaultPassphraseOps = require("./vault/passphrase-ops");
 
@@ -512,6 +516,7 @@ var AUDIT_USAGE = [
   "  archive        Bundle audit rows older than --before into a verified archive",
   "  export         Auditor evidence bundle for a date range",
   "  verify-bundle  Round-trip integrity check on an archive or export bundle",
+  "  verify-chain   Walk the live audit chain end-to-end; reports tampering",
   "  purge          Delete live rows already captured in a verified archive",
   "",
   "Common flags:",
@@ -527,12 +532,17 @@ var AUDIT_USAGE = [
   "  --to <date>            Latest recordedAt (inclusive)",
   "  --action <name>        Restrict to a single audit action",
   "",
+  "verify-chain flags:",
+  "  --db <path>            SQLite database path (required)",
+  "  --table <name>         Audit table name (default audit_log)",
+  "  --max-rows <N>         Stop after walking N rows (default: walk all)",
+  "",
   "purge flags:",
   "  --confirm              REQUIRED — operator acknowledgement of destructive op",
   "",
   "Exit codes:",
-  "  0  success",
-  "  1  operation failed",
+  "  0  success (or chain verified ok)",
+  "  1  operation failed (or chain tampered)",
   "  2  bad invocation",
 ].join("\n");
 
@@ -561,6 +571,7 @@ async function _runAudit(args, ctx) {
   }
   var sub = args.pos[0];
   var passphrase = _resolvePassphrase(args, ctx);
+  // verify-chain reads the live DB, no bundle passphrase needed.
   var passRequired = sub === "archive" || sub === "export" ||
                      sub === "verify-bundle" || sub === "purge";
   if (passRequired && !passphrase) {
@@ -633,6 +644,56 @@ async function _runAudit(args, ctx) {
     }
   }
 
+  if (sub === "verify-chain") {
+    var dbPathV = args.flags.db;
+    if (!dbPathV || dbPathV === true) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: --db <path> is required");
+      return 2;
+    }
+    dbPathV = _resolvePath(String(dbPathV), ctx.cwd);
+    var tableV = args.flags.table ? String(args.flags.table) : "audit_log";
+    var maxRows = args.flags["max-rows"];
+    var maxRowsN = maxRows === undefined ? undefined : Number(maxRows);
+    if (maxRowsN !== undefined && (!Number.isFinite(maxRowsN) || maxRowsN < 1)) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: --max-rows must be a positive integer");
+      return 2;
+    }
+    var dbV;
+    try { dbV = _openSqlite(dbPathV); }
+    catch (e) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: cannot open db at " + dbPathV +
+        ": " + ((e && e.message) || String(e)));
+      return 1;
+    }
+    try {
+      var queryAllAsync = async function (sql, params) {
+        var stmt = dbV.prepare(sql);
+        return Array.isArray(params) ? stmt.all.apply(stmt, params) : stmt.all();
+      };
+      var vc = await auditChain.verifyChain(queryAllAsync, tableV,
+        maxRowsN ? { maxRows: maxRowsN } : {});
+      if (vc.ok) {
+        _writeLine(ctx.stdout, "OK — chain verified" +
+          " (table=" + vc.table +
+          ", rowsVerified=" + vc.rowsVerified + ")");
+        return 0;
+      }
+      _writeLine(ctx.stderr, "FAIL — " + vc.reason +
+        " (table=" + vc.table +
+        ", rowsVerified=" + vc.rowsVerified +
+        ", breakAt=" + vc.breakAt +
+        ", breakRowId=" + vc.breakRowId + ")");
+      _writeLine(ctx.stderr, "  expected prevHash: " + vc.expected);
+      _writeLine(ctx.stderr, "  actual:            " + vc.actual);
+      return 1;
+    } catch (e) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: " + ((e && e.message) || String(e)));
+      return 1;
+    } finally {
+      try { dbV.close(); } catch (_e) { /* close best-effort */ }
+    }
+  }
+
   if (sub === "purge") {
     var inP = _resolveOutPath(args.flags.archive || args.flags.in, ctx);
     if (!inP) {
@@ -661,6 +722,282 @@ async function _runAudit(args, ctx) {
   return 2;
 }
 
+// ---- Subcommand: restore ----
+//
+// Operator workflow on top of b.restore: list bundles in storage,
+// inspect a specific one, do a live in-place restore (with rollback
+// preservation), and roll back to a previous restore point. Wraps the
+// restore primitive's run / inspect / list / rollback / list-rollbacks
+// surface; uses b.backup.localStorage as the storage adapter (the same
+// adapter that wrote the bundles).
+//
+// Two ways to identify a bundle for inspect / apply:
+//   --bundle <dir>            point at an extracted bundle directory
+//                             (parent dir is treated as storage root,
+//                              dir basename as bundle id — matches the
+//                              shape `blamejs backup extract` produces)
+//   --storage-root <root> --bundle-id <id>   use a multi-bundle root
+
+var RESTORE_USAGE = [
+  "Usage: blamejs restore <subcommand> [flags]",
+  "",
+  "Subcommands:",
+  "  list              List bundles available in storage",
+  "  inspect           Read a bundle manifest summary (no live changes)",
+  "  apply             Live in-place restore with rollback preserved",
+  "  rollback          Revert the most-recent (or named) restore",
+  "  list-rollbacks    List preserved rollback points",
+  "",
+  "Common flags:",
+  "  --data-dir <path>      Live data directory (apply / rollback / list-rollbacks)",
+  "  --storage-root <path>  Directory containing bundle subdirs (list)",
+  "  --bundle <dir>         Extracted bundle directory (inspect / apply)",
+  "  --bundle-id <id>       Alternative: pass id with --storage-root",
+  "  --rollback-root <path> Override rollback dir (default <data-dir>.rollbacks)",
+  "  --passphrase <string>  Bundle passphrase (or env BLAMEJS_BACKUP_PASSPHRASE)",
+  "",
+  "apply flags:",
+  "  --max-pulled-bytes <N> Refuse a bundle whose pulled bytes exceed N (default 4 GiB)",
+  "  --max-pulled-files <N> Refuse a bundle whose pulled file count exceeds N (default 100K)",
+  "  --no-audit             Suppress audit emission (default ON)",
+  "",
+  "rollback flags:",
+  "  --rollback <pathOrId>  Specific rollback point to restore (default: most recent)",
+  "",
+  "Exit codes:",
+  "  0  success",
+  "  1  operation failed",
+  "  2  bad invocation",
+].join("\n");
+
+// Resolve {storageRoot, bundleId} from either --bundle <dir> OR
+// --storage-root <root> --bundle-id <id>. Returns null + writes an
+// error on the report when neither shape works.
+function _resolveRestoreBundleSelector(args, ctx, report, requireBundle) {
+  var bundleFlag = args.flags.bundle;
+  var storageRootFlag = args.flags["storage-root"];
+  var bundleIdFlag = args.flags["bundle-id"];
+  if (bundleFlag && bundleFlag !== true) {
+    var bundlePath = _resolvePath(String(bundleFlag), ctx.cwd);
+    return {
+      storageRoot: path.dirname(bundlePath),
+      bundleId:    path.basename(bundlePath),
+    };
+  }
+  if (storageRootFlag && storageRootFlag !== true) {
+    var sr = _resolvePath(String(storageRootFlag), ctx.cwd);
+    if (requireBundle) {
+      if (!bundleIdFlag || bundleIdFlag === true) {
+        report.error("--bundle-id is required when using --storage-root", 2);
+        return null;
+      }
+      return { storageRoot: sr, bundleId: String(bundleIdFlag) };
+    }
+    return { storageRoot: sr, bundleId: null };
+  }
+  if (requireBundle) {
+    report.error("--bundle <dir> OR --storage-root <root> --bundle-id <id> is required", 2);
+  } else {
+    report.error("--storage-root <root> is required", 2);
+  }
+  return null;
+}
+
+async function _runRestore(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs restore").usage(RESTORE_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs restore " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(RESTORE_USAGE);
+  }
+  if (["list", "inspect", "apply", "rollback", "list-rollbacks"].indexOf(sub) === -1) {
+    cliHelpers.makeReporter(ctx, "blamejs restore").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs restore").usage(RESTORE_USAGE);
+  }
+
+  // list / inspect / apply all need a storage root + (for inspect/apply) a bundle id.
+  // rollback / list-rollbacks only need data-dir.
+  var dataDirFlag = args.flags["data-dir"];
+  function _requireDataDir() {
+    if (!dataDirFlag || dataDirFlag === true) {
+      report.error("--data-dir <path> is required", 2);
+      return null;
+    }
+    return _resolvePath(String(dataDirFlag), ctx.cwd);
+  }
+
+  if (sub === "list") {
+    var sel = _resolveRestoreBundleSelector(args, ctx, report, false);
+    if (!sel) return 2;
+    try {
+      var storage = backup.localStorage({ root: sel.storageRoot });
+      var bundles = await storage.listBundles();
+      if (bundles.length === 0) {
+        report.write("no bundles in " + sel.storageRoot);
+        return report.ok();
+      }
+      report.write("bundles in " + sel.storageRoot + ": " + bundles.length);
+      for (var i = 0; i < bundles.length; i++) {
+        var b = bundles[i];
+        report.write("  " + b.bundleId +
+          "  size=" + (b.size != null ? b.size + "B" : "?") +
+          "  createdAt=" + (b.createdAt || "?"));
+      }
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "inspect") {
+    var selI = _resolveRestoreBundleSelector(args, ctx, report, true);
+    if (!selI) return 2;
+    try {
+      var storageI = backup.localStorage({ root: selI.storageRoot });
+      // restore.create needs a passphrase + dataDir even for inspect because
+      // its closure captures them; pass placeholders since inspect doesn't
+      // touch them.
+      var rI = restore.create({
+        dataDir: path.join(os.tmpdir(), "blamejs-restore-inspect-noop"),
+        storage: storageI,
+        passphrase: "inspect-only-not-used",
+        audit: false,
+      });
+      var manifest = await rI.inspect(selI.bundleId);
+      var totalBytesI = 0;
+      for (var ix = 0; ix < manifest.files.length; ix++) {
+        totalBytesI += manifest.files[ix].encryptedSize || 0;
+      }
+      report.write("bundle:        " + selI.bundleId);
+      report.write("storage root:  " + selI.storageRoot);
+      report.write("manifest:      v" + (manifest.manifestVersion || manifest.version || "unknown"));
+      report.write("created:       " + (manifest.createdAt || "unknown"));
+      report.write("files:         " + manifest.files.length);
+      report.write("encrypted size: " + totalBytesI + " bytes");
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "apply") {
+    var dd = _requireDataDir();
+    if (!dd) return 2;
+    var selA = _resolveRestoreBundleSelector(args, ctx, report, true);
+    if (!selA) return 2;
+    var pp = cliHelpers.resolvePassphrase(args, ctx, {
+      flag: "passphrase", envVar: "BLAMEJS_BACKUP_PASSPHRASE",
+    });
+    if (!pp) {
+      return report.error("--passphrase or BLAMEJS_BACKUP_PASSPHRASE is required", 2);
+    }
+    var rollbackRootA = args.flags["rollback-root"]
+      ? _resolvePath(String(args.flags["rollback-root"]), ctx.cwd) : undefined;
+    var maxBytes = args.flags["max-pulled-bytes"];
+    var maxFiles = args.flags["max-pulled-files"];
+    if (maxBytes !== undefined && (!Number.isFinite(Number(maxBytes)) || Number(maxBytes) <= 0)) {
+      return report.error("--max-pulled-bytes must be a positive number", 2);
+    }
+    if (maxFiles !== undefined && (!Number.isFinite(Number(maxFiles)) || Number(maxFiles) <= 0)) {
+      return report.error("--max-pulled-files must be a positive number", 2);
+    }
+    try {
+      var storageA = backup.localStorage({ root: selA.storageRoot });
+      var rA = restore.create({
+        dataDir:         dd,
+        storage:         storageA,
+        passphrase:      pp,
+        rollbackRoot:    rollbackRootA,
+        audit:           args.flags["no-audit"] !== true,
+        maxPulledBytes:  maxBytes !== undefined ? Number(maxBytes) : undefined,
+        maxPulledFiles:  maxFiles !== undefined ? Number(maxFiles) : undefined,
+      });
+      var summary = await rA.run({ bundleId: selA.bundleId });
+      report.write("OK — restored");
+      report.write("  bundle:       " + summary.bundleId);
+      report.write("  files:        " + summary.fileCount);
+      report.write("  bytes:        " + summary.totalBytes);
+      report.write("  rollback at:  " + summary.rollbackPath);
+      report.write("  duration ms:  " + summary.durationMs);
+      report.write("");
+      report.write("Stop and start the app fresh against " + dd + " to pick up the restored state.");
+      report.write("Roll back with: blamejs restore rollback --data-dir " + dd);
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "rollback") {
+    var ddR = _requireDataDir();
+    if (!ddR) return 2;
+    var rollbackRootR = args.flags["rollback-root"]
+      ? _resolvePath(String(args.flags["rollback-root"]), ctx.cwd)
+      : (ddR + ".rollbacks");
+    var rollbackTarget = args.flags.rollback;
+    var targetPath = null;
+    if (rollbackTarget && rollbackTarget !== true) {
+      // operator can pass either a full path or just the basename inside rollback-root
+      var rt = String(rollbackTarget);
+      targetPath = path.isAbsolute(rt) ? rt : path.resolve(rollbackRootR, rt);
+    } else {
+      // Default to most-recent rollback point (mirrors restore.create().rollback()).
+      var ptsR;
+      try { ptsR = restoreRollback.list({ rollbackRoot: rollbackRootR }); }
+      catch (e) {
+        return report.error("listing rollbacks at " + rollbackRootR + ": " + ((e && e.message) || String(e)));
+      }
+      if (!ptsR || ptsR.length === 0) {
+        return report.error("no rollback points at " + rollbackRootR + " — pass --rollback <pathOrId> explicitly", 2);
+      }
+      targetPath = ptsR[0].rollbackPath;
+    }
+    try {
+      var rR = await restoreRollback.rollback({
+        dataDir:      ddR,
+        rollbackPath: targetPath,
+        rollbackRoot: rollbackRootR,
+      });
+      report.write("OK — rolled back");
+      report.write("  data dir:     " + ddR);
+      report.write("  used:         " + (targetPath || "most-recent rollback point"));
+      report.write("  discarded at: " + (rR.discardedAt || "(unknown)"));
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "list-rollbacks") {
+    var ddL = _requireDataDir();
+    if (!ddL) return 2;
+    var rollbackRootL = args.flags["rollback-root"]
+      ? _resolvePath(String(args.flags["rollback-root"]), ctx.cwd)
+      : (ddL + ".rollbacks");
+    try {
+      var pts = restoreRollback.list({ rollbackRoot: rollbackRootL });
+      if (pts.length === 0) {
+        report.write("no rollback points at " + rollbackRootL);
+        return report.ok();
+      }
+      report.write("rollback points at " + rollbackRootL + ": " + pts.length);
+      for (var p = 0; p < pts.length; p++) {
+        var pt = pts[p];
+        report.write("  " + (pt.rollbackPath || pt) +
+          (pt.recordedAt ? "  recordedAt=" + pt.recordedAt : "") +
+          (pt.bundleId ? "  bundleId=" + pt.bundleId : ""));
+      }
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  return 2;
+}
+
 // ---- Top-level help ----
 
 // ---- Subcommand: api-key ----
@@ -1860,6 +2197,7 @@ var TOP_USAGE = [
   "  api-key           Issue / revoke / list / rotate / verify API keys for a namespace",
   "  audit             Operator tooling on top of the audit chain (archive / export / verify / purge)",
   "  backup            Inspect / verify / extract a backup bundle from disk",
+  "  restore           Live in-place restore from a bundle (list / inspect / apply / rollback / list-rollbacks)",
   "  mtls              Inspect or generate the in-box mTLS CA + leaf certs (status / show-cert / init / issue / issue-p12)",
   "  vault             Seal / unseal / rotate the on-disk vault keypair (plaintext ↔ wrapped)",
   "  security          Run b.security.assertProduction against the live framework",
@@ -1919,6 +2257,7 @@ async function main(argv, opts) {
     if (subTopic === "api-key")      { _writeLine(ctx.stdout, API_KEY_USAGE);      return 0; }
     if (subTopic === "audit")        { _writeLine(ctx.stdout, AUDIT_USAGE);        return 0; }
     if (subTopic === "backup")       { _writeLine(ctx.stdout, BACKUP_USAGE);       return 0; }
+    if (subTopic === "restore")      { _writeLine(ctx.stdout, RESTORE_USAGE);      return 0; }
     if (subTopic === "mtls")         { _writeLine(ctx.stdout, MTLS_USAGE);         return 0; }
     if (subTopic === "vault")        { _writeLine(ctx.stdout, VAULT_USAGE);        return 0; }
     if (subTopic === "security")     { _writeLine(ctx.stdout, SECURITY_USAGE);     return 0; }
@@ -1940,6 +2279,7 @@ async function main(argv, opts) {
   if (cmd === "api-key")      return await _runApiKey(rest, ctx);
   if (cmd === "audit")        return await _runAudit(rest, ctx);
   if (cmd === "backup")       return await _runBackup(rest, ctx);
+  if (cmd === "restore")      return await _runRestore(rest, ctx);
   if (cmd === "mtls")         return await _runMtls(rest, ctx);
   if (cmd === "vault")        return await _runVault(rest, ctx);
   if (cmd === "security")     return await _runSecurity(rest, ctx);
@@ -1966,6 +2306,7 @@ module.exports = {
   API_KEY_USAGE:       API_KEY_USAGE,
   AUDIT_USAGE:         AUDIT_USAGE,
   BACKUP_USAGE:        BACKUP_USAGE,
+  RESTORE_USAGE:       RESTORE_USAGE,
   MTLS_USAGE:          MTLS_USAGE,
   VAULT_USAGE:         VAULT_USAGE,
 };

package/lib/log-stream-cloudwatch.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * AWS CloudWatch Logs sink — PutLogEvents over HTTPS with SigV4.
+ *
+ * Operator config:
+ *
+ *   {
+ *     region:           "us-east-1"
+ *     accessKeyId:      env("AWS_ACCESS_KEY_ID")
+ *     secretAccessKey:  env("AWS_SECRET_ACCESS_KEY")
+ *     sessionToken:     env("AWS_SESSION_TOKEN")    // optional, STS creds
+ *     logGroupName:     "my-app-logs"               // operator pre-creates
+ *     logStreamName:    "instance-1"                // operator pre-creates
+ *     endpoint:         "https://logs.us-east-1.amazonaws.com"   // optional
+ *     batchSize:        100                          // CW caps at 10K events / 1 MiB per call
+ *     maxBatchAgeMs:    C.TIME.seconds(5)
+ *     timeoutMs:        C.TIME.seconds(30)
+ *     retry:            { maxAttempts, baseDelayMs, ... }
+ *     bufferLimit:      10000
+ *     onDrop:           function ({ reason, batch, error }) { ... }
+ *   }
+ *
+ * Wire format (Logs_20140328 PutLogEvents — JSON-1.1 over HTTPS):
+ *
+ *   POST /
+ *   X-Amz-Target: Logs_20140328.PutLogEvents
+ *   Content-Type: application/x-amz-json-1.1
+ *   Authorization: AWS4-HMAC-SHA256 Credential=... SignedHeaders=... Signature=...
+ *   Body: { logGroupName, logStreamName, logEvents: [{ timestamp, message }, ...] }
+ *
+ * AWS quirks the framework handles:
+ *   - Events MUST be sorted by timestamp ascending — sink sorts before send.
+ *   - Per-batch caps: 10,000 events AND <= 1 MiB total payload. Operator
+ *     batchSize is enforced; the framework also splits batches when the
+ *     1 MiB ceiling is reached mid-build.
+ *   - Per-event 256 KiB hard cap. Oversized events are dropped at emit-time
+ *     with onDrop fired.
+ *   - sequenceToken is optional in modern CloudWatch (post-2023). If a
+ *     legacy account requires it, CloudWatch returns
+ *     InvalidSequenceTokenException with the expected token; the
+ *     framework retries with that token transparently.
+ *   - ResourceNotFoundException -> permanent error (operator forgot to
+ *     create the log group or stream); surfaced via onDrop with a
+ *     clear error.
+ *
+ * SigV4 signing reuses lib/object-store/sigv4.js with service: "logs".
+ */
+var C = require("./constants");
+var nodeCrypto = require("node:crypto");
+var sigv4 = require("./object-store/sigv4");
+var retryHelper = require("./retry");
+var { LogStreamError } = require("./framework-error");
+var httpClient = require("./http-client");
+
+var MAX_RESPONSE_BYTES = C.BYTES.mib(1);
+var CW_MAX_EVENTS_PER_BATCH = 10000;
+var CW_MAX_BATCH_BYTES      = C.BYTES.mib(1);
+var CW_MAX_EVENT_BYTES      = 256 * 1024;
+var CW_EVENT_OVERHEAD_BYTES = 26;
+
+var DEFAULTS = {
+  batchSize:     100,
+  maxBatchAgeMs: C.TIME.seconds(5),
+  timeoutMs:     C.TIME.seconds(30),
+  bufferLimit:   10000,
+};
+
+var _err = LogStreamError.factory;
+
+function _resolveEndpoint(cfg) {
+  if (cfg.endpoint) return cfg.endpoint.replace(/\/+$/, "") + "/";
+  return "https://logs." + cfg.region + ".amazonaws.com/";
+}
+
+function _eventByteSize(message) {
+  return Buffer.byteLength(message, "utf8") + CW_EVENT_OVERHEAD_BYTES;
+}
+
+function _serializeBatch(events, cfg, sequenceToken) {
+  events.sort(function (a, b) { return a.timestamp - b.timestamp; });
+  var body = {
+    logGroupName:  cfg.logGroupName,
+    logStreamName: cfg.logStreamName,
+    logEvents:     events,
+  };
+  if (sequenceToken) body.sequenceToken = sequenceToken;
+  return Buffer.from(JSON.stringify(body), "utf8");
+}
+
+function _signedHeaders(cfg, body) {
+  var url = _resolveEndpoint(cfg);
+  var payloadHash = nodeCrypto.createHash("sha256").update(body).digest("hex");
+  var unsigned = {
+    "Content-Type": "application/x-amz-json-1.1",
+    "X-Amz-Target": "Logs_20140328.PutLogEvents",
+  };
+  var signed = sigv4.signRequest({
+    method:          "POST",
+    url:             url,
+    headers:         unsigned,
+    payloadHash:     payloadHash,
+    region:          cfg.region,
+    service:         "logs",
+    accessKeyId:     cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+    sessionToken:    cfg.sessionToken || null,
+  });
+  return signed.headers;
+}
+
+function _post(cfg, body, headers) {
+  return httpClient.request({
+    method:           "POST",
+    url:              _resolveEndpoint(cfg),
+    headers:          headers,
+    body:             body,
+    idleTimeoutMs:    cfg.timeoutMs,
+    maxResponseBytes: MAX_RESPONSE_BYTES,
+    errorClass:       LogStreamError,
+    allowedProtocols: cfg.allowedProtocols,
+    allowInternal:    cfg.allowInternal,
+  });
+}
+
+function _isPermanentAwsError(err) {
+  if (!err) return false;
+  var msg = err.message || "";
+  if (/ResourceNotFoundException/.test(msg)) return true;
+  if (/InvalidParameterException/.test(msg)) return true;
+  if (/UnrecognizedClientException/.test(msg)) return true;
+  if (/AccessDeniedException/.test(msg)) return true;
+  if (/SerializationException/.test(msg)) return true;
+  return false;
+}
+
+function create(config) {
+  if (!config || !config.region) {
+    throw _err("BAD_OPT", "log-stream cloudwatch requires { region }");
+  }
+  if (!config.accessKeyId || !config.secretAccessKey) {
+    throw _err("BAD_OPT",
+      "log-stream cloudwatch requires { accessKeyId, secretAccessKey } " +
+      "(IAM role or env-supplied STS credentials)");
+  }
+  if (!config.logGroupName || !config.logStreamName) {
+    throw _err("BAD_OPT",
+      "log-stream cloudwatch requires { logGroupName, logStreamName } " +
+      "(operator pre-creates both via aws logs create-log-group / create-log-stream " +
+      "or CDK / Terraform; the framework does NOT auto-create)");
+  }
+  var cfg = Object.assign({}, DEFAULTS, config);
+  var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) { /* best-effort */ }
+  }
+  var buffer = [];
+  var dropCount = 0;
+  var flushTimer = null;
+  var inFlight = false;
+  var closed = false;
+  var sequenceToken = null;
+
+  function _scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(function () { flushTimer = null; _flush(); }, cfg.maxBatchAgeMs);
+    flushTimer.unref();
+  }
+
+  function _takeBatch() {
+    var batch = [];
+    var totalBytes = 0;
+    while (buffer.length > 0) {
+      var nextEvent = buffer[0];
+      var size = _eventByteSize(nextEvent.message);
+      if (batch.length > 0 &&
+          (batch.length >= cfg.batchSize ||
+           batch.length >= CW_MAX_EVENTS_PER_BATCH ||
+           totalBytes + size > CW_MAX_BATCH_BYTES)) {
+        break;
+      }
+      batch.push(buffer.shift());
+      totalBytes += size;
+    }
+    return batch;
+  }
+
+  async function _flush() {
+    if (inFlight) return;
+    if (buffer.length === 0) return;
+    inFlight = true;
+    try {
+      while (buffer.length > 0 && !closed) {
+        var batch = _takeBatch();
+        if (batch.length === 0) break;
+        try {
+          await retryHelper.withRetry(function () {
+            return _send(batch);
+          }, Object.assign({
+            isPermanent: _isPermanentAwsError,
+          }, cfg.retry || {}));
+        } catch (e) {
+          dropCount += batch.length;
+          _emitDrop("retry-exhausted", batch, e);
+          break;
+        }
+      }
+    } finally {
+      inFlight = false;
+      if (buffer.length > 0) _scheduleFlush();
+    }
+  }
+
+  async function _send(batch) {
+    var body = _serializeBatch(batch, cfg, sequenceToken);
+    var headers = _signedHeaders(cfg, body);
+    var res;
+    try {
+      res = await _post(cfg, body, headers);
+    } catch (e) {
+      var match = /expected sequenceToken is:\s*(\S+)/.exec(e.message || "");
+      if (match) {
+        sequenceToken = match[1];
+        var retryBody = _serializeBatch(batch, cfg, sequenceToken);
+        var retryHeaders = _signedHeaders(cfg, retryBody);
+        res = await _post(cfg, retryBody, retryHeaders);
+      } else {
+        throw e;
+      }
+    }
+    if (res && res.body) {
+      try {
+        var parsed = JSON.parse(res.body.toString("utf8"));
+        if (parsed && parsed.nextSequenceToken) sequenceToken = parsed.nextSequenceToken;
+      } catch (_e) { /* response body not JSON; modern CW returns empty */ }
+    }
+    return res;
+  }
+
+  function emit(record) {
+    if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
+    var message;
+    if (typeof record.message === "string") {
+      message = record.message;
+    } else {
+      message = JSON.stringify(record);
+    }
+    var size = _eventByteSize(message);
+    if (size > CW_MAX_EVENT_BYTES) {
+      _emitDrop("event-too-large", [{
+        timestamp: record.ts || Date.now(),
+        message:   message.slice(0, 200) + "...[truncated for drop event]",
+      }], new Error("event exceeds 256 KiB CloudWatch hard cap (was " + size + " bytes)"));
+      dropCount += 1;
+      return Promise.resolve({ accepted: false, reason: "event too large" });
+    }
+    if (buffer.length >= cfg.bufferLimit) {
+      var dropped = buffer.shift();
+      dropCount += 1;
+      _emitDrop("overflow", [dropped], null);
+    }
+    buffer.push({
+      timestamp: record.ts || Date.now(),
+      message:   message,
+    });
+    if (buffer.length >= cfg.batchSize) {
+      _flush().catch(function () {});
+    } else {
+      _scheduleFlush();
+    }
+    return Promise.resolve({ accepted: true, queued: buffer.length });
+  }
+
+  async function close() {
+    closed = true;
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    await _flush();
+  }
+
+  function stats() {
+    return {
+      queued:        buffer.length,
+      dropped:       dropCount,
+      inFlight:      inFlight,
+      sequenceToken: sequenceToken,
+      endpoint:      _resolveEndpoint(cfg),
+    };
+  }
+
+  return {
+    protocol: "cloudwatch",
+    emit:     emit,
+    close:    close,
+    stats:    stats,
+    flush:    _flush,
+  };
+}
+
+module.exports = {
+  create:                create,
+  _resolveEndpoint:      _resolveEndpoint,
+  _eventByteSize:        _eventByteSize,
+  _serializeBatch:       _serializeBatch,
+  _isPermanentAwsError:  _isPermanentAwsError,
+  CW_MAX_EVENTS_PER_BATCH: CW_MAX_EVENTS_PER_BATCH,
+  CW_MAX_BATCH_BYTES:    CW_MAX_BATCH_BYTES,
+  CW_MAX_EVENT_BYTES:    CW_MAX_EVENT_BYTES,
+};

package/lib/log-stream.js

@@ -14,12 +14,16 @@
  *              Model. Operators with an OTel collector running
  *              (k8s, cloud) get standard log forwarding without a
  *              vendor-specific adapter.
+ *   cloudwatch — AWS CloudWatch Logs (PutLogEvents) over HTTPS with
+ *              SigV4. Operator pre-creates the log group + log stream;
+ *              the framework signs and POSTs batches respecting the
+ *              10K-event / 1 MiB / 256 KiB-per-event AWS caps. Honors
+ *              IAM role + STS session tokens.
  *
  * Adapters listed as deferred and surfacing a clear error when
  * selected:
  *
- *   syslog     — RFC 5424 syslog over TLS
- *   cloudwatch — AWS CloudWatch Logs (PutLogEvents)
+ *   syslog — RFC 5424 syslog over TLS
  *
  * Every emit goes through lib/redact.js BEFORE any sink sees it. PHI/PCI
  * never reaches operational logs even on a misconfigured field name —
@@ -42,11 +46,12 @@
  *   logStream.shutdown()
  *   logStream.listSinks()                         → [{ name, protocol, stats }]
  */
-var localProto   = require("./log-stream-local");
-var webhookProto = require("./log-stream-webhook");
-var otlpProto    = require("./log-stream-otlp");
-var redactor     = require("./redact");
-var lazyRequire  = require("./lazy-require");
+var localProto      = require("./log-stream-local");
+var webhookProto    = require("./log-stream-webhook");
+var otlpProto       = require("./log-stream-otlp");
+var cloudwatchProto = require("./log-stream-cloudwatch");
+var redactor        = require("./redact");
+var lazyRequire     = require("./lazy-require");
 var protocolDispatcher = require("./protocol-dispatcher");
 var { LogStreamError } = require("./framework-error");
 
@@ -54,13 +59,13 @@ var dispatcher = protocolDispatcher.create({
   name:       "log-stream",
   errorClass: LogStreamError,
   protocols:  {
-    "local":   localProto,
-    "webhook": webhookProto,
-    "otlp":    otlpProto,
+    "local":      localProto,
+    "webhook":    webhookProto,
+    "otlp":       otlpProto,
+    "cloudwatch": cloudwatchProto,
   },
   deferred:   {
     "syslog":     { description: "RFC 5424 syslog over TLS" },
-    "cloudwatch": { description: "AWS CloudWatch Logs (PutLogEvents)" },
   },
   fallbackProtocol: "local",
 });
@@ -197,6 +202,71 @@ function listSinks() {
   });
 }
 
+// ---- bootFromEnv ----
+//
+// Operator-friendly env-driven init that mirrors b.network.bootFromEnv.
+// Reads BLAMEJS_LOG_STREAM_* env vars and constructs a single-sink
+// configuration matching the operator's choice. Skipped silently when
+// BLAMEJS_LOG_STREAM_PROTOCOL isn't set (operators using the in-code
+// init() path keep their existing wiring).
+//
+// Recognised env vars:
+//   BLAMEJS_LOG_STREAM_PROTOCOL    "local" | "webhook" | "otlp" | "cloudwatch"
+//   BLAMEJS_LOG_STREAM_MIN_LEVEL   "debug" | "info" | "warn" | "error"
+//
+//   webhook + otlp shared:
+//     BLAMEJS_LOG_STREAM_URL
+//     BLAMEJS_LOG_STREAM_TOKEN              (auth: bearer)
+//   otlp-only:
+//     BLAMEJS_LOG_STREAM_SERVICE_NAME
+//     BLAMEJS_LOG_STREAM_SERVICE_VERSION
+//   cloudwatch-only (AWS_* are standard):
+//     AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+//     BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_GROUP
+//     BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_STREAM
+//   local-only:
+//     BLAMEJS_LOG_STREAM_PATH
+function bootFromEnv(opts) {
+  opts = opts || {};
+  var env = opts.env || process.env;
+  var proto = env.BLAMEJS_LOG_STREAM_PROTOCOL;
+  if (!proto) return false;
+  var sink = { protocol: proto };
+  if (proto === "webhook") {
+    sink.url = env.BLAMEJS_LOG_STREAM_URL;
+    if (env.BLAMEJS_LOG_STREAM_TOKEN) {
+      sink.auth  = "bearer";
+      sink.token = env.BLAMEJS_LOG_STREAM_TOKEN;
+    }
+  } else if (proto === "otlp") {
+    sink.url            = env.BLAMEJS_LOG_STREAM_URL;
+    sink.serviceName    = env.BLAMEJS_LOG_STREAM_SERVICE_NAME    || "blamejs";
+    sink.serviceVersion = env.BLAMEJS_LOG_STREAM_SERVICE_VERSION || null;
+    if (env.BLAMEJS_LOG_STREAM_TOKEN) {
+      sink.auth  = "bearer";
+      sink.token = env.BLAMEJS_LOG_STREAM_TOKEN;
+    }
+  } else if (proto === "cloudwatch") {
+    sink.region          = env.AWS_REGION;
+    sink.accessKeyId     = env.AWS_ACCESS_KEY_ID;
+    sink.secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+    sink.sessionToken    = env.AWS_SESSION_TOKEN || null;
+    sink.logGroupName    = env.BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_GROUP;
+    sink.logStreamName   = env.BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_STREAM;
+  } else if (proto === "local") {
+    sink.path = env.BLAMEJS_LOG_STREAM_PATH;
+  } else {
+    throw _err("BAD_OPT",
+      "BLAMEJS_LOG_STREAM_PROTOCOL='" + proto + "' is not one of " +
+      "local | webhook | otlp | cloudwatch (or a custom backend wired via init())");
+  }
+  init({
+    sinks:    { primary: sink },
+    minLevel: env.BLAMEJS_LOG_STREAM_MIN_LEVEL || undefined,
+  });
+  return true;
+}
+
 function _resetForTest() {
   Object.keys(sinks).forEach(function (n) {
     try { if (sinks[n].raw.close) sinks[n].raw.close(); } catch (_e) {}
@@ -209,6 +279,7 @@ function _resetForTest() {
 
 module.exports = {
   init:               init,
+  bootFromEnv:        bootFromEnv,
   emit:               emit,
   debug:              debug,
   info:               info,

package/lib/object-store/sigv4.js

@@ -165,6 +165,12 @@ function signRequest(opts) {
   var amzDate = _formatAmzDate(date);
   var dateStamp = _formatDateStamp(date);
   var url = opts.url instanceof URL ? opts.url : new URL(opts.url);
+  // service defaults to s3 for back-compat — every call site predating
+  // v0.6.25 was object-store / S3. Other AWS services (logs, sqs, sns,
+  // kinesis, etc.) pass opts.service explicitly. The credentialScope
+  // and signing-key derivation both incorporate the service name, so
+  // this MUST match what the target service expects.
+  var service = opts.service || SERVICE;
 
   var headers = Object.assign({}, opts.headers || {});
   headers["host"] = url.host;
@@ -177,9 +183,9 @@ function signRequest(opts) {
   }
 
   var canon = canonicalRequest(opts.method, url, headers, opts.payloadHash);
-  var credentialScope = dateStamp + "/" + opts.region + "/" + SERVICE + "/aws4_request";
+  var credentialScope = dateStamp + "/" + opts.region + "/" + service + "/aws4_request";
   var sts = stringToSign(amzDate, credentialScope, canon);
-  var signingKey = deriveSigningKey(opts.secretAccessKey, dateStamp, opts.region, SERVICE);
+  var signingKey = deriveSigningKey(opts.secretAccessKey, dateStamp, opts.region, service);
   var signature = nodeCrypto.createHmac("sha256", signingKey).update(sts).digest("hex");
 
   var canonHeaders = canonicalHeaders(headers);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.24",
+  "version": "0.6.26",
   "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:aa9c8c0c-504f-4c75-87d4-297f40e4d752",
+  "serialNumber": "urn:uuid:e07786d1-53d1-4554-b3d1-ff784476a034",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T14:22:45.058Z",
+    "timestamp": "2026-05-02T15:17:41.618Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.24",
+      "bom-ref": "@blamejs/core@0.6.26",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.24",
+      "version": "0.6.26",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.24",
+      "purl": "pkg:npm/%40blamejs/core@0.6.26",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.24",
+      "ref": "@blamejs/core@0.6.26",
       "dependsOn": []
     }
   ]