@blamejs/blamejs-shop 0.4.31 → 0.4.32

package/lib/vendor/blamejs/docker/caddy/localstack.Caddyfile

@@ -0,0 +1,19 @@
+# TLS terminator in front of LocalStack. LocalStack has no supported way to
+# present a cert chaining to our test CA on its own :4566 listener, so Caddy
+# terminates TLS with the CA-issued localstack leaf and reverse-proxies to
+# LocalStack over the internal compose network. The framework's AWS clients
+# (CloudWatch Logs, SQS) connect here and verify the cert against the test CA
+# via NODE_EXTRA_CA_CERTS — no rejectUnauthorized:false.
+#
+# LocalStack does not verify SigV4 signatures (it ignores the secret key), so
+# the Host header it receives is irrelevant to auth; reverse_proxy's defaults
+# pass X-Amz-Target / Authorization / Content-Type through verbatim.
+
+{
+	auto_https off
+}
+
+:4566 {
+	tls /certs/localstack.crt /certs/localstack.key
+	reverse_proxy localstack:4566
+}

package/lib/vendor/blamejs/docker/init/generate-certs.sh

@@ -39,7 +39,7 @@ fi
 
 # Service list — each gets a leaf cert covering the docker-network
 # hostname, the host-bind 127.0.0.1 / [::1], and localhost.
-SERVICES="redis postgres mysql mongo minio rabbitmq nats syslog mailpit haproxy caddy nginx mitmproxy squid coredns"
+SERVICES="redis postgres mysql mongo minio rabbitmq nats syslog mailpit haproxy caddy nginx mitmproxy squid coredns azurite gcs otel localstack"
 
 for SVC in $SERVICES; do
   if [ -f "$CERT_DIR/$SVC.crt" ]; then

package/lib/vendor/blamejs/docker/otel/config.yaml

@@ -0,0 +1,42 @@
+# Test-only OpenTelemetry Collector (contrib). Receives the framework's
+# OTLP/HTTP log export over TLS (the stack's test CA) and writes every
+# received batch to a host-readable NDJSON file so a test can read it back
+# and assert that secrets / PII were redacted before egress.
+#
+# The framework posts to <base>:4318/v1/logs (OTLP HTTP, JSON). With only
+# cert_file/key_file set (no client_ca_file) the receiver does server-side
+# TLS, not mTLS — the client just needs to trust the CA via
+# NODE_EXTRA_CA_CERTS, with no rejectUnauthorized:false.
+
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+        tls:
+          cert_file: /certs/otel.crt
+          key_file: /certs/otel.key
+
+exporters:
+  # One OTLP ExportLogsServiceRequest as JSON per line (NDJSON). append:false
+  # is the default, so the file is truncated on start — each stack run gets a
+  # clean file. create_directory makes the collector materialize the path
+  # inside the mounted volume.
+  file:
+    path: /export/otlp-logs.json
+    format: json
+    create_directory: true
+  # Mirror to stderr at full fidelity for interactive debugging.
+  debug:
+    verbosity: detailed
+
+service:
+  extensions: [health_check]
+  pipelines:
+    logs:
+      receivers: [otlp]
+      exporters: [file, debug]

package/lib/vendor/blamejs/docker/postgres/initdb/10-replication.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Primary-side initdb hook. Allows streaming replication and client
+# connections from the docker bridge subnets so the standby can base-back-up
+# and stream, and so integration tests reach the server over the compose
+# network. Appended during initdb; the real server starts afterward and reads
+# the full file (no reload needed). Test-only: the network is loopback-isolated
+# (host ports bound to 127.0.0.1 / ::1), so trust is acceptable for the fixture.
+cat >> "$PGDATA/pg_hba.conf" <<'EOF'
+
+# --- blamejs test stack: replication + bridge-network access ---
+host replication all 172.30.0.0/16        trust
+host replication all fd00:dead:beef::/48  trust
+host all         all 172.30.0.0/16        trust
+host all         all fd00:dead:beef::/48  trust
+EOF

package/lib/vendor/blamejs/docker/postgres/replica-entrypoint.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Postgres hot-standby replica. On first boot (empty data dir) base-back-up
+# from the primary with -R (writes standby.signal + primary_conninfo);
+# thereafter just start and stream. Serves TLS with the same test-CA leaf as
+# the primary so the framework's read-replica client verifies it against the
+# CA with no rejectUnauthorized:false.
+
+set -eu
+
+# Certs into a postgres-owned location with the strict perms the server wants
+# (same shape as the primary's init-tls.sh).
+mkdir -p /var/lib/postgresql/certs
+cp /certs/postgres.crt /var/lib/postgresql/certs/server.crt
+cp /certs/postgres.key /var/lib/postgresql/certs/server.key
+cp /certs/ca.crt       /var/lib/postgresql/certs/root.crt
+chown -R postgres:postgres /var/lib/postgresql/certs
+chmod 600 /var/lib/postgresql/certs/server.key
+chmod 644 /var/lib/postgresql/certs/server.crt /var/lib/postgresql/certs/root.crt
+
+PGDATA="${PGDATA:-/var/lib/postgresql/18/docker}"
+
+if [ ! -s "$PGDATA/PG_VERSION" ]; then
+  echo "[replica] empty data dir — waiting for primary, then base-backing up..."
+  mkdir -p "$PGDATA"
+  until pg_isready -h postgres -p 5432 -U blamejs >/dev/null 2>&1; do
+    echo "[replica] primary not ready yet..."
+    sleep 2
+  done
+  # Replication is trust-authed from the bridge subnet (initdb hook), so no
+  # password is needed. -R writes standby.signal + primary_conninfo; -Xs
+  # streams WAL during the backup so the standby is consistent on start.
+  pg_basebackup -h postgres -p 5432 -U blamejs -D "$PGDATA" -Fp -Xs -R -P
+  chown -R postgres:postgres "$PGDATA"
+  chmod 700 "$PGDATA"
+  echo "[replica] base backup complete — starting as hot standby."
+fi
+
+exec docker-entrypoint.sh postgres -c config_file=/etc/postgresql/postgresql.conf

package/lib/vendor/blamejs/docker/toxiproxy/toxiproxy.json

@@ -0,0 +1,14 @@
+[
+  {
+    "name": "redis",
+    "listen": "[::]:16379",
+    "upstream": "redis:6379",
+    "enabled": true
+  },
+  {
+    "name": "postgres",
+    "listen": "[::]:15432",
+    "upstream": "postgres:5432",
+    "enabled": true
+  }
+]

package/lib/vendor/blamejs/docker-compose.test.yml

@@ -79,6 +79,7 @@ services:
       - certs:/certs:ro
       - ./docker/postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro
       - ./docker/postgres/init-tls.sh:/init-tls.sh:ro
+      - ./docker/postgres/initdb/10-replication.sh:/docker-entrypoint-initdb.d/10-replication.sh:ro
       - blamejs_test_pgdata:/var/lib/postgresql
     entrypoint:
       - "/bin/sh"
@@ -534,9 +535,217 @@ services:
       start_period: 60s
     restart: unless-stopped
 
+  # Azure Blob Storage emulator (blob service only), HTTPS via the test CA.
+  # Path-style account placement: blob URLs are
+  # https://<host>:10000/<account>/<container>/<blob> with the account in the
+  # PATH, not the host (unlike production <account>.blob.core.windows.net).
+  # The client uses endpoint=https://127.0.0.1:10000 with account
+  # devstoreaccount1 + the well-known emulator key. node:alpine image has no
+  # wget/curl and busybox sh lacks /dev/tcp, so the host-side checker probes
+  # :10000 (Azurite answers 400 on an unauthenticated GET, which is "up").
+  azurite:
+    image: mcr.microsoft.com/azure-storage/azurite:3.35.0
+    container_name: blamejs-test-azurite
+    ports:
+      - "127.0.0.1:10000:10000"
+      - "[::1]:10000:10000"
+    volumes:
+      - certs:/certs:ro
+      - blamejs_test_azuritedata:/data
+    command:
+      - "azurite-blob"
+      # Bind dual-stack (::) so both the IPv4 and IPv6 host-port mappings
+      # reach a listening socket — 0.0.0.0 is IPv4-only and the network's
+      # IPv6 publish path resets.
+      - "--blobHost"
+      - "::"
+      - "--blobPort"
+      - "10000"
+      - "--location"
+      - "/data"
+      - "--cert"
+      - "/certs/azurite.crt"
+      - "--key"
+      - "/certs/azurite.key"
+      - "--skipApiVersionCheck"
+    depends_on:
+      pki-init:
+        condition: service_completed_successfully
+    healthcheck:
+      disable: true
+    restart: unless-stopped
+
+  # Google Cloud Storage emulator, HTTPS via the test CA (loads our leaf via
+  # -cert-location/-private-key-location). In-memory backend; tests create
+  # buckets at setup. public-host must equal the client's connect authority
+  # so the XML/V4 routes match. fake-gcs-server does NOT verify the bearer
+  # token or V4 signature — the live test proves wire/URL/marshalling +
+  # TLS-trust, not signature correctness (that stays a unit-vector concern).
+  # scratch image (no shell) → host-side probe of /_internal/healthcheck.
+  fake-gcs:
+    image: fsouza/fake-gcs-server:1.54.0
+    container_name: blamejs-test-gcs
+    ports:
+      - "127.0.0.1:4443:4443"
+      - "[::1]:4443:4443"
+    volumes:
+      - certs:/certs:ro
+    command:
+      - "-scheme=https"
+      - "-host=0.0.0.0"
+      - "-port=4443"
+      - "-cert-location=/certs/gcs.crt"
+      - "-private-key-location=/certs/gcs.key"
+      - "-public-host=127.0.0.1:4443"
+      - "-external-url=https://127.0.0.1:4443"
+      - "-backend=memory"
+    depends_on:
+      pki-init:
+        condition: service_completed_successfully
+    healthcheck:
+      disable: true
+    restart: unless-stopped
+
+  # OpenTelemetry Collector (contrib) — receives OTLP/HTTP logs over TLS (test
+  # CA) on :4318/v1/logs and writes each received batch as NDJSON to
+  # ./docker/otel/export/otlp-logs.json so a test can read it back and assert
+  # secrets/PII were redacted before egress. scratch image (no shell) →
+  # host-side probe of the health_check extension on :13133.
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.153.0
+    container_name: blamejs-test-otel-collector
+    ports:
+      - "127.0.0.1:4318:4318"
+      - "[::1]:4318:4318"
+      - "127.0.0.1:13133:13133"
+      - "[::1]:13133:13133"
+    command: ["--config=/etc/otel/config.yaml"]
+    volumes:
+      - certs:/certs:ro
+      - ./docker/otel/config.yaml:/etc/otel/config.yaml:ro
+      - ./docker/otel/export:/export
+    depends_on:
+      pki-init:
+        condition: service_completed_successfully
+    healthcheck:
+      disable: true
+    restart: unless-stopped
+
+  # AWS emulator (CloudWatch Logs + SQS) for the cloudwatch log sink and the
+  # SQS queue backend. LocalStack stays plain HTTP on the internal network;
+  # the localstack-tls sidecar terminates TLS with the test CA so the client
+  # verifies the cert with no rejectUnauthorized:false. LocalStack does NOT
+  # verify SigV4 signatures (it ignores the secret key) — the live test proves
+  # request shape + sequence-token flow + read-back + redaction, not signature
+  # correctness. Image ships curl, so the readiness check is in-container.
+  localstack:
+    # Pinned to the last pre-unification semver. From 2026.03 (CalVer) the
+    # unified localstack/localstack image is Pro-gated and exits without a
+    # license token even with ACTIVATE_PRO=0; 4.14.0 is the community line and
+    # boots free. CloudWatch Logs + SQS are stable community services.
+    image: localstack/localstack:4.14.0
+    container_name: blamejs-test-localstack
+    environment:
+      ACTIVATE_PRO: "0"
+      SERVICES: "logs,sqs"
+      EAGER_SERVICE_LOADING: "1"
+      GATEWAY_LISTEN: "0.0.0.0:4566"
+    expose:
+      - "4566"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://localhost:4566/_localstack/health | grep -q '\"logs\"'"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 40s
+    restart: unless-stopped
+
+  localstack-tls:
+    image: caddy:2-alpine
+    container_name: blamejs-test-localstack-tls
+    ports:
+      - "127.0.0.1:4566:4566"
+      - "[::1]:4566:4566"
+    volumes:
+      - certs:/certs:ro
+      - ./docker/caddy/localstack.Caddyfile:/etc/caddy/Caddyfile:ro
+    depends_on:
+      pki-init:
+        condition: service_completed_successfully
+      localstack:
+        condition: service_healthy
+    healthcheck:
+      disable: true
+    restart: unless-stopped
+
+  # Postgres hot-standby streaming replica of the primary, so tests can prove
+  # read-replica routing (b.externalDb.read.query) against a real standby and
+  # that crypto-shred residual ciphertext is gone from the replica too. First
+  # boot base-backs-up from the primary (replica-entrypoint.sh); serves TLS on
+  # 5433 with the same test-CA leaf as the primary.
+  postgres-replica:
+    image: postgres:18-alpine
+    container_name: blamejs-test-postgres-replica
+    ports:
+      - "127.0.0.1:5433:5432"
+      - "[::1]:5433:5432"
+    environment:
+      POSTGRES_USER: blamejs
+      POSTGRES_PASSWORD: blamejs_test
+      POSTGRES_DB: blamejs_test
+      PGDATA: /var/lib/postgresql/18/docker
+    volumes:
+      - certs:/certs:ro
+      - ./docker/postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro
+      - ./docker/postgres/replica-entrypoint.sh:/replica-entrypoint.sh:ro
+      - blamejs_test_pgreplicadata:/var/lib/postgresql
+    entrypoint: ["/bin/sh", "/replica-entrypoint.sh"]
+    depends_on:
+      pki-init:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U blamejs -d blamejs_test"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 25s
+    restart: unless-stopped
+
+  # TCP fault-injection proxy in front of redis + postgres so tests can prove
+  # the framework's reconnect / failover behavior against a real backend that
+  # is made to drop, reset, or slow mid-connection (via the toxiproxy API on
+  # :8474). Transparent passthrough until a toxic is added, so the proxied
+  # ports speak the backend protocol verbatim. scratch image (no shell) →
+  # host-side probe. Bound dual-stack so both loopback families reach it.
+  toxiproxy:
+    image: ghcr.io/shopify/toxiproxy:2.12.0
+    container_name: blamejs-test-toxiproxy
+    command: ["-host=::", "-config=/config/toxiproxy.json"]
+    ports:
+      - "127.0.0.1:8474:8474"
+      - "[::1]:8474:8474"
+      - "127.0.0.1:16379:16379"
+      - "[::1]:16379:16379"
+      - "127.0.0.1:15432:15432"
+      - "[::1]:15432:15432"
+    volumes:
+      - ./docker/toxiproxy/toxiproxy.json:/config/toxiproxy.json:ro
+    depends_on:
+      redis:
+        condition: service_healthy
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      disable: true
+    restart: unless-stopped
+
 volumes:
   certs:
+  blamejs_test_azuritedata:
   blamejs_test_pgdata:
+  blamejs_test_pgreplicadata:
   blamejs_test_mysqldata:
   blamejs_test_mongodata:
   blamejs_test_miniodata:

package/lib/vendor/blamejs/examples/wiki/lib/page-generator.js

@@ -236,6 +236,85 @@ function _renderPrimitive(prim, resolveRelated) {
   });
 }
 
+// Resolve the @since to stamp on a factory namespace's synthesized ABI
+// sections: the guard's @module @since wins; else the earliest @since
+// across the file's real @primitive blocks; else "0.7.5" (the
+// gate-contract guard family's introduction version) so the validator's
+// semver gate is satisfied.
+function _factorySince(rec) {
+  if (rec.module && rec.module.tags && rec.module.tags.since) {
+    return rec.module.tags.since;
+  }
+  var earliest = null;
+  (rec.primitives || []).forEach(function (p) {
+    var s = p.tags && p.tags.since;
+    if (s && (!earliest || _semverLt(s, earliest))) earliest = s;
+  });
+  return earliest || "0.7.5";
+}
+
+// Numeric-segment semver compare (a < b). Pre-release suffixes are
+// ignored — the @since values in lib/ are release versions.
+function _semverLt(a, b) {
+  var pa = String(a).split("-")[0].split(".").map(function (n) { return parseInt(n, 10) || 0; });
+  var pb = String(b).split("-")[0].split(".").map(function (n) { return parseInt(n, 10) || 0; });
+  for (var i = 0; i < 3; i++) {
+    var da = pa[i] || 0, db = pb[i] || 0;
+    if (da !== db) return da < db;
+  }
+  return false;
+}
+
+// Substitute the ABI template placeholders in a single string:
+//   {NS}   → the guard namespace (e.g. guardCsv)
+//   {ERR}  → its error class (e.g. GuardCsvError)
+//   {CODE} → its error-code prefix (e.g. csv) — the stem in thrown codes
+//            ("csv.bad-posture"), which differs from the namespace.
+// {ERR} / {CODE} fall back to honest phrasing when the parser couldn't
+// resolve them (rather than emitting a literal "{ERR}" / "{CODE}").
+function _subAbi(text, ns, errClass, codePrefix) {
+  if (text == null) return text;
+  var err = errClass || "the guard's error class";
+  var code = codePrefix || ns;
+  return String(text)
+    .replace(/\{NS\}/g, ns)
+    .replace(/\{ERR\}/g, err)
+    .replace(/\{CODE\}/g, code);
+}
+
+// Turn an @abiTemplate record into a synthetic primitive record shaped
+// exactly like parseBlock's output, so it flows through _renderPrimitive
+// + the per-namespace ordering unchanged. {NS} -> ns, {ERR} -> error
+// class, {CODE} -> error-code prefix, @since filled from the owning guard.
+function _instantiateAbiTemplate(tpl, ns, errClass, codePrefix, since) {
+  var tags = tpl.tags || {};
+  var method = tags.method;
+  var newTags = {
+    primitive: "b." + ns + "." + method,
+    signature: _subAbi(tags.signature, ns, errClass, codePrefix),
+    since:     since,
+    status:    tags.status || "stable",
+  };
+  if (tags.compliance) newTags.compliance = tags.compliance;
+  if (tags.related)    newTags.related = _subAbi(tags.related, ns, errClass, codePrefix);
+  if (tags.opts != null) newTags.opts = _subAbi(tags.opts, ns, errClass, codePrefix);
+  if (Array.isArray(tags.examples)) {
+    newTags.examples = tags.examples.map(function (ex) { return _subAbi(ex, ns, errClass, codePrefix); });
+  }
+  return {
+    kind:  "primitive",
+    tags:  newTags,
+    prose: _subAbi(tpl.prose, ns, errClass, codePrefix),
+    // Synthetic blocks are well-formed by construction; carry the same
+    // ordering/mixed-kind flags parseBlock sets on a clean block.
+    proseAfterMultiLine: false,
+    mixedKind: null,
+    // Marker so downstream tooling can distinguish a synthesized ABI
+    // section from a hand-authored @primitive block.
+    abiSynthesized: true,
+  };
+}
+
 // Build a generated page object.
 //
 // pageSpec: {
@@ -261,12 +340,33 @@ function generatePage(pageSpec, docsByPath, resolveRelated) {
   // Group primitives by namespace, drop hidden ones.
   var byNs = {};
   var moduleByNs = {};
+  // Map ns → owning factory record + the @since to stamp on synthetic
+  // ABI-method sections. The factory lives on the file record; ns is the
+  // file's @module namespace.
+  var factoryByNs = {};
   var paths = Object.keys(docsByPath);
   for (var p = 0; p < paths.length; p++) {
     var rec = docsByPath[paths[p]];
+    var fileNs = null;
     if (rec.module && rec.module.tags && rec.module.tags.module) {
       var modSig = rec.module.tags.module.replace(/^\s*b\./, "");
       moduleByNs[modSig] = rec.module;
+      fileNs = modSig;
+    }
+    if (rec.factory) {
+      // Resolve the @since once per factory namespace: the guard's
+      // @module @since wins; else the earliest primitive's @since; else
+      // a conservative fallback the validator accepts.
+      var nsForFactory = fileNs;
+      if (!nsForFactory && rec.primitives.length > 0) {
+        nsForFactory = _nsOf((rec.primitives[0].tags && rec.primitives[0].tags.primitive) || "");
+      }
+      if (nsForFactory) {
+        factoryByNs[nsForFactory] = {
+          factory: rec.factory,
+          since:   _factorySince(rec),
+        };
+      }
     }
     for (var i = 0; i < rec.primitives.length; i++) {
       var prim = rec.primitives[i];
@@ -282,6 +382,38 @@ function generatePage(pageSpec, docsByPath, resolveRelated) {
     }
   }
 
+  // ---- Synthesize per-guard ABI-method sections from @abiTemplate ----
+  // For each namespace whose owning file is a defineGuard / defineParser
+  // factory call, instantiate the matching factory's ABI doc templates —
+  // substituting the namespace + error class + @since — and append them
+  // to byNs[ns]. The de-duplication is SOURCE-only: the prose lives once
+  // (in gate-contract.js's @abiTemplate blocks), but every guard's page
+  // still lists every ABI method it exposes. A method already documented
+  // by a real per-guard @primitive block (a bespoke gate, or a guard that
+  // kept its own compliancePosture) is skipped so the real block wins.
+  var templates = parser.factoryTemplates(docsByPath);
+  Object.keys(byNs).forEach(function (ns) {
+    var fb = factoryByNs[ns];
+    if (!fb) return;
+    var kindTemplates = templates[fb.factory.kind] || [];
+    // Methods already documented by a real per-guard block on this page.
+    var documented = {};
+    byNs[ns].forEach(function (pr) {
+      var sig = (pr.tags && pr.tags.primitive) || "";
+      var method = String(sig).replace(/^b\./, "").split(".").pop();
+      if (method) documented[method] = true;
+    });
+    kindTemplates.forEach(function (tpl) {
+      var method = tpl.tags && tpl.tags.method;
+      if (!method) return;
+      if (documented[method]) return;        // real block wins; skip template
+      if (hiddenSet["b." + ns + "." + method]) return;
+      var synth = _instantiateAbiTemplate(tpl, ns, fb.factory.errorClass, fb.factory.codePrefix, fb.since);
+      byNs[ns].push(synth);
+      documented[method] = true;             // guard against duplicate templates
+    });
+  });
+
   // Order primitives within each namespace: explicit `order` first, then
   // the rest in source order.
   var orderIdx = {};