@blamejs/blamejs-shop 0.3.51 → 0.3.52

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.52 (2026-06-02) — **Read-only admin audit log, database backup tooling, an email-deliverability guide, and a cryptographic integrity gate over the vendored framework.** Audit events were recorded but had no console view, there was no documented database backup path, no operator guidance for email deliverability, and the vendored framework tree was only checked for presence — not integrity. This release adds a read-only audit log screen in the admin console, a database export script plus point-in-time recovery documentation, an SPF/DKIM/DMARC deliverability guide, and a build gate that cryptographically verifies every file in the vendored framework so a tampered or accidentally edited dependency fails the build. **Added:** *Admin audit log screen* — A read-only Audit screen in the admin console lists recorded audit events — action, outcome, actor, resource, and details — with an outcome filter and pagination. Every field is HTML-escaped. The screen is a pure observability view: if the audit store is briefly unavailable it shows an empty table with a notice rather than erroring. · *Database backup and recovery tooling* — A new export script wraps the D1 export command (suitable for a scheduled export to object storage), and the operator docs gain a recovery section pointing at D1 Time Travel for point-in-time restore. · *Email deliverability operator guide* — SECURITY.md and the README gain an email-deliverability section covering the SPF, DKIM, and DMARC DNS setup that determines whether transactional and cart-recovery mail reaches the inbox, alongside the already-handled one-click unsubscribe and suppression behavior. · *Cryptographic integrity gate over the vendored framework* — The build now re-hashes every file in the vendored framework tree against a pinned manifest and fails if any digest changes, giving the no-hand-edits-to-vendored-code rule real enforcement. The check runs across the test matrix and inside the container image build.
+
 - v0.3.51 (2026-06-02) — **Payment scripts load under the strict CSP, an optional CAPTCHA gate guards signup and checkout, HSTS is preload-strength, and order actions are rate-limited.** The strict content-security-policy blocked the Stripe and PayPal scripts on the payment pages, so checkout would have failed even once payment keys were configured. Those pages now load the processor scripts through a route-scoped policy and same-origin script files, without relaxing the site-wide policy anywhere else. A CAPTCHA challenge can now be required on signup and checkout (and optionally login) once an operator configures a provider; it stays off until then. The edge now sends a two-year HSTS max-age so the domain qualifies for the preload list, and the order cancel, rate, and reorder actions are covered by the tighter per-route rate limit. **Added:** *Optional CAPTCHA gate on signup, checkout, and login* — When an operator configures a CAPTCHA provider (Cloudflare Turnstile, hCaptcha, or reCAPTCHA), a challenge is required on signup and checkout, with login behind an opt-in flag since passkey sign-in is already phishing-resistant. The token is verified server-side before the action proceeds. With no provider configured the gate is a no-op and every flow behaves exactly as before. **Changed:** *Preload-strength HSTS at the edge* — The edge now sends an HSTS max-age of two years (with includeSubDomains and preload), matching the container and meeting the one-year minimum required for HSTS preload-list inclusion. **Fixed:** *Payment pages load Stripe and PayPal under the strict CSP* — The pay and checkout pages now load the Stripe and PayPal scripts through a content-security-policy scoped to those routes plus same-origin script files, instead of inline script that the site-wide strict policy blocked. Checkout works once payment keys are set, and the site-wide policy — no inline script, Trusted Types required, restricted object and frame sources — is unchanged everywhere else. · *Order actions covered by the tighter rate limit* — Cancelling, rating, and reordering an order are now under the same strict per-route rate limit as other sensitive actions, rather than only the looser global limit.
 
 - v0.3.50 (2026-06-02) — **Installable PWA manifest, hreflang for multilingual stores, complete sitemap and robots coverage, localized edge pages, and product Q&A rich results.** Several search-engine and internationalization signals were missing or inconsistent between the cached (edge) and dynamically rendered pages. This release serves an installable web-app manifest and a service worker, emits hreflang alternates when a store runs path- or subdomain-based locales, localizes the blog, CMS, and policy pages on the cached path (they were always English), brings the robots.txt and sitemap into agreement across both render paths with collections, categories, and CMS pages now included, and emits Q&A structured data on product pages. It also fixes a bug that dropped every product from the dynamically rendered sitemap. **Added:** *Installable web-app manifest and service worker* — The store now serves a web-app manifest at /manifest.webmanifest and a service worker at /sw.js, and links the manifest from every page, so the storefront can be installed as a progressive web app. A working default is served out of the box; an operator who configures a custom manifest overrides it. · *hreflang alternates for multilingual stores* — When a store runs locales via URL prefixes (e.g. /de/) or subdomains, each page now emits rel=alternate hreflang links (plus x-default) so search engines map the equivalent localized URLs instead of treating them as duplicate content. Stores on a single locale, or locale-by-cookie, emit none. · *Product Q&A rich results* — A product page with answered customer questions now emits QAPage structured data so the questions and answers are eligible for rich results in search. **Fixed:** *Localized blog, CMS, and policy pages on the cached path* — The cached (edge-rendered) blog articles, CMS pages, and privacy/terms pages now carry the correct document language and direction for the active locale, matching the dynamically rendered pages. Previously they were always marked English and left-to-right, which harmed screen readers and search indexing and broke right-to-left layout. · *Consistent robots.txt and complete sitemap* — robots.txt now disallows the admin, cart, checkout, order, and account paths consistently on both render paths, and the sitemap now includes collection, category, and CMS-page URLs alongside products and blog posts. A bug that made the dynamically rendered sitemap omit every product (a list limit overflow) is fixed so the full catalog is listed.

package/README.md

@@ -45,6 +45,15 @@ node test/smoke.js
 - **`b.externalDb` adapter for Cloudflare D1** (`lib/externaldb-d1.js`) — service-binding + REST-API modes, normalized result envelope, AbortController timeouts, jittered retry on transient errors.
 - **`InventoryLock` Durable Object** — per-SKU serialization point so concurrent checkouts across container replicas can't oversell.
 - **`docs/deploy-cloudflare.md`** — operator deploy recipe end-to-end.
+- **Database backup & recovery** — D1 Time Travel gives 30 days of
+  always-on point-in-time recovery; `npm run d1-export` (`scripts/d1-export.js`)
+  writes a full logical `.sql` dump and can push it to a private R2 `backups/`
+  key. See SECURITY.md → Database backup & recovery.
+- **Email deliverability** (SPF / DKIM / DMARC + one-click List-Unsubscribe):
+  see SECURITY.md → Email deliverability for the DNS records to publish.
+- **Supply-chain integrity** — the build verifies every vendored file's
+  SHA-256 against `lib/vendor/MANIFEST.json`, so a hand-edit to the vendored
+  tree fails smoke. See SECURITY.md → Supply-chain integrity.
 
 ### Commerce primitives
 
@@ -87,7 +96,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/giftcards.js`** | Prepaid bearer gift cards. `issue({ amount_minor, currency })` generates a 16-char code (32-glyph alphabet, no ambiguous letters) via `b.crypto.generateBytes`, stores only its `namespaceHash` digest + a 4-char hint, and returns the plaintext code once. `balance(code)` / `lookup(code)` resolve a code to its live balance (constant-time hash compare); `redeem({ code, order_id, amount_minor })` decrements the balance with an atomic `balance >= amount` SQL guard so concurrent spends can't overdraw. Redeemed at checkout as a credit against the order grand total: the amount due drops by the applied balance (never below zero), the order still records the full total it owed, and the debit is recorded once per order — a card that fully covers the order is marked paid with no Stripe charge. Customers check a balance at `GET /gift-cards`; the page is not a code-existence oracle (unknown / malformed / expired all return the same generic not-found). |
 | **`lib/gift-card-ledger.js`** | Append-only credit / debit / expire history per gift card, with a denormalized `balance_after_minor` snapshot for O(1) balance reads. `credit` / `debit` / `expire` write one row each; `history(id)` paginates a card's transactions; `transactionsForOrder(id)` lists a card's movements for one order. The audit trail behind the admin gift-card ledger console; overdraft is refused at the primitive layer. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules + coupon-stacking policies — create / edit / archive each. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, and Discounts links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, and Discounts links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 

package/SECURITY.md

@@ -198,3 +198,61 @@ node -e "
   emails are stored hash-only (`b.crypto.namespaceHash`), and the
   account leaderboard exposes rank plus initials only, never an email or
   account id.
+- **Privileged actions are recorded and reviewable.** Every mutating
+  admin action and every catalog-API error is appended to a
+  tamper-evident, hash-chained audit log (the framework's `b.audit`
+  surface — append-only, verified at boot). Operators review it at
+  `/admin/audit`: a read-only activity log filterable by outcome
+  (success / failure / denied) and paginated. Opening the log is itself
+  recorded (an `audit.read` row), so reviewing the audit trail leaves
+  its own forensic mark.
+- **Email deliverability — SPF / DKIM / DMARC + one-click unsubscribe.**
+  Transactional and broadcast mail is composed on `b.mail`, which signs
+  each message with DKIM, but the receiving server still rejects or
+  spam-folders mail whose envelope DNS isn't published. Publish all
+  three records for the From: domain:
+    - **SPF:** a TXT record on the sending domain authorizing the
+      service that emits the envelope (e.g. `v=spf1
+      include:<your-relay> -all`). `b.mail` signs the body but does not
+      control the envelope sender, so SPF must name whatever relay
+      actually delivers.
+    - **DKIM:** `b.mail.dkim` generates the `DKIM-Signature` header;
+      publish the matching public key as a TXT record at
+      `<selector>._domainkey.<domain>`. The selector is the one
+      configured for the signing key.
+    - **DMARC:** publish `_dmarc.<domain>` with at least
+      `v=DMARC1; p=quarantine; rua=mailto:<aggregate-report-mailbox>`.
+      Align the SPF and DKIM domains with the From: domain so DMARC
+      passes; raise to `p=reject` once aggregate reports are clean.
+    - **One-click unsubscribe (RFC 8058):** the broadcast path emits
+      `List-Unsubscribe` plus `List-Unsubscribe-Post:
+      List-Unsubscribe=One-Click` (composed on `b.guardListUnsubscribe`).
+      Keep the unsubscribe endpoint reachable from the public origin —
+      mailbox providers fetch it directly, and an unreachable endpoint
+      hurts sender reputation.
+- **Database backup & recovery.** Two layers protect the live D1
+  database:
+    - **D1 Time Travel (always on).** Cloudflare retains a rolling
+      30-day point-in-time history of the database with no setup.
+      Recover with `wrangler d1 time-travel restore blamejs-shop
+      --timestamp <ISO-8601>` (or `--bookmark <id>`); inspect the
+      current bookmark with `wrangler d1 time-travel info blamejs-shop`.
+    - **Scheduled logical export.** `node scripts/d1-export.js --to-r2`
+      (or `npm run d1-export -- --to-r2`) produces a full `.sql` dump of
+      the live database and uploads it to the private `backups/` key in
+      the assets R2 bucket. Schedule it from the operator's own
+      cron / CI on whatever cadence the retention policy requires; it is
+      not wired into the deploy. The dump bears all customer data —
+      treat the R2 `backups/` prefix as sensitive. It is NOT on the
+      Worker's served asset path (the Worker serves only
+      `/assets/themes/...` and `brand/`), so a backup object is never
+      web-reachable.
+- **Supply-chain integrity — vendored bytes are verified on every
+  build.** `lib/vendor/MANIFEST.json` pins a per-file SHA-256 of the
+  entire vendored blamejs tree. The smoke gate (run in CI on every
+  push/PR and inside the container image build) recomputes each file's
+  digest and compares it against the manifest via the framework's own
+  `b.configDrift.verifyVendorIntegrity`, so a hand-edit to any vendored
+  source — or a vendor refresh that skipped re-stamping — fails the
+  build before it can ship. Refresh + re-stamp is a single command
+  (`scripts/vendor-update.sh blamejs <tag>`).

package/lib/admin.js

@@ -515,6 +515,12 @@ function mount(router, deps) {
   var orderExchanges  = deps.orderExchanges  || null; // exchange queue + FSM-action console disabled when absent
   var orderRatings    = deps.orderRatings    || null; // per-order rating moderation queue (flag/clear + public reply) disabled when absent
   var preorder        = deps.preorder        || null; // pre-order campaign console (define/launch/close) disabled when absent
+  // Read-only activity log at /admin/audit. Defaults ON — the framework
+  // audit chain is always booted by createApp, so the screen always has a
+  // data source (unlike the optional primitives above, which default off).
+  // An operator who wants the console surface minimized can pass
+  // `auditLog: false` to hide both the route and the nav link.
+  var auditLog        = deps.auditLog !== false;
 
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
@@ -522,7 +528,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, orderExport: !!orderExport };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, orderExport: !!orderExport, auditLog: auditLog };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -1739,6 +1745,72 @@ function mount(router, deps) {
     },
   ));
 
+  // ---- audit / activity log (read-only) -------------------------------
+  //
+  // A read-only window onto the framework's tamper-evident audit chain —
+  // every mutating admin action (`shop_admin.*`) and catalog-API error is
+  // recorded there. Container-only: it reads `b.audit.query`, which needs
+  // the booted framework DB, so there is no edge twin (and none is needed —
+  // the whole admin console is container-only). Defaults ON; hidden when an
+  // operator passes `auditLog: false`. No POST forms (read-only), so the
+  // shell's CSRF field injection is a no-op here. `b.audit.query` itself
+  // logs an `audit.read` row before each query, so opening this screen is
+  // forensically recorded.
+  //
+  // Request-shape reader → RETURN-DEFAULT discipline: bad query params are
+  // clamped / ignored, never thrown (a dashboard 500 on a fat-fingered URL
+  // is worse than showing all). An unrecognized ?outcome= falls back to
+  // no-filter with a notice, mirroring the orders bad-filter fallback.
+  var AUDIT_OUTCOMES = ["success", "failure", "denied"];
+  function _parseAuditQuery(req) {
+    var url = req.url ? new URL(req.url, "http://localhost") : null;
+    var q = {};
+    var notice = null;
+    var outcome = url && url.searchParams.get("outcome");
+    if (outcome) {
+      if (AUDIT_OUTCOMES.indexOf(outcome) !== -1) q.outcome = outcome;
+      else notice = "Unknown outcome filter — showing all.";
+    }
+    var action = url && url.searchParams.get("action");
+    if (typeof action === "string" && action.length) q.action = action.slice(0, 200);
+    var actorUserId = url && url.searchParams.get("actorUserId");
+    if (typeof actorUserId === "string" && actorUserId.length) q.actorUserId = actorUserId.slice(0, 200);
+    // limit: clamp to 1..200, default 50. offset: >= 0, default 0.
+    var limitN = parseInt((url && url.searchParams.get("limit")) || "", 10);
+    q.limit = (Number.isFinite(limitN) && limitN >= 1 && limitN <= 200) ? limitN : 50;
+    var offsetN = parseInt((url && url.searchParams.get("offset")) || "", 10);
+    q.offset = (Number.isFinite(offsetN) && offsetN >= 0) ? offsetN : 0;
+    q._page = Math.floor(q.offset / q.limit) + 1;
+    q._notice = notice;
+    return q;
+  }
+
+  if (auditLog) {
+    router.get("/admin/audit", _pageOrApi(true,
+      R(async function (req, res) {            // bearer → JSON
+        var q = _parseAuditQuery(req);
+        var rows = [];
+        try { rows = await b.audit.query(q); }
+        catch (_e) { rows = []; }
+        _json(res, 200, { rows: rows, page: q._page, limit: q.limit });
+      }),
+      async function (req, res) {              // browser cookie → HTML
+        var q = _parseAuditQuery(req);
+        var rows = [];
+        var notice = q._notice;
+        // Read-only observability view: ANY query failure (a malformed
+        // criterion, or an unavailable audit store) degrades to an empty
+        // table + notice, never a 500. Drop-silent by design.
+        try { rows = await b.audit.query(q); }
+        catch (_e) { rows = []; notice = notice || "The audit log is temporarily unavailable."; }
+        _sendHtml(res, 200, renderAdminAudit({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          rows: rows, filters: q, notice: notice,
+        }));
+      },
+    ));
+  }
+
   // ---- shipment tracking (operator-managed) ---------------------------
   //
   // Attach a shipment to an order (carrier + optional tracking number) and
@@ -9901,6 +9973,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
+  { key: "audit",        href: "/admin/audit",        label: "Audit",        requires: "auditLog" },
   { key: "exports",      href: "/admin/exports",      label: "Exports",      requires: "orderExport" },
   { key: "customers",    href: "/admin/customers",    label: "Customers",    requires: "customers" },
   { key: "segments",     href: "/admin/segments",     label: "Segments",     requires: "customerSegments" },
@@ -10212,6 +10285,90 @@ function renderAdminOrders(opts) {
   return _renderAdminShell(opts.shop_name, "Orders", body, "orders", opts.nav_available);
 }
 
+// The outcomes an operator can filter the audit log by — drives the chips.
+var AUDIT_OUTCOME_FILTERS = ["success", "failure", "denied"];
+
+// Read-only activity log. Renders the framework audit rows (action, outcome,
+// actor, resource, truncated metadata) for the selected outcome filter, with
+// offset/limit paging.
+//
+// XSS-CRITICAL: audit rows carry operator-controlled action names and
+// ATTACKER-INFLUENCED free text — a bot-driven `actorUserAgent`, a caught
+// error's message folded into `metadata`, an attacker-chosen resource id.
+// EVERY cell value flows through `_htmlEscape` (escape-by-default). This
+// class is un-lintable (no detector can tell a render-concat apart from a
+// string-build), so the XSS-payload regression test is the guarantee — see
+// test/layer-2-integration/admin-audit-console.test.js.
+function renderAdminAudit(opts) {
+  opts = opts || {};
+  var rows = opts.rows || [];
+  var filters = opts.filters || {};
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var active = filters.outcome || null;
+  var limit  = filters.limit || 50;
+  var offset = filters.offset || 0;
+
+  // Preserve an active ?action= filter across the outcome chips + pager.
+  function _withParams(extra) {
+    var parts = [];
+    if (extra.outcome)     parts.push("outcome=" + encodeURIComponent(extra.outcome));
+    if (filters.action)    parts.push("action=" + encodeURIComponent(filters.action));
+    if (filters.actorUserId) parts.push("actorUserId=" + encodeURIComponent(filters.actorUserId));
+    if (extra.offset != null) parts.push("offset=" + encodeURIComponent(String(extra.offset)));
+    if (limit !== 50)      parts.push("limit=" + encodeURIComponent(String(limit)));
+    return "/admin/audit" + (parts.length ? "?" + parts.join("&") : "");
+  }
+
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (active ? "" : " chip--on") + "\" href=\"" + _htmlEscape(_withParams({})) + "\">All</a>" +
+    AUDIT_OUTCOME_FILTERS.map(function (o) {
+      return "<a class=\"chip" + (active === o ? " chip--on" : "") + "\" href=\"" + _htmlEscape(_withParams({ outcome: o })) + "\">" + _htmlEscape(o) + "</a>";
+    }).join("") +
+    "</div>";
+
+  var bodyRows = rows.map(function (row) {
+    // metadata is a JSON string (audit.record stores it as JSON.stringify);
+    // escape THEN truncate so a long redacted blob can't blow the row, and
+    // so a payload inside it is neutralized before it reaches the DOM.
+    var meta = row.metadata == null ? "" : String(row.metadata);
+    var metaEsc = _htmlEscape(meta.length > 120 ? meta.slice(0, 120) + "…" : meta);
+    var resource = "";
+    if (row.resourceKind || row.resourceId) {
+      resource = _htmlEscape(row.resourceKind || "") +
+        (row.resourceId ? " <code>" + _htmlEscape(row.resourceId) + "</code>" : "");
+    } else {
+      resource = "—";
+    }
+    return "<tr>" +
+      "<td>" + _htmlEscape(_fmtDate(row.recordedAt)) + "</td>" +
+      "<td><code>" + _htmlEscape(row.action) + "</code></td>" +
+      "<td><span class=\"status-pill " + _htmlEscape(row.outcome) + "\">" + _htmlEscape(row.outcome) + "</span></td>" +
+      "<td>" + _htmlEscape(row.actorUserId == null ? "—" : row.actorUserId) + "</td>" +
+      "<td>" + resource + "</td>" +
+      "<td class=\"audit-meta\">" + metaEsc + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Time</th><th scope=\"col\">Action</th><th scope=\"col\">Outcome</th><th scope=\"col\">Actor</th><th scope=\"col\">Resource</th><th scope=\"col\">Details</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No audit events match.</p>";
+
+  // Pager: Newer steps back one page (disabled at offset 0); Older steps
+  // forward (shown only when the page is full — the standard "there may be
+  // more" heuristic). Filters are preserved in both hrefs.
+  var prevOffset = Math.max(0, offset - limit);
+  var newer = offset > 0
+    ? "<a class=\"btn btn--ghost\" href=\"" + _htmlEscape(_withParams({ outcome: active, offset: prevOffset })) + "\">← Newer</a>"
+    : "<span class=\"btn btn--ghost\" aria-disabled=\"true\">← Newer</span>";
+  var older = rows.length === limit
+    ? "<a class=\"btn btn--ghost\" href=\"" + _htmlEscape(_withParams({ outcome: active, offset: offset + limit })) + "\">Older →</a>"
+    : "";
+  var pager = "<div class=\"order-filters\">" + newer + older + "</div>";
+
+  var body = "<section><h2>Audit log</h2>" + notice + chips + table + (rows.length || offset > 0 ? pager : "") + "</section>";
+  return _renderAdminShell(opts.shop_name, "Audit", body, "audit", opts.nav_available);
+}
+
 // epoch-ms → "YYYY-MM-DD" for a date <input>'s value. Mirrors `_fmtDate`'s
 // guard so a bad value never throws inside the template.
 function _dateInputValue(v) {
@@ -15969,4 +16126,5 @@ module.exports = {
   renderAdminLoyaltyRewards:    renderAdminLoyaltyRewards,
   renderAdminLoyaltyReward:     renderAdminLoyaltyReward,
   renderAdminConfirm:      renderAdminConfirm,
+  renderAdminAudit:        renderAdminAudit,
 };

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.51",
+  "version": "0.3.52",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-/NizdENQkTc96romD0kmnl8220NAvW32QI0aSFuGiPbWE5lYbRxLXU5shsjlx5Ek",