@blamejs/blamejs-shop 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.16 (2026-05-25) — **PayPal express checkout — the on-page button.** PayPal checkout is now usable from the storefront. When PayPal is configured, the checkout page shows a native PayPal button (distinct from PayPal-through-Stripe): it opens a PayPal order for the current cart, the buyer approves in the PayPal popup, and the order is captured and marked paid. A verified PayPal webhook is the asynchronous backstop. This completes the native PayPal integration on top of the adapter and checkout orchestration shipped in the previous two releases. Card / Stripe checkout is unchanged. **Added:** *PayPal button + create/capture routes on the storefront* — The checkout page renders a PayPal button when `PAYPAL_CLIENT_ID` is configured. Its create step posts to `POST /checkout/paypal/create` (prices the cart, opens a PayPal order, persists the local order pending) and its approve step posts to `POST /checkout/paypal/capture` (captures and advances the order to paid, then redirects to the order page). Both validate input and never 500 on a missing cart or id. The buttons collect the same shipping fields as the card form. · *PayPal webhook endpoint* — `POST /api/webhooks/paypal` is the asynchronous backstop for captures completed or refunded out of band. The container verifies each event server-to-server through PayPal's verify-webhook-signature API (no edge HMAC pre-check, unlike Stripe), then advances the order; re-deliveries are idempotent. Point a PayPal webhook at `/api/webhooks/paypal`. **Changed:** *PayPal listed as configurable; CSP note* — The integrations status page and README document PayPal as a first-class checkout option once configured. As with the Stripe pay page's `js.stripe.com`, operators must allow `www.paypal.com` in their Content-Security-Policy `script-src` / `frame-src` for the PayPal SDK and approval popup.
+
+- v0.1.15 (2026-05-25) — **PayPal checkout orchestration.** Checkout can now run a PayPal order end to end, building on the adapter from the previous release. The orchestrator prices the cart, opens a PayPal order and persists the local order as pending, captures it after the buyer approves and advances the order to paid, and has a webhook backstop for captures completed or refunded out of band. Wired in when a PayPal app's credentials are present, and surfaced on the integrations status page. The storefront button and routes that drive this from the pay page come next; card / Stripe checkout is unchanged. **Added:** *checkout PayPal methods* — With a PayPal adapter wired (`paypal` dep), checkout gains three methods. `createPaypalOrder({ cart_id, ship_to, selected_shipping_id, customer, idempotency_key, return_url?, cancel_url? })` prices the cart, opens a PayPal Orders-v2 order, persists the local order in `pending` with the PayPal order id linked, and marks the cart converted. `capturePaypalOrder(paypalOrderId)` captures the approved order and advances the local order to `paid` (idempotent — a retry or a webhook that beat it won't double-transition). `handlePaypalEvent({ headers, rawBody })` is the asynchronous backstop: it verifies the event through PayPal, then maps `PAYMENT.CAPTURE.COMPLETED` → paid and `PAYMENT.CAPTURE.REFUNDED` → refunded, idempotent across re-deliveries. · *PayPal wired from configuration* — When `PAYPAL_CLIENT_ID` + `PAYPAL_SECRET` are set (with `PAYPAL_ENV` and `PAYPAL_WEBHOOK_ID`), the server builds the PayPal adapter and passes it to checkout; the integrations status page lists PayPal as action-needed once card checkout is also live. Off until configured; the existing checkout flow is untouched.
+
 - v0.1.14 (2026-05-25) — **PayPal payment adapter (Orders v2).** `payment.create({ adapter: "paypal", … })` is a new native PayPal adapter alongside the Stripe one — a from-scratch Orders-v2 client over the framework's SSRF-gated HTTP client, with no PayPal SDK dependency. It exchanges an OAuth2 client-credentials token (cached until it nears expiry), creates and captures orders, fetches and refunds them, and verifies inbound webhooks through PayPal's verify-webhook-signature API. This ships the adapter only; wiring it into the checkout flow and a storefront button comes next. Card / Stripe checkout is unchanged. **Added:** *PayPal Orders-v2 adapter* — `payment.create({ adapter: "paypal", clientId, secret, sandbox?, webhookId?, apiBase? })` returns `{ createOrder, captureOrder, getOrder, refund, verifyWebhook }`. `createOrder({ amount_minor, currency, order_id?, return_url?, cancel_url? })` opens a CAPTURE-intent order (amounts converted to PayPal's decimal-string major units, including 0-decimal currencies); `captureOrder(id)` finalizes it; `refund({ capture_id, amount_minor?, currency? })` refunds full or partial; `getOrder(id)` reads status. Every call carries an OAuth2 bearer token exchanged once and cached until ~2 minutes before expiry, and a `PayPal-Request-Id` for idempotency (plus the shared idempotency cache when a `query` handle is wired). `verifyWebhook(headers, rawBody, { webhookId })` confirms an inbound event through PayPal's verify-webhook-signature API and returns `{ ok, event }`. Outbound HTTP goes through `b.httpClient` — no `paypal` npm dependency. Off until the operator supplies credentials; the Stripe adapter and existing checkout are unchanged.
 
 - v0.1.13 (2026-05-25) — **Internal: uniform framework access across the library.** An internal consistency refactor with no API or behavior change. Every library module now captures the framework once at the top — straight from the vendored tree (`var b = require("./vendor/blamejs");`) — and uses `b.*` uniformly, replacing a per-module lazy accessor and its scattered call sites. Capturing the framework directly (rather than via the composing entry point) also avoids a circular-load edge case on leaf-first imports. Two source files that embedded a raw NUL byte as a map-key separator now use the `\u0000` escape, so the whole library is plain text. New lint rules lock all of this in place. Public APIs, runtime behavior, and the published surface are unchanged. **Added:** *Lint detectors for accessor uniformity and source hygiene* — Three repository lint rules now prevent drift: one rejects the reintroduction of the per-module lazy framework accessor (capture the framework once at module top); one rejects requiring the composing entry point from a leaf module (require the vendored framework directly — entry-point requires from a leaf create a circular-load hazard); and one rejects raw C0 control bytes in source files (write `\u0000` and friends as escapes so files stay plain text — grep / diff / editors handle them correctly). **Changed:** *Framework handle captured once per module* — Library modules previously reached the vendored framework through a lazy `_b()` accessor invoked at every call site. They now capture it once at module top — `var b = require("./vendor/blamejs");`, the same object the entry point re-exports as `.framework` — and reference `b.*` directly, matching how the edge worker already accesses it. Capturing it directly from the vendored tree (instead of through the composing entry point) keeps leaf-first module imports working — requiring a single module no longer pulls the entry point's whole assembly mid-initialization. No public API or runtime behavior changes.

package/README.md

@@ -57,9 +57,9 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/pricing.js`** | Pure-function money math — `lineTotal`, `subtotal`, `totals`, `format`. Multi-currency refused, banker's-style rounding, locale-aware via `Intl.NumberFormat`. |
 | **`lib/tax.js`** | Operator-table adapter. Country / state / postal_prefix → rate_bps. Most-specific-first match, banker's rounding. Pluggable adapter shape for future Stripe Tax / TaxJar / Avalara. |
 | **`lib/shipping.js`** | Operator-table adapter. Services with zones (flat or per-gram + base + min/max), free-over-threshold, `digital_only` flag. |
-| **`lib/payment.js`** | Stripe adapter — verify webhook (HMAC-SHA256 via upstream `b.webhook.verify` alg `hmac-sha256-stripe`), create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains (Apple Pay + Google Pay enablement for the Express Checkout Element). No `stripe` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
+| **`lib/payment.js`** | Payment adapters — **Stripe** (verify webhook HMAC-SHA256 via upstream `b.webhook.verify`, create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains for Apple/Google Pay) and **PayPal** (`adapter: "paypal"` — OAuth2 client-credentials token, create / capture / get / refund Orders v2, webhook verify via PayPal's verify-webhook-signature API). No `stripe` / `paypal` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
 | **`lib/order.js`** | FSM-driven post-checkout record via upstream `b.fsm`. States: pending → paid → fulfilling → shipped → delivered (+ refunded / cancelled). Every transition appends to `order_transitions`. |
-| **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` creates PaymentIntent + persists order in pending; `handleStripeEvent()` verifies webhook + fires the FSM transition (idempotent on re-delivery). |
+| **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` creates a Stripe PaymentIntent + persists order pending; `handleStripeEvent()` verifies webhook + fires the FSM transition. PayPal path: `createPaypalOrder()` opens a PayPal order + persists pending, `capturePaypalOrder()` captures → paid, `handlePaypalEvent()` is the webhook backstop. All idempotent on re-delivery. |
 | **`lib/email.js`** | Transactional templates — order receipt, ship notification, refund confirmation. Strict `{{var}}` renderer with HTML escape + refusal of unknown / unused placeholders. Composed on `b.mail` (DKIM/SPF/DMARC/BIMI upstream). |
 | **`lib/storefront.js`** | Server-rendered HTML — utility bar + sticky header + dark hero with code-preview card + primitives marquee + featured-product callout + collections grid + framework feature band + designed catalog grid + newsletter band + four-column footer. Designed surfaces also for PDP, cart, checkout, pay, order, account login / register / dashboard, search results, `/admin` API landing, 404. Image-bearing cards on the home + search grids pull from `catalog.media`. The default theme stylesheet is external (R2-served `themes/default/assets/css/main.css`) and CSP-compliant — operators override by uploading a replacement at the same key, by passing `opts.theme_css` to renderers, or by registering a named theme through the `theme` primitive. |
 | **`lib/customers.js`** | Customer accounts — passkey (WebAuthn) + **Sign in with Google / Apple** (OIDC). Email is stored hash-only (`b.crypto.namespaceHash` namespace `customer-email`); the raw address never lands in D1. Passkey credentials carry CBOR-encoded public keys, transport hints, and SHA3-512-fingerprinted attestation. `signInWithOIDC` keys federated accounts on the provider `(provider, subject)` and links an existing account only on a provider-verified email (never on an unverified one). `mintAppleClientSecret` produces Apple's required ES256 client-secret JWT from a Services-ID `.p8` key (the one classical signature the protocol mandates; the PQC default doesn't apply to an external IdP's wire format). Account routes (`/account/login`, `/account/register`, `/account`, `/account/login/google`, `/account/login/apple`) ship as designed cards on the storefront. |
@@ -163,10 +163,10 @@ variables. A signed-in operator can see the live on/off status of each at
 | **Apple Pay & Google Pay** | One-tap wallet buttons (Express Checkout Element) on the pay page. | Stripe (above) **+** register each web domain: `POST /admin/payment-method-domains {"domain_name":"shop.example.com"}` | Stripe performs Apple merchant validation and hosts the association file — **no Apple Developer account needed**. Apex, `www`, and each subdomain register separately; a live-mode registration also covers sandbox. |
 | **Sign in with Google** | A *Continue with Google* button on `/account/login` (OIDC). | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `SHOP_ORIGIN` (e.g. `https://shop.example.com`) | Create a Google Cloud **OAuth 2.0 Web** client; add `<SHOP_ORIGIN>/account/auth/google/callback` as an Authorized redirect URI; consent-screen scopes `openid email profile`. The button appears only when all three are set. |
 | **Sign in with Apple** | A *Continue with Apple* button on `/account/login` (OIDC). | `APPLE_TEAM_ID`, `APPLE_KEY_ID`, `APPLE_CLIENT_ID` (your **Services ID**), `APPLE_PRIVATE_KEY` (the `.p8` key contents), `SHOP_ORIGIN` | Needs an **Apple Developer Program** membership. Create a Services ID, enable Sign in with Apple, add `<SHOP_ORIGIN>/account/auth/apple/callback` as a Return URL, and create a Sign-in-with-Apple key (`.p8`). The shop mints Apple's ES256 client secret from the key at boot (re-minted each deploy, inside Apple's 6-month window). The button appears only when all five are set. |
+| **PayPal checkout** | A native PayPal button on `/checkout` (PayPal Orders v2 — create / approve / capture), distinct from PayPal-through-Stripe. | `PAYPAL_CLIENT_ID`, `PAYPAL_SECRET` (a PayPal REST app), `PAYPAL_WEBHOOK_ID`, `PAYPAL_ENV` (`sandbox`\|`live`); Stripe checkout must also be live | The shop exchanges the OAuth2 token and creates / captures orders server-side; the button drives `/checkout/paypal/create` + `/checkout/paypal/capture`. Point a PayPal webhook at `/api/webhooks/paypal` (verified through PayPal's API). Allow `www.paypal.com` in your CSP `script-src` / `frame-src` (as you would `js.stripe.com`). |
 
 **Planned / not available:**
 
-- **PayPal** — a separate adapter (Orders v2 + its own webhook); planned.
 - **Shop Pay / "Sign in with Shop"** — **not available** to a self-hosted,
   non-Shopify store: the credentials only issue from a Shopify Admin and payment
   flows through Shopify Payments. There is no path to enable it here.

package/lib/admin.js

@@ -1785,6 +1785,8 @@ var INTEGRATIONS_CATALOG = [
     set: "GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, SHOP_ORIGIN. Add <SHOP_ORIGIN>/account/auth/google/callback as a Google OAuth redirect URI." },
   { key: "apple_signin",     name: "Sign in with Apple",      enables: "A “Continue with Apple” button on the account login page.",
     set: "APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_CLIENT_ID (your Services ID), APPLE_PRIVATE_KEY (the .p8 key contents), SHOP_ORIGIN. Add <SHOP_ORIGIN>/account/auth/apple/callback as a Return URL on the Services ID. Requires an Apple Developer Program membership." },
+  { key: "paypal",           name: "PayPal checkout",         enables: "A native PayPal button on the checkout page (create / capture via PayPal Orders v2) — distinct from PayPal-through-Stripe.",
+    set: "PAYPAL_CLIENT_ID, PAYPAL_SECRET (a PayPal REST app), PAYPAL_WEBHOOK_ID, PAYPAL_ENV (sandbox|live). Card checkout (Stripe) must be live too. Point a PayPal webhook at /api/webhooks/paypal." },
 ];
 
 function renderAdminIntegrations(opts) {

package/lib/checkout.js

@@ -73,6 +73,15 @@ var STRIPE_EVENT_MAP = Object.freeze({
 // Subscription webhook event types route to the subscriptions
 // primitive (if wired via deps.subscriptions) instead of the order
 // FSM. The one-time-order path stays unchanged.
+// PayPal webhook event types → order FSM event. The create/capture flow
+// marks the order paid directly; these are the asynchronous backstop.
+var PAYPAL_EVENT_MAP = Object.freeze({
+  "PAYMENT.CAPTURE.COMPLETED": "mark_paid",
+  "PAYMENT.CAPTURE.DENIED":    null,        // no state change — operator decides
+  "PAYMENT.CAPTURE.REFUNDED":  "refund",
+  "CHECKOUT.ORDER.APPROVED":   null,        // approved but not captured yet
+});
+
 var STRIPE_SUB_EVENT_TYPES = Object.freeze({
   "customer.subscription.created": true,
   "customer.subscription.updated": true,
@@ -90,6 +99,7 @@ function create(deps) {
   var tax           = deps.tax;
   var shipping      = deps.shipping;
   var payment       = deps.payment;
+  var paypal        = deps.paypal || null;   // PayPal adapter — checkout-via-PayPal disabled when absent
   var order         = deps.order;
   var subscriptions = deps.subscriptions || null;
   // Optional — when wired, the buyer email is hashed (via the same
@@ -313,6 +323,128 @@ function create(deps) {
       }
       return { handled: true, event_type: eventType, order: updated };
     },
+
+    // ---- PayPal (Orders v2) ----------------------------------------------
+    //
+    // PayPal's flow is create → buyer-approve → capture, not a Stripe-style
+    // PaymentIntent + webhook. `createPaypalOrder` prices the cart, opens a
+    // PayPal order, and persists the local order in `pending` with the PayPal
+    // order id linked. `capturePaypalOrder` (called after the buyer approves)
+    // captures and advances the order to `paid`. `handlePaypalEvent` is the
+    // async backstop. All three require the `paypal` adapter to be wired.
+
+    createPaypalOrder: async function (input) {
+      if (!paypal) throw new TypeError("checkout.createPaypalOrder: paypal adapter not wired");
+      if (!input || typeof input !== "object") throw new TypeError("checkout.createPaypalOrder: input required");
+      if (!input.customer || typeof input.customer !== "object") throw new TypeError("checkout.createPaypalOrder: customer required");
+      var email = _email(input.customer.customer_email || input.customer.email);
+      if (!input.selected_shipping_id) throw new TypeError("checkout.createPaypalOrder: selected_shipping_id required");
+      var idempotencyKey = input.idempotency_key;
+      if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8) {
+        throw new TypeError("checkout.createPaypalOrder: idempotency_key (≥8 chars) required");
+      }
+      var quote = await _buildQuote(input);
+      if (quote.totals.grand_total_minor <= 0) {
+        throw new TypeError("checkout.createPaypalOrder: grand_total_minor must be > 0");
+      }
+      var ppOrder = await paypal.createOrder({
+        amount_minor: quote.totals.grand_total_minor,
+        currency:     quote.currency.toUpperCase(),
+        order_id:     quote.cart_id,
+        return_url:   input.return_url || undefined,
+        cancel_url:   input.cancel_url || undefined,
+      }, idempotencyKey);
+      var cartRow = await cart.get(quote.cart_id);
+      var createdOrder = await order.createFromCart({
+        cart_id:             quote.cart_id,
+        session_id:          cartRow.session_id,
+        customer_id:         cartRow.customer_id || null,
+        currency:            quote.currency,
+        subtotal_minor:      quote.totals.subtotal_minor,
+        discount_minor:      quote.totals.discount_minor,
+        tax_minor:           quote.totals.tax_minor,
+        shipping_minor:      quote.totals.shipping_minor,
+        grand_total_minor:   quote.totals.grand_total_minor,
+        payment_intent_id:   ppOrder.id,   // the PayPal order id (opaque); links the webhook + capture
+        ship_to:             input.ship_to,
+        customer_email_hash: customers ? customers.hashEmail(email) : null,
+        lines:               quote.lines.map(function (l) {
+          return { variant_id: l.variant_id, sku: l.sku, qty: l.qty, unit_amount_minor: l.unit_amount_minor, unit_currency: l.unit_currency };
+        }),
+      });
+      await cart.setStatus(quote.cart_id, "converted");
+      return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status };
+    },
+
+    // Capture an approved PayPal order, then advance the local order to paid.
+    // Idempotent: if the order already left `pending` (a webhook or a retry
+    // beat us), the capture result is returned without a second transition.
+    capturePaypalOrder: async function (paypalOrderId) {
+      if (!paypal) throw new TypeError("checkout.capturePaypalOrder: paypal adapter not wired");
+      if (typeof paypalOrderId !== "string" || !paypalOrderId.length) {
+        throw new TypeError("checkout.capturePaypalOrder: paypalOrderId required");
+      }
+      var o = await order.byPaymentIntent(paypalOrderId);
+      if (!o) return { handled: false, reason: "order-not-found", paypal_order_id: paypalOrderId };
+      // Guard on LOCAL status before calling PayPal: if a prior capture or a
+      // webhook already advanced the order, a second remote capture would be
+      // rejected by PayPal (orders capture once) — turning an idempotent retry
+      // into an exception. Treat already-advanced as a success no-op.
+      if (o.status !== "pending") {
+        return { handled: true, order: o, skipped: "already-advanced", paypal_order_id: paypalOrderId };
+      }
+      var cap = await paypal.captureOrder(paypalOrderId);
+      var captureId = null;
+      try { captureId = cap.purchase_units[0].payments.captures[0].id; } catch (_e) { captureId = null; }
+      var completed = cap && (cap.status === "COMPLETED" ||
+        (captureId && cap.purchase_units[0].payments.captures[0].status === "COMPLETED"));
+      if (completed && o.status === "pending") {
+        await order.transition(o.id, "mark_paid", {
+          reason:   "paypal:capture",
+          metadata: { paypal_order_id: paypalOrderId, paypal_capture_id: captureId },
+        });
+      }
+      return { handled: !!completed, order: await order.get(o.id), capture_id: captureId, capture: cap };
+    },
+
+    // Verify a PayPal webhook (server-to-server, via the adapter) and apply
+    // the matching order transition. The capture flow above is primary; this
+    // catches captures completed/refunded out of band. { handled, ... }.
+    handlePaypalEvent: async function (input) {
+      if (!paypal) throw new TypeError("checkout.handlePaypalEvent: paypal adapter not wired");
+      if (!input || typeof input !== "object") throw new TypeError("checkout.handlePaypalEvent: input required");
+      if (typeof input.rawBody !== "string") throw new TypeError("checkout.handlePaypalEvent: rawBody (string) required");
+      var v = await paypal.verifyWebhook(input.headers || {}, input.rawBody, { webhookId: input.webhookId });
+      if (!v.ok) {
+        var err = new Error("checkout: paypal webhook verification failed — " + v.reason);
+        err.code = "WEBHOOK_INVALID";
+        err.reason = v.reason;
+        throw err;
+      }
+      var event = v.event || {};
+      var eventType = event.event_type;
+      if (!eventType || !Object.prototype.hasOwnProperty.call(PAYPAL_EVENT_MAP, eventType)) {
+        return { handled: false, event_type: eventType || null };
+      }
+      var fsmEvent = PAYPAL_EVENT_MAP[eventType];
+      if (!fsmEvent) return { handled: false, event_type: eventType, reason: "no-state-change" };
+      // The PayPal order id lives in the capture resource's related ids.
+      var ppOrderId = null;
+      try { ppOrderId = event.resource.supplementary_data.related_ids.order_id; } catch (_e) { ppOrderId = null; }
+      if (!ppOrderId) return { handled: false, event_type: eventType, reason: "no-order-id" };
+      var o = await order.byPaymentIntent(ppOrderId);
+      if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
+      var alreadyAdvanced = (
+        (fsmEvent === "mark_paid" && o.status !== "pending") ||
+        (fsmEvent === "refund"    && o.status === "refunded")
+      );
+      if (alreadyAdvanced) return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+      var updated = await order.transition(o.id, fsmEvent, {
+        reason:   "paypal:" + eventType,
+        metadata: { paypal_event_id: event.id, paypal_order_id: ppOrderId },
+      });
+      return { handled: true, event_type: eventType, order: updated };
+    },
   };
 }
 
@@ -320,4 +452,5 @@ module.exports = {
   create:                 create,
   STRIPE_EVENT_MAP:       STRIPE_EVENT_MAP,
   STRIPE_SUB_EVENT_TYPES: STRIPE_SUB_EVENT_TYPES,
+  PAYPAL_EVENT_MAP:       PAYPAL_EVENT_MAP,
 };

package/lib/storefront.js

@@ -1620,6 +1620,15 @@ function renderCheckoutForm(opts) {
     });
   }
   var body = _render(CHECKOUT_PAGE, { subtotal: subtotal });
+  // When PayPal is configured, append its button below the card form. The
+  // block is built as raw HTML (appended after the strict render) so the SDK
+  // script + handlers survive; the client-id is the only interpolation and is
+  // attribute-escaped. The PayPal button's createOrder/onApprove drive the
+  // /checkout/paypal/create + /capture routes. (Operators must allow
+  // www.paypal.com in their CSP script-src/frame-src, as for js.stripe.com.)
+  if (opts.paypal_client_id) {
+    body += _paypalCheckoutBlock(opts.paypal_client_id, totals.currency);
+  }
   return _wrap({
     title:      "Checkout",
     shop_name:  shopName,
@@ -1629,6 +1638,31 @@ function renderCheckoutForm(opts) {
   });
 }
 
+function _paypalCheckoutBlock(clientId, currency) {
+  var esc = b.template.escapeHtml;
+  var cid = esc(String(clientId));
+  var cur = esc(String(currency || "USD"));
+  return "\n<div class=\"checkout-paypal\" style=\"max-width:32rem;margin:1.5rem auto 0;\">" +
+    "<div class=\"pay-card__divider\"><span>or pay with PayPal</span></div>" +
+    "<div id=\"paypal-button-container\"></div>" +
+    "<p id=\"paypal-error\" class=\"auth-form__message auth-form__message--err\" hidden></p>" +
+    "</div>" +
+    "<script src=\"https://www.paypal.com/sdk/js?client-id=" + cid + "&currency=" + cur + "&intent=capture\"></script>" +
+    "<script>(function(){" +
+    "if(!window.paypal){return;}" +
+    "var form=document.querySelector('.checkout-page form');" +
+    "var errEl=document.getElementById('paypal-error');" +
+    "function vals(){var d={};['email','name','country','state','postal'].forEach(function(k){var el=form&&form.elements[k];if(el){d[k]=el.value;}});return d;}" +
+    "function showErr(m){if(errEl){errEl.hidden=false;errEl.textContent=m||'PayPal checkout could not be completed.';}}" +
+    "paypal.Buttons({" +
+    "onClick:function(_d,actions){if(form&&form.reportValidity&&!form.reportValidity()){return actions.reject();}return actions.resolve();}," +
+    "createOrder:function(){return fetch('/checkout/paypal/create',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(vals())}).then(function(r){return r.json();}).then(function(d){if(!d.id){throw new Error(d.error||'create failed');}return d.id;});}," +
+    "onApprove:function(data){return fetch('/checkout/paypal/capture',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({paypal_order_id:data.orderID})}).then(function(r){return r.json();}).then(function(d){if(d.redirect){window.location.href=d.redirect;}else{showErr(d.error);}});}," +
+    "onError:function(){showErr();}" +
+    "}).render('#paypal-button-container');" +
+    "})();</script>\n";
+}
+
 // Stripe Elements payment page — embeds Stripe.js + a minimal
 // mount block. The publishable key is operator-supplied (env
 // `STRIPE_PUBLISHABLE_KEY` → forwarded into the rendered HTML).
@@ -2808,7 +2842,7 @@ function mount(router, deps) {
         return res.end ? res.end() : res.send("");
       }
       var totals = pricing.totals(c, lines, {});
-      _send(res, 200, renderCheckoutForm({ lines: lines, totals: totals, shop_name: shopName, theme: theme }));
+      _send(res, 200, renderCheckoutForm({ lines: lines, totals: totals, shop_name: shopName, theme: theme, paypal_client_id: deps.paypal ? deps.paypal_client_id : null }));
     });
 
     router.post("/checkout", async function (req, res) {
@@ -2867,6 +2901,76 @@ function mount(router, deps) {
       }
     });
 
+    // PayPal express checkout (Orders v2). Mounts when the PayPal adapter is
+    // wired. The pay-page PayPal button drives two AJAX calls: `create` opens
+    // a PayPal order for the current cart (returns its id for the SDK to
+    // approve in the popup); `capture` finalizes after approval and advances
+    // the local order to paid. Both read the session cart; the button posts
+    // the same ship_to fields the card form collects.
+    if (deps.paypal) {
+      router.post("/checkout/paypal/create", async function (req, res) {
+        function _json(status, obj) {
+          res.status(status);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var s = JSON.stringify(obj);
+          return res.end ? res.end(s) : res.send(s);
+        }
+        var body = req.body || {};
+        var sid = _readSidCookie(req);
+        if (!sid) return _json(400, { error: "no-session" });
+        var c = await deps.cart.bySession(sid);
+        if (!c || c.status !== "active") return _json(409, { error: "no-active-cart" });
+        var shipTo = {
+          country: (body.country || "").toUpperCase(),
+          state:   body.state ? String(body.state).toUpperCase() : undefined,
+          postal:  body.postal || undefined,
+        };
+        try {
+          var defaultShipId = typeof deps.default_shipping_id === "function"
+            ? await deps.default_shipping_id() : deps.default_shipping_id;
+          var created = await deps.checkout.createPaypalOrder({
+            cart_id:              c.id,
+            ship_to:              shipTo,
+            selected_shipping_id: body.selected_shipping_id || defaultShipId || "std",
+            customer:             { email: body.email, name: body.name },
+            idempotency_key:      "paypal:" + c.id + ":" + b.uuid.v7(),
+            return_url:           body.return_url || undefined,
+            cancel_url:           body.cancel_url || undefined,
+          });
+          // The PayPal JS SDK's createOrder expects `{ id }`.
+          return _json(200, { id: created.paypal_order_id, order_id: created.order.id });
+        } catch (e) {
+          return _json(e instanceof TypeError ? 400 : 502, { error: (e && e.message) || "paypal-create-failed" });
+        }
+      });
+
+      router.post("/checkout/paypal/capture", async function (req, res) {
+        function _json(status, obj) {
+          res.status(status);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var s = JSON.stringify(obj);
+          return res.end ? res.end(s) : res.send(s);
+        }
+        var body = req.body || {};
+        var paypalOrderId = body.paypal_order_id || body.orderID || body.orderId;
+        if (typeof paypalOrderId !== "string" || !paypalOrderId.length) return _json(400, { error: "paypal_order_id required" });
+        try {
+          var result = await deps.checkout.capturePaypalOrder(paypalOrderId);
+          if (!result.order) return _json(404, { error: "order-not-found" });
+          // Only redirect to the order page when the capture actually
+          // completed (or the order is already paid). A non-completing capture
+          // leaves the order pending — surface it as an error so the client
+          // doesn't show success for an unpaid order.
+          if (!result.handled && result.order.status !== "paid") {
+            return _json(502, { error: "capture-incomplete", status: result.order.status });
+          }
+          return _json(200, { order_id: result.order.id, status: result.order.status, redirect: "/orders/" + result.order.id });
+        } catch (e) {
+          return _json(502, { error: (e && e.message) || "paypal-capture-failed" });
+        }
+      });
+    }
+
     router.get("/pay/:order_id", async function (req, res) {
       var orderId = req.params && req.params.order_id;
       if (!orderId) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
@@ -2952,6 +3056,32 @@ function mount(router, deps) {
         return res.end ? res.end("handler error") : res.send("");
       }
     });
+
+    // PayPal webhook — the async backstop for captures completed/refunded out
+    // of band (the create/capture flow is primary). Verified server-to-server
+    // through PayPal's API (handlePaypalEvent), so unlike Stripe there is no
+    // edge HMAC pre-check; the raw body is captured upstream by
+    // webhookRawBodyCapture. Mounts only when the PayPal adapter is wired.
+    if (deps.paypal) {
+      router.post("/api/webhooks/paypal", async function (req, res) {
+        var raw = Buffer.isBuffer(req.body) ? req.body.toString("utf8")
+          : (typeof req.body === "string" ? req.body : "");
+        try {
+          var result = await deps.checkout.handlePaypalEvent({ headers: req.headers || {}, rawBody: raw });
+          res.status(200);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var payload = JSON.stringify({ ok: true, handled: !!(result && result.handled) });
+          return res.end ? res.end(payload) : res.send(payload);
+        } catch (e) {
+          if (e && e.code === "WEBHOOK_INVALID") {
+            res.status(400);
+            return res.end ? res.end("invalid signature") : res.send("");
+          }
+          res.status(500);
+          return res.end ? res.end("handler error") : res.send("");
+        }
+      });
+    }
   }
 
   // ---- customer accounts (passkey-only) ------------------------------

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.54",
-      "tag": "v0.12.54",
+      "version": "0.12.55",
+      "tag": "v0.12.55",
       "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.55 (2026-05-25) — **`b.structuredFields` — RFC 9651 Date and Display String types.** Brings the Structured Fields codec up to RFC 9651, which obsoletes RFC 8941 by adding two bare-item types. A Date (`@1659578233`) is an Integer number of seconds since the Unix epoch; a Display String (`%"f%c3%bc%c3%bc"`) is a Unicode string conveyed as percent-escaped UTF-8. parse returns them as distinct SfDate / SfDisplayString values, and serialize emits them canonically — a Date as `@` + integer, a Display String as `%"`-wrapped lowercase-percent-escaped UTF-8 that escapes only what RFC 9651 requires. Parsing is strict: a Date rejects a decimal / out-of-range value, and a Display String rejects uppercase escapes, raw non-ASCII, bad hex, and invalid UTF-8. Validated against the official httpwg structured-field-tests date and display-string vectors. **Added:** *RFC 9651 Date (`@…`) and Display String (`%"…"`) in `b.structuredFields`* — `parse` now reads the two RFC 9651 types: `@` + an Integer yields an `SfDate` (rejecting a decimal `@1.5`, an empty `@`, a sign-only `@-`, and out-of-range values), and `%"…"` yields an `SfDisplayString` (decoding lowercase `%XX` escapes as UTF-8, rejecting uppercase escapes, raw non-ASCII or control characters, malformed hex, and invalid UTF-8). `serialize` is the inverse — a Date as `@` + the integer, a Display String percent-escaping only non-printable / non-ASCII bytes plus `%` and `"`. The new `b.structuredFields.Date` and `b.structuredFields.DisplayString` wrappers construct these values. The module now tracks RFC 9651 (which obsoletes RFC 8941); the existing Item / List / Dictionary parsing is unchanged.
+
 - v0.12.54 (2026-05-25) — **`b.structuredFields.parse` / `serialize` — full RFC 8941 Structured Fields codec.** The structured-fields module gains a complete RFC 8941 parser and serializer alongside its existing quote-aware helpers. b.structuredFields.parse reads an Item, List, or Dictionary into a typed value model — items are { value, params }, lists are arrays of items / inner lists, dictionaries are Maps — with Tokens and byte sequences returned as distinct SfToken / SfByteSequence instances. It enforces the grammar strictly: integer and decimal digit caps, printable-ASCII strings, canonical base64 byte sequences, valid token and key grammar, and no trailing characters. b.structuredFields.serialize is the exact inverse. This is the real parser the framework's Content-Digest, Client Hints, Web Push, and HTTP Message Signature surfaces can build on instead of open-coding each field. Validated against the official httpwg structured-field-tests conformance vectors. **Added:** *`b.structuredFields.parse(input, type, opts?)` / `serialize(value, type, opts?)` / `Token` / `ByteSequence`* — `parse` accepts `type` of `"item"`, `"list"`, or `"dictionary"` and returns the value model (items as `{ value, params }` with a `Map` of parameters; lists as arrays of items or inner lists; dictionaries as `Map`s). Bare items are JS numbers (Integer / Decimal), strings, booleans, `SfToken`, or `SfByteSequence`. Malformed input is rejected — out-of-range integers, over-long decimals, non-printable string bytes, non-canonical base64, invalid tokens / keys, and any trailing characters — and `opts.ErrorClass` yields a typed error. `serialize` is the inverse, rounding decimals to three fractional digits and refusing values outside the RFC's ranges or grammar. `b.structuredFields.Token` and `b.structuredFields.ByteSequence` wrap those bare-item types for serialization. The existing `splitTopLevel` / `refuseControlBytes` / `unquoteSfString` helpers are unchanged.
 
 - v0.12.53 (2026-05-25) — **`b.contentDigest` — HTTP Content-Digest / Repr-Digest fields (RFC 9530).** Emit and verify the Content-Digest / Repr-Digest HTTP fields so a recipient can detect a corrupted or tampered message body. b.contentDigest.create builds the RFC 8941 dictionary value (sha-256=:base64:, sha-512=:base64:) over a body; b.contentDigest.verify recomputes each modern digest over the body and compares it in constant time. Only SHA-256 and SHA-512 are computed — the legacy algorithms RFC 9530 §6 marks insecure (MD5, SHA-1, the unix checksums) are ignored on verify, and a field carrying no modern digest is refused, so an attacker cannot downgrade integrity to an MD5-only digest. Content-Digest is the integrity companion to HTTP Message Signatures (b.httpSig, RFC 9421): sign the digest rather than the whole body. Verified against the RFC 9530 Appendix D worked examples. **Added:** *`b.contentDigest.create(body, opts?)` / `b.contentDigest.verify(fieldValue, body, opts?)`* — `create` returns a Content-Digest / Repr-Digest field value over the body — SHA-256 by default, or any subset of `["sha-256","sha-512"]` via `opts.algorithms` — and refuses insecure or unknown algorithms. `verify` parses the field, recomputes each SHA-256 / SHA-512 entry over the body, and compares constant-time; it throws `content-digest/mismatch` on any mismatch, ignores legacy / unknown entries, throws `content-digest/no-modern-digest` if the field has no SHA-256 / SHA-512 entry at all, and honours `opts.required` to force specific algorithms to be present and match. Composes the framework's structured-field helpers and constant-time compare; Repr-Digest is the same machinery over the selected representation (RFC 9110).

package/lib/vendor/blamejs/README.md

@@ -98,7 +98,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`)
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
 - **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`); RFC 9530 Content-Digest / Repr-Digest body-integrity fields (SHA-256 / SHA-512, legacy algorithms refused — `b.contentDigest`) to sign the digest rather than the whole body
-- **Structured Fields** — full RFC 8941 codec (`b.structuredFields.parse` / `serialize`): Items / Lists / Dictionaries, Inner Lists, Parameters, and all bare-item types (Integer / Decimal / String / Token / Byte Sequence / Boolean) with strict grammar + range enforcement — the parser behind Content-Digest, Client Hints, and HTTP Message Signatures
+- **Structured Fields** — full RFC 9651 codec (`b.structuredFields.parse` / `serialize`): Items / Lists / Dictionaries, Inner Lists, Parameters, and every bare-item type (Integer / Decimal / String / Token / Byte Sequence / Boolean / Date / Display String) with strict grammar + range enforcement — the parser behind Content-Digest, Client Hints, and HTTP Message Signatures
 - **CMS codec** — RFC 5652 Cryptographic Message Syntax encoder + decoder with PQC signers (ML-DSA-65 / ML-DSA-87 / SLH-DSA-SHAKE-256f; RFC 9909 + 9881) and KEMRecipientInfo recipients (ML-KEM-1024; RFC 9629 + 9936); ChaCha20-Poly1305 content encryption (RFC 8103) so Efail-class malleability cannot apply (`b.cms`)
 - **Stream throttle** — shared token-bucket bandwidth limiter (RFC 2697 srTCM shape); N concurrent `node:stream` pipelines draw from one operator-configured `bytesPerSec` budget (`b.streamThrottle`)
 - **TLS-RPT receiver** — RFC 8460 inbound aggregate-report ingest; HTTPS POST handler + §4.4 schema parser with gzip-bomb / ratio-bomb / depth-bomb defenses (`b.mail.deploy.parseTlsRptReport` / `b.mail.deploy.tlsRptIngestHttp`)

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

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "frameworkVersion": "0.12.54",
-  "createdAt": "2026-05-25T18:34:52.229Z",
+  "frameworkVersion": "0.12.55",
+  "createdAt": "2026-05-25T19:45:48.985Z",
   "exports": {
     "a2a": {
       "type": "object",
@@ -48698,6 +48698,18 @@
           "type": "function",
           "arity": 1
         },
+        "Date": {
+          "type": "function",
+          "arity": 1
+        },
+        "Decimal": {
+          "type": "function",
+          "arity": 1
+        },
+        "DisplayString": {
+          "type": "function",
+          "arity": 1
+        },
         "Token": {
           "type": "function",
           "arity": 1

package/lib/vendor/blamejs/lib/structured-fields.js

@@ -2,7 +2,7 @@
 /**
  * @module     b.structuredFields
  * @nav        HTTP
- * @title      RFC 8941 Structured Fields helpers
+ * @title      RFC 9651 Structured Fields
  * @order      317
  *
  * @intro
@@ -67,6 +67,10 @@
  *   b.structuredFields.splitTopLevel('alg="x;y";nonce=42', ";");
  *   // → ['alg="x;y"', 'nonce=42']
  */
+// node:util is a builtin (no lib require cycle) — used for strict UTF-8
+// validation of RFC 9651 Display Strings.
+var TextDecoder = require("node:util").TextDecoder;
+
 function splitTopLevel(s, sep) {
   if (typeof s !== "string") return [];
   if (sep !== "," && sep !== ";") {
@@ -237,13 +241,15 @@ function containsControlBytes(value, opts) {
 }
 
 // ---------------------------------------------------------------------------
-// Full RFC 8941 codec (parse + serialize). The helpers above are the
+// Full RFC 9651 codec (parse + serialize; RFC 9651 obsoletes RFC 8941
+// and adds the Date and Display String types). The helpers above are the
 // quote-aware splitters individual parsers reach for; the codec below is
 // the complete grammar — Items, Lists, Dictionaries, Inner Lists,
 // Parameters, and every bare-item type.
 //
-// Value model:
-//   bare item  → number (Integer) | SfDecimal | string | boolean | SfToken | SfByteSequence
+// Value model (RFC 9651, which obsoletes RFC 8941):
+//   bare item  → number (Integer) | SfDecimal | string | boolean | SfToken
+//                | SfByteSequence | SfDate | SfDisplayString
 //   item       → { value: bareItem, params: Map<string, bareItem> }
 //   inner list → { items: item[], params: Map<string, bareItem> }
 //   list       → (item | innerList)[]
@@ -268,6 +274,18 @@ function SfDecimal(value) {
   if (!(this instanceof SfDecimal)) return new SfDecimal(value);
   this.value = Number(value);
 }
+// RFC 9651 §3.3.7 Date (an Integer number of seconds since the Unix
+// epoch) and §3.3.8 Display String (a Unicode string conveyed as
+// percent-escaped UTF-8). Wrapped so they stay distinct from Integers
+// and plain Strings.
+function SfDate(value) {
+  if (!(this instanceof SfDate)) return new SfDate(value);
+  this.value = Number(value);
+}
+function SfDisplayString(value) {
+  if (!(this instanceof SfDisplayString)) return new SfDisplayString(value);
+  this.value = String(value);
+}
 
 function _sfErr(opts) {
   if (opts && typeof opts.ErrorClass === "function") {
@@ -359,12 +377,47 @@ function _parseToken(cx) {
   return new SfToken(cx.s.slice(start, cx.i));
 }
 
+var _utf8Strict = new TextDecoder("utf-8", { fatal: true });
+
+function _parseDate(cx, E) {
+  cx.i += 1; // "@"
+  var n = _parseNumber(cx, E);
+  if (n instanceof SfDecimal) throw E("structured-fields/parse", "date must be an integer number of seconds");
+  return new SfDate(n);
+}
+
+function _parseDisplayString(cx, E) {
+  cx.i += 1; // "%"
+  if (cx.s.charAt(cx.i) !== "\"") throw E("structured-fields/parse", "display string must open with %\"");
+  cx.i += 1;
+  var bytes = [];
+  while (cx.i < cx.s.length) {
+    var c = cx.s.charAt(cx.i); cx.i += 1;
+    if (c === "%") {
+      var h = cx.s.substr(cx.i, 2);
+      if (h.length !== 2 || !/^[0-9a-f]{2}$/.test(h)) throw E("structured-fields/parse", "display string escape must be %<lowercase-hex><lowercase-hex>");   // allow:raw-byte-literal — RFC 9651 §4.2.10 two-hex-digit escape
+      bytes.push(parseInt(h, 16));
+      cx.i += 2;
+    } else if (c === "\"") {
+      try { return new SfDisplayString(_utf8Strict.decode(Buffer.from(bytes))); }
+      catch (_e) { throw E("structured-fields/parse", "display string is not valid UTF-8"); }
+    } else {
+      var cc = c.charCodeAt(0);
+      if (cc < 0x20 || cc > 0x7e) throw E("structured-fields/parse", "display string contains a raw non-printable / non-ASCII character");   // allow:raw-byte-literal — RFC 9651 §4.2.10 printable-ASCII range
+      bytes.push(cc);
+    }
+  }
+  throw E("structured-fields/parse", "unterminated display string");
+}
+
 function _parseBareItem(cx, E) {
   var c = cx.s.charAt(cx.i);
   if (c === "-" || _isDigit(c)) return _parseNumber(cx, E);
   if (c === "\"") return _parseString(cx, E);
   if (c === ":") return _parseByteSeq(cx, E);
   if (c === "?") return _parseBoolean(cx, E);
+  if (c === "@") return _parseDate(cx, E);
+  if (c === "%") return _parseDisplayString(cx, E);
   if (c === "*" || _isAlpha(c)) return _parseToken(cx);
   throw E("structured-fields/parse", "unexpected character '" + (c || "<eof>") + "' at index " + cx.i);
 }
@@ -455,9 +508,11 @@ function _parseDict(cx, E) {
  * <code>"item"</code>, <code>"list"</code>, or <code>"dictionary"</code>.
  * Returns the value model: an item is <code>{ value, params }</code>
  * (params is a <code>Map</code>); a list is an array of items / inner
- * lists; a dictionary is a <code>Map</code>. Tokens and byte sequences
- * come back as <code>SfToken</code> / <code>SfByteSequence</code>
- * instances so they stay distinct from plain strings. Strictly enforces
+ * lists; a dictionary is a <code>Map</code>. Tokens, byte sequences,
+ * dates, and display strings come back as <code>SfToken</code> /
+ * <code>SfByteSequence</code> / <code>SfDate</code> /
+ * <code>SfDisplayString</code> instances so they stay distinct from
+ * plain strings and integers. Strictly enforces
  * the grammar — integer / decimal digit caps, printable-ASCII strings,
  * canonical base64, no trailing characters — and throws on any malformed
  * input (pass <code>opts.ErrorClass</code> for a typed error).
@@ -493,10 +548,31 @@ function _serDecimal(v, E) {
   if (s.indexOf(".") === -1) s += ".0";                  // a Decimal must carry a fractional part
   return s;
 }
+function _serDisplayString(s, E) {
+  if (typeof s !== "string") throw E("structured-fields/serialize", "display string value must be a string");
+  // RFC 9651 §4.1.10: serialize fails unless the value is a sequence of
+  // Unicode scalar values. A lone UTF-16 surrogate would otherwise be
+  // silently replaced with U+FFFD by Buffer.from, corrupting the output.
+  if (typeof s.isWellFormed === "function" ? !s.isWellFormed() : /[\uD800-\uDFFF]/.test(s.replace(/[\uD800-\uDBFF][\uDC00-\uDFFF]/g, ""))) {
+    throw E("structured-fields/serialize", "display string contains a lone surrogate (not a valid Unicode string)");
+  }
+  var bytes = Buffer.from(s, "utf8"), out = "%\"";
+  for (var i = 0; i < bytes.length; i += 1) {
+    var b = bytes[i];
+    if (b >= 0x20 && b <= 0x7e && b !== 0x25 && b !== 0x22) out += String.fromCharCode(b);   // allow:raw-byte-literal — RFC 9651 §4.1.10 printable ASCII except % and "
+    else out += "%" + (b < 0x10 ? "0" : "") + b.toString(16);                                // allow:raw-byte-literal — lowercase 2-hex escape
+  }
+  return out + "\"";
+}
 function _serBareItem(v, E) {
   if (v === true) return "?1";
   if (v === false) return "?0";
   if (v instanceof SfDecimal) return _serDecimal(v.value, E);
+  if (v instanceof SfDate) {
+    if (!Number.isInteger(v.value) || v.value > INT_MAX || v.value < INT_MIN) throw E("structured-fields/serialize", "date must be an integer in RFC 9651 range");
+    return "@" + String(v.value);
+  }
+  if (v instanceof SfDisplayString) return _serDisplayString(v.value, E);
   if (typeof v === "number") {
     if (!isFinite(v)) throw E("structured-fields/serialize", "cannot serialize a non-finite number");
     if (Number.isInteger(v)) {
@@ -603,4 +679,6 @@ module.exports = {
   Token:                SfToken,
   ByteSequence:         SfByteSequence,
   Decimal:              SfDecimal,
+  Date:                 SfDate,
+  DisplayString:        SfDisplayString,
 };

package/lib/vendor/blamejs/package.json

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

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

@@ -0,0 +1,18 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.12.55",
+  "date": "2026-05-25",
+  "headline": "`b.structuredFields` — RFC 9651 Date and Display String types",
+  "summary": "Brings the Structured Fields codec up to RFC 9651, which obsoletes RFC 8941 by adding two bare-item types. A Date (`@1659578233`) is an Integer number of seconds since the Unix epoch; a Display String (`%\"f%c3%bc%c3%bc\"`) is a Unicode string conveyed as percent-escaped UTF-8. parse returns them as distinct SfDate / SfDisplayString values, and serialize emits them canonically — a Date as `@` + integer, a Display String as `%\"`-wrapped lowercase-percent-escaped UTF-8 that escapes only what RFC 9651 requires. Parsing is strict: a Date rejects a decimal / out-of-range value, and a Display String rejects uppercase escapes, raw non-ASCII, bad hex, and invalid UTF-8. Validated against the official httpwg structured-field-tests date and display-string vectors.",
+  "sections": [
+    {
+      "heading": "Added",
+      "items": [
+        {
+          "title": "RFC 9651 Date (`@…`) and Display String (`%\"…\"`) in `b.structuredFields`",
+          "body": "`parse` now reads the two RFC 9651 types: `@` + an Integer yields an `SfDate` (rejecting a decimal `@1.5`, an empty `@`, a sign-only `@-`, and out-of-range values), and `%\"…\"` yields an `SfDisplayString` (decoding lowercase `%XX` escapes as UTF-8, rejecting uppercase escapes, raw non-ASCII or control characters, malformed hex, and invalid UTF-8). `serialize` is the inverse — a Date as `@` + the integer, a Display String percent-escaping only non-printable / non-ASCII bytes plus `%` and `\"`. The new `b.structuredFields.Date` and `b.structuredFields.DisplayString` wrappers construct these values. The module now tracks RFC 9651 (which obsoletes RFC 8941); the existing Item / List / Dictionary parsing is unchanged."
+        }
+      ]
+    }
+  ]
+}

package/lib/vendor/blamejs/test/layer-0-primitives/structured-fields-codec.test.js

@@ -24,6 +24,8 @@ function mineVal(v) {
   if (v instanceof SF.Token) return { token: v.value };
   if (v instanceof SF.ByteSequence) return { binary: b32(v.value) };
   if (v instanceof SF.Decimal) return v.value;   // compare a Decimal numerically (httpwg uses plain numbers)
+  if (v instanceof SF.Date) return { date: v.value };
+  if (v instanceof SF.DisplayString) return { displaystring: v.value };
   return v;
 }
 function mineParams(map) { var o = []; map.forEach(function (v, k) { o.push([k, mineVal(v)]); }); return o; }
@@ -37,6 +39,8 @@ function mine(out, type) {
 function httpVal(v) {
   if (v && v.__type === "token") return { token: v.value };
   if (v && v.__type === "binary") return { binary: v.value };
+  if (v && v.__type === "date") return { date: v.value };
+  if (v && v.__type === "displaystring") return { displaystring: v.value };
   return v;
 }
 function httpParams(arr) { return arr.map(function (p) { return [p[0], httpVal(p[1])]; }); }
@@ -86,6 +90,26 @@ var CASES = [
   { name: "dictionary bare key", raw: "a=1, b, c=3", t: "dictionary", expected: [["a", [1, []]], ["b", [true, []]], ["c", [3, []]]] },
   { name: "dictionary inner-list value", raw: "a=(1 2)", t: "dictionary", expected: [["a", [[[1, []], [2, []]], []]]] },
   { name: "trailing comma dict", raw: "a=1,", t: "dictionary", must_fail: true },
+  // RFC 9651 Date (§3.3.7)
+  { name: "date epoch", raw: "@0", t: "item", expected: [{ __type: "date", value: 0 }, []] },
+  { name: "date positive", raw: "@1659578233", t: "item", expected: [{ __type: "date", value: 1659578233 }, []] },
+  { name: "date negative", raw: "@-1659578233", t: "item", expected: [{ __type: "date", value: -1659578233 }, []] },
+  { name: "date decimal", raw: "@1659578233.12", t: "item", must_fail: true },
+  { name: "date too large", raw: "@1000000000000000", t: "item", must_fail: true },
+  { name: "date empty", raw: "@", t: "item", must_fail: true },
+  { name: "date sign only", raw: "@-", t: "item", must_fail: true },
+  { name: "date non-digit", raw: "@abc", t: "item", must_fail: true },
+  // RFC 9651 Display String (§3.3.8)
+  { name: "ascii display string", raw: '%"foo bar"', t: "item", expected: [{ __type: "displaystring", value: "foo bar" }, []] },
+  { name: "non-ascii display string (lowercase escaping)", raw: '%"f%c3%bc%c3%bc"', t: "item", expected: [{ __type: "displaystring", value: "füü" }, []] },
+  { name: "non-ascii display string (uppercase escaping)", raw: '%"f%C3%BC"', t: "item", must_fail: true },
+  { name: "non-ascii display string (unescaped)", raw: '%"füü"', t: "item", must_fail: true },
+  { name: "display string quoting", raw: '%"foo %22bar%22 \\ baz"', t: "item", expected: [{ __type: "displaystring", value: 'foo "bar" \\ baz' }, []] },
+  { name: "bad display string utf-8", raw: '%"%c3%28"', t: "item", must_fail: true },
+  { name: "bad display string hex", raw: '%"%g0%1w"', t: "item", must_fail: true },
+  { name: "truncated display string escape", raw: '%"%"', t: "item", must_fail: true },
+  { name: "unbalanced display string", raw: '%"foo', t: "item", must_fail: true },
+  { name: "single-quoted display string", raw: "%'foo'", t: "item", must_fail: true },
 ];
 
 function testConformance() {
@@ -135,6 +159,15 @@ function testDecimalTypePreserved() {
   check("serialize: an integral JS number serializes as an Integer", SF.serialize({ value: 5, params: new Map() }, "item") === "5");
 }
 
+function testDisplayStringSurrogate() {
+  function code(fn) { try { fn(); return "NO-THROW"; } catch (e) { return e.code; } }
+  // A lone UTF-16 surrogate is not a valid Unicode string — serialize must
+  // fail rather than silently emit U+FFFD (RFC 9651 §4.1.10).
+  check("serialize: lone surrogate display string refused", code(function () { SF.serialize({ value: new SF.DisplayString("a\uD800b"), params: new Map() }, "item"); }) === "structured-fields/serialize");
+  // A valid astral code point (surrogate pair) serializes fine.
+  check("serialize: astral code point display string ok", SF.serialize({ value: new SF.DisplayString("\u{1F600}"), params: new Map() }, "item") === '%"%f0%9f%98%80"');
+}
+
 function testTypedError() {
   function E(code, msg) { this.code = code; this.message = msg; }
   E.prototype = Object.create(Error.prototype);
@@ -151,6 +184,8 @@ function testSurface() {
   check("b.structuredFields.Token constructs a token", new b.structuredFields.Token("gzip").value === "gzip");
   check("b.structuredFields.ByteSequence constructs a byte sequence", Buffer.isBuffer(new b.structuredFields.ByteSequence(Buffer.from("x")).value));
   check("b.structuredFields.Decimal constructs a decimal", new b.structuredFields.Decimal(1.5).value === 1.5);
+  check("b.structuredFields.Date round-trips", b.structuredFields.serialize({ value: new b.structuredFields.Date(1659578233), params: new Map() }, "item") === "@1659578233");
+  check("b.structuredFields.DisplayString escapes non-ASCII", b.structuredFields.serialize({ value: new b.structuredFields.DisplayString("füü"), params: new Map() }, "item") === '%"f%c3%bc%c3%bc"');
 }
 
 async function run() {
@@ -158,6 +193,7 @@ async function run() {
   testConformance();
   testSerialize();
   testDecimalTypePreserved();
+  testDisplayStringSurrogate();
   testTypedError();
 }
 

package/package.json

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