@blamejs/blamejs-shop 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- 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.
 
 - v0.1.12 (2026-05-25) — **Card payments now finalize the order — the Stripe webhook is handled end to end.** A confirmed Stripe payment now advances the order from pending to paid. The container now serves the `POST /api/webhooks/stripe` route the edge worker forwards to: it re-verifies the event signature over the exact raw bytes, maps the event to the order's FSM transition, and is idempotent across Stripe's re-deliveries. Previously the edge verified the webhook but nothing consumed it on the container, so a paid PaymentIntent (card, Apple Pay, or Google Pay) left the order stuck in pending — no fulfillment, no paid status. Operators running checkout should upgrade and confirm their Stripe webhook points at `/api/webhooks/stripe`. **Added:** *Raw-body capture for payment webhooks* — A small middleware preserves the exact request bytes for the webhook path before the JSON body-parser runs, so signature verification (which is computed over the raw body) is reliable. It is scoped to the webhook routes and leaves every other request untouched. **Fixed:** *Stripe webhook completes the order* — `POST /api/webhooks/stripe` is now handled on the container: the event signature is re-verified against `STRIPE_WEBHOOK_SECRET` over the raw request body (a tampered or unsigned event is rejected with 400), then `payment_intent.succeeded` / `.canceled` / `charge.refunded` drive the order FSM (`mark_paid` / `cancel` / `refund`). Re-deliveries are idempotent — an event for an order already in the target state is acknowledged with 200 and skipped. A delivery for an unknown PaymentIntent is acknowledged without effect. This closes the gap where a confirmed payment never moved the order out of `pending`.

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: "Native PayPal create / capture via PayPal Orders v2 (distinct from PayPal-through-Stripe). The on-page button and webhook endpoint land in a follow-up release.",
+    set: "PAYPAL_CLIENT_ID, PAYPAL_SECRET (a PayPal REST app), PAYPAL_WEBHOOK_ID, PAYPAL_ENV (sandbox|live). Card checkout (Stripe) must be live too." },
 ];
 
 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/payment.js

@@ -43,6 +43,10 @@ var IDEMPOTENT_OPERATIONS    = {
   "subscription.create":   true,
   "subscription.update":   true,
   "subscription.cancel":   true,
+  // PayPal adapter mutating operations (Orders v2).
+  "paypal_order.create":   true,
+  "paypal_capture.create": true,
+  "paypal_refund.create":  true,
 };
 
 // ---- validation -----------------------------------------------------------
@@ -502,17 +506,261 @@ function stripe(opts) {
   };
 }
 
-function create(opts) {
+// ---- PayPal adapter -------------------------------------------------------
+//
+// PayPal Orders v2 over `b.httpClient`. Two structural differences from the
+// Stripe adapter: (1) every call needs an OAuth2 client-credentials access
+// token, exchanged up front and cached until it nears expiry; (2) webhook
+// verification is a server-to-server call to PayPal's own
+// verify-webhook-signature API — PayPal has no offline-HMAC shape like
+// Stripe's. Outbound goes through `b.httpClient` (SSRF-gated, retried); the
+// shared `_runIdempotent` cache applies when `query` is wired.
+var PAYPAL_API_BASE_LIVE    = "https://api-m.paypal.com";
+var PAYPAL_API_BASE_SANDBOX = "https://api-m.sandbox.paypal.com";
+var PAYPAL_HTTP_TIMEOUT_MS  = 15000;
+var PAYPAL_TOKEN_SKEW_MS    = C.TIME.minutes(2); // refresh this far before expiry
+
+// PayPal rejects decimal places for these currencies; everything else is
+// 2-decimal. Amounts cross the wire as decimal strings in MAJOR units.
+var PAYPAL_ZERO_DECIMAL     = { HUF: true, JPY: true, TWD: true };
+
+function _paypalApiBase(opts) {
+  if (opts.apiBase) return opts.apiBase.replace(/\/$/, "");
+  return opts.sandbox ? PAYPAL_API_BASE_SANDBOX : PAYPAL_API_BASE_LIVE;
+}
+
+function _minorToDecimalString(minor, currency) {
+  var dec = PAYPAL_ZERO_DECIMAL[currency] ? 0 : 2;
+  var neg = minor < 0;
+  var s = String(Math.abs(minor));
+  if (dec === 0) return (neg ? "-" : "") + s;
+  while (s.length <= dec) s = "0" + s;
+  return (neg ? "-" : "") + s.slice(0, s.length - dec) + "." + s.slice(s.length - dec);
+}
+
+function _headerCI(headers, name) {
+  if (!headers) return undefined;
+  if (headers[name] != null) return headers[name];
+  var lower = name.toLowerCase();
+  for (var k in headers) {
+    if (Object.prototype.hasOwnProperty.call(headers, k) && k.toLowerCase() === lower) return headers[k];
+  }
+  return undefined;
+}
+
+async function _paypalToken(opts, state) {
+  var now = state.now();
+  if (state.token && now < state.tokenExpiresAt) return state.token;
+  var httpClient = opts.httpClient || b.httpClient;
+  var basic = Buffer.from(opts.clientId + ":" + opts.secret).toString("base64");
+  var res = await httpClient.request({
+    method:  "POST",
+    url:     _paypalApiBase(opts) + "/v1/oauth2/token",
+    headers: {
+      "authorization":  "Basic " + basic,
+      "accept":         "application/json",
+      "content-type":   "application/x-www-form-urlencoded",
+      "user-agent":     "blamejs-shop (zero-dep)",
+    },
+    body:      "grant_type=client_credentials",
+    timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
+  });
+  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+  var json; try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = {}; }
+  if (res.statusCode < 200 || res.statusCode >= 300 || !json.access_token) {
+    var err = new Error("paypal: OAuth2 token exchange failed → HTTP " + res.statusCode +
+                        (json && json.error_description ? " — " + json.error_description : ""));
+    err.code = "PAYPAL_AUTH_" + res.statusCode;
+    err.statusCode = res.statusCode;
+    throw err;
+  }
+  state.token = json.access_token;
+  var ttlMs = (typeof json.expires_in === "number" ? json.expires_in : 0) * 1000; // allow:raw-time-literal — PayPal expires_in is a runtime seconds value; *1000 → ms
+  state.tokenExpiresAt = now + Math.max(0, ttlMs - PAYPAL_TOKEN_SKEW_MS);
+  return state.token;
+}
+
+async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
+  var token = await _paypalToken(opts, state);
+  var headers = {
+    "authorization": "Bearer " + token,
+    "accept":        "application/json",
+    "content-type":  "application/json",
+    "user-agent":    "blamejs-shop (zero-dep)",
+  };
+  if (requestId) headers["paypal-request-id"] = requestId;
+  var body = bodyObj != null ? JSON.stringify(bodyObj) : undefined;
+  if (body) headers["content-length"] = Buffer.byteLength(body, "utf8");
+  var httpClient = opts.httpClient || b.httpClient;
+  var res = await httpClient.request({
+    method:    method,
+    url:       _paypalApiBase(opts) + path,
+    headers:   headers,
+    body:      body,
+    timeoutMs: opts.timeoutMs || PAYPAL_HTTP_TIMEOUT_MS,
+  });
+  var text = res.body && res.body.toString ? res.body.toString("utf8") : "";
+  var json; try { json = text.length ? JSON.parse(text) : {}; } catch (_e) { json = { _raw: text }; }
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    var detail = json && (json.message || (json.details && json.details[0] && json.details[0].description)) || "";
+    var err = new Error("paypal: " + method + " " + path + " → HTTP " + res.statusCode + (detail ? " — " + detail : ""));
+    err.code = (json && json.name) || "PAYPAL_HTTP_" + res.statusCode;
+    err.statusCode = res.statusCode;
+    err.paypal = json || null;
+    throw err;
+  }
+  Object.defineProperty(json, "_paypalStatus",  { value: res.statusCode, enumerable: false });
+  Object.defineProperty(json, "_paypalRawText", { value: text,           enumerable: false });
+  return json;
+}
+
+function paypal(opts) {
   opts = opts || {};
-  if (opts.adapter && opts.adapter !== "stripe") {
-    throw new TypeError("payment.create: unknown adapter " + JSON.stringify(opts.adapter) + " — only 'stripe' is supported in v1");
+  _assertSecret(opts.clientId, "clientId");
+  _assertSecret(opts.secret,   "secret");
+  if (opts.query != null && typeof opts.query !== "function") {
+    throw new TypeError("payment: query must be a function (sql, params) => Promise<{ rows }>");
+  }
+  if (opts.now != null && typeof opts.now !== "function") {
+    throw new TypeError("payment: now must be a function returning current epoch ms");
+  }
+  var state = {
+    query:          opts.query || null,
+    now:            typeof opts.now === "function" ? opts.now : function () { return Date.now(); },
+    token:          null,
+    tokenExpiresAt: 0,
+  };
+
+  function _maybeIdempotent(operation, idempotencyKey, requestObj, doCall) {
+    if (!state.query || idempotencyKey == null) return doCall();
+    return _runIdempotent(state, operation, idempotencyKey, requestObj, doCall);
   }
-  return stripe(opts);
+
+  function _amount(input, label) {
+    _positiveInt(input.amount_minor, "amount_minor");
+    if (typeof input.currency !== "string" || !/^[A-Z]{3}$/.test(input.currency)) {
+      throw new TypeError("payment." + label + ": currency must be a 3-letter uppercase ISO 4217 code");
+    }
+    return { currency_code: input.currency, value: _minorToDecimalString(input.amount_minor, input.currency) };
+  }
+
+  return {
+    name: "paypal",
+
+    // Create an Orders-v2 order (intent CAPTURE). The returned `id` is the
+    // PayPal order id the buyer approves; `captureOrder` finalizes it.
+    createOrder: function (input, idempotencyKey) {
+      if (!input || typeof input !== "object") throw new TypeError("payment.createOrder: input object required");
+      var bodyObj = {
+        intent: "CAPTURE",
+        purchase_units: [{
+          amount:     _amount(input, "createOrder"),
+          custom_id:  input.order_id || undefined,
+          invoice_id: input.invoice_id || undefined,
+        }],
+      };
+      if (input.return_url || input.cancel_url) {
+        bodyObj.payment_source = { paypal: { experience_context: {
+          return_url: input.return_url || undefined,
+          cancel_url: input.cancel_url || undefined,
+        } } };
+      }
+      var requestId = "order:" + (input.order_id || idempotencyKey || b.uuid.v7());
+      return _maybeIdempotent("paypal_order.create", idempotencyKey, { op: "createOrder", input: input }, function () {
+        return _paypalCall(opts, state, "POST", "/v2/checkout/orders", bodyObj, requestId);
+      });
+    },
+
+    // Capture an approved order. Returns the capture resource (the
+    // `purchase_units[0].payments.captures[0].id` is the capture id refunds
+    // reference).
+    captureOrder: function (orderId, idempotencyKey) {
+      if (typeof orderId !== "string" || !orderId.length) throw new TypeError("payment.captureOrder: orderId required");
+      var requestId = "capture:" + orderId + (idempotencyKey ? ":" + idempotencyKey : "");
+      return _maybeIdempotent("paypal_capture.create", idempotencyKey, { op: "captureOrder", orderId: orderId }, function () {
+        return _paypalCall(opts, state, "POST", "/v2/checkout/orders/" + encodeURIComponent(orderId) + "/capture", {}, requestId);
+      });
+    },
+
+    getOrder: function (orderId) {
+      if (typeof orderId !== "string" || !orderId.length) throw new TypeError("payment.getOrder: orderId required");
+      return _paypalCall(opts, state, "GET", "/v2/checkout/orders/" + encodeURIComponent(orderId), null, null);
+    },
+
+    // Refund a capture — full when no amount is given, partial with
+    // { amount_minor, currency }.
+    refund: function (input, idempotencyKey) {
+      if (!input || typeof input !== "object") throw new TypeError("payment.refund: input object required");
+      if (typeof input.capture_id !== "string" || !input.capture_id.length) {
+        throw new TypeError("payment.refund: capture_id required");
+      }
+      var bodyObj = {};
+      if (input.amount_minor != null) bodyObj.amount = _amount(input, "refund");
+      if (input.note_to_payer) bodyObj.note_to_payer = input.note_to_payer;
+      if (input.invoice_id)    bodyObj.invoice_id = input.invoice_id;
+      // Multiple partial refunds on the SAME capture are legitimate + distinct,
+      // so the PayPal-Request-Id (PayPal's idempotency identity) must be unique
+      // per call by default — reusing `capture_id` alone would make PayPal
+      // replay the first refund instead of executing the next. A caller that
+      // wants a retry deduplicated passes an explicit idempotencyKey (or
+      // input.idempotency_suffix); otherwise a fresh uuid keeps each refund
+      // its own request. (createOrder / captureOrder stay stable on purpose —
+      // retrying those SHOULD be idempotent.)
+      var requestId = "refund:" + input.capture_id + ":" + (idempotencyKey || input.idempotency_suffix || b.uuid.v7());
+      return _maybeIdempotent("paypal_refund.create", idempotencyKey, { op: "refund", input: input }, function () {
+        return _paypalCall(opts, state, "POST",
+          "/v2/payments/captures/" + encodeURIComponent(input.capture_id) + "/refund", bodyObj, requestId);
+      });
+    },
+
+    // Verify an inbound webhook by calling PayPal's verify-webhook-signature
+    // API with the transmission headers + the configured webhook id + the
+    // event body. Returns { ok, event } on a SUCCESS verification status,
+    // { ok:false, reason } otherwise (drop-silent — never throws).
+    verifyWebhook: async function (headers, rawBody, vOpts) {
+      var webhookId = (vOpts && vOpts.webhookId) || opts.webhookId;
+      if (!webhookId) return { ok: false, reason: "no-webhook-id" };
+      var authAlgo        = _headerCI(headers, "paypal-auth-algo");
+      var certUrl         = _headerCI(headers, "paypal-cert-url");
+      var transmissionId  = _headerCI(headers, "paypal-transmission-id");
+      var transmissionSig = _headerCI(headers, "paypal-transmission-sig");
+      var transmissionTime= _headerCI(headers, "paypal-transmission-time");
+      if (!authAlgo || !certUrl || !transmissionId || !transmissionSig || !transmissionTime) {
+        return { ok: false, reason: "missing-transmission-headers" };
+      }
+      var event;
+      try { event = typeof rawBody === "string" ? JSON.parse(rawBody) : rawBody; }
+      catch (_e) { return { ok: false, reason: "malformed-body" }; }
+      var verifyBody = {
+        auth_algo:         authAlgo,
+        cert_url:          certUrl,
+        transmission_id:   transmissionId,
+        transmission_sig:  transmissionSig,
+        transmission_time: transmissionTime,
+        webhook_id:        webhookId,
+        webhook_event:     event,
+      };
+      var res;
+      try { res = await _paypalCall(opts, state, "POST", "/v1/notifications/verify-webhook-signature", verifyBody, null); }
+      catch (e) { return { ok: false, reason: "verify-call-failed", error: e && e.message }; }
+      if (res && res.verification_status === "SUCCESS") return { ok: true, event: event };
+      return { ok: false, reason: "verification-status-" + ((res && res.verification_status) || "unknown") };
+    },
+  };
+}
+
+function create(opts) {
+  opts = opts || {};
+  var adapter = opts.adapter || "stripe";
+  if (adapter === "stripe") return stripe(opts);
+  if (adapter === "paypal") return paypal(opts);
+  throw new TypeError("payment.create: unknown adapter " + JSON.stringify(opts.adapter) + " — 'stripe' and 'paypal' are supported");
 }
 
 module.exports = {
   create:                    create,
   stripe:                    stripe,
+  paypal:                    paypal,
   STRIPE_WEBHOOK_TOLERANCE:  STRIPE_WEBHOOK_TOLERANCE,
   IDEMPOTENCY_TTL_MS:        IDEMPOTENCY_TTL_MS,
   // Exposed for tests + Worker to share form-encoding shape.

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.53",
-      "tag": "v0.12.53",
+      "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,10 @@ 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).
 
 - v0.12.52 (2026-05-25) — **`b.privacyPass` — Privacy Pass origin-side token verification (RFC 9577 / 9578).** Anonymous, publicly verifiable authorization: an origin issues a WWW-Authenticate: PrivateToken challenge and verifies a presented token cryptographically, without learning who the client is and without a callback to the issuer. b.privacyPass implements the publicly verifiable token type 0x0002 (Blind RSA, 2048-bit): the token's authenticator is an RSA Blind Signature (RFC 9474) checked as RSASSA-PSS (SHA-384, 48-byte salt) over token_input = token_type ‖ nonce ‖ challenge_digest ‖ token_key_id, using only the issuer's public key. The token is bound to that key (token_key_id) and, optionally, to the challenge it answers, so a token minted for another origin is refused. Blind RSA is the algorithm Privacy Pass defines on the wire — like the DNSSEC / DANE verifiers it validates an external protocol's signatures rather than introducing classical crypto as a framework default. Verified against the RFC 9578 §8.2 test vector. **Added:** *`b.privacyPass.verifyToken(opts)` / `parseToken` / `buildChallenge`* — `buildChallenge` builds a TokenChallenge (RFC 9577 §2.1) and the matching `WWW-Authenticate: PrivateToken challenge=…, token-key=…` header an origin returns to request a token, scoped to an issuer (and optionally an origin and a 32-byte redemption context). `parseToken` splits a token into its fields (type / nonce / challenge_digest / token_key_id / authenticator). `verifyToken` verifies a type 0x0002 (Blind RSA) token: it confirms the token's `token_key_id` is the SHA-256 of the supplied issuer public key, optionally that its `challenge_digest` matches `opts.challenge`, and that the authenticator is a valid RSASSA-PSS signature over the token input. Refuses unknown / privately verifiable token types (the VOPRF type 0x0001 needs the issuer secret and is an issuer-side operation), key-id and challenge mismatches, and tampered authenticators. Marked experimental while the issuance protocols see deployment.

package/lib/vendor/blamejs/README.md

@@ -98,6 +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 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.53",
-  "createdAt": "2026-05-25T17:13:42.241Z",
+  "frameworkVersion": "0.12.55",
+  "createdAt": "2026-05-25T19:45:48.985Z",
   "exports": {
     "a2a": {
       "type": "object",
@@ -48694,14 +48694,42 @@
     "structuredFields": {
       "type": "object",
       "members": {
+        "ByteSequence": {
+          "type": "function",
+          "arity": 1
+        },
+        "Date": {
+          "type": "function",
+          "arity": 1
+        },
+        "Decimal": {
+          "type": "function",
+          "arity": 1
+        },
+        "DisplayString": {
+          "type": "function",
+          "arity": 1
+        },
+        "Token": {
+          "type": "function",
+          "arity": 1
+        },
         "containsControlBytes": {
           "type": "function",
           "arity": 2
         },
+        "parse": {
+          "type": "function",
+          "arity": 3
+        },
         "refuseControlBytes": {
           "type": "function",
           "arity": 2
         },
+        "serialize": {
+          "type": "function",
+          "arity": 3
+        },
         "splitTopLevel": {
           "type": "function",
           "arity": 2