@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/examples/wiki/Dockerfile

@@ -0,0 +1,120 @@
+# syntax=docker/dockerfile:1.7
+#
+# Wolfi-based image (Chainguard's distro) for the wiki reference app.
+#
+# Build context = repo root, not examples/wiki/. The wiki package.json
+# declares "@blamejs/core": "file:../..", so the framework source has
+# to be reachable from the wiki directory at install time. Compose
+# in this directory sets context: ../.. accordingly.
+#
+# Two stages:
+#   - builder uses cgr.dev/chainguard/node:latest-dev (shell + npm
+#     for the install-links resolve)
+#   - runtime uses cgr.dev/chainguard/node:latest (no shell, drops
+#     to the nonroot user, minimal attack surface)
+#
+# The vendored Argon2id native module ships glibc prebuilds; Wolfi is
+# glibc-based so the existing prebuilds load without rebuild.
+
+# Chainguard's :latest-dev runs as the `node` user by default with HOME
+# at /home/node. Anchor the build there with matching --chown=node:node
+# so npm install can create node_modules without any USER root step.
+# The :latest runtime image runs as `nonroot` (different user, lower
+# privilege); --chown=nonroot:nonroot on the COPY --from=deps rewrites
+# ownership at copy time into the runtime image.
+FROM cgr.dev/chainguard/node:latest-dev AS deps
+WORKDIR /home/node
+COPY --chown=node:node package.json index.js NOTICE LICENSE README.md ./
+COPY --chown=node:node bin ./bin
+COPY --chown=node:node lib ./lib
+COPY --chown=node:node examples/wiki ./examples/wiki
+WORKDIR /home/node/examples/wiki
+# Install deps + pre-build the public/dist bundle here in the build
+# stage so the runtime image ships with bundles already on disk. The
+# runtime container never needs to write to public/dist (which under
+# --cap-drop ALL + nonroot-only invocations would EACCES even on a
+# correctly-chowned dir). Bundle output is operator-deterministic
+# given a pinned source tree, so building at image-build time is a
+# reproducibility win as well.
+RUN rm -rf node_modules data data-e2e public/dist \
+ && npm install --no-package-lock --omit=dev --install-links \
+ && node -e "var b = require('@blamejs/core'); var path = require('node:path'); (async function () { var bundler = b.bundler.create({ entries: { wiki: path.join(process.cwd(), 'src', 'wiki.js'), editor: path.join(process.cwd(), 'src', 'editor.js') }, outdir: path.join(process.cwd(), 'public', 'dist'), manifest: 'manifest.json', hashLen: 16 }); await bundler.build(); console.log('[Dockerfile] bundle pre-built into public/dist'); })().catch(function (e) { console.error('bundle build failed:', e.stack || e); process.exit(1); });" \
+ && mkdir -p /home/node/data-skeleton
+
+FROM cgr.dev/chainguard/node:latest AS runtime
+# Explicit USER directive — Chainguard's :latest image already runs as
+# `nonroot` (UID 65532) by default, but Trivy's static Dockerfile
+# checker (DS-0002) flags any image without an explicit USER line
+# regardless of the base image's default. Restate it here.
+USER 65532:65532
+# Non-secret defaults baked into the image. Secrets (passphrases,
+# webhook secrets, admin password) are NEVER ENV-baked — they're
+# injected at runtime via env / docker secrets / mounted files.
+#
+# Available environment variables (operator-set at runtime):
+#
+#   NODE_ENV               production | development                 (default: production)
+#   WIKI_DATA_DIR          on-disk path for vault.key + sqlite +
+#                          audit chain                              (default: /data)
+#   WIKI_PORT              listen port                              (default: 3008)
+#
+#   WIKI_ADMIN_EMAIL       seeded admin login email                 (default: admin@blamejs.com)
+#   WIKI_ADMIN_PASSWORD    seeded admin password                    (REQUIRED — generated
+#                                                                    if absent, printed to
+#                                                                    stdout on first boot;
+#                                                                    set explicitly in prod)
+#   WIKI_WEBHOOK_URL       outbound page-edit webhook target        (optional)
+#   WIKI_WEBHOOK_SECRET    HMAC secret for the webhook              (required if URL set)
+#
+#   BLAMEJS_VAULT_PASSPHRASE
+#                          when set, the wiki auto-flips to vault:
+#                          wrapped + DB encrypted-at-rest at boot —
+#                          Argon2id-stretched into the wrapping key
+#                          for vault.key.sealed. Without it the wiki
+#                          boots in plaintext mode for dev ergonomics.
+#
+#   BLAMEJS_AUDIT_SIGNING_PASSPHRASE
+#                          when set, the audit-chain signing key is
+#                          sealed at boot (audit-sign.key.sealed on
+#                          disk) — Argon2id-stretched. Read at boot.
+#                          Different from BLAMEJS_AUDIT_PASSPHRASE.
+#
+#   BLAMEJS_AUDIT_PASSPHRASE
+#                          used by `blamejs audit archive/export/
+#                          verify/purge` CLI commands invoked
+#                          inside the container; not read at boot
+#
+#   WIKI_VAULT_MODE / WIKI_DB_AT_REST / WIKI_AUDIT_SIGNING_MODE
+#                          explicit overrides for the auto-detect
+#                          above ("wrapped" / "encrypted" / etc.)
+#
+#   BLAMEJS_DEPRECATIONS   "verbose" | "throw" | "silent"           (default: warn)
+#                          framework deprecation reporting mode
+#
+#   LOG_LEVEL              "debug" | "info" | "warn" | "error"      (default: info)
+#                          structured-log filter level
+ENV NODE_ENV=production \
+    WIKI_DATA_DIR=/data \
+    WIKI_PORT=3008
+WORKDIR /app
+COPY --from=deps --chown=65532:65532 /home/node/package.json /home/node/index.js /home/node/NOTICE /home/node/LICENSE /home/node/README.md ./
+COPY --from=deps --chown=65532:65532 /home/node/bin ./bin
+COPY --from=deps --chown=65532:65532 /home/node/lib ./lib
+COPY --from=deps --chown=65532:65532 /home/node/examples/wiki ./examples/wiki
+# Pre-create WIKI_DATA_DIR (default /data) with nonroot ownership so
+# the runtime user can populate it with vault.key + sqlite + audit
+# chain on first boot. The framework's createApp does
+# fs.mkdirSync(dataDir, {recursive:true}); without this, that mkdir
+# fails because nonroot (UID 65532) doesn't have write permission on
+# /. Production deployments bind-mount a named volume on top of
+# /data — see examples/wiki/docker-compose.prod.yml. This empty
+# pre-created dir is the fallback for a `docker run` with no volume
+# (the post-publish smoke-test job's invocation).
+COPY --from=deps --chown=65532:65532 /home/node/data-skeleton /data
+WORKDIR /app/examples/wiki
+EXPOSE 3008
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:3008/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+# The Chainguard node image has ENTRYPOINT ["/usr/bin/node"], so CMD
+# is just the script path the operator wants Node to run.
+CMD ["server.js"]

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

@@ -0,0 +1,157 @@
+# blamejs wiki — reference app + docs site
+
+The blamejs wiki is the framework's documentation site, built as a working blamejs app. It is a working reference operators can study to see every primitive wired up in an opinionated baseline configuration.
+
+## Boot
+
+```bash
+cd examples/wiki
+npm install
+WIKI_ADMIN_PASSWORD="some-strong-password" npm start
+```
+
+Server listens on `http://localhost:3008` by default. Override with `WIKI_PORT`. Admin credentials via `WIKI_ADMIN_EMAIL` (default `admin@blamejs.com`) and `WIKI_ADMIN_PASSWORD` (required ≥ 8 chars; a random dev password is generated and printed if unset).
+
+## Run with Docker Compose
+
+```bash
+cd examples/wiki
+docker compose up --build
+```
+
+The compose file mounts a named volume (`wiki-data`) at `/data` so the vault key, sqlite database, and audit chain persist across container restarts. Set `WIKI_ADMIN_PASSWORD` (and any other `WIKI_*` envs from `server.js`) in a `.env` file alongside `docker-compose.yml`, or in the host environment, to pin a stable admin credential. Healthcheck hits `/healthz` every 30 seconds.
+
+The `Dockerfile` is multi-stage (deps build + slim runtime), runs as the unprivileged `node` user, and uses a `node:24-slim` base (24.14+ — the engine pin in `package.json` requires `>=24.14.1` for CVE-2026-21713 fix). Argon2id routes through Node's built-in `crypto.argon2*` API, so the image carries no native-module prebuild.
+
+For production deploys with TLS terminator + auto Let's Encrypt, see [DEPLOY.md](./DEPLOY.md) — it documents the `docker-compose.prod.yml` overlay that fronts the wiki with Caddy and pulls the published `ghcr.io/blamejs/blamejs-wiki` image instead of building from source.
+
+## Run the e2e test
+
+```bash
+cd examples/wiki
+npm test
+```
+
+Boots the server in-process on an ephemeral port, hits each route with browser-shaped headers (CORS-on path included so the compression backpressure path is exercised), validates response codes and body content, walks every internal link, and verifies every code-block language is loadable by the Prism bundle. **102/102 checks** at present.
+
+## What's wired (baseline-all-features stance)
+
+The wiki is a reference, not a one-off — every in-process primitive the framework ships is wired with operator-safe defaults. Operators copying this app inherit the right baseline.
+
+### Security middleware (all ON)
+
+- `b.middleware.requestId` — every response carries `X-Request-Id`
+- `b.middleware.securityHeaders` — HSTS, X-Frame-Options, COOP, COEP, etc.
+- `b.middleware.botGuard` — rejects requests missing real-browser headers
+- `b.middleware.cors` — same-origin only (`allowedOrigins: []`)
+- `b.middleware.rateLimit` — 120 req/min memory token-bucket; `/healthz` skipped
+- `b.middleware.cspNonce` — per-request nonce for inline styles/scripts
+- `b.middleware.bodyParser` — form-URL-encoded + JSON
+- `b.middleware.compression` — Brotli + gzip negotiation
+- `b.middleware.attachUser` — session cookie → `req.user`
+- `b.middleware.csrfProtect` — POST forms include hidden CSRF token
+- `b.middleware.health` — `/healthz` (liveness), `/readyz` (readiness with DB check), `/startupz` (startup)
+
+### State + storage
+
+- `b.db` — SQLite with sealed columns + audit chain + audit signing
+- `b.migrations` — `migrations/0001-pages-schema.js` creates pages table + FTS5 mirror + sync triggers
+- `b.seeders` — `seeders/prod/0001-default-pages.js` seeds the concern-group nav (rerunnable: true)
+- `b.cache` — page-render cache, namespace `wiki.page`, 5-minute TTL, audit-emitting
+
+### Auth
+
+- `b.auth.password` (Argon2id) — admin login
+- `b.session` — sealed cookie token, 24h expiry
+- `b.permissions` — `admin` and `viewer` roles, `admin` scope gates `/admin/*`
+
+### Rendering
+
+- `b.template` — eval-free template engine, views in `views/`
+- `b.render.html` / `b.render.htmlString` / `b.render.json` / `b.render.redirect`
+- `b.staticServe` — assets in `public/` (favicon.ico, robots.txt, etc.)
+
+### Localization
+
+- `b.i18n` — wired with English by default. Operators add locales by extending the `translations` object or pointing `dir` at a JSON tree.
+
+### Validation + observability + audit
+
+- `b.slug` — admin save uses `b.slug(value, { fallback })` for URL slug normalization
+- `b.audit` — every login / page edit / cache clear / etc. emits with the 5 W's (WHO/WHAT/WHEN/WHERE/HOW) via `b.requestHelpers.extractActorContext`
+- `b.observability` — every primitive's events (cache hit/miss, audit emit, etc.) route through here; pluggable to OTel
+- `b.metrics` + `b.tracing` — pass-through unless operator wires a real backend
+
+## What's documented but not wired (operator-specific)
+
+These primitives are intentionally NOT wired in the wiki because they require operator-supplied infrastructure (TLS certs, SMTP servers, external DB, etc.). The docs pages explain how operators integrate them:
+
+- `b.cluster` — opt-in HA (active/active leader election)
+- `b.externalDb` — Postgres / SQLite-cluster operator-side
+- `b.mtlsCa` — operator-managed certificate authority
+- `b.pqcGate` — TLS layer for production deploy
+- `b.mail` + `b.mailBounce` — SMTP / SES operator setup
+- `b.websocket` + `b.websocketChannels` — operator-opt-in for live features
+- `b.objectStore` + `b.storage` — S3 / GCS / Azure Blob (operator backend)
+- `b.backup` + `b.restore` — CLI workflow
+- `b.bundler` — frontend asset bundling (no client JS in the wiki yet)
+
+## Production deploy
+
+The wiki ships with development-friendly defaults (`vault: { mode: "plaintext" }`, `db: { atRest: "plain", auditSigning: { mode: "plaintext" } }`). For production:
+
+1. Set `BLAMEJS_VAULT_PASSPHRASE` (or wire a `vault.passphraseSource`)
+2. Change `vault.mode` to `"wrapped"` (default)
+3. Change `db.atRest` to `"encrypted"` (default; requires tmpfs at `/dev/shm` or `BLAMEJS_TMPDIR`)
+4. Change `db.auditSigning.mode` to `"wrapped"`
+5. Deploy behind a TLS-terminating reverse proxy OR enable `b.pqcGate`
+6. Set `WIKI_TRUST_PROXY=1` if (and only if) the wiki sits behind a reverse proxy that injects `x-forwarded-proto`. With trustProxy off (the default), the wiki ignores `x-forwarded-proto` for cookie Secure-flag detection, so a misconfigured deployment can't accept attacker-supplied `x-forwarded-proto: https` as proof a request was over TLS.
+7. Set `WIKI_ADMIN_PASSWORD` to a strong value managed by your secret-store
+
+## Trust model for editable page bodies
+
+Page bodies are stored verbatim and rendered as raw HTML (the template uses `{{{ body }}}`, not `{{ body }}`). This is **intentional**, but it means:
+
+- **Anyone with admin credentials can ship arbitrary HTML / `<script>` / `<style>` to every page reader.** The `wiki:admin` scope is fully equivalent to "operator-trusted to author the rendered output."
+- The framework's strict CSP (no `'unsafe-inline'`) blocks inline `<script>` even from admin-authored bodies — an XSS payload pasted into a page would not execute. This is the framework's defense-in-depth, not a license to lower CSP.
+- The save-time `b.htmlBalance.check()` is for shape correctness (unclosed tags would otherwise eat surrounding layout), **not** for sanitization.
+
+Adopters who plan to expand the editor surface beyond a single trusted admin should swap `{{{ body }}}` for sanitized rendering. The framework does not ship an HTML sanitizer primitive; the recommended pattern is to vendor a maintained sanitizer (DOMPurify-equivalent) and wrap it in a small `b.sanitize`-shape helper module — same vendoring discipline as `lib/vendor/MANIFEST.json`. Run sanitization at **save** time so the stored body is already safe; running it at render time means an XSS payload sits in the database in case the sanitizer ever regresses.
+
+## File layout
+
+```
+examples/wiki/
+├── package.json                  # depends on @blamejs/core via file:../..
+├── server.js                     # createApp boot, all primitives wired
+├── routes/
+│   ├── pages.js                  # public routes (split: registerSpecific + registerCatchAll)
+│   └── admin.js                  # login / logout / dashboard / edit / save (admin-gated)
+├── views/
+│   ├── _layout.html              # base layout (locale, dir, csp-nonce, csrf-token, user)
+│   ├── partials/
+│   │   └── nav.html              # concern-group navigation
+│   ├── home.html
+│   ├── page.html                 # renders DB-stored page bodies
+│   ├── login.html
+│   ├── search.html
+│   └── admin/
+│       ├── dashboard.html
+│       └── edit.html
+├── migrations/
+│   └── 0001-pages-schema.js      # pages + FTS5 + sync triggers
+├── seeders/
+│   └── prod/
+│       └── 0001-default-pages.js # nav landing pages
+├── public/                       # static assets (favicon etc.)
+├── test/
+│   └── e2e.js                    # boot-and-probe via node:http with browser headers
+└── data/                         # local SQLite + vault key (gitignored)
+```
+
+## Known gaps
+
+- **Search**: `/search?q=...` works against the FTS5 index, but most concern-group pages are still stubs so there isn't much to find yet.
+- **Concern-group pages are stubs**: most landing pages (Auth, Storage, HTTP, etc.) currently have a "Coming soon" body. Full primitive walkthroughs land as each group is written.
+- **Editor is plain HTML**: the admin edit screen is a `<textarea>`. A small client-side enhancement (autosave, slug-from-title preview) is on the list.
+- **Recipe pages**: cluster mode, mail, websocket, FTS5 schema walkthrough — stubbed for now.

package/lib/vendor/blamejs/examples/wiki/cli-snapshot.json

@@ -0,0 +1,250 @@
+{
+  "topCommands": [
+    "api-key",
+    "api-snapshot",
+    "audit",
+    "backup",
+    "config-drift",
+    "dev",
+    "erase",
+    "file-type",
+    "help",
+    "migrate",
+    "mtls",
+    "password",
+    "restore",
+    "retention",
+    "security",
+    "seed",
+    "vault",
+    "version"
+  ],
+  "perCommand": {
+    "migrate": {
+      "subcommands": [
+        "down",
+        "status",
+        "up"
+      ],
+      "flags": [
+        "--db",
+        "--dir",
+        "--steps"
+      ]
+    },
+    "seed": {
+      "subcommands": [
+        "run",
+        "status"
+      ],
+      "flags": [
+        "--db",
+        "--dir",
+        "--env",
+        "--force",
+        "--only"
+      ]
+    },
+    "dev": {
+      "subcommands": [],
+      "flags": [
+        "--arg",
+        "--command",
+        "--grace-ms",
+        "--ignore",
+        "--kill-signal",
+        "--watch"
+      ]
+    },
+    "api-snapshot": {
+      "subcommands": [
+        "capture",
+        "compare"
+      ],
+      "flags": [
+        "--file",
+        "--module"
+      ]
+    },
+    "audit": {
+      "subcommands": [
+        "archive",
+        "export",
+        "purge",
+        "verify-bundle",
+        "verify-chain"
+      ],
+      "flags": [
+        "--in",
+        "--out",
+        "--passphrase"
+      ]
+    },
+    "restore": {
+      "subcommands": [
+        "apply",
+        "inspect",
+        "list",
+        "list-rollbacks",
+        "rollback"
+      ],
+      "flags": [
+        "--bundle",
+        "--bundle-id",
+        "--data-dir",
+        "--passphrase",
+        "--storage-root"
+      ]
+    },
+    "api-key": {
+      "subcommands": [
+        "issue",
+        "list",
+        "revoke",
+        "rotate",
+        "verify"
+      ],
+      "flags": []
+    },
+    "backup": {
+      "subcommands": [
+        "extract",
+        "inspect",
+        "verify"
+      ],
+      "flags": [
+        "--bundle",
+        "--passphrase",
+        "--to"
+      ]
+    },
+    "mtls": {
+      "subcommands": [
+        "init",
+        "issue",
+        "issue-p12",
+        "show-cert",
+        "status"
+      ],
+      "flags": [
+        "--data-dir"
+      ]
+    },
+    "vault": {
+      "subcommands": [
+        "rotate",
+        "seal",
+        "status",
+        "unseal"
+      ],
+      "flags": [
+        "--data-dir",
+        "--keep-plaintext",
+        "--new-passphrase",
+        "--passphrase"
+      ]
+    },
+    "security": {
+      "subcommands": [
+        "assert"
+      ],
+      "flags": [
+        "--data-dir",
+        "--forbid-env",
+        "--no-audit-signing",
+        "--no-db-at-rest",
+        "--no-ntp-strict",
+        "--no-vault",
+        "--require-env"
+      ]
+    },
+    "config-drift": {
+      "subcommands": [
+        "inspect",
+        "verify"
+      ],
+      "flags": [
+        "--baseline",
+        "--data-dir"
+      ]
+    },
+    "file-type": {
+      "subcommands": [],
+      "flags": [
+        "--allowlist",
+        "--json"
+      ]
+    },
+    "password": {
+      "subcommands": [],
+      "flags": [
+        "--breach-check",
+        "--email",
+        "--fail-closed",
+        "--json",
+        "--max-length",
+        "--min-length",
+        "--plaintext",
+        "--profile",
+        "--stdin",
+        "--username"
+      ]
+    },
+    "erase": {
+      "subcommands": [],
+      "flags": [
+        "--confirm",
+        "--data-dir",
+        "--reason",
+        "--row-id",
+        "--table"
+      ]
+    },
+    "retention": {
+      "subcommands": [
+        "preview",
+        "run"
+      ],
+      "flags": []
+    }
+  },
+  "readme": [
+    "api-key",
+    "api-snapshot",
+    "audit",
+    "backup",
+    "config-drift",
+    "dev",
+    "erase",
+    "file-type",
+    "help",
+    "migrate",
+    "mtls",
+    "password",
+    "restore",
+    "retention",
+    "security",
+    "seed",
+    "vault",
+    "version"
+  ],
+  "readmePairs": [
+    "api-key:issue",
+    "api-snapshot:capture",
+    "audit:archive",
+    "backup:inspect",
+    "config-drift:inspect",
+    "file-type:detect",
+    "migrate:up",
+    "mtls:status",
+    "password:check",
+    "restore:list",
+    "retention:preview",
+    "security:assert",
+    "seed:run",
+    "vault:status",
+    "version:blamejs"
+  ],
+  "wiki": [],
+  "wikiPairs": []
+}