@blamejs/blamejs-shop 0.0.44

package/lib/theme.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * @module shop.theme
+ * @title  Theme — file-backed templates with fallback resolution
+ *
+ * @intro
+ *   Operators ship a custom storefront look without forking
+ *   `lib/storefront.js`. The theme primitive defines a directory
+ *   layout under `themes/<name>/` and a fallback chain so a partial
+ *   override is enough — any view not present in the active theme
+ *   falls back to the bundled `themes/default/` set.
+ *
+ *   Composition: each theme owns one `b.template` engine instance
+ *   bound to its own directory. `render(viewName, data)` tries the
+ *   active engine first; a missing-view error transparently falls
+ *   back to the default engine. Both engines run with strict HTML
+ *   escape on `{{ expr }}` and raw passthrough on `{{{ expr }}}`.
+ *
+ *   View names + theme names are slug-shaped (`^[a-z0-9][a-z0-9-]{0,63}$`)
+ *   so request-derived input that reaches `render()` can't path-
+ *   traverse out of `themesDir`. The underlying `b.template` engine
+ *   also rejects `..` and NUL inside view names as defense in depth.
+ *
+ *   Asset URLs: `assetUrl("css/main.css")` resolves to
+ *   `/assets/themes/<name>/css/main.css`. Operators upload theme
+ *   assets to R2 under the same prefix; the Worker's static asset
+ *   pass-through serves them. Theme HTML references assets via this
+ *   helper so a theme swap relocates URLs automatically.
+ *
+ *   When the active theme directory is missing entirely (typo in
+ *   `SHOP_THEME`, undeployed theme), `create()` throws `ThemeError`
+ *   at boot time — operators don't ship a broken storefront.
+ */
+
+// `b.template.create({ viewsDir })` itself validates that the views
+// directory exists, refuses `..` / NUL inside view names, and throws
+// "template: view not found: <name>" when a render() call lands on a
+// missing file. The theme primitive composes on that surface — we
+// catch the missing-view throw and walk the fallback chain rather
+// than duplicating an `fs.existsSync` check in this layer.
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+var SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var MISSING_VIEW_RE = /template: view not found:/;
+
+function ThemeError(message) {
+  var e = new Error(message);
+  e.name = "ThemeError";
+  return e;
+}
+
+function _validateSlug(label, value) {
+  if (typeof value !== "string" || !SLUG_RE.test(value)) {
+    throw ThemeError("theme: " + label + " must match /^[a-z0-9][a-z0-9-]{0,63}$/, got " + JSON.stringify(value));
+  }
+}
+
+function _joinPath(parent, child) {
+  // Trim trailing separator on parent so the join yields a single sep.
+  var p = parent;
+  while (p.length > 0 && (p.charAt(p.length - 1) === "/" || p.charAt(p.length - 1) === "\\")) {
+    p = p.slice(0, p.length - 1);
+  }
+  return p + "/" + child;
+}
+
+function _tryCreateEngine(viewsDir) {
+  // Wrap b.template.create — when the directory is missing it throws
+  // "template: viewsDir does not exist: <path>". We convert that to
+  // ThemeError so the caller's contract is one error type.
+  try {
+    return _b().template.create({ viewsDir: viewsDir });
+  } catch (e) {
+    var msg = e && e.message || "";
+    if (msg.indexOf("viewsDir does not exist") !== -1) {
+      throw ThemeError("theme.create: theme directory not found: " + viewsDir);
+    }
+    throw e;
+  }
+}
+
+/**
+ * @primitive shop.theme.create
+ * @signature shop.theme.create(opts)
+ * @since     0.0.32
+ *
+ * Builds a theme loader bound to `<themesDir>/<name>` with a fallback
+ * engine bound to `<themesDir>/<fallback>` (default "default"). The
+ * returned object exposes `render(viewName, data)`, `exists(viewName)`,
+ * and `assetUrl(path)`.
+ *
+ * View lookup walks the active theme first, then the fallback chain.
+ * A view present in neither throws `ThemeError`. The fallback theme's
+ * directory MUST exist — the bundled `themes/default/` is the
+ * baseline reference set the storefront expects to find.
+ *
+ * @opts
+ *   themesDir:   string,   // required — parent directory of theme dirs
+ *   name:        string,   // required — active theme slug
+ *   fallback:    string,   // optional, default "default"
+ *
+ * @example
+ *   var theme = shop.theme.create({
+ *     themesDir: "./themes",
+ *     name:      "acme",
+ *   });
+ *   var html = theme.render("home", { products: [...] });
+ *   theme.assetUrl("css/main.css");
+ *   // → "/assets/themes/acme/css/main.css"
+ */
+function create(opts) {
+  opts = opts || {};
+  if (!opts.themesDir || typeof opts.themesDir !== "string") {
+    throw ThemeError("theme.create: opts.themesDir required (string)");
+  }
+  _validateSlug("name", opts.name);
+  var fallbackName = opts.fallback == null ? "default" : opts.fallback;
+  _validateSlug("fallback", fallbackName);
+
+  var activeDir   = _joinPath(opts.themesDir, opts.name);
+  var fallbackDir = _joinPath(opts.themesDir, fallbackName);
+
+  // _tryCreateEngine surfaces missing-directory as ThemeError; both
+  // calls run at create time so an operator with a typo in SHOP_THEME
+  // (or an undeployed theme dir) fails the boot rather than the first
+  // customer request.
+  var activeEngine = _tryCreateEngine(activeDir);
+  var fallbackEngine = activeDir === fallbackDir
+    ? activeEngine
+    : _tryCreateEngine(fallbackDir);
+
+  function _isMissingView(err) {
+    return err && err.message && MISSING_VIEW_RE.test(err.message);
+  }
+
+  function exists(viewName) {
+    _validateSlug("viewName", viewName);
+    // Compile through the engine; cache hit on the second call. A
+    // missing-view error is converted to "false"; any other error
+    // (template syntax) propagates so operators see real bugs.
+    try { activeEngine.compile(viewName);   return true; }
+    catch (e) { if (!_isMissingView(e)) throw e; }
+    if (fallbackEngine === activeEngine) return false;
+    try { fallbackEngine.compile(viewName); return true; }
+    catch (e) { if (!_isMissingView(e)) throw e; return false; }
+  }
+
+  function render(viewName, data) {
+    _validateSlug("viewName", viewName);
+    try { return activeEngine.render(viewName, data || {}); }
+    catch (e) {
+      if (!_isMissingView(e)) throw e;
+    }
+    if (fallbackEngine === activeEngine) {
+      throw ThemeError("theme.render: view not found in '" + opts.name + "': " + viewName);
+    }
+    try { return fallbackEngine.render(viewName, data || {}); }
+    catch (e) {
+      if (_isMissingView(e)) {
+        throw ThemeError("theme.render: view not found in '" + opts.name +
+          "' or fallback '" + fallbackName + "': " + viewName);
+      }
+      throw e;
+    }
+  }
+
+  function assetUrl(p) {
+    if (typeof p !== "string" || p.length === 0) {
+      throw ThemeError("theme.assetUrl: path required (non-empty string)");
+    }
+    if (p.indexOf("..") !== -1 || p.indexOf("\0") !== -1) {
+      throw ThemeError("theme.assetUrl: path contains forbidden character: " + JSON.stringify(p));
+    }
+    var clean = p.charAt(0) === "/" ? p.slice(1) : p;
+    return "/assets/themes/" + opts.name + "/" + clean;
+  }
+
+  return {
+    name:       opts.name,
+    fallback:   fallbackName,
+    render:     render,
+    exists:     exists,
+    assetUrl:   assetUrl,
+  };
+}
+
+module.exports = {
+  create:     create,
+  ThemeError: ThemeError,
+};

package/lib/vendor/MANIFEST.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "Vendored dependencies — no npm runtime packages. Use `scripts/vendor-update.sh blamejs <tag>` to update.",
+  "_about": "blamejs.shop vendors a single framework — blamejs — which itself bundles every server-side crypto/identity dependency. The transitive packages blamejs ships are surfaced in its own MANIFEST.json at lib/vendor/blamejs/lib/vendor/MANIFEST.json — Trivy / Grype rely on that nested data for CVE attribution.",
+  "packages": {
+    "blamejs": {
+      "version": "0.12.2",
+      "tag": "v0.12.2",
+      "license": "Apache-2.0",
+      "author": "blamejs contributors",
+      "source": "https://github.com/blamejs/blamejs",
+      "_about": "The Node framework blamejs.shop builds on. Vendored as a shallow git clone of the release tag at lib/vendor/blamejs/. Run `npm run vendor blamejs <vX.Y.Z>` to refresh.",
+      "files": {
+        "server": "lib/vendor/blamejs/"
+      },
+      "bundler": "shallow git clone of release tag from github.com/blamejs/blamejs",
+      "bundledAt": "2026-05-22"
+    }
+  }
+}

package/lib/vendor/blamejs/.clusterfuzzlite/Dockerfile

@@ -0,0 +1,23 @@
+# ClusterFuzzLite build image for blamejs.
+#
+# Inherits from oss-fuzz's JavaScript base-builder (jazzer.js +
+# libFuzzer + the compile_javascript_fuzzer helper pre-installed).
+# Copy the framework source + harnesses, then build.sh wires each
+# fuzz target into a libFuzzer-shaped runnable.
+#
+# ClusterFuzzLite consumes this same Dockerfile for the PR + batch
+# fuzz workflows (`.github/workflows/cflite_*.yml`). OSS-Fuzz upstream
+# uses the project-specific Dockerfile under `oss-fuzz/projects/blamejs/`
+# which mirrors this shape — keep them in sync.
+
+FROM gcr.io/oss-fuzz-base/base-builder-javascript
+
+# Copy the framework source. ClusterFuzzLite mounts the repo at
+# $SRC/blamejs, so we COPY everything (including fuzz/) into one
+# place under $SRC.
+COPY . $SRC/blamejs
+
+# Build script wires `compile_javascript_fuzzer` for each harness.
+COPY .clusterfuzzlite/build.sh $SRC/
+
+WORKDIR $SRC/blamejs

package/lib/vendor/blamejs/.clusterfuzzlite/build.sh

@@ -0,0 +1,34 @@
+#!/bin/bash -eu
+#
+# ClusterFuzzLite / OSS-Fuzz build script for blamejs.
+#
+# Wires every `fuzz/<name>.fuzz.js` harness into a libFuzzer-shaped
+# runnable via the base-builder-javascript image's
+# `compile_javascript_fuzzer` helper. The matching
+# `fuzz/<name>_seed_corpus/` directory is zipped into the seed
+# corpus the engine bootstraps from.
+#
+# Local debug:
+#   docker run -it -v "$PWD:/src/blamejs" gcr.io/oss-fuzz-base/base-builder-javascript
+#   cd /src/blamejs && bash .clusterfuzzlite/build.sh
+
+cd "$SRC/blamejs"
+
+# Stage every harness into $OUT/<base>. compile_javascript_fuzzer
+# resolves the module via Node's normal resolution from the repo
+# root, so `require("..")` in each harness picks up the framework
+# entry-point.
+for fuzzer in fuzz/*.fuzz.js; do
+  base=$(basename "$fuzzer" .fuzz.js)
+  echo "[blamejs build] compiling $base"
+  compile_javascript_fuzzer blamejs "$fuzzer" --sync
+
+  # Zip the seed corpus if it exists.
+  seed_dir="fuzz/${base}_seed_corpus"
+  if [ -d "$seed_dir" ]; then
+    echo "[blamejs build] packaging seed corpus for $base"
+    ( cd "$seed_dir" && zip -q -r "$OUT/${base}_seed_corpus.zip" . )
+  fi
+done
+
+echo "[blamejs build] done — $(find "$OUT" -mindepth 1 -maxdepth 1 | wc -l) artifacts in \$OUT"

package/lib/vendor/blamejs/.clusterfuzzlite/project.yaml

@@ -0,0 +1,16 @@
+# ClusterFuzzLite project config.
+#
+# Consumed by `google/clusterfuzzlite/actions/build_fuzzers` and
+# `run_fuzzers` (see `.github/workflows/cflite_*.yml`).
+#
+# The OSS-Fuzz upstream project config under
+# `oss-fuzz/projects/blamejs/project.yaml` mirrors this — keep them
+# in sync.
+
+language: javascript
+fuzzing_engines:
+  - libfuzzer
+sanitizers:
+  - none   # jazzer.js is pure-JS; libFuzzer drives mutation without a native sanitizer
+homepage: "https://blamejs.com"
+main_repo: "https://github.com/blamejs/blamejs"

package/lib/vendor/blamejs/.dockerignore

@@ -0,0 +1,45 @@
+.git
+.github
+.gitignore
+.gitattributes
+
+# Local editor / OS scratch
+.vscode
+.idea
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Dependency / build output (rebuilt inside the image)
+node_modules
+**/node_modules
+**/dist
+**/build
+**/coverage
+
+# Per-app runtime state — never bake into an image
+**/data
+**/data-e2e
+**/public/dist
+
+# Test fixtures, lockfiles for the wiki example, large reproducibles
+test
+**/test
+*.log
+*.pid
+*.pid.lock
+
+# Credential / secret material — defense in depth
+*.pem
+*.key
+*.crt
+*.cert
+*.p12
+*.pfx
+secrets.json
+credentials.json
+
+# Backup / patch artifacts
+*.bak
+*.orig
+*.rej

package/lib/vendor/blamejs/.gitattributes

@@ -0,0 +1,42 @@
+# Vendored dependencies — treat as binary so git never rewrites line
+# endings between Windows and Linux checkouts. The framework's vendor
+# manifest pins SHA-256 hashes on the on-disk content; CRLF/LF
+# conversion would break the hash on the off-platform checkout.
+lib/vendor/** -text binary
+
+# Shell scripts MUST stay LF — they run inside Linux containers
+# (OSS-Fuzz base-builder, ClusterFuzzLite, the wiki / release
+# container Dockerfiles, npm-publish build steps) where bash chokes
+# on CRLF with "$'\r': command not found". Without this rule, a
+# Windows checkout's CRLF rewrite ships into the Docker copy + the
+# script fails at line 1.
+*.sh text eol=lf
+
+# Derived artifacts the release-notes generator owns end-to-end —
+# rebuild emits LF, so the on-disk file is pinned to LF on every
+# platform. Without this, Windows checkouts would get CRLF and the
+# generator's `--check` drift-gate in smoke would need to keep
+# eating the cost of normalizing both sides before comparing.
+CHANGELOG.md text eol=lf
+release-notes/*.json text eol=lf
+
+# Native modules — always binary.
+*.node binary
+*.so binary
+*.dylib binary
+*.dll binary
+*.a binary
+*.glibc binary
+*.musl binary
+
+# Standard binary types.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.zip binary
+*.gz binary
+*.tar binary
+*.tgz binary
+*.pdf binary

package/lib/vendor/blamejs/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Auto-routes review requests when PRs touch matching paths.
+# Order matters: later patterns override earlier ones.
+
+*   @dotCooCoo

package/lib/vendor/blamejs/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: dotCooCoo
+ko_fi: dotcoocoo

package/lib/vendor/blamejs/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,58 @@
+---
+name: Bug report
+about: Report a defect in the framework or wiki example app
+title: ''
+labels: bug
+assignees: ''
+---
+
+<!--
+Security bug? Don't file here — see SECURITY.md for the disclosure
+process. Public issues are for non-security defects.
+
+Before filing: search existing issues to avoid duplicates.
+-->
+
+## What happened
+
+<!-- One or two sentences. What did the framework do that you didn't expect. -->
+
+## What you expected
+
+## How to reproduce
+
+<!-- Minimal repro. Code snippet preferred over prose. -->
+
+```js
+// minimal repro
+```
+
+Or, for CLI / runtime bugs, the full command + flags:
+
+```bash
+blamejs <subcommand> --flag value
+```
+
+## Environment
+
+- blamejs version: `v0.X.Y` (or main `<sha>`)
+- Node.js version: `node --version`
+- OS: `uname -a` or Windows version
+- Vault mode (if relevant): `plaintext` / `wrapped`
+- DB mode (if relevant): `plain` / `encrypted`
+
+## Logs / output
+
+<details><summary>Click to expand</summary>
+
+```
+paste relevant log lines or error stack traces here
+```
+
+</details>
+
+## What you've already tried
+
+<!-- Helpful for ruling out duplicates / known interactions. -->
+
+## Additional context

package/lib/vendor/blamejs/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/blamejs/blamejs/security/advisories/new
+    about: Report a security vulnerability privately. See SECURITY.md for the disclosure policy + response time SLA.
+  - name: Question or general discussion
+    url: https://github.com/blamejs/blamejs/discussions
+    about: For questions, design discussions, or feature ideas you want to socialize before opening a feature-request issue.

package/lib/vendor/blamejs/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,99 @@
+---
+name: Feature request
+about: Propose a new framework primitive, CLI subcommand, or operator-facing capability
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+<!--
+Per CONTRIBUTING.md → "Ship complete, not incremental": every framework
+primitive lands with the full operator-facing scope, not "minimum viable
+with key features deferred." File the issue first to discuss scope before
+opening a PR; it saves a round of rework.
+-->
+
+## Problem
+
+<!-- What operator pain are you solving? Concrete scenario preferred over abstract. -->
+
+## Proposed primitive / surface
+
+<!-- What does the operator's API look like? Show the call site as you imagine it. -->
+
+```js
+// Imagined usage
+var foo = b.foo.create({
+  ...
+});
+await foo.doThing(...);
+```
+
+If it's a CLI subcommand, the imagined invocation:
+
+```bash
+blamejs foo do-thing --flag value
+```
+
+## Initial-release scope
+
+What's IN the first shipped version:
+-
+
+What's explicitly OUT (and why each "out" is a complete decision, not a deferred bullet):
+-
+
+## Configuration surface
+
+<!-- Which opts keys does the new primitive's create() accept? -->
+
+```
+allowedKeys: [
+  "name",
+  "audit",
+  ...
+]
+```
+
+## Failure modes
+
+<!-- Pick the input-validation policy consciously per call site:
+
+  - Boot-time / config-time inputs:  THROW with a clear error code so
+    operators see the typo at boot, not at first request.
+  - Hot-path observability sinks (audit / metrics / events):  DROP
+    SILENT — these must never crash the request that triggered them.
+  - Request-shape readers (request helpers, defensive parsers):
+    RETURN DEFAULTS for missing / non-string input — the network sends
+    what it sends; rejecting at the read site moves errors out of band.
+-->
+
+- Bad opts at `create()` → throw with code
+- Hot-path sink failure → drop silent
+- Bad request-shape input → return default
+
+## Crypto / audit / security implications
+
+<!-- Does this primitive touch the vault / sealed columns / audit chain? -->
+
+- [ ] No crypto state involved
+- [ ] Reads sealed columns (uses `b.cryptoField` automatically)
+- [ ] Writes new sealed-by-default schema (declares `sealedFields` in the collection definition)
+- [ ] Emits audit events (which namespace? does it need `audit.registerNamespace`?)
+- [ ] Adds a new envelope-versioned algorithm (which ID? back-compat with old data?)
+
+## Operator-facing surface
+
+<!-- Where does this show up for operators? -->
+
+- [ ] Wiki seeded docs updated (which concern group?)
+- [ ] DEPLOY.md env vars updated
+- [ ] CLI subcommand
+- [ ] Admin UI demo in the wiki
+- [ ] None — internal-only primitive
+
+## Alternatives considered
+
+<!-- What did you rule out and why. Saves the reviewer asking. -->
+
+## Additional context

package/lib/vendor/blamejs/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,77 @@
+<!--
+Thanks for the PR! Fill in the sections below. The Lint summary CI
+check is required to pass before merge — local pre-flight:
+
+  node test/smoke.js
+  cd examples/wiki && rm -rf data data-e2e && node test/e2e.js
+  npx eslint@latest --max-warnings 0 .
+
+See CONTRIBUTING.md for the full PR loop + house rules. Security-
+sensitive patches: don't open here, see SECURITY.md.
+-->
+
+## Summary
+
+<!-- One or two sentences. What does this change and why. -->
+
+## Type of change
+
+<!-- Check all that apply -->
+
+- [ ] Bug fix (no API change)
+- [ ] New framework primitive
+- [ ] New CLI subcommand
+- [ ] Wiki / docs / DEPLOY.md update
+- [ ] Vendored dep refresh
+- [ ] Test coverage / CI improvement
+- [ ] Refactor (no behavior change)
+- [ ] Other:
+
+## Linked issue
+
+<!-- Required for non-trivial changes. See CONTRIBUTING.md → "The PR loop" → step 1. -->
+
+Closes #
+
+## House rules checklist
+
+<!-- See CONTRIBUTING.md → "House rules". -->
+
+- [ ] No new npm runtime dependencies (vendored via `scripts/vendor-update.sh` if a new external library was needed)
+- [ ] All crypto operations use the framework's PQC stack (no SHA-256 / AES-GCM / P-256-only / Ed25519-outside-hybrid)
+- [ ] New audit-emitting code registers its namespace via `audit.registerNamespace`
+- [ ] CommonJS / `var` / no TypeScript / no transpilation
+- [ ] Used framework primitives (`C.TIME.*`, `C.BYTES.*`, `timingSafeEqual`, `b.validateOpts`, etc.) instead of raw literals or hand-rolled helpers
+- [ ] New `create()` factory uses `validateOpts` for opts allow-list (boot-time validation)
+- [ ] No "future patch" deferrals — sweep across all existing call sites in this same PR if introducing a shared helper
+
+## Tests
+
+- [ ] `node test/smoke.js` passes — count: `____`
+- [ ] `examples/wiki/test/e2e.js` passes — count: `____`
+- [ ] `npx eslint@latest --max-warnings 0 .` exits 0
+- [ ] New tests added for the new behavior:
+  - [ ] Layer 0 (primitive)
+  - [ ] Layer 1 (state-touching)
+  - [ ] Layer 2 (middleware composition)
+  - [ ] Layer 3 (end-to-end framework boot)
+  - [ ] Wiki e2e (operator-facing route)
+
+## Documentation
+
+<!-- Check the ones that apply to this PR -->
+
+- [ ] Wiki seeded pages updated (`examples/wiki/seeders/prod/0001-default-pages.js`) for new operator-facing surfaces
+- [ ] DEPLOY.md updated for new env vars / GitHub settings / cosign / verification
+- [ ] SECURITY.md updated for new threat model entries / supported versions
+- [ ] README.md updated if the new feature appears in the high-level pitch
+- [ ] Commit message explains *why* and *what tradeoff*, not just *what*
+
+## Behavior changes
+
+<!-- If this PR changes existing behavior (output channel, exit code, default value, ...),
+     call it out here so the next release notes can flag it. -->
+
+## Open questions / reviewer focus
+
+<!-- Anything you want the reviewer to look at specifically. -->

package/lib/vendor/blamejs/.github/dependabot.yml

@@ -0,0 +1,37 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "deps"
+      - "github-actions"
+
+  - package-ecosystem: "npm"
+    directory: "/examples/wiki"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "deps"
+      - "examples"
+
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "deps"
+      - "devdeps"
+
+  - package-ecosystem: "docker"
+    directory: "/examples/wiki"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    labels:
+      - "deps"
+      - "docker"