@blamejs/blamejs-shop 0.0.126 → 0.0.127

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.127 (2026-05-24) — **Self-serve returns — customers request RMAs on their orders, operators approve and refund.** Signed-in customers can request a return against one of their own orders — pick the items and a reason at the order, then track status at /account/returns. Operators work the queue at /admin/returns: approve (with a refund amount), mark received, refund, or reject with a reason, following the pending → approved → received → refunded lifecycle. The customer request route loads the order and confirms it belongs to the signed-in customer before showing it, and builds the return lines from the order's own records, so a foreign or guessed order id returns 404 and a client can't return items it never bought. **Added:** *Customer return requests + status* — `/account/orders/:order_id/return` shows the order's items with a reason picker; `/account/returns` lists the customer's RMAs with status (pending / approved / received / refunded / rejected) and any rejection reason. The account dashboard links to it. Empty selection or a bad reason re-renders the form with the message. · *Operator return queue* — `GET /admin/returns?status=pending` lists the queue across all orders; `GET /admin/returns/:id` reads one; `POST /admin/returns/:id/approve` (with refund amount), `/received`, `/refund`, and `/reject` (with reason) walk the lifecycle. Bearer-token-gated; an illegal transition is a 409 and a bad id a 404, never a 500. · *`returns.listByStatus(status, opts)`* — Lists return authorizations across all orders by status, newest first, with the same opaque cursor as `listForCustomer`. Backs the operator queue.
+
 - v0.0.126 (2026-05-24) — **Address book — saved shipping and billing addresses on the account page.** Signed-in customers can now keep a book of addresses at /account/addresses: add, edit, set a default shipping or billing address, and remove. Addresses are per-customer; every action that targets a specific address first confirms it belongs to the signed-in customer, so a guessed id can't read or change someone else's address. **Added:** *Address book at `/account/addresses`* — List, add, and edit saved addresses (recipient, company, two street lines, city, region, postal code, ISO country, phone). The account dashboard links to it. A blank product catalog isn't required — this is account surface only. · *Default shipping / billing* — Mark one address as the default shipping and one as the default billing; promoting a new default clears the previous one. Surfaced as badges on each card. · *Ownership-checked mutations* — Edit, update, set-default, and remove all resolve the address by id and verify it belongs to the signed-in customer before acting — a foreign or guessed id returns 404, never another customer's data. Add/edit re-render the form with the validation message on bad input.
 
 - v0.0.124 (2026-05-24) — **Save for later — move cart items into a holding list and back.** Each cart line now has a "Save for later" control that moves the item out of the cart into a per-customer holding list without losing it. Saved items live on a new account page where they can be moved back to the cart or removed. Moving an item back reprices it to the current catalog price and checks stock first, so a saved item that sold out (and isn't backorderable) can't silently re-enter the cart. Login-required, since the list is scoped to one customer. **Added:** *Save-for-later control on cart lines* — Each editable cart line gets a Save-for-later control. `POST /cart/lines/:line_id/save` moves the line out of the cart into the customer's saved list (`moveFromCart`). Login-gated — a signed-out shopper is redirected to sign in. · *`/account/saved` — the holding list* — A new account page lists saved items with a thumbnail, the saved price for reference, and Move-to-cart / Remove controls. Items whose product was archived render as "no longer available" rather than breaking the list. The account dashboard links to it (alongside Wishlist). · *Move back to cart, repriced + stock-checked* — `POST /saved/:save_id/move-to-cart` returns the item to the session cart at the current catalog price (not the stale snapshot) and refuses if the SKU is out of stock and not backorderable. `POST /saved/:save_id/remove` drops a saved row.

package/README.md

@@ -67,9 +67,10 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/wishlist.js`** | Per-customer saved products. The PDP renders a login-gated "Save to wishlist" toggle and a "N shoppers saved this" social-proof count; `/account/wishlist` lists saved items (remove + reopen, orphan-tolerant when a product is archived). `POST /wishlist/toggle` is idempotent (`INSERT OR IGNORE`) and redirects to the canonical product slug or a safe same-origin `return_to`. UUID-shape-validated ids, `b.pagination` HMAC cursors. |
 | **`lib/save-for-later.js`** | Per-customer cart holding list. Each cart line gets a login-gated "Save for later" control (`POST /cart/lines/:id/save` → `moveFromCart`); `/account/saved` lists items with Move-to-cart / Remove. `moveToCart` reprices to the current catalog price and stock-gates (out-of-stock + non-backorderable is refused). Composes `catalog.inventory` + `catalog.prices` + `catalog.variants`. |
 | **`lib/addresses.js`** | Per-customer address book at `/account/addresses` — add / edit / set default shipping or billing / remove. One-default-per-role invariant (promoting clears the prior). Every by-id route confirms the address belongs to the signed-in customer before acting (a guessed id returns 404). `b.guardUuid` ids, 2-char ISO country. |
+| **`lib/returns.js`** | Self-serve RMAs. Customer requests a return against their own order at `/account/orders/:id/return` (items + reason, ownership-checked, lines built from the order's own records) and tracks status at `/account/returns`. Operators work `/admin/returns` — approve (refund amount) / mark received / refund / reject — over the pending → approved → received → refunded FSM; illegal transitions are 409, bad ids 404. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`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. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. |
+| **`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. |
 | **`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. |
 
@@ -88,6 +89,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0012_wishlist.sql` — per-customer saved products (unique customer + product + variant)
 - `migrations-d1/0041_save_for_later.sql` — per-customer cart holding list (price snapshot + source line)
 - `migrations-d1/0026_customer_addresses.sql` — per-customer address book (default shipping/billing flags)
+- `migrations-d1/0023_returns.sql` — return authorizations + lines (RMA lifecycle FSM)
 
 ### Demo seed
 

package/lib/admin.js

@@ -163,6 +163,7 @@ function mount(router, deps) {
   var assetPrefix   = typeof deps.asset_prefix === "string" ? deps.asset_prefix : "/assets/";
   var catalogImport = deps.catalogImport || null;   // bulk-import route disabled when absent
   var reviews       = deps.reviews       || null;   // moderation endpoints disabled when absent
+  var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
 
   try { _b().audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -580,6 +581,118 @@ function mount(router, deps) {
     }));
   }
 
+  // ---- returns (moderation) -------------------------------------------
+
+  // Operator-side RMA moderation. The queue lists return
+  // authorizations across all orders in one status (defaults to
+  // `pending`); approve / received / refund / reject walk the same FSM
+  // the customer-facing request path leaves in `pending`. A bad state
+  // transition (e.g. refund-from-pending) and a malformed :id both
+  // surface as client errors (4xx), never a 500. Endpoints are omitted
+  // entirely when no returns primitive is wired.
+  if (returns) {
+    function _returnsClientError(e) {
+      // A transition refused by the FSM or a not-found row is the
+      // caller's problem, not the server's. `_currentStatus` raises a
+      // not-found TypeError; `_assertTransition` raises an Error tagged
+      // RMA_TRANSITION_REFUSED. Map both to 4xx. (Bad-shape input is a
+      // plain TypeError, which the wrapper already maps to 400.)
+      if (!e) return null;
+      if (e.code === "RMA_NOT_FOUND") return { status: 404, slug: "return-not-found" };
+      if (e.code === "RMA_TRANSITION_REFUSED") return { status: 409, slug: "return-transition-refused" };
+      return null;
+    }
+
+    router.get("/admin/returns", R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var status = (url && url.searchParams.get("status")) || "pending";
+      var cursor = url && url.searchParams.get("cursor");
+      var limitS = url && url.searchParams.get("limit");
+      var limit  = limitS == null ? undefined : parseInt(limitS, 10);
+      var page = await returns.listByStatus(status, { cursor: cursor || undefined, limit: limit });
+      _json(res, 200, page);
+    }));
+
+    router.get("/admin/returns/:id", R(async function (req, res) {
+      var rma;
+      try {
+        rma = await returns.get(req.params.id);
+      } catch (e) {
+        // A non-UUID :id raises a guardUuid TypeError — surface it as a
+        // 404 (the route is a defensive request-shape reader, never a
+        // 500). Re-raise anything that isn't the bad-id shape so the
+        // wrapper's generic handling applies.
+        if (e instanceof TypeError) return _problem(res, 404, "return-not-found");
+        throw e;
+      }
+      if (!rma) return _problem(res, 404, "return-not-found");
+      _json(res, 200, rma);
+    }));
+
+    router.post("/admin/returns/:id/approve", W("return.approve", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.approve(req.params.id, {
+          refund_amount_minor: body.refund_amount_minor,
+          refund_currency:     body.refund_currency,
+          operator_notes:      body.operator_notes,
+        });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+
+    router.post("/admin/returns/:id/received", W("return.received", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.markReceived(req.params.id, { operator_notes: body.operator_notes });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+
+    router.post("/admin/returns/:id/refund", W("return.refund", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.refund(req.params.id, { operator_notes: body.operator_notes });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+
+    router.post("/admin/returns/:id/reject", W("return.reject", async function (req, res) {
+      var body = req.body || {};
+      var rma;
+      try {
+        rma = await returns.reject(req.params.id, {
+          rejected_reason: body.rejected_reason,
+          operator_notes:  body.operator_notes,
+        });
+      } catch (e) {
+        var ce = _returnsClientError(e);
+        if (ce) return _problem(res, ce.status, ce.slug, e.message);
+        throw e;
+      }
+      _json(res, 200, rma);
+      return rma;
+    }));
+  }
+
   // ---- config ---------------------------------------------------------
 
   var config = deps.config || null;

package/lib/returns.js

@@ -516,6 +516,57 @@ function create(opts) {
       return { rows: rows, next_cursor: next };
     },
 
+    listByStatus: async function (status, listOpts) {
+      var statusFilter = _status(status);
+      listOpts = listOpts || {};
+      var limit = listOpts.limit == null ? DEFAULT_LIST_LIMIT : listOpts.limit;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIST_LIMIT) {
+        throw new TypeError("returns.listByStatus: limit must be 1..." + MAX_LIST_LIMIT);
+      }
+      var cursorVals = null;
+      if (listOpts.cursor != null) {
+        if (typeof listOpts.cursor !== "string") {
+          throw new TypeError("returns.listByStatus: cursor must be an opaque string or null");
+        }
+        try {
+          var state = _b().pagination.decodeCursor(listOpts.cursor, cursorSecret);
+          if (JSON.stringify(state.orderKey) !== JSON.stringify(RMA_ORDER_KEY)) {
+            throw new TypeError("returns.listByStatus: cursor orderKey mismatch");
+          }
+          cursorVals = state.vals;
+        } catch (e) {
+          if (e instanceof TypeError) throw e;
+          throw new TypeError("returns.listByStatus: cursor — " + (e && e.message || "malformed"));
+        }
+      }
+
+      var sql, params;
+      if (cursorVals) {
+        sql = "SELECT * FROM return_authorizations WHERE status = ?1 AND " +
+              "(created_at < ?2 OR (created_at = ?2 AND id < ?3)) " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?4";
+        params = [statusFilter, cursorVals[0], cursorVals[1], limit];
+      } else {
+        sql = "SELECT * FROM return_authorizations WHERE status = ?1 " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?2";
+        params = [statusFilter, limit];
+      }
+      var rows = (await query(sql, params)).rows;
+      for (var i = 0; i < rows.length; i += 1) {
+        await _hydrate(rows[i]);
+      }
+      var last = rows[rows.length - 1];
+      var next = null;
+      if (last && rows.length === limit) {
+        next = _b().pagination.encodeCursor({
+          orderKey: RMA_ORDER_KEY,
+          vals:     [last.created_at, last.id],
+          forward:  true,
+        }, cursorSecret);
+      }
+      return { rows: rows, next_cursor: next };
+    },
+
     summaryForOperator: async function (input) {
       input = input || {};
       var from = _epochOrNull(input.from, "from");

package/lib/storefront.js

@@ -1134,6 +1134,120 @@ function renderAddresses(opts) {
   });
 }
 
+var RETURN_REASONS = [
+  ["defective", "Defective / doesn't work"],
+  ["wrong-item", "Wrong item received"],
+  ["not-as-described", "Not as described"],
+  ["no-longer-needed", "No longer needed"],
+  ["damaged-in-transit", "Damaged in transit"],
+  ["other", "Other"],
+];
+
+function _returnStatusBadge(status) {
+  return "<span class=\"return-status return-status--" + _b().template.escapeHtml(String(status)) + "\">" +
+    _b().template.escapeHtml(String(status)) + "</span>";
+}
+
+// Customer-facing return-request form for one order. `opts.order` is the
+// order row, `opts.lines` its order_lines. `opts.notice` is an optional
+// error bounced back from a failed POST.
+function renderReturnForm(opts) {
+  var esc = _b().template.escapeHtml;
+  var order = opts.order;
+  var lines = opts.lines || [];
+  var lineRows = "";
+  for (var i = 0; i < lines.length; i += 1) {
+    var l = lines[i];
+    lineRows +=
+      "<li class=\"return-line\">" +
+        "<label class=\"return-line__pick\">" +
+          "<input type=\"checkbox\" name=\"return_" + esc(l.id) + "\" value=\"1\">" +
+          "<span class=\"return-line__sku\"><code>" + esc(l.sku) + "</code></span>" +
+        "</label>" +
+        "<label class=\"return-line__qty\">Qty to return " +
+          "<input type=\"number\" name=\"qty_" + esc(l.id) + "\" value=\"" + (Number(l.qty) || 1) + "\" min=\"1\" max=\"" + (Number(l.qty) || 1) + "\">" +
+          " <span class=\"return-line__of\">of " + (Number(l.qty) || 1) + "</span>" +
+        "</label>" +
+      "</li>";
+  }
+  var reasonOpts = RETURN_REASONS.map(function (r) {
+    return "<option value=\"" + esc(r[0]) + "\">" + esc(r[1]) + "</option>";
+  }).join("");
+  var notice = opts.notice
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.notice)) + "</p>"
+    : "";
+  var body =
+    "<section class=\"return-form-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/returns\">Returns</a></li>" +
+        "<li aria-current=\"page\">Request a return</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"return-form-page__title\">Request a return</h1>" +
+      "<p class=\"return-form-page__order\">Order <code>" + esc(order.id) + "</code></p>" +
+      notice +
+      "<form class=\"return-form form-stack\" method=\"post\" action=\"/account/orders/" + esc(order.id) + "/return\">" +
+        "<fieldset class=\"return-form__lines\"><legend>Which items?</legend>" +
+          "<ul class=\"return-line-list\">" + lineRows + "</ul>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span class=\"form-field__label\">Reason</span>" +
+          "<select name=\"reason\" required>" + reasonOpts + "</select></label>" +
+        "<label class=\"form-field\"><span class=\"form-field__label\">Notes (optional)</span>" +
+          "<textarea name=\"customer_notes\" maxlength=\"2000\" rows=\"4\"></textarea></label>" +
+        "<button type=\"submit\" class=\"btn-primary\">Request return</button>" +
+      "</form>" +
+    "</section>";
+  return _wrap({
+    title:      "Request a return",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// Customer's return-authorization list.
+function renderReturns(opts) {
+  var esc = _b().template.escapeHtml;
+  var rmas = opts.rmas || [];
+  var rowsHtml = "";
+  for (var i = 0; i < rmas.length; i += 1) {
+    var r = rmas[i];
+    var date = r.created_at ? new Date(Number(r.created_at)).toISOString().slice(0, 10) : "";
+    rowsHtml +=
+      "<li class=\"return-card\">" +
+        "<div class=\"return-card__head\">" +
+          "<code class=\"return-card__rma\">" + esc(r.rma_code) + "</code>" +
+          _returnStatusBadge(r.status) +
+        "</div>" +
+        "<p class=\"return-card__meta\">" + esc(String(r.reason || "")) +
+          (date ? " &middot; <time datetime=\"" + esc(date) + "\">" + esc(date) + "</time>" : "") +
+          (Number(r.refund_amount_minor) > 0 ? " &middot; refund " + esc(pricing.format(Number(r.refund_amount_minor), r.refund_currency || "USD")) : "") +
+        "</p>" +
+        (r.status === "rejected" && r.rejected_reason ? "<p class=\"return-card__reject\">" + esc(String(r.rejected_reason)) + "</p>" : "") +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"return-list\">" + rowsHtml + "</ul>"
+    : "<p class=\"return-empty\">No returns yet. Start one from an order in your account.</p>";
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li aria-current=\"page\">Returns</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Returns</h1>" +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      "Returns",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Product-level "Save to wishlist" control + social-proof count.
 // Byte-compatible with the edge renderer (`worker/render/product.js`)
 // so both paths emit identical markup. Action-only label — the toggle
@@ -2066,6 +2180,7 @@ var ACCOUNT_DASH_PAGE =
   "      <a class=\"btn-secondary\" href=\"/account/wishlist\">Wishlist</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/saved\">Saved for later</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/addresses\">Addresses</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/returns\">Returns</a>\n" +
   "      <form method=\"post\" action=\"/account/logout\"><button type=\"submit\" class=\"btn-ghost\">Sign out</button></form>\n" +
   "    </div>\n" +
   "  </header>\n" +
@@ -3214,6 +3329,102 @@ function mount(router, deps) {
       _addrAction("archive",          function (id) { return deps.addresses.archive(id); });
     }
 
+    // Self-serve returns — a customer requests an RMA against one of
+    // their own orders and tracks its status. Operators action it via
+    // the admin /admin/returns queue. Needs the returns primitive + an
+    // order handle (to load + ownership-check the order being returned).
+    if (deps.returns && deps.order) {
+      function _returnsAuth(req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        return auth;
+      }
+      // Load the order named in :order_id and confirm it belongs to the
+      // signed-in customer. A malformed id (guardUuid TypeError), a
+      // missing order, or someone else's order all return 404 — never a
+      // 500, never a leak of another customer's order.
+      async function _ownedOrder(req, res, auth) {
+        var order;
+        try { order = await deps.order.get(req.params && req.params.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return order;
+      }
+
+      router.get("/account/returns", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var page = await deps.returns.listForCustomer(auth.customer_id, { limit: 50 });
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderReturns({ rmas: page.rows, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.get("/account/orders/:order_id/return", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var order = await _ownedOrder(req, res, auth); if (!order) return;
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderReturnForm({ order: order, lines: order.lines || [], shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.post("/account/orders/:order_id/return", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var order = await _ownedOrder(req, res, auth); if (!order) return;
+        var body = req.body || {};
+        var cartCount = await _cartCountForReq(req);
+        // Build the return lines from the order's own lines (authoritative
+        // sku/qty), keyed by the checkboxes the customer ticked — never
+        // trust a client-supplied sku.
+        var orderLines = order.lines || [];
+        var picked = [];
+        for (var i = 0; i < orderLines.length; i += 1) {
+          var ol = orderLines[i];
+          if (body["return_" + ol.id] !== "1") continue;
+          var wanted = parseInt(body["qty_" + ol.id], 10);
+          var qty = Number.isFinite(wanted) && wanted >= 1 && wanted <= ol.qty ? wanted : ol.qty;
+          picked.push({ order_line_id: ol.id, sku: ol.sku, qty: qty });
+        }
+        if (picked.length === 0) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: orderLines, notice: "Select at least one item to return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
+        try {
+          await deps.returns.request({
+            order_id:       order.id,
+            customer_id:    auth.customer_id,
+            reason:         body.reason,
+            customer_notes: body.customer_notes,
+            lines:          picked,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) {
+            return _send(res, 400, renderReturnForm({
+              order: order, lines: orderLines, notice: (e && e.message) || "Please check your return request.",
+              shop_name: shopName, cart_count: cartCount,
+            }));
+          }
+          throw e;
+        }
+        res.status(303); res.setHeader && res.setHeader("location", "/account/returns");
+        return res.end ? res.end() : res.send("");
+      });
+    }
+
     // Product reviews — submission requires a logged-in customer AND a
     // verified purchase of the product (the gate, not just a badge).
     // Only mounts when both the reviews primitive and an order handle

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.32",
-      "tag": "v0.12.32",
+      "version": "0.12.33",
+      "tag": "v0.12.33",
       "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.33 (2026-05-24) — **`b.cose` — COSE_Sign1 sign / verify (RFC 9052) over the in-tree CBOR codec.** COSE is the signed-statement substrate under SCITT, CWT, and C2PA — the CBOR-native counterpart to JWS. `b.cose` ships COSE_Sign1 signing and verification composing the v0.12.32 `b.cbor` codec for the deterministic Sig_structure encoding. It signs with the classical COSE algorithms that interoperate today — ES256 / ES384 / ES512 (ECDSA) and EdDSA (Ed25519), all with final IANA algorithm ids (RFC 9053) — and with ML-DSA-87 (FIPS 204) for PQC-forward deployments. Verification accepts the same set, so the framework both produces COSE other implementations read today and consumes third-party COSE. There is no classical default: the caller names the algorithm and supplies the key. **Added:** *`b.cose.sign(payload, opts)` / `b.cose.verify(coseSign1, opts)`* — `sign` produces a tagged COSE_Sign1 with `alg` in the integrity-protected header; `verify` returns `{ payload, alg, protectedHeaders, unprotectedHeaders }`. The Sig_structure (`["Signature1", protected, external_aad, payload]`) is deterministically CBOR-encoded; ECDSA signatures use the IEEE-P1363 fixed-width encoding COSE mandates (RFC 9053 §2.1), not ASN.1 DER. `external_aad` is bound into the signature. v1 is single-signer with an attached payload; detached payload, COSE_Sign (multi-signer), COSE_Mac0, and COSE_Encrypt are deferred-with-condition (operator demand). **Security:** *Bounded, alg-allowlisted, crit-checked verification* — `verify` decodes the COSE_Sign1 bytes AND the protected-header bstr through the bounded `b.cbor.decode` (depth + size caps, indefinite-length / tag / duplicate-key refusal). `opts.algorithms` is a required allowlist (no defaults — name the accepted algorithms). A `crit` header (label 2) listing a header label the verifier does not understand is refused (RFC 9052 §3.1 crit-bypass defense), as is a `crit` label absent from the protected header. The COSE algorithm switch refuses any unrecognized id at the default branch. · *ML-DSA-87 COSE algorithm id is a non-final draft* — ML-DSA-87 uses COSE algorithm id `-50`, a requested (non-final) IANA assignment from draft-ietf-cose-dilithium — an ML-DSA-87 COSE_Sign1 is not yet broadly interoperable and the id may change; it is pinned deliberately with the re-open condition being IANA finalization. SLH-DSA-SHAKE-256f has no registered COSE algorithm id at all and cannot be represented in COSE. The COSE_Sign1 mechanism and the classical algorithms are stable; ML-DSA-87 is the forward-looking opt-in.
+
 - v0.12.32 (2026-05-24) — **`b.cbor` — bounded, deterministic in-tree CBOR codec (RFC 8949).** CBOR is the binary serialization underneath COSE (RFC 9052), CWT, SCITT, and WebAuthn attestation — a foundational substrate the framework needs in-tree to build signed-statement primitives without a third-party parser. `b.cbor` is that codec, bounded by default like every parser the framework ships: a binary decoder is attack surface, so the defaults refuse the shapes a hostile encoder uses to exhaust memory or stack. The encoder emits Deterministically Encoded CBOR (RFC 8949 §4.2) — shortest-form heads, definite lengths, map keys sorted by encoded bytes, no indefinite-length items — so two semantically-equal values encode to byte-identical output, the property COSE signatures and SCITT receipts depend on. **Added:** *`b.cbor.encode(value, opts?)` / `b.cbor.decode(buffer, opts?)` / `b.cbor.Tag`* — `encode` produces deterministic CBOR from numbers (integers + float64), bigint (64-bit range), strings, `Buffer` / `Uint8Array`, arrays, `Map` or plain objects, `b.cbor.Tag`, and the simple values. `decode` returns the value with maps decoded to a `Map` (CBOR keys may be integers — COSE header labels are) and byte strings to `Buffer`. `b.cbor.Tag(tag, value)` carries a major-type-6 tagged item. `decode(buf, { requireDeterministic: true })` additionally asserts the input was itself canonically encoded (decode → re-encode → byte-compare), refusing a non-canonical re-encoding on a signature-verify path where it would be a malleability vector. **Security:** *Bounded-by-default decoder* — `maxDepth` (default 64, ceiling 256) caps nesting against stack exhaustion; `maxBytes` (default 16 MiB, ceiling 64 MiB) caps total input, and a declared string / array / map length exceeding the remaining bytes is refused before any allocation (no length-prefix memory bomb). Indefinite-length items (additional-info 31) are refused — a streaming-complexity / DoS vector forbidden by deterministic encoding. Reserved additional-info (28–30) is refused. Tags are refused unless allowlisted via `allowedTags` (a tag triggers semantic reprocessing — an un-vetted tag is a confused-deputy vector). Duplicate map keys (RFC 8949 §5.6) and trailing bytes after the data item are refused.
 
 - v0.12.31 (2026-05-24) — **`b.auth.jar.parse` — verify RFC 9101 JWT-Secured Authorization Requests (server side).** A plain OAuth authorization request carries its parameters in the URL query string, where a browser, proxy, or referer log can tamper with or leak them. RFC 9101 JAR packs those parameters into a JWT the client signs — the request object — so the authorization server can confirm they arrived exactly as sent. `b.auth.jar.parse(jar, opts)` is the server-side verifier and the request-side counterpart to the existing JARM response handling (`b.auth.oauth.parseJarmResponse`). It delegates the signature check to `b.auth.jwt.verifyExternal` — which already enforces a mandatory `algorithms` allowlist and refuses the alg-confusion (`alg: "none"`, HMAC-vs-RSA) and JWE-on-a-JWS-verifier shapes against a JWKS public-key trust source — then pins `iss` and the `client_id` claim to the expected client, pins `aud` to this server's issuer identifier, refuses a nested `request` / `request_uri` (RFC 9101 §6.3 recursion / confused-deputy vector), and returns the authorization parameters with the JWT envelope claims stripped. **Added:** *`b.auth.jar.parse(jar, opts)` — request-object verification* — `opts.clientId` (the expected client — pins `iss` + the `client_id` claim), `opts.audience` (this server's issuer identifier — pins `aud`), `opts.algorithms` (required signature allowlist — no defaults, the alg-confusion defense), and one of `opts.jwks` / `opts.jwksUri` / `opts.keyResolver` (the client's verification key). Returns `{ params, claims }` where `params` is the authorization parameters (`response_type`, `redirect_uri`, `scope`, `state`, `nonce`, …) with the JWT envelope claims (`iss`, `aud`, `exp`, `iat`, `nbf`, `jti`) removed. A request object whose `client_id` claim disagrees with `opts.clientId`, or that nests a `request` / `request_uri`, is refused. Emitting a request object (the client side) is deferred-with-condition: it requires signing with the client's key under a classical JWS algorithm, and the framework's own JWT signer is PQC-only for the tokens it issues — a PQC-signed request object would not interoperate with a standard authorization server; client-side emission re-opens when a classical JWS signer lands or operators surface the need. Until then clients sign request objects with their existing JOSE tooling.

package/lib/vendor/blamejs/README.md

@@ -126,6 +126,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **JSON / SQL / schema** — `b.safeJson` (with `maxKeys` cap defending CVE-2026-21717 V8 HashDoS), `b.safeBuffer`, `b.safeSql`, `b.safeSchema`
 - **URL + path** — `b.safeUrl` (IDN mixed-script / homograph refuse); `b.safeJsonPath` (refuses filter `?(...)`, deep-scan `$..`, script-shape `(@.x)` for safe Postgres JSONB ops)
 - **Binary codec** — `b.cbor` bounded deterministic CBOR (RFC 8949 §4.2): depth/size caps, indefinite-length + reserved-info + tag + duplicate-key refusal, `requireDeterministic` canonical-form check; the in-tree substrate under COSE / CWT / SCITT / WebAuthn attestation
+- **COSE signing** — `b.cose` COSE_Sign1 sign/verify (RFC 9052) over `b.cbor`: classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) plus ML-DSA-87 (PQC-forward, draft id); bounded + alg-allowlisted + crit-bypass-checked verification; the signed-statement substrate under SCITT / CWT / C2PA
 - **Document parsers** — `b.parsers` (XML / TOML / YAML / .env); `b.config` (schema-validated env)
 - **File-type detection** — `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.)
 ### Content-safety gates

package/lib/vendor/blamejs/SECURITY.md

@@ -376,6 +376,7 @@ This is the minimum-viable security posture for a production deployment. The fra
 - [ ] For idempotency-key middleware on multi-process fleets — use `b.middleware.idempotencyKey.dbStore({ db: b.db })` instead of `memoryStore`. As of v0.9.15 the dbStore defaults to `hashKeys: true` (operator-supplied keys are sha3-512 namespace-hashed before insert/lookup so the DB never sees raw keys that might carry PII — order numbers / emails / vendor prefixes) and `seal: true` (cached response `headers` + `body` are sealed via `b.cryptoField.sealRow` AEAD envelope when vault is initialized so a DB dump leaks neither). Forensic columns (`status_code` / `fingerprint` / `expires_at`) stay plaintext-queryable without unsealing. Opt-out via `{ hashKeys: false, seal: false }` only with a documented justification
 - [ ] For long-running daemons exposing live metrics — use `b.metrics.snapshot.startWriter({ path, intervalMs, fields })` to flush an atomic JSON snapshot to disk; let a CLI/sidecar consume it via `b.metrics.snapshot.read(path)` + `b.metrics.snapshot.render(snap, { format: "prometheus" | "text" })`. Avoids opening an HTTP port for scrape access. Snapshot read uses `b.safeJson.parse` with a 4 MiB ceiling so a hostile writer with disk-write access can't OOM the reader
 - [ ] For decoding CBOR from untrusted sources (COSE / CWT / WebAuthn attestation objects, IoT payloads): use `b.cbor.decode(buffer, opts)` — bounded by default (depth + total-size caps, indefinite-length + reserved-info refusal), never a raw streaming parser. Allowlist only the tags you process via `allowedTags` (an un-vetted tag triggers semantic reprocessing — a confused-deputy vector), and on a signature-verify path pass `requireDeterministic: true` so a non-canonical re-encoding can't slip a malleable representation past the verifier
+- [ ] For verifying COSE_Sign1 (RFC 9052) signed statements (SCITT receipts, CWT, C2PA manifests): use `b.cose.verify(coseSign1, { algorithms, publicKey })` — `algorithms` is a required allowlist (no defaults, the alg-confusion defense), the COSE bytes + protected header decode through the bounded `b.cbor`, and a `crit` header naming a label the verifier doesn't understand is refused (§3.1 crit-bypass). Bind request context with `externalAad`. ML-DSA-87's COSE id is a non-final draft — prefer the classical ES256 / EdDSA ids for interoperable signing today
 - [ ] For install-pipeline contexts that run BEFORE the framework is installed (Dockerfile build stages, `install.sh`, `update.sh`, SEA bundle verification) — use `b.selfUpdate.standaloneVerifier` (since v0.9.13). It's a zero-dep verifier (only `node:crypto` + `node:fs`) for ECDSA P-384 / Ed25519 / ML-DSA-87 signatures. Operators physically copy the file via `cp "$(node -p "require('@blamejs/core').selfUpdate.standaloneVerifier.path")" install/standalone-verifier.js` into their install pipeline alongside an operator-owned pubkey
 - [ ] For daemons that rotate TLS posture without restarting (pinset reload / certificate refresh / `C.TLS_GROUP_PREFERENCE` updates) — call `b.pqcAgent.reload()` after the posture change so the next `b.pqcAgent.agent` access rebuilds against current TLS state. Existing in-flight sockets complete naturally; idle keep-alive sockets are torn down
 - [ ] For SBOM regeneration / vendor-data integrity sweeps / release-asset bundling — use `b.crypto.hashFilesParallel(filePaths, { algorithms, concurrency, onProgress })` to hash N files in parallel in a single-pass per file. Operator-tunable concurrency cap (default `min(8, paths.length)`, range 1..256) + tunable algorithms list (default `["sha256", "sha3-512"]` for PQC-first + legacy compat). Returns rows in input order

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

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "frameworkVersion": "0.12.32",
-  "createdAt": "2026-05-24T19:44:18.478Z",
+  "frameworkVersion": "0.12.33",
+  "createdAt": "2026-05-24T20:50:22.285Z",
   "exports": {
     "a2a": {
       "type": "object",
@@ -13452,6 +13452,52 @@
         }
       }
     },
+    "cose": {
+      "type": "object",
+      "members": {
+        "ALGORITHMS": {
+          "type": "object",
+          "members": {
+            "ES256": {
+              "type": "primitive",
+              "valueType": "number"
+            },
+            "ES384": {
+              "type": "primitive",
+              "valueType": "number"
+            },
+            "ES512": {
+              "type": "primitive",
+              "valueType": "number"
+            },
+            "EdDSA": {
+              "type": "primitive",
+              "valueType": "number"
+            },
+            "ML-DSA-87": {
+              "type": "primitive",
+              "valueType": "number"
+            }
+          }
+        },
+        "COSE_SIGN1_TAG": {
+          "type": "primitive",
+          "valueType": "number"
+        },
+        "CoseError": {
+          "type": "function",
+          "arity": 4
+        },
+        "sign": {
+          "type": "function",
+          "arity": 2
+        },
+        "verify": {
+          "type": "function",
+          "arity": 2
+        }
+      }
+    },
     "cra": {
       "type": "object",
       "members": {

package/lib/vendor/blamejs/index.js

@@ -456,6 +456,7 @@ module.exports = {
   // the codepoint-stability contract.
   jose:             { jwe: { experimental: require("./lib/jose-jwe-experimental") } },
   cbor:             require("./lib/cbor"),
+  cose:             require("./lib/cose"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/vendor/blamejs/lib/cose.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * @module b.cose
+ * @nav    Crypto
+ * @title  COSE signing (RFC 9052)
+ *
+ * @intro
+ *   COSE_Sign1 signing and verification (RFC 9052 / 9053), composing
+ *   the in-tree <code>b.cbor</code> codec for the deterministic
+ *   Sig_structure encoding. COSE is the signed-statement substrate
+ *   under SCITT, CWT, and C2PA — a CBOR-native counterpart to JWS.
+ *
+ *   <strong>Signing</strong> supports the classical COSE signature
+ *   algorithms that are interoperable today — ES256 / ES384 / ES512
+ *   (ECDSA) and EdDSA (Ed25519), all with final IANA algorithm ids
+ *   (RFC 9053) — alongside ML-DSA-87 (FIPS 204) for PQC-forward
+ *   deployments. There is no classical <em>default</em>: the caller
+ *   names the algorithm and supplies the key. <strong>Verification</strong>
+ *   accepts the same set, so the framework both produces COSE other
+ *   implementations can read today and consumes third-party COSE.
+ *
+ *   <strong>Standards-maturity caveat on the PQC algorithm:</strong>
+ *   the COSE algorithm identifier for ML-DSA-87 is <code>-50</code>, a
+ *   <em>requested</em> (non-final) IANA assignment from
+ *   draft-ietf-cose-dilithium; it may change before that draft is
+ *   published, so an ML-DSA-87 COSE_Sign1 is not yet broadly
+ *   interoperable — pin the identifier deliberately, re-open on IANA
+ *   finalization. SLH-DSA-SHAKE-256f (the framework's default PQC
+ *   signature elsewhere) has <strong>no</strong> COSE algorithm
+ *   identifier registered at all (the COSE SPHINCS+ draft registers
+ *   only the Category-1 'small' sets), so it cannot be represented in
+ *   COSE and is not offered here. The COSE_Sign1 mechanism itself, and
+ *   the classical algorithms, are stable; ML-DSA-87 is the forward-
+ *   looking opt-in.
+ *
+ *   <strong>Verify is bounded.</strong> The COSE_Sign1 bytes and the
+ *   protected-header bstr are decoded through <code>b.cbor.decode</code>
+ *   (depth + size caps, indefinite-length / tag / duplicate-key
+ *   refusal). The protected header is the integrity-protected one;
+ *   <code>alg</code> (label 1) lives there. A <code>crit</code> (label
+ *   2) listing a header label the verifier does not understand is
+ *   refused (RFC 9052 §3.1) — a crit-bypass defense.
+ *
+ *   v1 ships COSE_Sign1 (single-signer) with an attached payload.
+ *   Detached payload, COSE_Sign (multi-signer), COSE_Mac0, and
+ *   COSE_Encrypt are deferred-with-condition (operator demand).
+ *
+ * @card
+ *   COSE_Sign1 sign / verify (RFC 9052) over the in-tree CBOR codec —
+ *   ML-DSA-87 signing (experimental, draft alg id) + classical verify,
+ *   bounded + crit-checked. The substrate under SCITT / CWT / C2PA.
+ */
+
+var nodeCrypto = require("node:crypto");
+var cbor = require("./cbor");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var CoseError = defineClass("CoseError", { alwaysPermanent: true });
+
+var COSE_SIGN1_TAG = 18;                                                               // allow:raw-byte-literal — RFC 9052 COSE_Sign1 CBOR tag
+var HDR_ALG = 1;                                                                       // RFC 9052 §3.1 header label: alg
+var HDR_CRIT = 2;                                                                      // header label: crit
+var HDR_CONTENT_TYPE = 3;                                                              // header label: content type
+var HDR_KID = 4;                                                                       // header label: kid
+
+// COSE algorithm identifiers. ML-DSA-87 is a NON-FINAL requested
+// assignment (draft-ietf-cose-dilithium) — pinned deliberately, re-open
+// on IANA finalization. The classical ECDSA / EdDSA ids are final
+// (RFC 9053). SLH-DSA is intentionally absent (no registered COSE id).
+var ALG_NAME_TO_ID = {
+  "ML-DSA-87": -50,
+  "ES256": -7, "ES384": -35, "ES512": -36, "EdDSA": -8,                                // allow:raw-byte-literal — COSE algorithm identifiers (RFC 9053), not byte sizes
+};
+var ALG_ID_TO_NAME = {};
+Object.keys(ALG_NAME_TO_ID).forEach(function (k) { ALG_ID_TO_NAME[ALG_NAME_TO_ID[k]] = k; });
+
+// Signable algorithms: the classical ECDSA / EdDSA set (final COSE
+// ids, interoperable today) plus ML-DSA-87 (draft id, PQC-forward).
+// All are accepted for VERIFY as well. There is no classical default —
+// the caller names the algorithm explicitly.
+var SIGNABLE = ["ML-DSA-87", "ES256", "ES384", "ES512", "EdDSA"];
+
+// Header labels this verifier understands — a `crit` entry naming any
+// other label is refused (RFC 9052 §3.1 crit-bypass defense).
+var UNDERSTOOD_LABELS = [HDR_ALG, HDR_CRIT, HDR_CONTENT_TYPE, HDR_KID];
+
+function _toKeyObject(key, kind) {
+  if (key && typeof key === "object" && typeof key.asymmetricKeyType === "string") return key;
+  try {
+    return kind === "private" ? nodeCrypto.createPrivateKey(key) : nodeCrypto.createPublicKey(key);
+  } catch (e) {
+    throw new CoseError("cose/bad-key", "cose: could not load " + kind + " key: " + e.message);
+  }
+}
+
+function _algParamsFor(algId) {
+  switch (algId) {
+    case -50: return { nodeAlg: null };                                                // ML-DSA-87 (KeyObject specifies the hash)
+    case -8:  return { nodeAlg: null };                                                // allow:raw-byte-literal — EdDSA COSE alg id (RFC 9053), not a size
+    case -7:  return { nodeAlg: "sha256", dsaEncoding: "ieee-p1363" };                 // ES256
+    case -35: return { nodeAlg: "sha384", dsaEncoding: "ieee-p1363" };                 // ES384
+    case -36: return { nodeAlg: "sha512", dsaEncoding: "ieee-p1363" };                 // ES512
+    default:
+      throw new CoseError("cose/unknown-alg", "cose: unrecognized COSE algorithm id " + algId);
+  }
+}
+
+function _bstr(x) {
+  if (Buffer.isBuffer(x)) return x;
+  if (x instanceof Uint8Array) return Buffer.from(x);
+  if (typeof x === "string") return Buffer.from(x, "utf8");
+  throw new CoseError("cose/bad-bytes", "cose: expected bytes (Buffer / Uint8Array / string)");
+}
+
+// Sig_structure (RFC 9052 §4.4) for COSE_Sign1:
+//   [ "Signature1", body_protected (bstr), external_aad (bstr), payload (bstr) ]
+// deterministically CBOR-encoded — the bytes that are signed / verified.
+function _toBeSigned(protectedBstr, externalAad, payload) {
+  return cbor.encode(["Signature1", protectedBstr, externalAad, payload]);
+}
+
+/**
+ * @primitive b.cose.sign
+ * @signature b.cose.sign(payload, opts)
+ * @since     0.12.33
+ * @status    stable
+ * @related   b.cose.verify, b.cbor.encode
+ *
+ * Produce a tagged COSE_Sign1 (RFC 9052) over <code>payload</code>
+ * (bytes). <code>alg</code> is one of the classical ECDSA / EdDSA
+ * algorithms (final COSE ids, interoperable today) or
+ * <code>"ML-DSA-87"</code> (draft id <code>-50</code>, PQC-forward).
+ * <code>alg</code> is placed in the integrity-protected header.
+ *
+ * @opts
+ *   {
+ *     alg:                 string,    // "ES256" | "ES384" | "ES512" | "EdDSA" | "ML-DSA-87"
+ *     privateKey:          object,    // matching KeyObject or PEM
+ *     kid?:                string,    // → unprotected header label 4
+ *     contentType?:        number,    // → protected header label 3
+ *     externalAad?:        Buffer,    // default empty — bound into the signature
+ *     unprotectedHeaders?: object,    // extra unprotected map entries (numeric keys)
+ *   }
+ *
+ * @example
+ *   var coseSign1 = await b.cose.sign(Buffer.from("statement"), {
+ *     alg: "ES256", privateKey: ecKey, kid: "key-1",
+ *   });
+ */
+async function sign(payload, opts) {
+  validateOpts.requireObject(opts, "cose.sign", CoseError);
+  validateOpts(opts, ["alg", "privateKey", "kid", "contentType", "externalAad", "unprotectedHeaders"], "cose.sign");
+  if (SIGNABLE.indexOf(opts.alg) === -1) {
+    throw new CoseError("cose/unsignable-alg",
+      "cose.sign: alg must be one of " + SIGNABLE.join(" / ") +
+      " (SLH-DSA has no COSE algorithm id and is not offered)");
+  }
+  if (!opts.privateKey) {
+    throw new CoseError("cose/no-key", "cose.sign: opts.privateKey is required");
+  }
+  var algId = ALG_NAME_TO_ID[opts.alg];
+  var params = _algParamsFor(algId);
+  var key = _toKeyObject(opts.privateKey, "private");
+
+  var protMap = new Map();
+  protMap.set(HDR_ALG, algId);
+  if (typeof opts.contentType === "number") protMap.set(HDR_CONTENT_TYPE, opts.contentType);
+  var protectedBstr = cbor.encode(protMap);
+
+  var unprot = new Map();
+  if (typeof opts.kid === "string") unprot.set(HDR_KID, Buffer.from(opts.kid, "utf8"));
+  if (opts.unprotectedHeaders && typeof opts.unprotectedHeaders === "object") {
+    var uk = Object.keys(opts.unprotectedHeaders);
+    for (var i = 0; i < uk.length; i++) unprot.set(Number(uk[i]), opts.unprotectedHeaders[uk[i]]);
+  }
+
+  var payloadBytes = _bstr(payload);
+  var externalAad = opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad);
+  var toBeSigned = _toBeSigned(protectedBstr, externalAad, payloadBytes);
+
+  // ML-DSA-87 + EdDSA: the KeyObject specifies the algorithm, so a
+  // null digest name is correct. ECDSA: a digest + the IEEE-P1363
+  // fixed-width signature encoding COSE mandates (RFC 9053 §2.1, not
+  // ASN.1 DER).
+  var signature = (params.nodeAlg === null)
+    ? nodeCrypto.sign(null, toBeSigned, key)
+    : nodeCrypto.sign(params.nodeAlg, toBeSigned, { key: key, dsaEncoding: params.dsaEncoding });
+
+  var sign1 = [protectedBstr, unprot, payloadBytes, signature];
+  return cbor.encode(new cbor.Tag(COSE_SIGN1_TAG, sign1));
+}
+
+/**
+ * @primitive b.cose.verify
+ * @signature b.cose.verify(coseSign1, opts)
+ * @since     0.12.33
+ * @status    experimental
+ * @related   b.cose.sign, b.cbor.decode
+ *
+ * Verify a COSE_Sign1 (RFC 9052) and return its payload + headers.
+ * The bytes are decoded through the bounded <code>b.cbor</code> codec;
+ * <code>alg</code> is read from the integrity-protected header and must
+ * be in <code>opts.algorithms</code>; a <code>crit</code> header naming
+ * a label the verifier does not understand is refused. Accepts ML-DSA-87
+ * plus the classical ECDSA / EdDSA COSE algorithms.
+ *
+ * @opts
+ *   {
+ *     algorithms:   string[],  // required — accepted alg names (allowlist)
+ *     publicKey?:   object,    // the verification key (KeyObject / PEM)
+ *     keyResolver?: function,  // (protectedHeaders, unprotectedHeaders) → key
+ *     externalAad?: Buffer,    // must match what was signed
+ *     maxBytes?:    number,    // forwarded to b.cbor.decode
+ *     maxDepth?:    number,
+ *   }
+ *
+ * @example
+ *   var out = await b.cose.verify(coseSign1, { algorithms: ["ML-DSA-87"], publicKey: pub });
+ *   // → { payload: <Buffer>, alg: "ML-DSA-87", protectedHeaders: Map, unprotectedHeaders: Map }
+ */
+async function verify(coseSign1, opts) {
+  validateOpts.requireObject(opts, "cose.verify", CoseError);
+  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "externalAad", "maxBytes", "maxDepth"], "cose.verify");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new CoseError("cose/algorithms-required",
+      "cose.verify: opts.algorithms is required (no defaults — name the accepted algorithms)");
+  }
+  for (var ai = 0; ai < opts.algorithms.length; ai++) {
+    if (!(opts.algorithms[ai] in ALG_NAME_TO_ID)) {
+      throw new CoseError("cose/unknown-alg", "cose.verify: unknown algorithm '" + opts.algorithms[ai] + "'");
+    }
+  }
+  if (!opts.publicKey && typeof opts.keyResolver !== "function") {
+    throw new CoseError("cose/no-key", "cose.verify: pass publicKey or keyResolver");
+  }
+
+  var decoded = cbor.decode(_bstr(coseSign1), {
+    allowedTags: [COSE_SIGN1_TAG],
+    maxBytes:    opts.maxBytes,
+    maxDepth:    opts.maxDepth,
+  });
+  // Accept tagged (18) or bare COSE_Sign1 array.
+  var arr = (decoded instanceof cbor.Tag && decoded.tag === COSE_SIGN1_TAG) ? decoded.value : decoded;
+  if (!Array.isArray(arr) || arr.length !== 4) {
+    throw new CoseError("cose/malformed", "cose.verify: not a COSE_Sign1 (expected a 4-element array)");
+  }
+  var protectedBstr = arr[0];
+  var unprotected = arr[1];
+  var payload = arr[2];
+  var signature = arr[3];
+  if (!Buffer.isBuffer(protectedBstr) || !Buffer.isBuffer(signature)) {
+    throw new CoseError("cose/malformed", "cose.verify: protected header and signature must be byte strings");
+  }
+  if (payload === null || payload === undefined) {
+    throw new CoseError("cose/detached-unsupported",
+      "cose.verify: detached payload (nil) is not supported in v1 — attached payload only");
+  }
+  // COSE_Sign1 payload is a bstr (RFC 9052 §4.2) — refuse a non-byte
+  // payload rather than return a value that violates the documented
+  // { payload: Buffer } shape.
+  if (!Buffer.isBuffer(payload)) {
+    throw new CoseError("cose/malformed", "cose.verify: payload must be a byte string (bstr)");
+  }
+  // The unprotected header is a CBOR map — refuse a non-map rather
+  // than silently coerce it to empty (callers read kid etc. from it).
+  if (!(unprotected instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.verify: unprotected header must be a CBOR map");
+  }
+
+  // Decode the protected header (bounded) — empty bstr means no protected headers.
+  var protMap = protectedBstr.length === 0 ? new Map()
+    : cbor.decode(protectedBstr, { maxBytes: opts.maxBytes, maxDepth: opts.maxDepth });
+  if (!(protMap instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.verify: protected header is not a CBOR map");
+  }
+
+  // crit-bypass defense: every label in a crit array must be one the
+  // verifier understands AND must be present in the protected header.
+  if (protMap.has(HDR_CRIT)) {
+    var crit = protMap.get(HDR_CRIT);
+    if (!Array.isArray(crit)) {
+      throw new CoseError("cose/bad-crit", "cose.verify: crit (label 2) must be an array");
+    }
+    for (var ci = 0; ci < crit.length; ci++) {
+      if (UNDERSTOOD_LABELS.indexOf(crit[ci]) === -1) {
+        throw new CoseError("cose/crit-unknown",
+          "cose.verify: crit lists header label " + crit[ci] + " which is not understood (RFC 9052 §3.1)");
+      }
+      if (!protMap.has(crit[ci])) {
+        throw new CoseError("cose/crit-absent",
+          "cose.verify: crit lists label " + crit[ci] + " not present in the protected header");
+      }
+    }
+  }
+
+  var algId = protMap.get(HDR_ALG);
+  var algName = ALG_ID_TO_NAME[algId];
+  if (algName === undefined) {
+    throw new CoseError("cose/unknown-alg", "cose.verify: unrecognized protected alg id " + algId);
+  }
+  if (opts.algorithms.indexOf(algName) === -1) {
+    throw new CoseError("cose/alg-not-allowed",
+      "cose.verify: alg '" + algName + "' is not in the allowlist");
+  }
+  var params = _algParamsFor(algId);                                                    // throws cose/unknown-alg on an unrecognized id
+
+  var key = opts.publicKey
+    ? _toKeyObject(opts.publicKey, "public")
+    : _toKeyObject(opts.keyResolver(protMap, unprotected), "public");
+
+  var externalAad = opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad);
+  var toBeSigned = _toBeSigned(protectedBstr, externalAad, payload);
+
+  var ok;
+  if (params.nodeAlg === null) {
+    ok = nodeCrypto.verify(null, toBeSigned, key, signature);
+  } else {
+    ok = nodeCrypto.verify(params.nodeAlg, toBeSigned,
+      { key: key, dsaEncoding: params.dsaEncoding }, signature);
+  }
+  if (!ok) {
+    throw new CoseError("cose/bad-signature", "cose.verify: signature verification failed");
+  }
+  return {
+    payload:             payload,
+    alg:                 algName,
+    protectedHeaders:    protMap,
+    unprotectedHeaders:  unprotected,
+  };
+}
+
+module.exports = {
+  sign:        sign,
+  verify:      verify,
+  ALGORITHMS:  ALG_NAME_TO_ID,
+  COSE_SIGN1_TAG: COSE_SIGN1_TAG,
+  CoseError:   CoseError,
+};

package/lib/vendor/blamejs/package.json

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

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.12.33",
+  "date": "2026-05-24",
+  "headline": "`b.cose` — COSE_Sign1 sign / verify (RFC 9052) over the in-tree CBOR codec",
+  "summary": "COSE is the signed-statement substrate under SCITT, CWT, and C2PA — the CBOR-native counterpart to JWS. `b.cose` ships COSE_Sign1 signing and verification composing the v0.12.32 `b.cbor` codec for the deterministic Sig_structure encoding. It signs with the classical COSE algorithms that interoperate today — ES256 / ES384 / ES512 (ECDSA) and EdDSA (Ed25519), all with final IANA algorithm ids (RFC 9053) — and with ML-DSA-87 (FIPS 204) for PQC-forward deployments. Verification accepts the same set, so the framework both produces COSE other implementations read today and consumes third-party COSE. There is no classical default: the caller names the algorithm and supplies the key.",
+  "sections": [
+    {
+      "heading": "Added",
+      "items": [
+        {
+          "title": "`b.cose.sign(payload, opts)` / `b.cose.verify(coseSign1, opts)`",
+          "body": "`sign` produces a tagged COSE_Sign1 with `alg` in the integrity-protected header; `verify` returns `{ payload, alg, protectedHeaders, unprotectedHeaders }`. The Sig_structure (`[\"Signature1\", protected, external_aad, payload]`) is deterministically CBOR-encoded; ECDSA signatures use the IEEE-P1363 fixed-width encoding COSE mandates (RFC 9053 §2.1), not ASN.1 DER. `external_aad` is bound into the signature. v1 is single-signer with an attached payload; detached payload, COSE_Sign (multi-signer), COSE_Mac0, and COSE_Encrypt are deferred-with-condition (operator demand)."
+        }
+      ]
+    },
+    {
+      "heading": "Security",
+      "items": [
+        {
+          "title": "Bounded, alg-allowlisted, crit-checked verification",
+          "body": "`verify` decodes the COSE_Sign1 bytes AND the protected-header bstr through the bounded `b.cbor.decode` (depth + size caps, indefinite-length / tag / duplicate-key refusal). `opts.algorithms` is a required allowlist (no defaults — name the accepted algorithms). A `crit` header (label 2) listing a header label the verifier does not understand is refused (RFC 9052 §3.1 crit-bypass defense), as is a `crit` label absent from the protected header. The COSE algorithm switch refuses any unrecognized id at the default branch."
+        },
+        {
+          "title": "ML-DSA-87 COSE algorithm id is a non-final draft",
+          "body": "ML-DSA-87 uses COSE algorithm id `-50`, a requested (non-final) IANA assignment from draft-ietf-cose-dilithium — an ML-DSA-87 COSE_Sign1 is not yet broadly interoperable and the id may change; it is pinned deliberately with the re-open condition being IANA finalization. SLH-DSA-SHAKE-256f has no registered COSE algorithm id at all and cannot be represented in COSE. The COSE_Sign1 mechanism and the classical algorithms are stable; ML-DSA-87 is the forward-looking opt-in."
+        }
+      ]
+    }
+  ]
+}

package/lib/vendor/blamejs/test/layer-0-primitives/codebase-patterns.test.js

@@ -2237,6 +2237,21 @@ async function testNoDuplicateCodeBlocks() {
       ],
       reason: "v0.12.29 — input-shape validation prelude (`validateOpts(allowedKeys) + chained typeof / range guards + typed-error throw`). ai-dp.mechanism validates a DP mechanism descriptor (type / sensitivity / epsilon / delta / bound); dora._validateReportInput validates a DORA Art. 17 incident report; config.loadDbBacked validates DB-backed config opts; guard-snapshot-envelope.validate validates a sealed snapshot envelope. Each enforces a distinct spec's field set with a primitive-specific typed error; the shingle is the validateOpts-then-guard idiom, not behaviour.",
     },
+    {
+      mode:  "family-subset",
+      files: [
+        "lib/cose.js:verify",
+        "lib/auth/sd-jwt-vc-issuer.js:create",
+        "lib/break-glass.js:_validatePolicySet",
+        "lib/calendar.js:validate",
+        "lib/db.js:declareRequireDualControl",
+        "lib/dsr.js:create",
+        "lib/fedcm.js:wellKnown",
+        "lib/middleware/assetlinks.js:create",
+        "lib/network-heartbeat.js:start",
+      ],
+      reason: "v0.12.33 — opts / structure validation prelude (`validateOpts(allowedKeys) + chained required-field + typeof guards + typed-error throw`). cose.verify validates a COSE_Sign1 opts blob + decoded structure (RFC 9052); the peers each validate a distinct spec's shape (SD-JWT-VC issuer opts / break-glass policy set / JSCalendar object / DDL dual-control declaration / DSR request / FedCM well-known manifest / Android Asset Links / heartbeat config). Each throws a primitive-specific typed error; the shingle is the validateOpts-then-guard idiom, not behaviour. Same family as the v0.12.29 input-shape-validation cluster.",
+    },
     {
       mode:  "family-subset",
       files: [

package/lib/vendor/blamejs/test/layer-0-primitives/cose.test.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Layer 0 — b.cose COSE_Sign1 (RFC 9052) sign/verify over the in-tree
+ * b.cbor codec. Classical ECDSA / EdDSA (final COSE ids, useable
+ * today) + ML-DSA-87 (draft id, PQC-forward). Bounded decode +
+ * crit-bypass + alg-allowlist + tamper + external-aad binding.
+ */
+
+var b = require("../../index");
+var helpers = require("../helpers");
+var check = helpers.check;
+var nodeCrypto = require("node:crypto");
+
+var EC = nodeCrypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+var ED = nodeCrypto.generateKeyPairSync("ed25519");
+var ML = nodeCrypto.generateKeyPairSync("ml-dsa-87");
+
+function testSurface() {
+  check("b.cose.sign exposed", typeof b.cose.sign === "function");
+  check("b.cose.verify exposed", typeof b.cose.verify === "function");
+  check("b.cose.ALGORITHMS exposes COSE alg ids", b.cose.ALGORITHMS["ES256"] === -7 && b.cose.ALGORITHMS["ML-DSA-87"] === -50);
+  check("b.cose.COSE_SIGN1_TAG is 18", b.cose.COSE_SIGN1_TAG === 18);
+  check("b.cose.CborError-style CoseError exposed", typeof b.cose.CoseError === "function");
+}
+
+async function testClassicalUseableToday() {
+  var s = await b.cose.sign(Buffer.from("hello"), { alg: "ES256", privateKey: EC.privateKey, kid: "k1" });
+  check("ES256: output is a tagged COSE_Sign1 (tag 18 → 0xd2)", s[0] === 0xd2);
+  var v = await b.cose.verify(s, { algorithms: ["ES256"], publicKey: EC.publicKey });
+  check("ES256: round-trips payload + alg", v.payload.toString() === "hello" && v.alg === "ES256");
+  check("ES256: kid surfaced in unprotected headers", Buffer.isBuffer(v.unprotectedHeaders.get(4)) && v.unprotectedHeaders.get(4).toString() === "k1");
+  check("ES256: alg in protected header", v.protectedHeaders.get(1) === -7);
+
+  var sed = await b.cose.sign("msg", { alg: "EdDSA", privateKey: ED.privateKey });
+  check("EdDSA: round-trips (string payload → bstr)", (await b.cose.verify(sed, { algorithms: ["EdDSA"], publicKey: ED.publicKey })).payload.toString() === "msg");
+}
+
+async function testPqcForward() {
+  var s = await b.cose.sign(Buffer.from("pqc"), { alg: "ML-DSA-87", privateKey: ML.privateKey });
+  var v = await b.cose.verify(s, { algorithms: ["ML-DSA-87"], publicKey: ML.publicKey });
+  check("ML-DSA-87: round-trips (COSE alg -50, draft)", v.payload.toString() === "pqc" && v.alg === "ML-DSA-87" && v.protectedHeaders.get(1) === -50);
+}
+
+async function testTamperAndAllowlist() {
+  var s = await b.cose.sign(Buffer.from("data"), { alg: "ES256", privateKey: EC.privateKey });
+  var t = Buffer.from(s); t[t.length - 1] ^= 0xff;
+  var tampered = null;
+  try { await b.cose.verify(t, { algorithms: ["ES256"], publicKey: EC.publicKey }); } catch (e) { tampered = e; }
+  check("verify: tampered signature refused", tampered && tampered.code === "cose/bad-signature");
+
+  var notAllowed = null;
+  try { await b.cose.verify(s, { algorithms: ["EdDSA"], publicKey: EC.publicKey }); } catch (e) { notAllowed = e; }
+  check("verify: alg not in allowlist refused", notAllowed && notAllowed.code === "cose/alg-not-allowed");
+
+  // external_aad must match what was signed.
+  var sa = await b.cose.sign(Buffer.from("d"), { alg: "ES256", privateKey: EC.privateKey, externalAad: Buffer.from("ctx-A") });
+  var aadMismatch = null;
+  try { await b.cose.verify(sa, { algorithms: ["ES256"], publicKey: EC.publicKey, externalAad: Buffer.from("ctx-B") }); } catch (e) { aadMismatch = e; }
+  check("verify: external_aad mismatch refused", aadMismatch && aadMismatch.code === "cose/bad-signature");
+  var aadOk = await b.cose.verify(sa, { algorithms: ["ES256"], publicKey: EC.publicKey, externalAad: Buffer.from("ctx-A") });
+  check("verify: matching external_aad accepted", aadOk.payload.toString() === "d");
+}
+
+async function testCritBypassDefense() {
+  // Craft a COSE_Sign1 whose protected header lists an unknown crit
+  // label (99). The crit check fires before signature verification —
+  // an unknown mandatory label must be refused (RFC 9052 §3.1).
+  var protMap = new Map([[1, -7], [2, [99]]]);
+  var protectedBstr = b.cbor.encode(protMap);
+  var arr = [protectedBstr, new Map(), Buffer.from("p"), Buffer.from([0, 0])];
+  var coseBytes = b.cbor.encode(new b.cbor.Tag(18, arr));
+  var refused = null;
+  try { await b.cose.verify(coseBytes, { algorithms: ["ES256"], publicKey: EC.publicKey }); } catch (e) { refused = e; }
+  check("verify: unknown crit label refused (crit-bypass defense)", refused && refused.code === "cose/crit-unknown");
+}
+
+async function testValidation() {
+  var bads = [
+    [function () { return b.cose.sign(Buffer.from("x"), { alg: "SLH-DSA-SHAKE-256f", privateKey: ML.privateKey }); }, "cose/unsignable-alg"],
+    [function () { return b.cose.sign(Buffer.from("x"), { alg: "ES256" }); }, "cose/no-key"],
+    [function () { return b.cose.verify(Buffer.from([0x84]), { publicKey: EC.publicKey }); }, "cose/algorithms-required"],
+    [function () { return b.cose.verify(Buffer.from([0x84]), { algorithms: ["ES256"] }); }, "cose/no-key"],
+  ];
+  var ok = true;
+  for (var i = 0; i < bads.length; i++) {
+    var caught = null;
+    try { await bads[i][0](); } catch (e) { caught = e; }
+    if (!caught || caught.code !== bads[i][1]) { ok = false; check("validation " + i + " expected " + bads[i][1] + " got " + (caught && caught.code), false); }
+  }
+  check("sign/verify: malformed args throw the right codes", ok);
+
+  // Detached payload (nil) is explicitly unsupported in v1.
+  var protBstr = b.cbor.encode(new Map([[1, -7]]));
+  var detached = b.cbor.encode(new b.cbor.Tag(18, [protBstr, new Map(), null, Buffer.from([0, 0])]));
+  var det = null;
+  try { await b.cose.verify(detached, { algorithms: ["ES256"], publicKey: EC.publicKey }); } catch (e) { det = e; }
+  check("verify: detached payload refused (v1 attached-only)", det && det.code === "cose/detached-unsupported");
+
+  // Codex P2 on PR #184 — a non-byte payload (text string here) must
+  // be refused, not returned as a non-Buffer.
+  var textPayload = b.cbor.encode(new b.cbor.Tag(18, [protBstr, new Map(), "not-bytes", Buffer.from([0, 0])]));
+  var np = null;
+  try { await b.cose.verify(textPayload, { algorithms: ["ES256"], publicKey: EC.publicKey }); } catch (e) { np = e; }
+  check("verify: non-byte payload refused", np && np.code === "cose/malformed");
+
+  // Codex P2 on PR #184 — a non-map unprotected header must be refused,
+  // not silently coerced to empty.
+  var badUnprot = b.cbor.encode(new b.cbor.Tag(18, [protBstr, ["array-not-map"], Buffer.from("p"), Buffer.from([0, 0])]));
+  var bu = null;
+  try { await b.cose.verify(badUnprot, { algorithms: ["ES256"], publicKey: EC.publicKey }); } catch (e) { bu = e; }
+  check("verify: non-map unprotected header refused", bu && bu.code === "cose/malformed");
+}
+
+async function run() {
+  testSurface();
+  await testClassicalUseableToday();
+  await testPqcForward();
+  await testTamperAndAllowlist();
+  await testCritBypassDefense();
+  await testValidation();
+}
+
+module.exports = { run: run };
+
+if (require.main === module) {
+  run().then(
+    function () { console.log("[cose] OK — " + helpers.getChecks() + " checks passed"); },
+    function (e) { console.error("FAIL:", e && e.stack || e); process.exit(1); }
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.0.126",
+  "version": "0.0.127",
   "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": {