@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/.gitignore

@@ -0,0 +1,102 @@
+# Deny all dotfiles by default; allow-list specific ones below.
+# Catches .env*, .aws/, .ssh/, .npmrc-with-tokens, .vscode/, .idea/,
+# .bash_history, .DS_Store, AI-tooling scratch, and anything else
+# that conventionally lives in a dotfile we don't intend to ship.
+.*
+
+# Dotfiles we DO want tracked
+!.gitignore
+!.gitattributes
+!.github/
+!.editorconfig
+!.dockerignore
+!.hadolint.yaml
+!.nvmrc
+!.npmrc
+!.clusterfuzzlite/
+!.gitleaks.toml
+!.pinact.yaml
+# Vendor-data integrity surface — pubkey ships in tarball so operators
+# verify .data.js signatures against the maintainer's pinned key.
+!lib/vendor/.vendor-data-pubkey
+
+# Build / dependencies
+node_modules/
+dist/
+build/
+out/
+coverage/
+*.tsbuildinfo
+
+# Runtime / logs
+*.log
+*.pid
+*.pid.lock
+*.seed
+tmp/
+
+# OS junk (non-dotfile)
+Thumbs.db
+desktop.ini
+
+# Editor scratch (non-dotfile)
+*.swp
+*.swo
+*~
+
+# Credential / key material — belt-and-braces over .*
+*.pem
+*.key
+*.crt
+*.cert
+*.p12
+*.pfx
+secrets.json
+credentials.json
+id_rsa*
+id_ed25519*
+
+# Vendored cert bundles MUST track — operator-managed assets pinned
+# by SHA-256 in lib/vendor/MANIFEST.json. The blanket *.pem / *.crt
+# rules above guard against accidental commit of OPERATOR-PRIVATE
+# keys; the framework's own published trust roots (BIMI, future CA
+# bundles) are public and ship with the package.
+!lib/vendor/*.pem
+!lib/vendor/*.crt
+
+# Backup / patch artifacts
+*.bak
+*.orig
+*.rej
+
+# Example-app per-instance runtime state (vault keys, SQLite DBs, etc.)
+# The example app's repo-tracked content is its source; data/ is local.
+examples/*/data/
+examples/*/data-e2e/
+# On Windows the wiki e2e's data-e2e path can land under a literal
+# `C:/` directory inside examples/wiki/ when an env var like
+# BLAMEJS_E2E_DATA_DIR holds a Windows-absolute path that Node joins
+# onto cwd. The colon is either ASCII `:` or NTFS's Unicode
+# substitute U+F03A — match both. Ignore the whole branch so it
+# never reaches staging.
+examples/*/C\:/
+examples/wiki/C*/
+examples/*/package-lock.json
+# Top-level lockfile — the framework owns its stack via vendoring
+# (lib/vendor/) and runs zero npm deps (runtime OR dev). Any
+# package-lock.json that appears at the root is from a transient
+# `npm install` and shouldn't be tracked.
+/package-lock.json
+# Bundler output — content-hashed at boot from src/. Only the source
+# (src/*.js) is tracked; the hashed artifacts are reproducible.
+examples/*/public/dist/
+
+# Local-only release tooling — gen-changelog runs against an
+# operator's clone; CHANGELOG.md ships hand-curated from the
+# release commit instead of regenerated each release.
+scripts/gen-changelog.js
+
+# CycloneDX SBOM — generated by the npm-publish workflow at publish
+# time and bundled into the tarball; never committed. Local `npm sbom`
+# runs would otherwise leave the file lying around.
+sbom.cdx.json

package/lib/vendor/blamejs/.gitleaks.toml

@@ -0,0 +1,166 @@
+title = "blamejs gitleaks config"
+
+# Inherit gitleaks' default ruleset (AWS keys, GCP creds, GitHub tokens,
+# npm tokens, generic high-entropy strings, etc.) and add framework-
+# specific allowlists below. New rules CAN be added here when the
+# framework gains a new credential shape it wants the scan to catch
+# (e.g. WIKI_WEBHOOK_SECRET in operator config); for now the defaults
+# are the policy.
+[extend]
+useDefault = true
+
+# gitleaks 8.21+ requires the [[allowlists]] (plural) form; the
+# singular [allowlist] is deprecated and rejected when [[allowlists]]
+# is also present. Each [[allowlists]] block is independent — a finding
+# is suppressed if ANY block matches.
+
+[[allowlists]]
+description = "Vendored binaries + crypto-fixture entropy in tests"
+paths = [
+  # Vendored deps (lib/vendor/) ship pre-built CJS bundles + native
+  # argon2 prebuilds for every supported platform. The bundles inline
+  # enough random-shaped lookup tables that gitleaks' entropy detector
+  # trips on them every run. The framework's own SECURITY.md + manifest
+  # already cover provenance for these bytes — gitleaks adding noise on
+  # top isn't a useful signal.
+  '''lib/vendor/.*''',
+  # Test fixtures: tests embed deterministic test keys (vault/audit/
+  # webhook signing) for round-trip exercises. They're plainly named
+  # `test-*` / `fixture-*` and never reach prod.
+  '''test/.*\.test\.js''',
+  '''test/00-primitives\.js''',
+  '''test/40-consumers\.js''',
+  '''test/50-integration\.js''',
+  '''test/smoke\.js''',
+  '''test/helpers/.*''',
+  # Exploit corpora are deliberately-crafted hostile inputs (JWT
+  # algorithm-confusion, kid-traversal, etc.) used by the guard test
+  # suite. The strings are public-domain attack samples, not secrets.
+  '''test/fixtures/.*''',
+  # Wiki seeders embed example tokens / secrets in code blocks for
+  # documentation purposes (e.g. "WIKI_WEBHOOK_SECRET=hunter2-pad-pad").
+  # Each example is operator-readable and obviously fake.
+  '''examples/wiki/seeders/.*''',
+  # Reference SBOM file (committed alongside the package) carries the
+  # vendored package versions, not credentials.
+  '''sbom\.json''',
+]
+
+[[allowlists]]
+description = "Doc-string credential-shaped placeholders"
+# Patterns that match operator-facing docs; real credentials don't ship
+# there. BEARER token templates, hunter2-style example passphrases,
+# the wiki validator's deterministic test JWT secret.
+regexes = [
+  '''Authorization: Bearer <[A-Za-z0-9_-]+>''',
+  '''hunter2-?pass-?[A-Za-z0-9-]+''',
+  '''wiki-validator-jwt-secret''',
+  '''blamejs-(?:wiki-validator-|test-)?passphrase[A-Za-z0-9-]*''',
+  # JWT compact-serialization shape — base64url `eyJ...` header (decodes
+  # to `{"...`), then dot, then base64url payload + dot + base64url
+  # signature. Documentation and test fixtures legitimately embed JWT-
+  # shaped strings (b.guardJwt + b.guardAuth fixtures, examples in
+  # operator-facing wiki). Real signing keys never appear in compact
+  # serialization shape — they're PEM / DER / PKCS#8.
+  '''eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*''',
+  # Source files split JWT fixtures across multiple string literals
+  # for line-length; gitleaks then sees individual base64url segments.
+  # Match a single `eyJ`-prefixed segment of substantive length to
+  # cover that split-literal shape too.
+  '''eyJ[A-Za-z0-9_-]{20,}''',
+  # KEM-envelope object-literal shapes (`{ privateKey, cipherText }`,
+  # `{ privateKey, x25519PrivateKey }`, etc.) appear in error messages,
+  # CHANGELOG entries, and JSDoc @example blocks documenting the
+  # ML_KEM_768X25519 / ML_KEM_1024 surfaces. The literals are
+  # parameter names, not credentials.
+  '''\{\s*privateKey\s*,\s*[A-Za-z][A-Za-z0-9_]*\s*\}''',
+]
+
+[[allowlists]]
+description = "Camel-case identifier names that trip generic-api-key entropy"
+# Public parameter / property names in the framework's KEM envelope
+# surface (e.g. `x25519PrivateKey`, `mlkemPrivateKey`) score above the
+# generic-api-key entropy threshold (3.7+) because they're long
+# camelCase words with no separators. gitleaks reports the bare
+# identifier as the "secret"; the bracketed destructure-shape regex
+# above doesn't catch that bare-identifier form. Stopwords match the
+# extracted-secret string literally and suppress the finding.
+stopwords = [
+  "x25519PrivateKey",
+  "x25519PublicKey",
+  "mlkemPrivateKey",
+  "mlkemPublicKey",
+]
+
+[[allowlists]]
+description = "Pre-config-landing commits (audited manually) + their fingerprints"
+# Commits made before this config landed predate the secret-scan gate
+# and were already audited manually. Pinning the SHA prevents the new
+# scan from blocking the next push on noise from the old history.
+# Operators rotating real secrets STILL must follow the SECURITY.md
+# breach-response process — the skip is for false-positives only.
+#
+# fingerprints are a finer-grained suppression on top of commits —
+# gitleaks 8.21+ requires at least one of (commits/paths/regexes/
+# stopwords) per block, so we combine the two-level suppression here.
+commits = [
+  # v0.4.x-era smoke.js had ~2500 lines (pre layer-N-* split). The
+  # `redact({ field: "REDACTED" })` line at 2415 trips the jwt rule on
+  # the placeholder string used by b.redact tests.
+  "74e627ea0fea39f06e01fe424a19724bea37aee8",
+  # v0.7.28 CHANGELOG entry documents the ML_KEM_768_X25519 envelope
+  # surface; the `privateKey: mlkemPrivateKey` JS-object-literal in
+  # the doc snippet trips the generic-api-key rule on adjacent
+  # high-entropy content. Plain operator-readable doc text, no real
+  # secret. Allowlist matches the same pattern as the 74e627e entry.
+  "fb91792bfe01e3b90478c5a65cbe71affdfdbdb6",
+  # v0.8.0 commit re-stating the same `{ privateKey, cipherText }`
+  # KEM-envelope shape in CHANGELOG.md + lib/crypto.js error
+  # messages. Parameter-name literal, no credential. The regex
+  # allowlist above catches future occurrences.
+  "1a7fef088f29b531d5d4391af6ea611d17f8c644",
+  # v0.8.49 wiki source-driven migration commit — JSDoc @example
+  # placeholders re-tripped the generic-api-key + stripe-access-token
+  # rules. The text was rewritten the next commit; suppress in history.
+  "a270ae987b83e1497b76aee41480fbc021f6bf9a",
+  # v0.8.50 CI green-up commit — the CHANGELOG entry quoted the
+  # KEM-recipient destructure shape (`{ privateKey, x25519PrivateKey }`)
+  # while explaining the v0.8.49 fix; gitleaks re-flagged the same
+  # token in the documentation prose. The next commit rewrote the
+  # CHANGELOG entry to avoid the literal shape.
+  "959b44bb322e7559ec106a19bb21784a4ba9dc25",
+  # v0.10.0 mail-stack final bundle commit — b.mail.crypto.pgp
+  # @example block carries a `privateKeyPem: "-----BEGIN PRIVATE
+  # KEY----- ..."` doc placeholder. The PEM-framing sentinel trips
+  # the private-key rule; the body is a literal "..." with no
+  # entropy. Documentation, not a key.
+  "37fdff6c56337a6b7e88027025fbf590f7b10b31",
+  # Same `@example` placeholder, now landed on main via the squash-
+  # merge of PR #83 (commit d126fa4). gitleaks scans every commit
+  # SHA the placeholder ever appeared in.
+  "d126fa416043ee7f47d89011951378a06c91a617",
+]
+fingerprints = [
+  "74e627ea0fea39f06e01fe424a19724bea37aee8:test/smoke.js:jwt:2415",
+  "fb91792bfe01e3b90478c5a65cbe71affdfdbdb6:CHANGELOG.md:generic-api-key:11",
+  "1a7fef088f29b531d5d4391af6ea611d17f8c644:CHANGELOG.md:generic-api-key:11",
+  "1a7fef088f29b531d5d4391af6ea611d17f8c644:lib/crypto.js:generic-api-key:375",
+  "1a7fef088f29b531d5d4391af6ea611d17f8c644:lib/crypto.js:generic-api-key:380",
+  # v0.8.49 wiki source-driven migration. JSDoc @example blocks in
+  # lib/api-key.js (fake hex token shape), lib/log-stream.js (Stripe
+  # `sk_live_...` redaction example), and lib/crypto.js (KEM
+  # envelope `{ privateKey, x25519PrivateKey }` shape) tripped the
+  # generic-api-key + stripe-access-token rules. The text was
+  # rewritten in the next commit to use placeholder shapes; the
+  # fingerprints suppress the old shape in the historical commit.
+  "a270ae987b83e1497b76aee41480fbc021f6bf9a:lib/api-key.js:generic-api-key:182",
+  "a270ae987b83e1497b76aee41480fbc021f6bf9a:lib/log-stream.js:stripe-access-token:178",
+  "a270ae987b83e1497b76aee41480fbc021f6bf9a:lib/crypto.js:generic-api-key:1044",
+  "959b44bb322e7559ec106a19bb21784a4ba9dc25:CHANGELOG.md:generic-api-key:11",
+  # v0.10.0 mail-stack final bundle — b.mail.crypto.pgp @intro
+  # @example shows a sign() call with `privateKeyPem: "-----BEGIN
+  # PRIVATE KEY----- ..."` placeholder. The PEM-framing sentinel
+  # trips the private-key rule; the body is a literal "..." with
+  # no entropy. Documentation, not a key.
+  "37fdff6c56337a6b7e88027025fbf590f7b10b31:lib/mail-crypto-pgp.js:private-key:76",
+]

package/lib/vendor/blamejs/.hadolint.yaml

@@ -0,0 +1,18 @@
+# Hadolint config — strict by default, with a small set of explicit
+# exceptions for patterns we use intentionally.
+
+failure-threshold: warning
+
+# Trust the Chainguard registry for base images (its tag immutability
+# is stronger than tag pinning for most operators).
+trustedRegistries:
+  - cgr.dev
+  - docker.io
+  - ghcr.io
+
+ignored:
+  # DL3007 (always tag the version) — Chainguard's :latest follows
+  # weekly rebuilds and IS the recommended tag for security updates.
+  # We accept the trade-off and bump the digest pin in lockstep with
+  # release-container.yml when it's pinned at the workflow layer.
+  - DL3007

package/lib/vendor/blamejs/.npmrc

@@ -0,0 +1,5 @@
+save-exact=true
+engine-strict=true
+package-lock=true
+fund=false
+audit=false

package/lib/vendor/blamejs/.pinact.yaml

@@ -0,0 +1,17 @@
+# pinact configuration — refuses any tag-shaped `uses:` reference EXCEPT
+# the documented exception below.
+#
+# The single exception is the SLSA reusable workflow. SLSA's internal
+# builder-fetch step refuses non-tag `BUILDER_REF` values ("Invalid ref:
+# <40-hex>. Expected ref of the form refs/tags/vX.Y.Z"), so the call
+# MUST be tag-pinned. Mitigated by slsa-framework's upstream tag-
+# protection + immutable-release rules. Same suppression also appears
+# as a per-line `# allow:slsa-framework-action-not-sha-pinned` marker in
+# `.github/workflows/npm-publish.yml` for the codebase-patterns gate.
+#
+# See npm-publish.yml comment block + memory/specs/release-v0.10.19-plan.md.
+
+version: 3
+
+ignore_actions:
+  - name: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml

package/lib/vendor/blamejs/ARCHITECTURE.md

@@ -0,0 +1,158 @@
+# blamejs architecture
+
+A new contributor's guide to where things live and why. The repository tree at `git ls-tree -r HEAD --name-only | wc -l` is north of 800 files; this doc is the orientation map.
+
+## Top-level layout
+
+```
+blamejs/
+├── bin/              # `blamejs` CLI entry shim → lib/cli.js
+├── index.js          # Single npm export — `var b = require("@blamejs/core")`
+├── lib/              # Framework source (the SHIPPED code)
+│   ├── vendor/       # Vendored crypto + utility libraries (no npm runtime deps)
+│   ├── middleware/   # HTTP middleware primitives
+│   ├── auth/         # Auth-flow primitives (password, passkey, OAuth, JWT, TOTP)
+│   ├── parsers/      # Safe-by-default config parsers (yaml, toml, json, schema)
+│   ├── object-store/ # S3/Azure/local object-store backends
+│   ├── vault/        # Vault keypair management + passphrase ops
+│   ├── backup/       # Backup bundle creation
+│   └── *.js          # Top-level primitives (one .js per primitive)
+├── examples/wiki/    # Reference operator-built app (lives at blamejs.com)
+├── test/             # Layered tests (smoke runner walks every layer)
+│   ├── layer-0-primitives/
+│   ├── layer-1-state/
+│   ├── 30-chain.js etc.  # Layer 2/3 integration tests
+│   └── helpers/      # Shared test fixtures + capture helpers
+├── scripts/          # Vendor-update + sync-to-public + audit-history tooling
+├── .github/          # CI + release-container workflows + issue templates
+└── *.md              # README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, ARCHITECTURE
+```
+
+## Single export, named primitives
+
+Operators consume the framework via one `require()`:
+
+```js
+var b = require("@blamejs/core");
+
+await b.createApp({...});       // app boot
+b.audit.safeEmit({...});         // audit chain
+var keys = b.apiKey.create({...}); // primitive instances
+```
+
+Every primitive is namespaced under `b.X`. `index.js` is the canonical export list — when adding a new primitive, register it there in alphabetical order (within its group: Crypto / Storage / Audit / HTTP / Observability / Auth / etc.). The grep is `git grep "var X =" index.js` to find similar entries.
+
+## Where each concern lives
+
+| Concern | Primary file(s) | Tests |
+|---|---|---|
+| App boot orchestration | `lib/app.js` | `test/layer-3-*` |
+| HTTP router | `lib/router.js` | `test/30-chain.js`, `test/00-primitives.js` |
+| Middleware (CORS, CSRF, rate-limit, body parsing, etc.) | `lib/middleware/*.js` | `test/layer-0-primitives/*.test.js` |
+| Vault (PQC keypair, sealed/wrapped) | `lib/vault/index.js` + `lib/vault/wrap.js` + `lib/vault/passphrase-ops.js` | `test/layer-1-state/vault*.test.js` |
+| Sealed-column DB | `lib/db.js` + `lib/crypto-field.js` | `test/layer-1-state/sealed-fields*.test.js` |
+| Audit chain | `lib/audit.js` + `lib/audit-chain.js` + `lib/audit-sign.js` + `lib/chain-writer.js` | `test/30-chain.js` |
+| API keys | `lib/api-key.js` | `test/layer-0-primitives/api-key*.test.js` |
+| Permissions (RBAC) | `lib/permissions.js` | `test/00-primitives.js` |
+| Sessions | `lib/session.js` + `lib/middleware/attach-user.js` | `test/layer-1-state/session*.test.js` |
+| Mail / notify / webhook | `lib/mail.js` + `lib/notify.js` + `lib/webhook.js` | `test/00-primitives.js` |
+| i18n | `lib/i18n.js` + `lib/middleware/i18n-mw.js` (folded into i18n.js) | `test/00-primitives.js` |
+| Cluster mode + external DB | `lib/cluster.js` + `lib/external-db.js` + `lib/cluster-storage.js` | `test/30-chain.js` |
+| Backup / restore | `lib/backup/index.js` + `lib/restore.js` + `lib/restore-bundle.js` | `test/00-primitives.js` |
+| Templates | `lib/template.js` (eval-free interpreter) | `test/00-primitives.js` |
+| Logging / metrics / tracing | `lib/log.js` + `lib/metrics.js` + `lib/tracing.js` + `lib/observability.js` | `test/00-primitives.js` |
+| CLI | `lib/cli.js` (dispatch) + `lib/cli-helpers.js` (shared headless-app + reporter) | `test/layer-0-primitives/cli-*.test.js` |
+| Wiki example app | `examples/wiki/server.js` + `examples/wiki/lib/build-app.js` + `examples/wiki/routes/*.js` + `examples/wiki/views/*.html` | `examples/wiki/test/e2e.js` |
+| Outbound HTTP + SSRF gate | `lib/http-client.js` + `lib/ssrf-guard.js` + `lib/safe-url.js` | `test/layer-0-primitives/http-client-*.test.js` + `test/layer-0-primitives/ssrf-guard*.test.js` |
+| Outbound WebSocket client | `lib/ws-client.js` | `test/layer-0-primitives/ws-client*.test.js` |
+| Network configurability (NTP/NTS/DNS/proxy/CA) | `lib/network/*.js` | `test/layer-0-primitives/network-*.test.js` |
+| Object store + bucket-ops + Object Lock | `lib/object-store/*.js` | `test/layer-1-state/object-store*.test.js` |
+| Outbox / inbox (exactly-once) | `lib/outbox.js` + `lib/inbox.js` | `test/layer-1-state/outbox-inbox*.test.js` |
+| Content-safety guards (`b.guard*`) | `lib/guard-*.js` + `lib/gate-contract.js` + `lib/codepoint-class.js` | `test/layer-0-primitives/guard-*.test.js` + `test/layer-5-integration/guard-host-integration.test.js` |
+| Compliance regimes | `lib/compliance.js` + `lib/dora.js` + `lib/dsr.js` + `lib/cra-report.js` + `lib/nis2-report.js` + `lib/sec-cyber.js` + `lib/fapi2.js` + `lib/fdx.js` + `lib/tcpa-10dlc.js` + `lib/iab-tcf.js` + `lib/iab-mspa.js` + `lib/incident-report.js` | per-regime tests under `test/layer-0-primitives/` |
+| MCP / GraphQL Federation / A2A guards | `lib/mcp.js` + `lib/graphql-federation.js` + `lib/a2a.js` | `test/layer-0-primitives/mcp*.test.js` + similar |
+| Honeytoken / forensic snapshot / config drift | `lib/honeytoken.js` + `lib/audit-tools.js` (`forensicSnapshot`) + `lib/config-drift.js` (`verifyVendorIntegrity`) | `test/layer-0-primitives/honeytoken*.test.js` + `test/layer-0-primitives/config-drift*.test.js` |
+| Account-takeover kill-switch | `lib/auth/ato-kill-switch.js` | `test/layer-0-primitives/ato-kill-switch*.test.js` |
+| Content credentials (C2PA / SB-942) | `lib/content-credentials.js` | `test/layer-0-primitives/content-credentials*.test.js` |
+| Events bus + CloudEvents | `lib/events.js` + `lib/cloud-events.js` | `test/layer-0-primitives/events*.test.js` |
+| Feature flags (OpenFeature) | `lib/flag.js` + `lib/middleware/flag-context.js` | `test/layer-0-primitives/flag*.test.js` |
+| File-upload chunking + filename safety | `lib/file-upload.js` + `lib/guard-filename.js` | `test/layer-1-state/file-upload*.test.js` |
+
+## Boot order
+
+`b.createApp({...})` orchestrates a strict dependency-ordered boot. Skipping or reordering breaks invariants downstream.
+
+1. **Vault** — keypair loaded (or generated on first run). Sealed columns + audit chain + signed checkpoints all depend on the vault key being available.
+2. **External DB** (cluster mode only) — if `opts.externalDb` is set, init the cluster's durable backend.
+3. **Cluster lease** — if `opts.cluster` is set, acquire the leader lease before touching any framework schema.
+4. **Framework schema** — `_blamejs_audit_log`, `_blamejs_audit_checkpoints`, `_blamejs_sessions`, `_blamejs_api_keys`, `_blamejs_consent_log`, etc. created if absent (idempotent).
+5. **Local DB** — open the sqlite file (or in-memory tmpfs handle in encrypted-at-rest mode).
+6. **Router + middleware stack** — request-id → securityHeaders → botGuard → cors → fetchMetadata → networkAllowlist (when wired) → rateLimit → dailyByteQuota → cspNonce → cookies → bodyParser → compression → attachUser → dbRoleFor (when wired) → csrfProtect → traceLogCorrelation → spanHttpServer → cspReport (route-mounted) → health. Operator-mounted variants: `requireAuth` / `requireAal` / `requireMtls` / `requireStepUp` / `requireBoundKey` / `bearerAuth` / `dpop` / `hostAllowlist` / `requireMethods` / `requireContentType` / `gpc` / `errorHandler`.
+7. **Operator routes** — the `routes: function (router) {...}` callback runs. Operator wires their own routes on top of the middleware stack.
+8. **Error handler** — last so it catches everything from operator routes and middleware.
+
+`app.shutdown()` reverses the order.
+
+## Audit-everything posture
+
+Every operator action emits to the audit chain. The framework primitives self-emit (e.g., `apiKey.issue` → `apikey.issue`); operators emit their own via `audit.safeEmit({ action: "wiki.page.edited", ... })`. The shape is the 5 W's (WHO/WHAT/WHEN/WHERE/HOW) — the framework derives most of it from the request via `b.requestHelpers.extractActorContext(req)`.
+
+A new namespace must be registered before first emission:
+
+```js
+b.audit.registerNamespace("myapp"); // call once at app bootstrap
+```
+
+The framework's own namespaces are pre-registered in `lib/audit.js` — read `FRAMEWORK_NAMESPACES` for the live set with per-name sub-event documentation. The smoke test `test/layer-0-primitives/audit-framework-namespaces.test.js` walks `lib/` for emission patterns and fails CI on any missing registration.
+
+## Crypto envelope versioning
+
+Every encrypted blob starts with a 4-byte header identifying KEM / cipher / KDF. `b.crypto.decrypt` dispatches on the header bytes, not on a guess at the active default — old blobs continue reading after the active algorithm rolls forward.
+
+To add a new algorithm (HQC when standardized, etc.):
+
+1. Assign the next ID in `lib/crypto.js`'s `KEM` / `CIPHER` / `KDF` constants
+2. Implement the encrypt/decrypt path in `lib/crypto.js`
+3. Set the `ACTIVE_*` constant for new writes
+4. Keep the old ID's decrypt case in place — back-compat is mandatory
+5. Vendor the upstream library via `scripts/vendor-update.sh`
+
+The same pattern works for new ciphers and KDFs.
+
+## Vendoring policy
+
+Zero npm runtime dependencies. `lib/vendor/` holds bundled third-party libraries with their license + version + provenance manifest at `lib/vendor/MANIFEST.json`. The vendor-update script (`scripts/vendor-update.sh`) does:
+
+1. `npm install <pkg> [@version]` (in a scratch dir)
+2. esbuild bundle to `lib/vendor/<name>.cjs` (server) and `public/js/<name>.js` (browser, where applicable)
+3. Copy + update MANIFEST.json
+4. Remove the npm install (no `node_modules` dep persists)
+
+For the noble-* libraries (ESM-only upstream), there's a manual ESM→CJS conversion step in the script — see `scripts/vendor-update.sh` for the exact handling.
+
+## Tests
+
+The smoke target (`node test/smoke.js`) is the single entry point that walks all four layers in order:
+
+- **Layer 0 — Primitives** (`test/layer-0-primitives/`): pure-function primitives. No DB, no network, no vault.
+- **Layer 1 — State** (`test/layer-1-state/`): primitives that touch the DB or vault. Spin up an isolated data dir per test.
+- **Layer 2 — Composition** (`test/00-primitives.js` + others): middleware composition + framework integration.
+- **Layer 3 — End-to-end** (`test/30-chain.js`, `test/50-integration.js`): full framework boot scenarios including cluster mode + external DB.
+
+A new framework primitive lands with at least Layer 0 tests. New middleware lands with Layer 2. New CLI subcommand lands with `test/layer-0-primitives/cli-X.test.js` (see `cli-vault.test.js`, `cli-backup.test.js`, `cli-api-key.test.js` for the established shape — they boot a real headless app instance via `b.cliHelpers.bootApp` and round-trip operations through the CLI dispatcher).
+
+The wiki example app has its own e2e at `examples/wiki/test/e2e.js` — boots the wiki on an ephemeral port, hits every authenticated and public route via `node:http`, asserts the rendered output. Operators forking the framework should keep their own equivalent.
+
+## Where to read first
+
+If you're new to the codebase and want to understand how it fits together, read in this order:
+
+1. `index.js` — the single export surface
+2. `lib/app.js` `createApp()` — the boot orchestration
+3. `lib/audit.js` — the audit chain shape (most other primitives emit through this)
+4. `lib/crypto.js` — envelope versioning + active algorithms
+5. `lib/middleware/csrf-protect.js` — a representative middleware (cookie-mode + boot-time validation + `req.X` exposure)
+6. `lib/cli.js` + `lib/cli-helpers.js` — the CLI dispatch + headless-app pattern
+7. `examples/wiki/lib/build-app.js` — what an operator-built app looks like
+
+This isn't a complete tour — it's enough orientation to start contributing meaningfully without spelunking every primitive.