@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/docs/cis-postgres-crosswalk.md

@@ -0,0 +1,102 @@
+# CIS Postgres Benchmark — blamejs cross-walk
+
+This document maps **CIS PostgreSQL Benchmarks (v14 / v15 / v16)** to the
+framework primitives that satisfy each control. Operators wire the
+result into compliance evidence packages alongside the framework's
+audit chain.
+
+The crosswalk lists **the framework's posture** (how the primitive
+default discharges the control out of the box), **operator action**
+(what the operator must additionally configure on the Postgres host),
+and **citation** (the CIS section number).
+
+## 1. Installation and Patches
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 1.1 | Ensure packages are obtained from authorized repositories | n/a | OS-layer; track upstream PostgreSQL security advisories. |
+| 1.2 | Ensure systemd Service Files Are Enabled | n/a | OS-layer; `systemctl enable postgresql` outside the framework. |
+| 1.3 | Ensure Data Cluster Initialized Successfully | n/a | Operator-managed `initdb`. |
+
+## 2. Directory and File Permissions
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 2.1 | Ensure the file permissions mask is correct | n/a | OS-layer; data dir 0700. |
+| 2.2 | Ensure the PostgreSQL pg_wheel group membership is correct | n/a | OS-layer. |
+
+## 3. Logging Monitoring and Auditing
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 3.1.2 | Ensure the log destinations are set correctly | `b.audit.safeEmit` writes every framework-emitted event into the audit chain | Forward Postgres CSV logs to the same SIEM the framework's audit chain ships to. |
+| 3.1.3 | Ensure the logging collector is enabled | n/a | `logging_collector = on` in `postgresql.conf`. |
+| 3.1.4-22 | log_destination / log_filename / log_rotation_* / log_min_messages / log_connections / log_disconnections / log_error_verbosity / log_statement / log_timezone | n/a (framework reads via b.externalDb pool) | Operator-supplied `postgresql.conf`. The framework's `b.compliance.set("hipaa")` posture emits a `compliance.posture.tz_warning` when `process.env.TZ` isn't UTC — mirror at the Postgres layer with `log_timezone = 'UTC'`. |
+| 3.2 | Ensure the PostgreSQL Audit Extension (pgaudit) Is Enabled | Composes — framework audit chain captures every write the framework emits; pgaudit captures the Postgres-level statements the framework doesn't see. | Install + enable `pgaudit` extension; configure `pgaudit.log = 'all'`. |
+
+## 4. User Access and Authorization
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 4.1 | Ensure sudo Is Configured Correctly | n/a | OS-layer. |
+| 4.2 | Ensure Excessive Administrative Privileges Are Revoked | `b.db.declareRowPolicy` emits ROW LEVEL SECURITY migrations | Operator runs the migration; principle-of-least-privilege at the role level. |
+| 4.3 | Ensure Excessive Function Privileges Are Revoked | n/a | `REVOKE EXECUTE ON FUNCTION ...` per role. |
+| 4.4 | Ensure Excessive DML Privileges Are Revoked from PUBLIC | `b.db.declareView` + `declareRowPolicy` emit GRANT/REVOKE migrations | Run the framework migration; the framework refuses to write directly under PUBLIC roles. |
+| 4.5 | Ensure Row Level Security (RLS) Is Configured Correctly | `b.db.declareRowPolicy` is the framework's RLS primitive | Use it for every multi-tenant table. |
+| 4.6 | Ensure the set_user Extension Is Installed | n/a | Operator-installed extension. |
+
+## 5. Connection and Login
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 5.1 | Ensure login via "local" UNIX domain socket Is Configured Correctly | n/a | `pg_hba.conf` — `local all all peer`. |
+| 5.2 | Ensure login via "host" TCP/IP Socket Is Configured Correctly | Framework defaults to `TLSv1.3` minimum on every TLS socket via `tls.DEFAULT_MIN_VERSION` set at index.js entry | `pg_hba.conf` — `hostssl ... cert clientcert=verify-full`; framework sets the floor, operator pins the role. |
+| 5.3 | Ensure Passwords are Stored in Encrypted Format | `b.auth.password` uses Argon2id (RFC 9106) | Postgres-side: `password_encryption = 'scram-sha-256'`. |
+| 5.4 | Ensure max_connections Is Set Correctly | `b.externalDb` connection-pool config | `max_connections` matches pool size + headroom. |
+
+## 6. PostgreSQL Settings
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 6.1 | Understanding attack vectors and runtime parameters | n/a | Operator-managed. |
+| 6.2 | Ensure 'backend' runtime parameters are configured correctly | `b.externalDb` pool sets `application_name` per connection | `statement_timeout = 60000`, `idle_in_transaction_session_timeout = 60000`. |
+| 6.7 | Ensure FIPS 140-2 OpenSSL Cryptography is Used | Framework uses Node's nodeCrypto bound to OpenSSL on Linux | Operator builds Postgres against FIPS-validated OpenSSL. |
+| 6.8 | Ensure SSL Is Configured Correctly | TLS 1.3 framework-wide; `b.network.tls.ocsp` + `b.network.tls.ct` for outbound | `ssl = on`, `ssl_min_protocol_version = 'TLSv1.3'`. |
+| 6.9 | Ensure pgcrypto Is Installed | Framework uses XChaCha20-Poly1305 + SHA3-512 + ML-KEM-1024 in-process | Operator installs pgcrypto only if needed for column-level Postgres-side crypto. |
+
+## 7. Replication
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 7.1 | Ensure a replication-only user is created | `b.cluster.create({ externalDbBackend })` uses operator-supplied pool — framework doesn't create roles itself | Create `replication_user` role; framework's cluster module reads under that role. |
+| 7.2 | Ensure logical replication is configured | `b.outbox.create({ envelope: "debezium" })` provides change-event emission compatible with logical-replication consumers | Enable `wal_level = logical`. |
+| 7.3 | Ensure base backups are configured and functional | `b.backup.scheduleTest({ cron, restoreTo, verify, posture })` runs periodic restore-and-verify drills (HIPAA §164.308(a)(7)(ii)(D)) | Wire `pg_basebackup` for the Postgres-layer side. |
+| 7.4 | Ensure WAL archiving is configured and functional | n/a | `archive_mode = on`, `archive_command = '...'`. |
+| 7.5 | Ensure streaming replication parameters are configured correctly | n/a | `max_wal_senders`, `wal_keep_size`. |
+
+## 8. Special Configuration Considerations
+
+| CIS § | Control | Framework posture | Operator action |
+| ----- | ------- | ----------------- | --------------- |
+| 8.1 | Ensure PostgreSQL subdirectory locations are outside the data cluster | n/a | Operator-managed paths. |
+| 8.2 | Ensure the backup and restore tool, 'pgBackRest', is installed and configured | `b.backup` + `b.restoreBundle` provide framework-level encrypted bundles with ML-DSA-87 signed manifest (`b.backupBundle.verifyManifestSignature`) | Operators with petabyte-scale data combine pgBackRest with framework backup for layer-2 belt-and-suspenders. |
+| 8.3 | Ensure miscellaneous configuration settings are correct | n/a | Operator-managed. |
+
+## Framework primitives that close the gap
+
+- **`b.tenantQuota.create`** — per-tenant DB storage caps (CIS 4.5
+  composes; ISO 27001 A.8.1.5)
+- **`b.tenantQuota.budget`** — per-tenant query budget
+- **`b.tenantQuota.instrumentQuery`** — emits `db.tenant.crossover`
+  on RLS-bypass
+- **`b.db.exportCsv`** — RFC 4180 strict export with SHA3-512 manifest
+  + ML-DSA-87 signature
+- **`b.db.getTableMetadata({ format: "json-schema-2020-12" })`** — JSON
+  Schema 2020-12 representation of every table (sealed/derived
+  annotations preserved)
+- **`b.audit.export({ format: "cadf" })`** — CADF (ISO/IEC 19395:2017)
+  envelope export for federated SIEM
+- **`b.drRunbook.emit({ posture: "hipaa", ... })`** — disaster-recovery
+  runbook generator composing b.budr + b.cluster + b.backup
+- **`b.backupBundle.verifyManifestSignature`** — ML-DSA-87 signature
+  verification on restore

package/lib/vendor/blamejs/docs/cis-sqlite-equivalent.md

@@ -0,0 +1,92 @@
+# SQLite CIS-equivalent — blamejs hardening crosswalk
+
+CIS does NOT publish a SQLite Benchmark — SQLite is library-shaped,
+embedded into the framework process rather than running as a service,
+so the per-host audit/role/replication controls a Postgres benchmark
+covers don't apply. Operators under HIPAA / PCI-DSS / SOC 2 / FedRAMP
+still need an evidence package showing the framework's SQLite layer
+meets the equivalent control intent.
+
+This document synthesises a CIS-equivalent crosswalk from:
+
+- **NIST SP 800-53 Rev. 5** AC / AU / CM / SC / SI control families
+- **CIS PostgreSQL Benchmark v16** (the closest published baseline)
+- **The framework's defaults** (which apply uniformly across SQLite
+  + Postgres deployments)
+
+For every adapted control, the framework's posture is the operator's
+evidence — the framework primitive name + the audit-emission events it
+produces.
+
+## File-system & process isolation
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| DB file readable only by owning process | AC-3 | `b.db.init({ atRest: "encrypted" })` writes db.enc with mode 0600 (atomicFile.writeSync). Plaintext DB lives in tmpfs (`/dev/shm/blamejs-*` on Linux) — wiped on every clean shutdown via `removePlaintextFiles`. |
+| Encryption-at-rest with PQC primitives | SC-28 | Default mode = `encrypted`. XChaCha20-Poly1305 + Argon2id (RFC 9106). Operator-supplied passphrase via `BLAMEJS_VAULT_PASSPHRASE_*` env. |
+| Backup encryption mandatory under regulated postures | SC-28(1) | `b.compliance.set("hipaa")` / `pci-dss` causes `b.backup.create` to refuse `encrypt: false` (F-BUDR-4). |
+| Backup integrity protection | SC-12 | Manifest is signed with the audit-sign keypair (ML-DSA-87 / SLH-DSA-SHAKE-256f). `b.backupBundle.verifyManifestSignature` rejects tampered bundles. |
+| Periodic backup test | CP-9(1) | `b.backup.scheduleTest({ cron, restoreTo, verify, posture })` emits `backup.test.passed` / `.failed` audit rows (HIPAA §164.308(a)(7)(ii)(D)). |
+
+## Audit & accountability
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| Append-only audit log | AU-9(2) | `audit_log` BEFORE-DELETE trigger refuses writes; chained with SHA3-512 prevHash/rowHash. Every row carries a `monotonicCounter` indexed `unique`. |
+| Audit-log signed checkpoint | AU-10 | `b.audit.checkpoint` emits ML-DSA-87 / SLH-DSA-SHAKE-256f signed `audit_checkpoints` rows. The audit-tip sidecar (`<dataDir>/audit.tip`) detects rollback at boot. |
+| Time-source synchronisation | AU-8(1) | `b.db.init` runs `b.ntpCheck.bootCheck` against operator-supplied NTP servers; warning / fatal thresholds via `BLAMEJS_NTP_DRIFT_*`. |
+| Audit export for federated SIEM | AU-6(3) | `b.audit.export({ format: "cadf" })` emits CADF (ISO/IEC 19395) envelope mapping every audit field. |
+| Tamper-evident integrity check | SI-7 | `b.db.integrityCheck` runs `PRAGMA integrity_check` on demand; `b.db.integrityMonitor({ intervalMs })` schedules periodic verification with audit emission. |
+
+## Access control
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| Per-tenant data isolation | AC-3 | `b.tenantQuota.create` / `b.tenantQuota.budget` / `b.tenantQuota.instrumentQuery` provide storage caps + query budget + crossover detection. SOC 2 CC6.1 + ISO 27001 A.8.1.5. |
+| Role-context for every query | AC-6 | `b.dbRoleContext` binds an actor → audit emission row pair on every query the framework executes. |
+| WORM (write-once-read-many) for regulatory tables | AU-9(1) | `b.db.declareWorm({ table })` installs SQLite trigger refusing UPDATE/DELETE; required under postures `sec-17a-4`, `finra-4511`, `fda-21cfr11`. |
+| Dual-control on sensitive operations | AC-3(7) | `b.dualControl.consume` gates `b.db.eraseHard` on declared tables. |
+| Step-up auth on PHI/PCI columns | IA-2(11) | `b.breakGlass` wraps column-policy / row-enforcement step-up auth (PHI / PCI columns require fresh second-factor grant + reason). |
+
+## Configuration management
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| Configuration drift detection | CM-2 | `b.configDrift` snapshots framework config + emits `config.drift.detected` events on change. |
+| Schema migrations under change control | CM-3 | `b.migrations.create` installs `_blamejs_migrations` tracking; every DDL emits `db.ddl.executed` audit rows (D-M1). |
+| DDL audit | AU-12 | DDL_RE-classified statements emit per-statement audit rows automatically. |
+| Reflective schema metadata | CM-8 | `b.db.getTableMetadata({ format: "json-schema-2020-12" })` emits a JSON Schema 2020-12 representation of every table for inventory tooling. |
+
+## Data export & evidence
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| RFC 4180 strict CSV export | AU-7 | `b.db.exportCsv({ table, where, signWith })` — RFC 4180 strict + UTF-8 BOM optional + ISO-8601 timestamp casts + SHA3-512 manifest + ML-DSA-87 signature. |
+| Subject-access export (GDPR Art. 15) | n/a | `b.subject.export(subjectId)` walks every registered subject table with auto-unseal. |
+| Audit-slice export with chain proof | AU-6 | `b.auditTools.exportSlice({ from, to, action, passphrase })` — encrypted bundle + chain proof. |
+
+## Disaster recovery
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| Documented DR plan | CP-2 | `b.drRunbook.emit({ outDir, posture, services, rtoMs, rpoMs })` generates posture-appropriate Markdown runbook composing b.budr + b.cluster + b.backup. |
+| Recovery-time / recovery-point objectives | CP-2(8) | DR runbook captures per-service RTO/RPO. |
+| Tested backup restoration | CP-9(1) | `b.backup.scheduleTest` (above). |
+
+## Crypto
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| Approved cryptographic algorithms | SC-13 | XChaCha20-Poly1305 (RFC 8439), SHA3-512, SHAKE256, HKDF-SHA3-512, ML-KEM-1024, ML-DSA-87, SLH-DSA-SHAKE-256f, Argon2id. No AES-GCM / SHA-256 / P-256 defaults. |
+| Cryptographic key protection | SC-28(1) | Vault keys sealed under operator passphrase; audit-signing key sealed under a SEPARATE passphrase. Both via Argon2id wrap. |
+| Cryptographic module verification | CM-6 | The framework refuses to load older audit-sign keys without an `algorithm` field. |
+| Quantum-safe defaults | SC-12 | PQC-first throughout. `b.pqcGate` rejects classical-only handshakes when the operator opts in. |
+
+## Network
+
+| Control intent | NIST 800-53 | Framework posture |
+| -------------- | ----------- | ----------------- |
+| TLS 1.3 minimum | SC-8 | `tls.DEFAULT_MIN_VERSION = "TLSv1.3"` set at index.js entry; sticky for the entire process. |
+| OCSP stapling | SC-12 | `b.network.tls.ocsp` for outbound; required under HIPAA/PCI-DSS/DORA postures. |
+| Certificate Transparency SCT verification | SC-12 | `b.network.tls.ct` for outbound. |
+| DoH for DNS | SC-20 | `b.network.dns.doh` is the framework default for outbound DNS. |

package/lib/vendor/blamejs/eslint.config.mjs

@@ -0,0 +1,204 @@
+// ESLint config for the blamejs framework + examples.
+//
+// Posture: catch bug-class problems (undefined references, unused
+// variables, redeclarations, equality slips, control-flow issues).
+// Don't enforce style ("var" vs "const", arrow-vs-function, etc.) —
+// the codebase has settled conventions documented in CLAUDE.md that
+// ESLint shouldn't second-guess.
+//
+// Target: Node 24 LTS, CommonJS modules, ES2024 syntax. Vendored
+// dependencies under lib/vendor/, examples/wiki/public/vendor/, and
+// any node_modules are excluded.
+//
+// Standalone (no @eslint/js / globals npm dependency) so this lints
+// cleanly via `npx eslint@10` without resolving extra peer deps.
+
+const NODE_GLOBALS = {
+  // CommonJS module system
+  module:           "readonly",
+  require:          "readonly",
+  exports:          "writable",
+  __dirname:        "readonly",
+  __filename:       "readonly",
+  // Node runtime
+  process:          "readonly",
+  Buffer:           "readonly",
+  global:           "readonly",
+  globalThis:       "readonly",
+  console:          "readonly",
+  setTimeout:       "readonly",
+  setInterval:      "readonly",
+  setImmediate:     "readonly",
+  clearTimeout:     "readonly",
+  clearInterval:    "readonly",
+  clearImmediate:   "readonly",
+  queueMicrotask:   "readonly",
+  performance:      "readonly",
+  structuredClone:  "readonly",
+  // Web-platform APIs that Node 24 ships
+  fetch:            "readonly",
+  crypto:           "readonly",
+  URL:              "readonly",
+  URLSearchParams:  "readonly",
+  TextEncoder:      "readonly",
+  TextDecoder:      "readonly",
+  Worker:           "readonly",
+  WorkerGlobalScope:"readonly",
+  AbortController:  "readonly",
+  AbortSignal:      "readonly",
+  Event:            "readonly",
+  EventTarget:      "readonly",
+  MessageChannel:   "readonly",
+  MessagePort:      "readonly",
+  ReadableStream:   "readonly",
+  WritableStream:   "readonly",
+  TransformStream:  "readonly",
+  Blob:             "readonly",
+  File:             "readonly",
+  FormData:         "readonly",
+  Headers:          "readonly",
+  Request:          "readonly",
+  Response:         "readonly",
+  // Modern intrinsics
+  BigInt:           "readonly",
+  Atomics:          "readonly",
+  SharedArrayBuffer:"readonly",
+  WeakRef:          "readonly",
+  FinalizationRegistry: "readonly",
+};
+
+const COMMON_RULES = {
+  // Bug-class rules
+  "no-undef":                  "error",
+  "no-redeclare":              "error",
+  "no-const-assign":           "error",
+  "no-delete-var":             "error",
+  "no-shadow-restricted-names":"error",
+  "no-global-assign":          "error",
+  "no-import-assign":          "error",
+  "no-func-assign":            "error",
+  "no-class-assign":           "error",
+  "no-this-before-super":      "error",
+  "no-ex-assign":              "error",
+  "no-cond-assign":            ["error", "except-parens"],
+  "no-self-assign":            "error",
+  "no-self-compare":           "error",
+  "no-unreachable":            "error",
+  "no-unsafe-finally":         "error",
+  "no-unsafe-negation":        "error",
+  "no-unsafe-optional-chaining": "error",
+  "no-fallthrough":            "error",
+  "no-async-promise-executor": "error",
+  "use-isnan":                 "error",
+  "valid-typeof":              "error",
+  "getter-return":             "error",
+  "no-compare-neg-zero":       "error",
+  "no-constant-condition":     ["error", { checkLoops: false }],
+  "no-constant-binary-expression": "error",
+  "no-dupe-keys":              "error",
+  "no-dupe-args":              "error",
+  "no-dupe-else-if":           "error",
+  "no-duplicate-case":         "error",
+  "no-sparse-arrays":          "error",
+  "no-invalid-regexp":         "error",
+  "no-misleading-character-class": "error",
+  "no-regex-spaces":           "error",
+  "no-useless-backreference":  "error",
+  "no-control-regex":          "error",
+  "no-irregular-whitespace":   "error",
+  "no-octal":                  "error",
+  "no-debugger":               "error",
+  "no-prototype-builtins":     "error",
+  // Strict equality — `null` allowed for the `== null` / `!= null`
+  // null-or-undefined idiom; everything else must use `===` / `!==`.
+  "eqeqeq":                    ["error", "always", { null: "ignore" }],
+  "no-throw-literal":          "error",
+  "no-promise-executor-return":"error",
+  "default-case":              "error",
+  "no-loss-of-precision":      "error",
+
+  // Hygiene rules — code clarity, dead-code removal.
+  "no-unused-vars":            ["error", {
+    args:                      "none",
+    varsIgnorePattern:         "^_",
+    caughtErrors:              "all",
+    caughtErrorsIgnorePattern: "^_",
+    destructuredArrayIgnorePattern: "^_",
+  }],
+  "no-useless-escape":         "error",
+  "no-empty":                  ["error", { allowEmptyCatch: true }],
+  "no-extra-boolean-cast":     "error",
+  "no-unused-expressions":     ["error", { allowShortCircuit: true, allowTernary: true }],
+  "no-unused-private-class-members": "error",
+};
+
+export default [
+  {
+    ignores: [
+      "**/node_modules/**",
+      "lib/vendor/**",
+      "examples/wiki/public/vendor/**",
+      "examples/wiki/public/dist/**",
+      "**/data/**",
+      "**/data-e2e/**",
+      "**/.git/**",
+      ".test-output/**",
+      ".claude/**",
+      // Wiki snippets are embedded into pages where `b` / `db` /
+      // `req` / `res` are in scope; some use top-level await. They're
+      // executed by the wiki e2e harness inside a wrapping context,
+      // not standalone.
+      "examples/wiki/snippets/**",
+    ],
+  },
+  {
+    files: ["**/*.js"],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType:  "commonjs",
+      globals:     NODE_GLOBALS,
+    },
+    rules: COMMON_RULES,
+  },
+  {
+    files: ["**/*.mjs"],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType:  "module",
+      globals:     NODE_GLOBALS,
+    },
+    rules: COMMON_RULES,
+  },
+  // Browser-side scripts (wiki client bundle source, prism-test etc.).
+  {
+    files: ["examples/*/public/**/*.js", "examples/*/src/**/*.js"],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType:  "script",
+      globals: {
+        // Browser globals — supplements the Node set above.
+        window:        "readonly",
+        document:      "readonly",
+        navigator:     "readonly",
+        location:      "readonly",
+        localStorage:  "readonly",
+        sessionStorage:"readonly",
+        Element:       "readonly",
+        HTMLElement:   "readonly",
+        Node:          "readonly",
+        Prism:         "readonly",
+        IntersectionObserver: "readonly",
+        MutationObserver:     "readonly",
+        ResizeObserver:       "readonly",
+        getComputedStyle:     "readonly",
+        history:              "readonly",
+        alert:                "readonly",
+        confirm:              "readonly",
+        prompt:               "readonly",
+        XMLHttpRequest:       "readonly",
+        WebSocket:            "readonly",
+      },
+    },
+    rules: COMMON_RULES,
+  },
+];

package/lib/vendor/blamejs/examples/wiki/Caddyfile

@@ -0,0 +1,40 @@
+# Caddy config for blamejs.com — automatic Let's Encrypt TLS,
+# reverse-proxy to the wiki container on the docker-compose network.
+#
+# Caddy issues + renews certificates automatically. The operator only
+# needs to point blamejs.com A/AAAA records at the host running this.
+
+blamejs.com, www.blamejs.com {
+	# Canonicalize www.* → apex.
+	@www host www.blamejs.com
+	redir @www https://blamejs.com{uri} 308
+
+	encode zstd gzip
+
+	# Pass through to the wiki container by service name on the
+	# compose network (Caddy resolves "wiki" to the container).
+	# Caddy reads {$WIKI_PORT} from its own environment at config-load
+	# time. The prod compose passes WIKI_PORT through to BOTH the wiki
+	# and caddy services so an operator who overrides WIKI_PORT in
+	# `.env` gets a consistent upstream — without this, an operator
+	# carrying WIKI_PORT=8080 from a pre-v0.11.40 deploy would have
+	# the wiki listening on 8080 while Caddy forwarded to the new
+	# default, surfacing as 502s on the public site.
+	reverse_proxy wiki:{$WIKI_PORT:3008} {
+		# Forward the original scheme so the wiki's CORS same-origin
+		# detection trusts X-Forwarded-Proto: https.
+		header_up X-Forwarded-Proto https
+		header_up X-Forwarded-For {remote_host}
+	}
+
+	# Caddy applies sensible TLS defaults; pin to 1.3 floor explicitly.
+	tls {
+		protocols tls1.3
+	}
+
+	# Log to stdout so Docker captures it.
+	log {
+		output stdout
+		format json
+	}
+}

package/lib/vendor/blamejs/examples/wiki/DEPLOY.md

@@ -0,0 +1,218 @@
+# Deploying the wiki
+
+The wiki ships with two compose configurations:
+
+- `docker-compose.yml` — local dev. Builds from source, exposes 3008.
+- `docker-compose.prod.yml` — production overlay. Pulls the published GHCR image, fronts it with Caddy for automatic TLS, exposes 80/443.
+
+## Quick deploy to a VPS for `blamejs.com`
+
+Prerequisites:
+
+- A host with Docker + Docker Compose installed
+- Inbound 80/443 open
+- DNS `A` (and `AAAA` if IPv6) for `blamejs.com` and `www.blamejs.com` pointing at the host
+- A stable strong admin password (see `.env` below)
+
+Steps:
+
+```bash
+# 1. Get the deploy artifacts onto the host
+git clone https://github.com/blamejs/blamejs.git
+cd blamejs/examples/wiki
+
+# 2. Configure the .env (every value below is optional except the
+#    one explicitly marked REQUIRED — see "Environment variables"
+#    section for the full matrix).
+cat > .env <<'EOF'
+# REQUIRED
+WIKI_ADMIN_PASSWORD=<a strong passphrase>
+
+# Recommended once you flip the wiki to wrapped vault mode
+BLAMEJS_VAULT_PASSPHRASE=<a different strong passphrase>
+
+# Optional — defaults shown
+WIKI_ADMIN_EMAIL=admin@blamejs.com
+WIKI_PORT=3008
+LOG_LEVEL=info
+
+# Optional — outbound page-edit webhook
+WIKI_WEBHOOK_URL=
+WIKI_WEBHOOK_SECRET=
+EOF
+chmod 600 .env
+
+# 3. Start the stack
+docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+# 4. Watch the first boot — Caddy will request the cert from
+#    Let's Encrypt and the wiki will seed its admin user.
+docker compose logs -f
+```
+
+When the Caddy logs show `certificate obtained successfully`, the site is live at `https://blamejs.com`.
+
+## Environment variables
+
+The wiki container reads its configuration from environment. `docker-compose.prod.yml` wires every variable below from your `.env`; the Dockerfile sets non-secret defaults so an operator who just wants the basics can leave most blank.
+
+### Wiki app
+
+| Variable | Required? | Default | Purpose |
+|---|---|---|---|
+| `WIKI_ADMIN_PASSWORD` | **yes (production)** | random + printed to stdout once | Seeded admin login. Setting it explicitly avoids the random-on-each-restart pattern. |
+| `WIKI_ADMIN_EMAIL` | no | `admin@blamejs.com` | Seeded admin login email. |
+| `WIKI_PORT` | no | `3008` | HTTP listen port inside the container. Caddy proxies to this; rarely overridden. |
+| `WIKI_DATA_DIR` | no | `/data` | On-disk path the wiki writes vault key + sqlite + audit chain to. Bound to a Docker volume in the compose. |
+| `WIKI_WEBHOOK_URL` | no | unset | Outbound HTTPS endpoint that receives one POST per `wiki.page.edited` event. |
+| `WIKI_WEBHOOK_SECRET` | required if URL set | unset | HMAC secret the webhook receiver uses to verify the request signature. |
+
+### Framework (`BLAMEJS_*`)
+
+| Variable | Required? | Default | Purpose |
+|---|---|---|---|
+| `BLAMEJS_VAULT_PASSPHRASE` | required for production posture | unset | Argon2id-stretched into the vault-key wrapping key. **Setting this auto-flips the wiki to wrapped vault + encrypted-at-rest DB at boot** (the wiki's `lib/build-app.js` reads the env var as the production-posture signal). Without it the wiki boots in plaintext mode for dev ergonomics. |
+| `BLAMEJS_AUDIT_SIGNING_PASSPHRASE` | required for production posture | unset | Argon2id-stretched into the audit-signing key wrap. **Setting this auto-flips audit-sign to wrapped at boot** (`audit-sign.key.sealed` on disk, never plaintext). Different from `BLAMEJS_AUDIT_PASSPHRASE` below — that's for the archive CLI, not boot-time signing. |
+| `BLAMEJS_AUDIT_PASSPHRASE` | only when running `blamejs audit` CLI | unset | Used by `blamejs audit archive / export / verify / purge` for the chain-export bundle wrap. Not read at app boot. |
+| `WIKI_VAULT_MODE` | no | auto-detect | `wrapped` \| `plaintext`. Explicit override for the auto-detect logic above. |
+| `WIKI_DB_AT_REST` | no | auto-detect | `encrypted` \| `plain`. Explicit override. |
+| `WIKI_AUDIT_SIGNING_MODE` | no | auto-detect | `wrapped` \| `plaintext`. Explicit override. |
+| `BLAMEJS_BACKUP_PASSPHRASE` | only when running `blamejs backup` CLI | unset | Used by `blamejs backup verify / extract` against an existing bundle on disk. Not read at app boot. |
+| `BLAMEJS_DEPRECATIONS` | no | `warn` | `warn` (default) emits a structured log line; `throw` makes deprecated calls fail loud (recommended pre-v1); `silent` suppresses. |
+
+### Standard Node
+
+| Variable | Required? | Default | Purpose |
+|---|---|---|---|
+| `NODE_ENV` | no | `production` | Standard `production`/`development` flag. |
+| `LOG_LEVEL` | no | `info` | Structured-log filter. `debug` / `info` / `warn` / `error`. |
+
+### Secrets handling
+
+Every passphrase / webhook secret in the table above is **never** ENV-baked into the image — they're injected at runtime via the `.env` file (compose), Docker secrets, or a secret-manager mount. The `.env` file should be `chmod 600` and excluded from version control. The `Dockerfile` only sets non-secret defaults (`NODE_ENV`, `WIKI_DATA_DIR`, `WIKI_PORT`).
+
+## What's where
+
+- The wiki container persists state in the `wiki-data` named volume — vault key, sealed audit-signing key, sqlite database, audit chain. **Back this up.** Losing it loses the audit chain and admin credentials.
+- Caddy persists ACME state in the `caddy-data` named volume. Deleting it forces a re-issuance from scratch — Let's Encrypt rate limits apply, so don't.
+- All TLS is Caddy's. The wiki container only speaks HTTP on the compose network.
+
+## Updating to a new version
+
+```bash
+# Pin the new version in docker-compose.prod.yml (image: ghcr.io/...:vX.Y.Z)
+docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+The wiki container's healthcheck on `/healthz` ensures Caddy only routes once the new container is ready.
+
+## Rolling back
+
+```bash
+# Edit docker-compose.prod.yml back to the previous image tag.
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d wiki
+```
+
+The on-disk schema is forward-compatible within a minor; downgrading across a minor isn't supported.
+
+## Troubleshooting
+
+- **Caddy can't issue cert** — check that ports 80 and 443 are reachable from the public internet (Let's Encrypt's HTTP-01 challenge needs port 80). Run `docker compose logs caddy` for the specific ACME error.
+- **Wiki returns 502** — the wiki container's healthcheck is failing. `docker compose logs wiki` shows the cause; usually missing `WIKI_ADMIN_PASSWORD` or a corrupt vault key.
+- **Cookies / sessions don't stick** — the wiki sets `Secure` cookies in production. If you're testing on `http://` for some reason, sessions will drop; either add `WIKI_INSECURE_COOKIES=1` (dev only) or use the proper TLS path.
+
+## GitHub repository + Actions setup (publishing your own image)
+
+If you're forking `blamejs` (or running this wiki as your own deployment that ships its own GHCR image), the workflows have prerequisites on the GitHub side that aren't visible in the code. Configure these once per org / per fork.
+
+### Org-level Actions billing
+
+The release-container workflow runs five jobs per tag push: 3 lint jobs, the build/scan/sign/publish job, and a post-publish smoke-test. The build job does a multi-arch build (linux/amd64 + linux/arm64 via QEMU) which consumes more runner-minutes than a single-arch build. Make sure the **organization's** Actions spending limit (not personal) is non-zero — public-repo Linux runner-minutes are free on most plans, but a `Stop usage: Yes` setting with a $0 limit blocks all jobs.
+
+- **Org settings**: `https://github.com/organizations/<your-org>/settings/billing`
+- **Spending limit**: `https://github.com/organizations/<your-org>/settings/billing/spending_limit`
+- Symptom of a billing block: a job fails in seconds with no steps, no runner allocated, and an annotation containing `"recent account payments have failed or your spending limit needs to be increased"`. The fix has to propagate from GitHub's billing system after you change the limit; allow a few minutes.
+
+### Workflow permissions (already set in the YAML, but worth knowing)
+
+`.github/workflows/release-container.yml` declares the minimum permissions the workflow needs. Each one is required for a specific step:
+
+| Permission | Used by | Why |
+|---|---|---|
+| `contents: read` | `actions/checkout@v6` | Read the repo source |
+| `packages: write` | `docker/login-action@v4` + `docker/build-push-action@v7` | Push the built image to `ghcr.io/<owner>/blamejs-wiki` |
+| `id-token: write` | `sigstore/cosign-installer@v3` + `cosign sign --yes` | Mint a short-lived OIDC token GitHub Actions exchanges with Sigstore's Fulcio for a keyless signing certificate |
+
+CI (`ci.yml`) declares `contents: read` + `pull-requests: write` (the latter so the lint-summary job can post / update the sticky PR comment).
+
+These are scoped per workflow; the org-level **default permissions** at `https://github.com/organizations/<your-org>/settings/actions` should be set to `Read repository contents and packages permissions` (the most-restrictive default) so workflows that don't declare explicit permissions can't accidentally write.
+
+### GHCR package visibility
+
+GitHub Container Registry packages default to **private** when a workflow first publishes them. For an open-source framework, you'll want public so operators can `docker pull` without authenticating:
+
+- `https://github.com/orgs/<your-org>/packages/container/blamejs-wiki/settings`
+- "Change visibility" → Public
+
+Even with a public package, the post-publish smoke-test job logs in via `docker/login-action@v4` (using the auto-provided `GITHUB_TOKEN`) — login is a no-op for public packages and required for private, so the same workflow shape works either way.
+
+### Cosign signature verification (downstream operators)
+
+The publish job signs the multi-arch manifest with Sigstore's keyless flow — there's no long-lived key to manage. The signing identity is the workflow itself, attested by GitHub's OIDC issuer. Downstream operators verify before pulling:
+
+```bash
+cosign verify ghcr.io/<your-org>/blamejs-wiki:<tag> \
+  --certificate-identity-regexp "https://github.com/<your-org>/<repo>/.github/workflows/release-container.yml@refs/tags/v.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+A successful verification proves the image was built by the actual release-container workflow on a tag push, and not pushed by anyone with `packages: write` directly. Combine with the SBOM + provenance attestations the workflow attaches (`provenance: true` + `sbom: true` on `docker/build-push-action`) for full supply-chain confidence.
+
+### Branch protection (recommended)
+
+For `main`, require the CI workflow's lint-summary job to pass before merge. The lint-summary aggregates ESLint + Hadolint + ShellCheck and is the single check name to add to "Required status checks":
+
+- `https://github.com/<your-org>/<repo>/settings/branches`
+- Add rule for `main`
+- "Require status checks to pass before merging" → "Lint summary"
+- Optionally also require: "Framework smoke (ubuntu-latest)" + "Wiki e2e (ubuntu-latest)"
+
+### Tag-driven releases
+
+The release-container workflow triggers on `push: tags: ["v*"]`. The canonical release flow runs through `node scripts/release.js`, which orchestrates everything from version bump through publish:
+
+```bash
+# One-shot — patch bump, runs every gate in sequence, opens PR, watches CI, tags, watches publish
+node scripts/release.js all
+
+# Or individual phases:
+node scripts/release.js prepare    # bump + regen CHANGELOG + api-snapshot + static gates
+node scripts/release.js regen      # re-regen artifacts after release-notes edits (mid-flow)
+node scripts/release.js smoke      # SMOKE_PARALLEL=64 + (auto) wiki e2e if examples/wiki touched
+node scripts/release.js commit     # release/v<next> branch + signed commit (resumable)
+node scripts/release.js push       # gitleaks + push + open PR
+node scripts/release.js watch      # gh pr checks --watch + flag unresolved Codex threads
+node scripts/release.js merge      # squash-merge after re-checking threads
+node scripts/release.js tag        # signed annotated tag + push tag
+node scripts/release.js publish    # watch npm-publish + release-container workflows
+
+# Minor bump (rolls up prior minor's release-notes automatically):
+node scripts/release.js all --minor
+
+# Read-only state report:
+node scripts/release.js status
+```
+
+Pre-requisites the script enforces:
+- Operator wrote `release-notes/v<next>.json` (the only manual content step). The script refuses with a stub template if missing.
+- SSH signing config in place (the script refuses if `git log -1 --pretty='%G?'` doesn't report `G`).
+
+After the tag push, the release-container workflow runs all 5 jobs; on success, image is at `ghcr.io/<your-org>/blamejs-wiki:<tag>` (signed, scanned, smoke-tested). Operators pin the new tag in `docker-compose.prod.yml`'s `image:` line on the deploy host, then `docker compose pull && docker compose up -d`.
+
+Hot-fixes / dry-runs use the `workflow_dispatch` trigger with the `dry_run` input — run the build + scan path without pushing or signing, useful for verifying a Dockerfile change before tagging:
+
+```bash
+gh workflow run release-container.yml --repo <your-org>/<repo> --ref <branch> -F dry_run=true
+```