@blamejs/core 0.6.24 → 0.6.25

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **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`).

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.25",
   "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:c8d4ecf3-0360-4291-bedc-af54ef2eca2a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T14:22:45.058Z",
+    "timestamp": "2026-05-02T14:44:53.846Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.24",
+      "bom-ref": "@blamejs/core@0.6.25",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.24",
+      "version": "0.6.25",
       "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.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.24",
+      "ref": "@blamejs/core@0.6.25",
       "dependsOn": []
     }
   ]