@blamejs/blamejs-shop 0.0.51 → 0.0.53

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.53 (2026-05-22) — **Docs refresh, sample catalog tripled, designed empty-cart card, worker hardening.** Four surfaces refresh in one release. `SECURITY.md` + `CONTRIBUTING.md` + `docs/deploy-cloudflare.md` cover the scoped package name + custom domain + the full 0001-0010 migration table. The sample catalog grows from 4 products to 12 (Operator Hoodie, Vault Stick, Signing Cable, Build Pass, Audit Log Kit, Self-Hosted Plan, Operator Mug, Sticker Pack — each with its own brand-coloured SVG hero). The empty-cart row gains a designed `cart-empty` card with the brand 🛒 icon, eyebrow + title + lede + dual CTAs (`Browse products` primary, `Find a specific product` ghost linking the header search). The Worker gets a `/robots.txt` edge fallback (so crawlers get a clean answer even during container cold-start), the warming-up page picks up `noindex`/`canonical`/`aria-live`/refresh tuned to `Sec-Fetch-Mode`, and a new `/_/version` probe surfaces deploy state. **Added:** *Sample catalog grows from 4 to 12 products with brand-coloured SVG heroes* — `scripts/sample-product-images/{operator-hoodie,vault-stick,signing-cable,build-pass,audit-log-kit,self-hosted-plan,operator-mug,sticker-pack}.svg` ship as the next round of reference imagery. Apparel SVGs use dark-ink gradients with accent-orange illustrations; hardware uses navy-to-blue gradients with grey/black device silhouettes + accent-orange chip highlights; digital uses purple-to-navy with credential-artifact motifs carrying a visible PQC / ML-DSA seal; bundles use deep-orange or green with stacked-object compositions. All 800×800 viewBox, system font stack, monospace SKU at bottom-right. `scripts/seed-sample-products.sql` + `scripts/seed-sample-product-media.sql` extend with the matching catalog + media rows (UUIDv7 ids continue the existing numbering 0005-000c). · *Designed empty-cart card* — `renderCart` emits a `.cart-empty` section instead of a bare `<td colspan>` row when there are no lines. The card carries the brand emoji in a dashed-border circle, `Cart` eyebrow, `Your cart is empty` headline, a lede that explains how the cart holds the add-time price, and dual CTAs — `Browse products →` (primary, → `/`) + `Find a specific product` (ghost, anchors `#site-search-q` for header-search focus without inline JS). Populated cart gains a `Shop / Cart` breadcrumb above the section head, matching the PDP's pattern. · *Worker `/robots.txt` edge fallback* — Even during container cold-start, the Worker now serves a minimal `User-agent: *\nAllow: /\nSitemap: https://blamejs.shop/sitemap.xml\n` directly at the edge with a 1h cache. Crawlers never see the warming page for robots probes. R2-uploaded `/assets/robots.txt` overrides still win for operators with a custom policy. · *Worker `/_/version` deploy probe* — Operator-friendly diagnostic endpoint returning `{ worker, container_image, time }`. No auth required (pure read-only probe); use it to verify a deploy reached the edge before sending traffic. · *`CONTRIBUTING.md`* — 210 lines covering: dev environment setup (clone → vendor-update → smoke), the release workflow (release-notes JSON → CHANGELOG rebuild → branch → PR → admin merge → tag → publish), code conventions (CommonJS, `var`, zero npm runtime deps, compose `b.*` primitives, vendored tree read-only, security defaults non-opt-in, PQC-first), how to run + write tests (smoke + layer-0/1/2, `waitUntil` over `setTimeout`), the explicit list of artifacts each publish produces, and a pointer to `SECURITY.md` for vuln reporting. **Changed:** *Warming-up page — `noindex`, canonical, ARIA-live, refresh tuned to navigation mode* — The cold-start fallback page picks up `<meta name="robots" content="noindex, nofollow">` + a canonical link so crawlers don't index the placeholder. The auto-refresh interval shifts based on `Sec-Fetch-Mode` — 5 seconds for `navigate` requests (real visitor in a browser tab), 8 seconds for non-navigation fetches (XHR/fetch/Stripe.js probes that shouldn't spam the container). A new `aria-live="polite"` region announces the warming state to screen readers. · *`SECURITY.md` — Stripe webhook clause updated to match shipped code* — The container's defense-in-depth verification clause used a placeholder phrase from before `lib/payment.js` shipped. Now describes the actual `b.webhook.verify` call (alg `hmac-sha256-stripe`) running inside `lib/payment.js` before any FSM transition. Every other audit point matched the workflow output as-is — SLSA L3 provenance, Sigstore-keyless SBOM signatures, SHA-256 + SHA3-512 digests, ML-DSA-65 PQC sidecar. · *`docs/deploy-cloudflare.md` — custom-domain section + 0001-0010 migration table + demo-seed step* — Adds a `Wire a custom domain` section (zone-add → Worker custom-domain bind → `wrangler.toml` route alternative → TLS verify). Replaces the bare-paragraph migration mention with the explicit 0001-0010 table (calling out the intentional `0007` gap from the abandoned discounts work). Adds a `Seed demo content` section that runs both seed SQL files via `wrangler d1 execute --remote`. Switches the existing migration-apply step to `--remote` for clarity.
+
+- v0.0.52 (2026-05-22) — **Live deploy moves to the custom domain — README + wrangler config point at https://blamejs.shop.** The reference deploy now serves at `https://blamejs.shop` instead of the `*.workers.dev` subdomain. README header now reads 'Homepage: **https://blamejs.shop**' and the admin-API curl example uses a placeholder `your-shop.example.com` host since operators replace it with their own. `wrangler.toml#D1_BRIDGE_URL` switches to `https://blamejs.shop` so the container's externalDb adapter calls back through the canonical origin. **Changed:** *README header — 'Homepage' instead of 'Live demo', custom domain* — `Homepage: **https://blamejs.shop**` replaces the previous `Live demo: **https://blamejs-shop.coocoo.workers.dev/**`. Operators evaluating the framework now see the canonical address. The admin-API curl example in the operator quick-start drops the placeholder `<your-worker>.workers.dev` host in favour of a `your-shop.example.com` placeholder with a comment pointing at the reference deploy. · *`wrangler.toml#D1_BRIDGE_URL` → `https://blamejs.shop`* — The container's externalDb D1 adapter posts SQL to `<D1_BRIDGE_URL><D1_BRIDGE_PATH>` (the Worker's service-binding bridge endpoint). Updating the base URL routes those internal calls through the custom domain. Cloudflare resolves custom domains to the same Worker that serves `*.workers.dev`, so the bridge keeps working with no router change.
+
 - v0.0.51 (2026-05-22) — **SEO crawl surfaces — `/robots.txt` + `/sitemap.xml` listing every active product.** Crawlers landing on the live shop had no discovery surface — every product page was reachable only by being linked from the home grid, and there was no robots.txt to direct the crawl. This release wires `/robots.txt` (allow-everything-except-session-scoped, pointing at the sitemap) and `/sitemap.xml` (lists the home + /admin + every `status='active'` product with its `updated_at` lastmod, capped at 1000 rows). The XML is hand-rolled — no node:xml dep — with attribute-escaped values so a slug containing `&` or `<` can't break out of the document. **Added:** *`GET /robots.txt`* — `User-agent: *` + `Allow: /` for crawlable surfaces. Disallow paths cover the session-scoped + operator-only surfaces (`/admin`, `/cart`, `/checkout`, `/pay/`, `/orders/`, `/account`) — none of those have crawl value and exposing them risks crawlers tripping rate limits on the cart-bound DO. `Sitemap:` directive resolves from the request `Host` header so the same handler serves the right absolute URL for `localhost:8080` (dev), `blamejs-shop.coocoo.workers.dev` (live), or any custom domain. `Cache-Control: public, max-age=3600`. Operators with stricter requirements override by uploading a `robots.txt` key to R2 — the Worker's static-asset bridge serves R2 keys ahead of the storefront router, so the bucket file wins. · *`GET /sitemap.xml`* — Lists the home page (priority 1.0, daily changefreq), the `/admin` landing (priority 0.3, monthly changefreq), and every `status='active'` product (priority 0.8, weekly changefreq) with the product's `updated_at` or `created_at` as `lastmod` (ISO date). Capped at 1000 rows — the sitemap spec allows 50,000 but a shop at that scale should pre-segment into a sitemap index. The XML is hand-rolled, attribute-escape applies `&`, `<`, `>`, `"`, `'` so an operator-supplied slug can't break the document. `Cache-Control: public, max-age=300` so a catalog update propagates inside five minutes without an operator action.
 
 - v0.0.50 (2026-05-22) — **OpenGraph + Twitter Card meta tags — shared links unfurl with proper previews.** Pages rendered without `og:*` or `twitter:*` tags. Sharing the live URL in Slack / iMessage / Twitter / Discord landed a bare URL with no preview, no image, no description. This release wires OpenGraph + Twitter Card meta tags into the LAYOUT head with sensible site-level defaults (brand logo + shop-level lede). The PDP overrides them with product-specific values — `og:title` is the product title, `og:description` is the catalog `description`, `og:image` is the first attached media URL — so a product share renders with the actual hero image + product copy. **Added:** *OpenGraph + Twitter Card tags in `LAYOUT`* — `<meta property="og:type">`, `og:site_name`, `og:title`, `og:description`, `og:image`, `og:url` + the Twitter Card analogues (`twitter:card=summary_large_image`, `twitter:title`, `twitter:description`, `twitter:image`). All templated through `{{og_*}}` placeholders so the `_render` HTML-escape protects against operator-supplied content breaking out of the attribute boundary. `<meta name="description">` also lands so non-OG crawlers see the same description. · *Default OG values on `_wrap(opts)`* — Every page renders with sensible defaults: `og:type=website`, `og:title=<page title> — <shop name>`, `og:description=Open-source ecommerce framework built on blamejs. Server-rendered HTML, post-quantum crypto, zero npm runtime dependencies.`, `og:image=/assets/brand/logo.png`. Per-renderer overrides via `opts.og_*` work surgically — only the field passed in overrides; the rest stay on defaults. · *Product-specific OG on the PDP* — `renderProduct` overrides four OG fields: `og_type=product`, `og_title=<product.title> — <shop_name>`, `og_description=<product.description>` (or a generated fallback when the description is empty), `og_image=<assetPrefix><heroMedia.r2_key>` (the first attached media row). A PDP share now renders the SVG hero + the product copy, not the brand logo + a generic shop description.

package/README.md

@@ -8,7 +8,7 @@
 
 Open-source ecommerce framework built on [blamejs](https://github.com/blamejs/blamejs). Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.
 
-Live demo: **https://blamejs-shop.coocoo.workers.dev/**
+Homepage: **https://blamejs.shop**
 
 ## Requirements
 
@@ -121,7 +121,9 @@ npx wrangler d1 migrations apply blamejs-shop --remote
 npx wrangler deploy
 
 # 5. Seed a product via the admin API
-curl -X POST https://<your-worker>.workers.dev/admin/products \
+#    (replace the host with your own worker route or custom domain;
+#    the reference deploy lives at https://blamejs.shop)
+curl -X POST https://your-shop.example.com/admin/products \
   -H "Authorization: Bearer $ADMIN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"slug":"first","title":"First product","status":"active"}'

package/SECURITY.md

@@ -123,9 +123,11 @@ node -e "
 - **Stripe webhook signature.** Inbound `POST` to
   `/api/webhooks/stripe` is signature-verified at the Worker edge
   (HMAC-SHA256 over `<timestamp>.<body>`, 5-minute tolerance window)
-  before forwarding to the container. The container also re-verifies
-  defense-in-depth once the payment primitive lands. An unsigned or
-  out-of-window delivery never touches origin resources.
+  before forwarding to the container. The container re-verifies the
+  same signature defense-in-depth via `b.webhook.verify` (alg
+  `hmac-sha256-stripe`) inside `lib/payment.js` before any FSM
+  transition runs. An unsigned or out-of-window delivery never
+  touches origin resources.
 - **Worker → Container trust boundary.** The Worker treats the
   container as untrusted-for-D1: it never proxies arbitrary headers
   into D1, only the explicit `sql` + `params` from the bridge body.

package/lib/giftcards.js

@@ -0,0 +1,410 @@
+"use strict";
+/**
+ * @module shop.giftcards
+ * @title  Gift cards primitive — issue and redeem prepaid balance
+ *
+ * @intro
+ *   A gift card is a bearer credential. Whoever knows the plaintext
+ *   code can spend the balance — so the shop never stores it. On
+ *   `issue` we generate a 16-character alphanumeric code from
+ *   `b.crypto.generateBytes`, store the
+ *   `b.crypto.namespaceHash("giftcard-code", plaintext)` digest, and
+ *   return the plaintext exactly once. The issuer is responsible for
+ *   delivering it to the recipient (email, paper insert, etc.).
+ *
+ *   The `code_hint` is the last 4 plaintext characters — useful when
+ *   an operator triaging a support request needs to identify which
+ *   row the customer is asking about. Four characters of a 32-letter
+ *   alphabet is 2^20 ≈ one-in-a-million space, far too small to
+ *   enable brute-force recovery of the remaining 12.
+ *
+ *   Recipients without an account are addressed by an email-hash
+ *   (`b.crypto.namespaceHash("giftcard-recipient", email)`) so a
+ *   stolen D1 dump leaks no recipient addresses while still letting
+ *   the storefront resolve "this address owns these cards" after the
+ *   recipient registers.
+ *
+ *   Composition:
+ *     var gc = bShop.giftcards.create({ query: q });
+ *     var { id, code, code_hint } = await gc.issue({
+ *       amount_minor: 5000, currency: "USD", issued_to_email: "alice@example.com",
+ *     });
+ *     // deliver `code` to the recipient. Never readable again.
+ *     var view = await gc.balance(code);
+ *     var { remaining_balance_minor, redemption_id } =
+ *       await gc.redeem({ code: code, order_id: orderId, amount_minor: 2500 });
+ *
+ *   Display formatting (`XXXX-XXXX-XXXX-XXXX`) is purely cosmetic —
+ *   redemption + balance + lookup all strip hyphens (and ASCII
+ *   whitespace) before hashing, so a customer who types the dashes
+ *   back in works without special handling.
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+var CODE_NAMESPACE      = "giftcard-code";
+var RECIPIENT_NAMESPACE = "giftcard-recipient";
+
+// Alphabet excludes 0/O/I/1 so a code spoken aloud / read off a
+// printed insert doesn't collapse into ambiguous characters. 32
+// glyphs means each byte modulo-32 lands on a uniform draw (256 is a
+// multiple of 32 — no modulo-bias correction needed).
+var CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+var CODE_LEN      = 16;
+var CODE_HINT_LEN = 4;
+var CODE_ALPHABET_RE = /^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]+$/;
+
+var CURRENCY_RE = /^[A-Z]{3}$/;
+var STATUSES    = ["active", "redeemed", "expired", "voided"];
+
+// ---- validators ---------------------------------------------------------
+
+function _uuid(s, label) {
+  try { return _b().guardUuid.sanitize(s, { profile: "strict" }); }
+  catch (e) { throw new TypeError("giftcards: " + label + " — " + (e && e.message || "invalid UUID")); }
+}
+
+function _amountMinor(n, label) {
+  if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+    throw new TypeError("giftcards: " + label + " must be a positive integer (minor units)");
+  }
+  return n;
+}
+
+function _currency(c) {
+  // ISO 4217 alpha-3, uppercase. Matches the storage CHECK
+  // (length(currency) = 3) and the operator-facing convention.
+  if (typeof c !== "string" || !CURRENCY_RE.test(c)) {
+    throw new TypeError("giftcards: currency must be 3-letter uppercase ISO 4217");
+  }
+  return c;
+}
+
+function _status(s) {
+  if (typeof s !== "string" || STATUSES.indexOf(s) === -1) {
+    throw new TypeError("giftcards: status must be one of " + STATUSES.join(", "));
+  }
+  return s;
+}
+
+function _expiresAt(ts) {
+  if (ts == null) return null;
+  if (typeof ts !== "number" || !Number.isInteger(ts) || ts <= 0) {
+    throw new TypeError("giftcards: expires_at must be a positive integer epoch-ms or null");
+  }
+  return ts;
+}
+
+function _now() { return Date.now(); }
+
+// ---- code generation + canonicalization ---------------------------------
+
+// Map random bytes to the 32-character alphabet. 256 % 32 === 0 so
+// each modulo lands on a uniform alphabet index — no rejection
+// sampling needed. Routes through `b.crypto.generateBytes` (SHAKE256
+// over OS-RNG) for defense-in-depth over the bare OS RNG.
+function _generateCode() {
+  var buf = _b().crypto.generateBytes(CODE_LEN);
+  var out = "";
+  for (var i = 0; i < CODE_LEN; i += 1) {
+    out += CODE_ALPHABET.charAt(buf[i] & 31);
+  }
+  return out;
+}
+
+// Display form: XXXX-XXXX-XXXX-XXXX. Pure cosmetic — the hash
+// derivation runs on the canonicalized (hyphen-stripped) form.
+function _formatCode(plain) {
+  return plain.slice(0, 4) + "-" + plain.slice(4, 8) + "-" + plain.slice(8, 12) + "-" + plain.slice(12, 16);
+}
+
+// Strip hyphens + ASCII whitespace so a customer who types the
+// dashes (or pastes with a trailing newline) works without special
+// handling. Returns the canonical 16-character uppercase code, or
+// throws if the result isn't a well-formed alphabet draw.
+function _canonicalCode(input) {
+  if (typeof input !== "string" || !input.length) {
+    throw new TypeError("giftcards: code must be a non-empty string");
+  }
+  // Operator-facing affordance: tolerate hyphens + ASCII whitespace
+  // anywhere. Anything else (including unicode whitespace, control
+  // bytes, or out-of-alphabet glyphs) is a refusal — we don't want a
+  // sloppy normalizer to map two distinct codes to the same hash.
+  var stripped = input.replace(/[-\s]+/g, "").toUpperCase();
+  if (stripped.length !== CODE_LEN) {
+    throw new TypeError("giftcards: code must be " + CODE_LEN + " alphabet characters (hyphens optional)");
+  }
+  if (!CODE_ALPHABET_RE.test(stripped)) {
+    throw new TypeError("giftcards: code contains characters outside the gift-card alphabet");
+  }
+  return stripped;
+}
+
+function _hashCode(canonical) {
+  return _b().crypto.namespaceHash(CODE_NAMESPACE, canonical);
+}
+
+function _hashRecipient(email) {
+  // Recipient email is a free-form operator-supplied string at this
+  // tier; the storefront route layer is responsible for guardEmail
+  // validation before issuing the card. Here we only enforce
+  // shape-tier: non-empty, no control bytes (the namespaceHash
+  // primitive refuses CR/LF itself).
+  if (typeof email !== "string" || !email.length) {
+    throw new TypeError("giftcards: issued_to_email must be a non-empty string when provided");
+  }
+  // Lowercase the address before hashing so two casings of the same
+  // recipient collide on lookup. Local-part case sensitivity (RFC
+  // 5321) is operator-irrelevant for gift-card delivery — operators
+  // address the human, not the mailbox.
+  return _b().crypto.namespaceHash(RECIPIENT_NAMESPACE, email.toLowerCase());
+}
+
+// ---- factory ------------------------------------------------------------
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+
+  // `lookup` resolves a plaintext code to the live card row. Returns
+  // null on no match. The hash compare itself is constant-time
+  // because we go through `b.crypto.namespaceHash` (SHA3-512
+  // deterministic) and then SQL = comparison on the hex hash — an
+  // attacker who can time the query can't distinguish "no row" from
+  // "wrong hash" because both paths execute the same query.
+  // We additionally route the hex compare through
+  // `b.crypto.timingSafeEqual` for the returned row so a future
+  // refactor that adds non-constant-time matching can't slip in.
+  async function _lookup(plaintextCode) {
+    var canonical = _canonicalCode(plaintextCode);
+    var hash = _hashCode(canonical);
+    var r = await query(
+      "SELECT id, code_hash, balance_minor, currency, status, expires_at " +
+      "FROM giftcards WHERE code_hash = ?1",
+      [hash],
+    );
+    if (!r.rows.length) return null;
+    var row = r.rows[0];
+    // Belt-and-braces: the SQL = already matched, but route the hex
+    // strings through timingSafeEqual so the equality check leaves no
+    // micro-timing oracle in case a future schema change moves to a
+    // collection scan.
+    if (!_b().crypto.timingSafeEqual(row.code_hash, hash)) return null;
+    return {
+      id:            row.id,
+      balance_minor: row.balance_minor,
+      currency:      row.currency,
+      status:        row.status,
+      expires_at:    row.expires_at,
+    };
+  }
+
+  return {
+    CODE_NAMESPACE:      CODE_NAMESPACE,
+    RECIPIENT_NAMESPACE: RECIPIENT_NAMESPACE,
+    CODE_ALPHABET:       CODE_ALPHABET,
+    CODE_LEN:            CODE_LEN,
+    STATUSES:            STATUSES,
+
+    issue: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("giftcards.issue: input object required");
+      }
+      _amountMinor(input.amount_minor, "amount_minor");
+      _currency(input.currency);
+      var expiresAt = _expiresAt(input.expires_at);
+
+      var issuedToCustomerId = null;
+      if (input.issued_to_customer_id != null) {
+        issuedToCustomerId = _uuid(input.issued_to_customer_id, "issued_to_customer_id");
+      }
+      var issuedToEmailHash = null;
+      if (input.issued_to_email != null) {
+        issuedToEmailHash = _hashRecipient(input.issued_to_email);
+      }
+
+      // Allow neither, either, or both. A purely operator-issued card
+      // (promotion / refund credit) has no recipient identity at all.
+
+      var id   = _b().uuid.v7();
+      var code = _generateCode();
+      var hash = _hashCode(code);
+      var hint = code.slice(CODE_LEN - CODE_HINT_LEN);
+      var ts   = _now();
+
+      await query(
+        "INSERT INTO giftcards (id, code_hash, code_hint, currency, issued_minor, balance_minor, " +
+        "issued_to_customer_id, issued_to_email_hash, expires_at, status, created_at, updated_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?5, ?6, ?7, ?8, 'active', ?9, ?9)",
+        [
+          id, hash, hint, input.currency, input.amount_minor,
+          issuedToCustomerId, issuedToEmailHash, expiresAt, ts,
+        ],
+      );
+
+      // `code` is returned plaintext exactly ONCE. The issuer
+      // delivers it. Subsequent reads against this row only ever see
+      // the hash + hint.
+      return {
+        id:        id,
+        code:      _formatCode(code),
+        code_hint: hint,
+      };
+    },
+
+    // Public helper — returns null on no-match (constant-time at the
+    // hash layer; see `_lookup`).
+    lookup: function (plaintextCode) {
+      return _lookup(plaintextCode);
+    },
+
+    balance: async function (plaintextCode) {
+      var row = await _lookup(plaintextCode);
+      if (!row) return null;
+      return {
+        balance_minor: row.balance_minor,
+        currency:      row.currency,
+        status:        row.status,
+        expires_at:    row.expires_at,
+      };
+    },
+
+    redeem: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("giftcards.redeem: input object required");
+      }
+      _amountMinor(input.amount_minor, "amount_minor");
+      var orderId = null;
+      if (input.order_id != null) orderId = _uuid(input.order_id, "order_id");
+
+      var row = await _lookup(input.code);
+      if (!row) {
+        var miss = new Error("giftcards.redeem: code not recognized");
+        miss.code = "GIFTCARD_NOT_FOUND";
+        throw miss;
+      }
+      if (row.status !== "active") {
+        var inactive = new Error("giftcards.redeem: card is " + row.status);
+        inactive.code = "GIFTCARD_NOT_ACTIVE";
+        throw inactive;
+      }
+      var ts = _now();
+      if (row.expires_at != null && row.expires_at <= ts) {
+        // Expired-but-still-flagged-active: lazily transition the
+        // row so future reads reflect reality, then refuse this
+        // redemption. The transition itself is idempotent — every
+        // `redeem`/`balance` caller does the same check.
+        await query(
+          "UPDATE giftcards SET status = 'expired', updated_at = ?1 WHERE id = ?2 AND status = 'active'",
+          [ts, row.id],
+        );
+        var exp = new Error("giftcards.redeem: card is expired");
+        exp.code = "GIFTCARD_EXPIRED";
+        throw exp;
+      }
+      if (input.amount_minor > row.balance_minor) {
+        var ins = new Error("giftcards.redeem: amount exceeds remaining balance");
+        ins.code = "GIFTCARD_INSUFFICIENT_BALANCE";
+        throw ins;
+      }
+
+      // Atomic decrement guarded by a balance check at the SQL tier
+      // so two concurrent redemptions can't double-spend. The
+      // `balance_minor >= ?` predicate plus the row-level lock the
+      // UPDATE takes means whichever transaction lands second sees
+      // rowCount === 0 and we surface as insufficient.
+      var dec = await query(
+        "UPDATE giftcards SET balance_minor = balance_minor - ?1, " +
+        "status = CASE WHEN balance_minor - ?1 = 0 THEN 'redeemed' ELSE status END, " +
+        "updated_at = ?2 WHERE id = ?3 AND balance_minor >= ?1 AND status = 'active'",
+        [input.amount_minor, ts, row.id],
+      );
+      if (dec.rowCount === 0) {
+        // Race: another redemption beat us to the balance. Refuse
+        // with the same shape as the up-front insufficient check so
+        // the caller doesn't have to distinguish "checked then
+        // raced" from "always insufficient".
+        var raced = new Error("giftcards.redeem: amount exceeds remaining balance");
+        raced.code = "GIFTCARD_INSUFFICIENT_BALANCE";
+        throw raced;
+      }
+
+      var redemptionId = _b().uuid.v7();
+      await query(
+        "INSERT INTO giftcard_redemptions (id, giftcard_id, order_id, amount_minor, redeemed_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5)",
+        [redemptionId, row.id, orderId, input.amount_minor, ts],
+      );
+
+      var remaining = row.balance_minor - input.amount_minor;
+      return {
+        remaining_balance_minor: remaining,
+        redemption_id:           redemptionId,
+      };
+    },
+
+    "void": async function (id, opts2) {
+      opts2 = opts2 || {};
+      _uuid(id, "giftcard id");
+      var r = await query(
+        "SELECT id, status FROM giftcards WHERE id = ?1",
+        [id],
+      );
+      if (!r.rows.length) return null;
+      var row = r.rows[0];
+      if (row.status === "redeemed") {
+        var already = new Error("giftcards.void: card is fully redeemed");
+        already.code = "GIFTCARD_ALREADY_REDEEMED";
+        throw already;
+      }
+      if (row.status === "voided") {
+        // Idempotent — already voided; return the row as-is.
+        var existing = await query("SELECT * FROM giftcards WHERE id = ?1", [id]);
+        return existing.rows[0] || null;
+      }
+      var ts = _now();
+      await query(
+        "UPDATE giftcards SET status = 'voided', updated_at = ?1 WHERE id = ?2",
+        [ts, id],
+      );
+      // `opts2.reason` is operator-supplied free-form; it's not
+      // persisted on the row (no schema column) but accepted so a
+      // future audit-log primitive can ride alongside without a
+      // surface change.
+      void opts2.reason;
+      var after = await query("SELECT * FROM giftcards WHERE id = ?1", [id]);
+      return after.rows[0] || null;
+    },
+
+    listForCustomer: async function (customerId, opts3) {
+      _uuid(customerId, "customer_id");
+      opts3 = opts3 || {};
+      var sql = "SELECT * FROM giftcards WHERE issued_to_customer_id = ?1";
+      var params = [customerId];
+      if (opts3.status != null) {
+        _status(opts3.status);
+        sql += " AND status = ?2";
+        params.push(opts3.status);
+      }
+      sql += " ORDER BY created_at DESC";
+      var r = await query(sql, params);
+      return r.rows;
+    },
+  };
+}
+
+module.exports = {
+  create:              create,
+  CODE_NAMESPACE:      CODE_NAMESPACE,
+  RECIPIENT_NAMESPACE: RECIPIENT_NAMESPACE,
+  CODE_ALPHABET:       CODE_ALPHABET,
+  CODE_LEN:            CODE_LEN,
+  STATUSES:            STATUSES,
+};

package/lib/index.js

@@ -54,4 +54,5 @@ module.exports = {
   webhooks:        require("./webhooks"),
   analytics:       require("./analytics"),
   inventoryAlerts: require("./inventory-alerts"),
+  giftcards:       require("./giftcards"),
 };

package/lib/storefront.js

@@ -1085,6 +1085,12 @@ function renderOrder(opts) {
 
 var CART_PAGE =
   "<section class=\"cart-page\">\n" +
+  "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\">\n" +
+  "    <ol>\n" +
+  "      <li><a href=\"/\">Shop</a></li>\n" +
+  "      <li aria-current=\"page\">Cart</li>\n" +
+  "    </ol>\n" +
+  "  </nav>\n" +
   "  <header class=\"section-head\">\n" +
   "    <p class=\"eyebrow\">Your cart</p>\n" +
   "    <h1 class=\"section-head__title\">Review your items</h1>\n" +
@@ -1110,6 +1116,28 @@ var CART_PAGE =
   "  </div>\n" +
   "</section>\n";
 
+var CART_EMPTY_PAGE =
+  "<section class=\"cart-page cart-page--empty\">\n" +
+  "  <nav class=\"breadcrumb\" aria-label=\"Breadcrumb\">\n" +
+  "    <ol>\n" +
+  "      <li><a href=\"/\">Shop</a></li>\n" +
+  "      <li aria-current=\"page\">Cart</li>\n" +
+  "    </ol>\n" +
+  "  </nav>\n" +
+  "  <div class=\"cart-empty\">\n" +
+  "    <div class=\"cart-empty__card\">\n" +
+  "      <p class=\"cart-empty__icon\" aria-hidden=\"true\">🛒</p>\n" +
+  "      <p class=\"eyebrow cart-empty__eyebrow\">Cart</p>\n" +
+  "      <h1 class=\"cart-empty__title\">Your cart is empty</h1>\n" +
+  "      <p class=\"cart-empty__lede\">Browse the catalog and the products you add show up here. Items hold their price at add-time, not at checkout.</p>\n" +
+  "      <div class=\"cart-empty__cta\">\n" +
+  "        <a href=\"/\" class=\"btn-primary\">Browse products <span aria-hidden=\"true\">→</span></a>\n" +
+  "        <a href=\"#site-search-q\" class=\"btn-ghost\">Find a specific product</a>\n" +
+  "      </div>\n" +
+  "    </div>\n" +
+  "  </div>\n" +
+  "</section>\n";
+
 function renderCart(opts) {
   if (!opts) throw new TypeError("storefront.renderCart: opts required");
   var lines  = opts.lines  || [];
@@ -1156,26 +1184,30 @@ function renderCart(opts) {
     return String(s == null ? "" : s)
       .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
   }
-  var rows = rendered.map(function (l) {
-    var thumb = l.image_url
-      ? "<span class=\"cart-line__thumb\"><img src=\"" + _escAttr(l.image_url) + "\" alt=\"" + _escAttr(l.image_alt) + "\" loading=\"lazy\"></span>"
-      : "<span class=\"cart-line__thumb cart-line__thumb--empty\" aria-hidden=\"true\"></span>";
-    return _render(CART_LINE_EDITABLE, {
-      sku:            l.sku,
-      qty:            l.qty,
-      unit:           l.unit,
-      total:          l.total,
-      line_id:        l.id,
-      product_title:  l.product_title,
-      product_url:    l.product_url,
-    }).replace("RAW_CART_LINE_THUMB", thumb);
-  }).join("");
-  if (!rows) rows = "<tr><td colspan=\"5\" class=\"empty\">Your cart is empty.</td></tr>";
-  var body = _render(CART_PAGE, {
-    line_rows: "RAW_LINES",
-    subtotal:  subtotal,
-    total:     total,
-  }).replace("RAW_LINES", rows);
+  var body;
+  if (rendered.length === 0) {
+    body = CART_EMPTY_PAGE;
+  } else {
+    var rows = rendered.map(function (l) {
+      var thumb = l.image_url
+        ? "<span class=\"cart-line__thumb\"><img src=\"" + _escAttr(l.image_url) + "\" alt=\"" + _escAttr(l.image_alt) + "\" loading=\"lazy\"></span>"
+        : "<span class=\"cart-line__thumb cart-line__thumb--empty\" aria-hidden=\"true\"></span>";
+      return _render(CART_LINE_EDITABLE, {
+        sku:            l.sku,
+        qty:            l.qty,
+        unit:           l.unit,
+        total:          l.total,
+        line_id:        l.id,
+        product_title:  l.product_title,
+        product_url:    l.product_url,
+      }).replace("RAW_CART_LINE_THUMB", thumb);
+    }).join("");
+    body = _render(CART_PAGE, {
+      line_rows: "RAW_LINES",
+      subtotal:  subtotal,
+      total:     total,
+    }).replace("RAW_LINES", rows);
+  }
   return _wrap({
     title:      "Cart",
     shop_name:  shopName,

package/lib/vendor/MANIFEST.json

@@ -3,8 +3,8 @@
   "_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.3",
-      "tag": "v0.12.3",
+      "version": "0.12.4",
+      "tag": "v0.12.4",
       "license": "Apache-2.0",
       "author": "blamejs contributors",
       "source": "https://github.com/blamejs/blamejs",

package/lib/vendor/blamejs/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.4 (2026-05-22) — **`SECURITY.md` Watch list — remove stale "framework doesn't ship CMS / S/MIME" entry.** The Watch list bullet claiming `framework does not ship a CMS / S/MIME / PKCS#7 surface today` has been wrong since v0.10.13 — `b.cms.encodeSignedData` / `decode` / `encodeEnvelopedData` / `parseSignedData` shipped then, and `b.mail.crypto.smime.sign` / `verify` / `verifyAll` / `checkCert` shipped under the mail-stack. The Watch list is for CVE classes the framework deliberately doesn't ship a primitive for; CMS no longer fits that shape. Entry removed. **Fixed:** *Watch list no longer claims CMS / S/MIME are unshipped* — `b.cms` exposes RFC 5652 ContentInfo / SignedData / EnvelopedData encode + decode with PQC signer support (ML-DSA-65 per RFC 9909 §5, ML-DSA-87 per RFC 9909 §6, SLH-DSA-SHAKE-256f per RFC 9881). `b.mail.crypto.smime` builds on it for RFC 8551 S/MIME signed + enveloped mail with `checkCert` for X.509 chain validation. The SECURITY.md Watch list entry that pointed operators to external CMS libraries is gone; operators on regulated mail interop reach for the in-framework primitives instead.
+
 - v0.12.3 (2026-05-22) — **README "What ships in the box" backfill — mail-stack listeners + JSCalendar + new postures.** The README's "Communication" + "Compliance regimes" bullets lagged behind the v0.11.24-v0.12.1 ship cadence. Backfilled: `b.mail.send.deliver` (turnkey outbound delivery chain), the four mail-server listeners (mx / submission / imap / jmap), the JMAP EmailSubmission/set reference handler, mail-crypto (CMS + PGP+WKD), the mail-stack agent, `b.calendar` (RFC 8984 JSCalendar substrate with full BY*+BYSETPOS+multi-rule expansion), and the 16 newly-promoted postures from v0.12.1 (`42-cfr-part-2` / `hti-1` / `uscdi-v4` / `irs-1075` / `nist-800-172-r3` / `tlp-2.0` / `soci-au` / `ffiec-cat-2` / `cri-profile-v2.0` / `m-22-09` / `m-22-18` / `nist-800-53-r5-privacy` / `nist-ai-600-1-genai` / `nist-csf-2.0` / `sb-53` / `nyc-ll144-2024`). **Changed:** *Communication section names every mail-stack listener + delivery chain + crypto primitive* — New entries: `b.mail.send.deliver` (MX → MTA-STS → DANE → REQUIRETLS → SMTP → DSN chain), four `b.mail.server.*` listeners, JMAP EmailSubmission reference handler, `b.mail.crypto.cms` + `b.mail.crypto.pgp`, `b.mail.agent` + `b.mailStore`, and `b.calendar` (JSCalendar / iCalendar bridge for JMAP Calendars interop). · *Compliance regimes section lists the 16 v0.12.1 backfilled postures* — New rows organise the additions under three sub-bullets: AI governance adds `nyc-ll144-2024` / `sb-53` / `nist-ai-rmf-1.0` / `nist-ai-600-1-genai` alongside the existing AI-act / NYC-LL144 / Colorado / Illinois entries; a new "Federal / sectoral" row covers `42-cfr-part-2` / `hti-1` / `uscdi-v4` / `irs-1075` / `nist-csf-2.0` / `nist-800-53-r5-privacy` / `nist-800-172-r3` / `m-22-09` / `m-22-18` / `ffiec-cat-2` / `cri-profile-v2.0`; a new "Critical infrastructure / info-sharing" row covers `soci-au` / `tlp-2.0`.
 
 - v0.12.2 (2026-05-22) — **Release-process docs point at `scripts/release.js` (the orchestrator shipped in v0.12.0).** `CONTRIBUTING.md` (maintainer section) and `examples/wiki/DEPLOY.md` ("Tag-driven releases") described the old multi-step manual release flow — version bump → commit → push → tag → push tag — without mentioning the v0.12.0 orchestrator. Both docs now point at `node scripts/release.js` as the canonical release mechanism, list the eight idempotent subcommands, and call out the two pre-requisites the script enforces (release-notes JSON + signed-commit config). **Added:** *`scripts/release.js regen` — re-run artifact regeneration mid-flow* — Edits to `release-notes/v<next>.json` after `prepare` (e.g. addressing a Codex finding, fixing a leak-vocabulary refusal) previously required running `node scripts/generate-changelog-entry.js --rebuild` + `scripts/refresh-api-snapshot.js` + `scripts/check-api-snapshot.js` + `scripts/check-changelog-extract.js` manually. The new `regen` subcommand wraps all four into a single idempotent step. Safe to run any time from any branch. The `prepare` phase calls the same shared helper internally so behaviour stays consistent. **Changed:** *`CONTRIBUTING.md` maintainer section names the orchestrator* — The release-process bullet now reads `node scripts/release.js — eight idempotent subcommands (prepare → smoke → commit → push → watch → merge → tag → publish) plus all for a one-shot`. The existing DEPLOY.md link stays as a pointer for the wiki-container side of the same flow. · *`examples/wiki/DEPLOY.md` Tag-driven releases section rewritten* — Replaces the four-bullet manual flow with the orchestrator surface, including the `all` / `all --minor` one-shot, the per-phase subcommands, and the pre-requisites the script enforces (release-notes JSON present, SSH signing config in place). The downstream wiki-image deploy step on the host (pin `docker-compose.prod.yml` + `docker compose pull && up -d`) is unchanged. **Fixed:** *`scripts/release.js` signature verification uses `git verify-commit` as the canonical truth* — The v0.12.0 orchestrator's commit-signature gate parsed `git log -1 --pretty=%h %G? %GS` looking for `G` in the second column. On some platforms the `%G?` format token's `?` character can be eaten by argument resolution, returning empty stdout even when the signature is Good. The fix runs `git verify-commit HEAD` (whose exit code is the canonical signal `required_signatures` GH ruleset enforces) as the primary check; the `%G?` parse stays as a human-readable confirmation but no longer gates the script. Surfaced via dogfooding the orchestrator on this very release. · *`scripts/release.js` Docker bind-mount path handles Windows host paths with spaces* — The `push` phase's gitleaks step bind-mounted the repo root via `-v <path>:/repo`. The previous path transform produced `/C:/Users/...` on Windows, which Docker's `-v src:dst[:mode]` parser interpreted as having three colon-separated fields. Fix: transform `C:\Users\...` to `//c/Users/...` (lowercased drive letter, double-slash prefix — matches Git Bash's `$(pwd)` form Docker Desktop accepts). POSIX hosts pass through unchanged. Operators with Windows paths containing spaces, parentheses, or special characters can now run `node scripts/release.js push` without manual mount fiddling.

package/lib/vendor/blamejs/SECURITY.md

@@ -412,7 +412,6 @@ CVE classes the framework tracks but does not currently ship a primitive for —
 - **AdonisJS multipart-filename → arbitrary-write class** — the framework's `b.fileUpload` routes every multipart filename through `b.guardFilename.gate({ profile: "strict" })` by default (path traversal / null-byte / NTFS ADS / UNC / overlong UTF-8 / Windows reserved names / RTLO bidi). Operators implementing a parallel multipart receiver outside the framework's primitive must wire the same gate.
 - **fs.realpath symlink-chain Permission Model bypass class** — see "Operator territory" entry above; the framework's symlink defenses live at the application layer (`b.vault` PEM-file read-side + `b.staticServe` realpath gate); operators using Node's experimental Permission Model add it as defense-in-depth, never as the primary symlink-resolution boundary.
 - **QUIC / HTTP/3 outbound (RFC 9000 / RFC 9001)** — the framework's `b.httpClient` is HTTP/1.1 + HTTP/2 only. QUIC + HTTP/3 are deferred-with-condition: re-open when Node's `--experimental-quic` flag graduates to stable and `node:http3` ships. Until then, operators wanting outbound h3 wire their own client outside the framework (see `lib/http-client.js` header note on the future `kind: "h3"` transport shape). The framework's TLS 1.3 + h2 anti-amplification + flow-control caps remain in force on every other transport. Inbound h3 is similarly deferred; operators terminating h3 at the edge route h2 / h1 to the framework's `b.router`.
-- **CMS (RFC 5083 / RFC 5652) + SHAKE-in-CMS (RFC 8702)** — the framework does not ship a CMS / S/MIME / PKCS#7 surface today. Operators integrating S/MIME-encoded mail or PKCS#7-signed payloads route through a separately-firewalled CMS library and pin the SHAKE-256 / SHA3-512 hash identifiers from RFC 8702 §3 / §4 when they set the signing algorithm. CMS support is deferred-with-condition: re-open when operator demand surfaces for S/MIME-encoded mail receivers OR when a regulatory regime mandates CMS-shaped envelope formats. The framework's existing `b.crypto` envelope (XChaCha20-Poly1305 + ML-KEM-1024 + SLH-DSA) covers the at-rest + in-transit shapes operators need today without the CMS legacy surface.
 
 ---
 

package/lib/vendor/blamejs/api-snapshot.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "frameworkVersion": "0.12.3",
-  "createdAt": "2026-05-22T21:50:06.665Z",
+  "frameworkVersion": "0.12.4",
+  "createdAt": "2026-05-22T23:12:46.997Z",
   "exports": {
     "a2a": {
       "type": "object",

package/lib/vendor/blamejs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/lib/vendor/blamejs/release-notes/v0.12.4.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.12.4",
+  "date": "2026-05-22",
+  "headline": "`SECURITY.md` Watch list — remove stale \"framework doesn't ship CMS / S/MIME\" entry",
+  "summary": "The Watch list bullet claiming `framework does not ship a CMS / S/MIME / PKCS#7 surface today` has been wrong since v0.10.13 — `b.cms.encodeSignedData` / `decode` / `encodeEnvelopedData` / `parseSignedData` shipped then, and `b.mail.crypto.smime.sign` / `verify` / `verifyAll` / `checkCert` shipped under the mail-stack. The Watch list is for CVE classes the framework deliberately doesn't ship a primitive for; CMS no longer fits that shape. Entry removed.",
+  "sections": [
+    {
+      "heading": "Fixed",
+      "items": [
+        {
+          "title": "Watch list no longer claims CMS / S/MIME are unshipped",
+          "body": "`b.cms` exposes RFC 5652 ContentInfo / SignedData / EnvelopedData encode + decode with PQC signer support (ML-DSA-65 per RFC 9909 §5, ML-DSA-87 per RFC 9909 §6, SLH-DSA-SHAKE-256f per RFC 9881). `b.mail.crypto.smime` builds on it for RFC 8551 S/MIME signed + enveloped mail with `checkCert` for X.509 chain validation. The SECURITY.md Watch list entry that pointed operators to external CMS libraries is gone; operators on regulated mail interop reach for the in-framework primitives instead."
+        }
+      ]
+    }
+  ],
+  "references": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {