@blamejs/core 0.6.23 → 0.6.25

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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.
 - **0.6.21** (2026-05-02) — closes the medium / low audit findings flagged after v0.6.18. **Cluster cache `invalidateTag`** now actually works — the cluster backend gained a `_blamejs_cache_tags` junction table (`(cacheKey, tag)` PK + index on `tag`), tag-aware `set` / `del` / `clear` / `_sweep`, plus `getTags(key)`. The old NOT_SUPPORTED-on-cluster path is gone; multi-tag rotation, mid-flight tag replacement on update, and namespace-scoped sweeps all covered. **Multi-column cursor pagination** — `b.pagination.cursor({ orderBy: [{column,direction},...] })` accepts a string (single column), an array of strings (multi, all using `opts.direction`), or an array of `{column,direction}` objects (mixed directions). The keyset WHERE expands to the standard OR cascade so successive pages can't skip or repeat rows when ties on the leading columns are broken by trailing ones. `_id` is appended as a tiebreaker if not in the chain. The Query class also gained chained `orderBy(col, dir)` calls — second-and-later calls extend a multi-column ORDER BY in the SQL. Cursor format is bumped to encode `{ orderKey, vals, forward }` instead of the old `{ orderBy, dir, orderByVal, id, forward }` — pre-1.0 break, no compat shim. **DoH POST mode** (RFC 8484 §4.1) — `b.network.dns.useDnsOverHttps({ method })` accepts `"GET" | "POST" | undefined` (auto). Auto switches to POST when the GET URL would exceed 2048 bytes (long DNS names). **DoT connection pooling** — per-`(host:port)` cached TLS socket with a 2-minute idle timeout, serialized in-flight queries per socket. Eliminates the per-query handshake. **INI parser** shipped as `b.parsers.ini` — covers Windows .ini / .gitconfig / systemd-unit / php.ini / tox.ini shape: sections (incl. `[parent.child]` / `[parent "child"]` nesting), `;` and `#` comments (inline + leading), single + double quoting with `\n` `\t` `\\` `\"` `\'` escapes, boolean coercion (`true`/`false`/`yes`/`no`/`on`/`off`), decimal + hex integers + floats. Prototype-pollution defense (`__proto__` / `constructor` / `prototype` rejected). Duplicate-key policy throws by default; `onDuplicate: "first" | "last"` opts in to silent shadowing. Section / per-section key / value-bytes caps configurable. **Cookie-jar file persistence** — `b.httpClient.cookieJar.create({ persist: "file", file: "/abs/path", vault: b.vault })` loads at construct, debounce-flushes on every set/clear, plus `flush()` and `close()` for explicit lifecycle. With `vault`, on-disk bytes are sealed; without, plaintext JSON (operator chooses). **Comment cleanups per rule §4** — `vault/index.js` stale `// later` removed, `mail.js` "future patch" wording rewritten as scope, `bundler.js` "What it does NOT do today (deliberately deferred)" rewritten as "Out of scope", `archive.js` "v1 scope cuts (deferred)" rewritten as "Out of scope", `framework-schema.js` "next release" wording rewritten to describe what's actually shipped, `http-client.js` "out of reach today" / "we'll plumb it through when h3 lands" rewritten as scope statements. **README CLI section** updated to reflect the v0.6.17 + v0.6.18 + v0.6.19 + v0.6.20 additions (security / config-drift / file-type / password / erase / retention) — was missing 6 subcommands.

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, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`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-otlp.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * OTLP/HTTP-JSON log sink — OpenTelemetry Protocol logs over HTTP/JSON.
+ *
+ * Per the OTLP spec (v1.3+, Logs Data Model), log records are wrapped in
+ * a ResourceLogs envelope and POSTed to the operator's collector
+ * endpoint. Marshalling is OTel-native: timeUnixNano (string), severity
+ * mapping per OTel spec, attribute typing.
+ *
+ * Operator config:
+ *
+ *   {
+ *     url:                 "https://otel-collector.example.com:4318/v1/logs"
+ *                          // OR the collector root — "/v1/logs" auto-appended
+ *     headers:             { ... }   // additional headers (api keys, tenant ids)
+ *     auth:                'none' | 'bearer' | 'basic' | 'header'
+ *     token / username+password
+ *     serviceName:         "my-service"   // emitted as resource service.name
+ *     serviceVersion:      "1.2.3"        // resource service.version
+ *     resourceAttributes:  { env: "prod", region: "us-east-1" }
+ *                          // additional resource attributes
+ *     scopeName:           "blamejs"      // instrumentation scope name
+ *     batchSize:           100
+ *     maxBatchAgeMs:       C.TIME.seconds(5)
+ *     timeoutMs:           C.TIME.seconds(30)
+ *     retry:               { maxAttempts, baseDelayMs, ... }
+ *     bufferLimit:         10000   // ring-buffer cap; drops oldest on overflow
+ *     onDrop:              function ({ reason, batch, error }) { ... }
+ *   }
+ *
+ * Severity mapping (per OTel Logs Data Model):
+ *   debug → 5 (DEBUG)
+ *   info  → 9 (INFO)
+ *   warn  → 13 (WARN)
+ *   error → 17 (ERROR)
+ *
+ * Endpoint convention: most OTel collectors expose:
+ *   <base>:4318/v1/logs   — HTTP/JSON path (per OTLP HTTP §4.5)
+ *   <base>:4317           — gRPC path (NOT supported here)
+ *
+ * If `url` ends in `/v1/logs` it's used as-is. If not, `/v1/logs` is
+ * appended (collector root → logs endpoint). Operators with a custom
+ * routing prefix pass the full URL.
+ *
+ * Why JSON not protobuf: protobuf needs a schema parser (vendored dep
+ * or hand-rolled). The OTLP/HTTP spec accepts both Content-Type:
+ * application/json and application/x-protobuf; the JSON variant is the
+ * "no extra deps" path consistent with the framework's vendoring stance.
+ * Operators benchmarking >100K logs/s ship the OTel Collector locally
+ * (collector → upstream gRPC) — this sink hands JSON to the local
+ * collector which forwards.
+ */
+var C = require("./constants");
+var retryHelper = require("./retry");
+var { LogStreamError } = require("./framework-error");
+var httpClient = require("./http-client");
+var safeUrl = require("./safe-url");
+var authHeader = require("./auth-header");
+
+var MAX_RESPONSE_BYTES = C.BYTES.mib(1);
+
+// OTel Logs Data Model severity numbers.
+// https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
+var SEVERITY = {
+  debug: { number: 5,  text: "DEBUG" },
+  info:  { number: 9,  text: "INFO"  },
+  warn:  { number: 13, text: "WARN"  },
+  error: { number: 17, text: "ERROR" },
+};
+
+var DEFAULTS = {
+  scopeName:     "blamejs",
+  batchSize:     100,
+  maxBatchAgeMs: C.TIME.seconds(5),
+  timeoutMs:     C.TIME.seconds(30),
+  bufferLimit:   10000,
+};
+
+var _err = LogStreamError.factory;
+
+function _resolveUrl(url) {
+  // If the URL already ends in "/v1/logs" (with or without trailing slash),
+  // use as-is. Otherwise treat as the collector root and append.
+  var trimmed = url.replace(/\/+$/, "");
+  if (/\/v1\/logs$/.test(trimmed)) return trimmed;
+  return trimmed + "/v1/logs";
+}
+
+function _authHeaders(config) {
+  if (config.auth === "header") return Object.assign({}, config.headers || {});
+  return authHeader.fromConfig(config);
+}
+
+// OTel attribute encoding — JSON form per OTLP spec. Each attribute is
+// { key: <name>, value: { <type>Value: <v> } } where the type field
+// matches the JS type at the boundary.
+function _encodeAttrValue(v) {
+  if (v === null || v === undefined) return null;
+  var t = typeof v;
+  if (t === "string")  return { stringValue: v };
+  if (t === "boolean") return { boolValue: v };
+  if (t === "number") {
+    if (Number.isInteger(v)) return { intValue: String(v) };       // OTLP int is string-encoded
+    return { doubleValue: v };
+  }
+  if (Array.isArray(v)) {
+    return { arrayValue: { values: v.map(function (e) { return _encodeAttrValue(e); }).filter(Boolean) } };
+  }
+  if (t === "object") {
+    return { kvlistValue: { values: _encodeAttrs(v) } };
+  }
+  return { stringValue: String(v) };
+}
+
+function _encodeAttrs(obj) {
+  if (!obj || typeof obj !== "object") return [];
+  return Object.keys(obj).map(function (k) {
+    var encoded = _encodeAttrValue(obj[k]);
+    if (!encoded) return null;
+    return { key: k, value: encoded };
+  }).filter(Boolean);
+}
+
+function _resourceAttrs(cfg) {
+  var attrs = {};
+  if (cfg.serviceName)    attrs["service.name"]    = cfg.serviceName;
+  if (cfg.serviceVersion) attrs["service.version"] = cfg.serviceVersion;
+  if (cfg.resourceAttributes && typeof cfg.resourceAttributes === "object") {
+    Object.assign(attrs, cfg.resourceAttributes);
+  }
+  return attrs;
+}
+
+function _toLogRecord(record) {
+  var sev = SEVERITY[record.level] || SEVERITY.info;
+  // OTel timeUnixNano is a string (JSON can't safely represent 64-bit ints).
+  var nanos = String(BigInt(record.ts) * 1000000n);
+  var attrs = record.meta ? _encodeAttrs(record.meta) : [];
+  return {
+    timeUnixNano:     nanos,
+    observedTimeUnixNano: nanos,
+    severityNumber:   sev.number,
+    severityText:     sev.text,
+    body:             { stringValue: record.message == null ? "" : String(record.message) },
+    attributes:       attrs,
+  };
+}
+
+function _serializeBatch(records, cfg, scopeVersion) {
+  var resourceAttrs = _resourceAttrs(cfg);
+  return Buffer.from(JSON.stringify({
+    resourceLogs: [
+      {
+        resource: {
+          attributes: _encodeAttrs(resourceAttrs),
+        },
+        scopeLogs: [
+          {
+            scope: {
+              name:    cfg.scopeName,
+              version: scopeVersion,
+            },
+            logRecords: records.map(_toLogRecord),
+          },
+        ],
+      },
+    ],
+  }), "utf8");
+}
+
+function _post(url, body, headers, timeoutMs, allowedProtocols, allowInternal) {
+  return httpClient.request({
+    method:           "POST",
+    url:              url,
+    headers:          headers,
+    body:             body,
+    idleTimeoutMs:    timeoutMs,
+    maxResponseBytes: MAX_RESPONSE_BYTES,
+    errorClass:       LogStreamError,
+    allowedProtocols: allowedProtocols,
+    allowInternal:    allowInternal,
+  });
+}
+
+function create(config) {
+  if (!config || !config.url) throw _err("BAD_OPT", "log-stream otlp requires { url }");
+  var cfg = Object.assign({}, DEFAULTS, config);
+  var resolvedUrl = _resolveUrl(cfg.url);
+  // Validate URL shape + scheme at create time. Default HTTPS-only;
+  // operators with an internal cleartext OTel collector pass
+  // cfg.allowedProtocols (safeUrl.ALLOW_HTTP_ALL).
+  safeUrl.parse(resolvedUrl, {
+    allowedProtocols: cfg.allowedProtocols || safeUrl.ALLOW_HTTP_TLS,
+    errorClass:       LogStreamError,
+  });
+  var scopeVersion = cfg.scopeVersion || (function () {
+    try { return require("../package.json").version; } catch (_e) { return "unknown"; }
+  })();
+  var headers = Object.assign({
+    "Content-Type": "application/json",
+    "Accept":       "application/json",
+  }, _authHeaders(cfg));
+  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) { /* drop callback is best-effort */ }
+  }
+  var buffer = [];
+  var dropCount = 0;
+  var flushTimer = null;
+  var inFlight = false;
+  var closed = false;
+
+  function _scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(function () { flushTimer = null; _flush(); }, cfg.maxBatchAgeMs);
+    flushTimer.unref();
+  }
+
+  async function _flush() {
+    if (inFlight) return;
+    if (buffer.length === 0) return;
+    inFlight = true;
+    try {
+      while (buffer.length > 0 && !closed) {
+        var batch = buffer.splice(0, cfg.batchSize);
+        var body = _serializeBatch(batch, cfg, scopeVersion);
+        try {
+          await retryHelper.withRetry(function () {
+            return _post(resolvedUrl, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
+          }, cfg.retry);
+        } catch (e) {
+          dropCount += batch.length;
+          _emitDrop("retry-exhausted", batch, e);
+          break;
+        }
+      }
+    } finally {
+      inFlight = false;
+      if (buffer.length > 0) _scheduleFlush();
+    }
+  }
+
+  function emit(record) {
+    if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
+    if (buffer.length >= cfg.bufferLimit) {
+      var dropped = buffer.shift();
+      dropCount += 1;
+      _emitDrop("overflow", [dropped], null);
+    }
+    buffer.push(record);
+    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,
+      url:      resolvedUrl,
+    };
+  }
+
+  return {
+    protocol: "otlp",
+    emit:     emit,
+    close:    close,
+    stats:    stats,
+    flush:    _flush,
+  };
+}
+
+module.exports = {
+  create:       create,
+  // Exposed for tests + advanced operator wiring.
+  _resolveUrl:  _resolveUrl,
+  _encodeAttrs: _encodeAttrs,
+  _toLogRecord: _toLogRecord,
+  SEVERITY:     SEVERITY,
+};

package/lib/log-stream.js

@@ -4,12 +4,26 @@
  * redaction and bidirectional command channel.
  *
  * Same dispatcher pattern: backends configured per-name with a protocol
- * + protocol-specific options. Built-in protocols are 'local'
- * (append-only file with rotation) and 'webhook' (generic HTTP POST —
- * covers Splunk HEC, Datadog, Sumo Logic, Loki, custom). Specialized
- * adapters (syslog over TLS, OpenTelemetry OTLP, AWS CloudWatch,
- * Vector/Fluentd) are listed as deferred and surface a clear error
- * when selected.
+ * + protocol-specific options. Built-in protocols:
+ *
+ *   local    — append-only file with rotation
+ *   webhook  — generic HTTP POST; covers Splunk HEC, Datadog, Sumo
+ *              Logic, Loki, custom collectors that ingest JSON
+ *   otlp     — OpenTelemetry Protocol over HTTP/JSON; ResourceLogs
+ *              envelope with severity mapping per OTel Logs Data
+ *              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
  *
  * Every emit goes through lib/redact.js BEFORE any sink sees it. PHI/PCI
  * never reaches operational logs even on a misconfigured field name —
@@ -32,21 +46,26 @@
  *   logStream.shutdown()
  *   logStream.listSinks()                         → [{ name, protocol, stats }]
  */
-var localProto   = require("./log-stream-local");
-var webhookProto = require("./log-stream-webhook");
-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");
 
 var dispatcher = protocolDispatcher.create({
   name:       "log-stream",
   errorClass: LogStreamError,
-  protocols:  { "local": localProto, "webhook": webhookProto },
+  protocols:  {
+    "local":      localProto,
+    "webhook":    webhookProto,
+    "otlp":       otlpProto,
+    "cloudwatch": cloudwatchProto,
+  },
   deferred:   {
     "syslog":     { description: "RFC 5424 syslog over TLS" },
-    "otlp":       { description: "OpenTelemetry Logs OTLP/HTTP" },
-    "cloudwatch": { description: "AWS CloudWatch Logs (PutLogEvents)" },
   },
   fallbackProtocol: "local",
 });
@@ -183,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) {}
@@ -195,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.23",
+  "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:47563cfb-199b-4000-ba99-0e3102e87442",
+  "serialNumber": "urn:uuid:c8d4ecf3-0360-4291-bedc-af54ef2eca2a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T14:07:01.711Z",
+    "timestamp": "2026-05-02T14:44:53.846Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.23",
+      "bom-ref": "@blamejs/core@0.6.25",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.23",
+      "version": "0.6.25",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.23",
+      "purl": "pkg:npm/%40blamejs/core@0.6.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.23",
+      "ref": "@blamejs/core@0.6.25",
       "dependsOn": []
     }
   ]