@doswiftly/storefront-operations 11.3.1 → 11.5.0

package/AGENTS.md

@@ -27,8 +27,8 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 11.3.1
-- **Queries**: 48
+- **Schema version**: 11.5.0
+- **Queries**: 49
 - **Mutations**: 40
 - **Fragments**: 100
 <!-- AUTOGEN:STATS:END -->

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 11.5.0
+
+### Minor Changes
+
+- 190fd9d: Version sync with `@doswiftly/storefront-sdk` (linked release pair). No operations file changes — `OrderByToken` query and `Order.accessToken` field were shipped in the previous version (11.4.0); this bump keeps the operations package version aligned with the SDK release that now selects `accessToken` in its built-in `Order` fragment for `cartComplete`.
+
+  If you already use `@doswiftly/storefront-operations` for codegen, no regeneration is required (`queries.graphql` and `fragments.graphql` are unchanged). The companion `@doswiftly/storefront-sdk` upgrade is where the actual behavior change lands (see that changelog entry).
+
+- e6c80ce: Auth route handlers (`createSetTokenHandler`, `createClearTokenHandler`, `createWhoamiHandler`) now accept an optional `isTrustedOrigin` predicate. This unblocks the BFF auth flow when the storefront runs behind a reverse proxy (DoSwiftly hosting, Vercel, custom edge proxy) that rewrites or strips the `Host` header — since 11.3.0 the strict `Origin host = Host` comparison returned 403 for every login, logout, and page-load hydration in that topology, leaving the auth cookie unset and every auth-gated route redirecting to login.
+
+  ### Fix
+
+  Each handler accepts a new `isTrustedOrigin` callback:
+
+  ```ts
+  type OriginValidator = (ctx: {
+    origin: string;
+    originHost: string;
+    request: Request;
+  }) => boolean | Promise<boolean>;
+  ```
+
+  When the predicate returns truthy the strict `Origin host = Host header` comparison is bypassed; when it returns falsy (or is not configured) the existing strict check applies. A thrown predicate fails closed — the error is logged and the strict check applies as if the predicate returned `false`.
+
+  Two pre-built predicates are exported:
+  - `trustedForwardedHostValidator` — passes when `Origin host` equals `X-Forwarded-Host` (falling back to `X-Original-Host`). Use this when a reverse proxy you control sets one of those headers per request. The DoSwiftly hosting platform and Vercel both qualify.
+  - `originAllowlistValidator(['https://shop.example.com', 'other-shop.example'])` — passes when `Origin` matches an entry in a static list. Useful when one storefront is hosted on multiple hostnames (custom apex + platform subdomain) and you do not want to depend on forwarded-host headers.
+
+  ### Upgrade impact
+  - New storefronts scaffolded via `doswiftly init` ship with `isTrustedOrigin: trustedForwardedHostValidator` configured by default.
+  - Existing storefronts using the SDK behind a reverse proxy need a 3-line change to each route handler under `app/api/auth/`:
+    ```ts
+    import {
+      createSetTokenHandler,
+      trustedForwardedHostValidator,
+    } from "@doswiftly/storefront-sdk";
+    export const POST = createSetTokenHandler({
+      isTrustedOrigin: trustedForwardedHostValidator,
+    });
+    ```
+  - Storefronts deployed without a reverse proxy (single-tier hosting where the Next.js process receives traffic directly) need no changes — the default strict check still works because the Host header arrives intact.
+
+  ### Security
+
+  The predicate is invoked AFTER the Origin header is parsed (rejecting malformed origins) and BEFORE the strict Host comparison. Forwarded-host validation is safe because the trusted intermediary overwrites those headers on every inbound request (`headers.set(...)`, not `append`), so an attacker cannot forge them via a browser `fetch()` — browsers cannot set `X-Forwarded-*` from JavaScript (they are forbidden request headers per the fetch spec).
+
+  Defense-in-depth layers continue to apply: CORS preflight at the backend, `SameSite=Lax` on the auth cookie, `HttpOnly` + `Secure` cookie attributes, and the strict Origin URL parse (still rejects malformed origin and the `?host=trusted` query-string bypass).
+
+## 11.4.0
+
+### Minor Changes
+
+- 9bd60e8: Added `OrderByToken` query and `accessToken` field on the `Order` type for guest order summary access.
+
+  **What's new for storefronts:**
+  - **`Order.accessToken: String!`** — opaque per-order token returned in `cartComplete.order.accessToken`. Pass it to `OrderByToken` to render the order summary for guests who have not signed in. The token is permanent until the order is deleted and stable across reads (safe to share via signed URLs in confirmation emails).
+  - **`OrderByToken($token: String!, $email: String)` query** — fetches a single order using the access token. The optional `email` argument is a defense-in-depth guard: when provided, it must match the order's buyer email case-insensitively; on mismatch the query returns `null` exactly like an invalid token (response shape is identical so attackers cannot distinguish the failure mode).
+  - Rate-limited to 5 requests per minute per IP+shop. Throttled clients receive a GraphQL error with `extensions.code: THROTTLED`.
+  - Response carries `Cache-Control: no-store` so per-customer data is never served from CDN or browser cache between users.
+
+  **Storage recommendation:** persist the token in an **HTTP-only cookie** (preferred) or `sessionStorage` for the post-checkout summary page — **never `localStorage`** (XSS-readable).
+
+  **Backward compatibility:** strictly additive. Existing queries (`CustomerOrder`, cart mutations, customer auth) are unchanged — upgrade is opt-in.
+
 ## 11.3.1
 
 ### Patch Changes

package/README.md

@@ -201,6 +201,7 @@ full executable body of each operation.
 | `Customer` | Full customer profile — basic info plus the first 10 addresses and first 10 orders. Heaviest customer query; for narrow use cases prefer `CustomerProfile` (no orders / addresses) or `CustomerOrder` (single order). Returns null if unauthenticated. |
 | `CustomerProfile` | Lightweight customer profile (no orders, no addresses list). Use for settings / profile pages that only need basic customer info — much cheaper than `Customer`. Returns null if unauthenticated. |
 | `CustomerOrder` | Single order by `orderId`. Returns only orders that belong to the authenticated customer (cross-customer access returns null, not an error). Much cheaper than fetching the full `Customer` payload to access one order. Use on the order detail page. |
+| `OrderByToken` | Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted. |
 
 #### Discount Code Validation
 

package/fragments.graphql

@@ -301,6 +301,7 @@ fragment Customer on Customer {
 fragment Order on Order {
   id
   orderNumber
+  accessToken
   totals {
     total {
       ...Money

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **11.3.1**
-> 48 queries · 40 mutations · 100 fragments
+> Schema version: **11.5.0**
+> 49 queries · 40 mutations · 100 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -430,6 +430,27 @@ query CustomerOrder($orderId: ID!) {
 }
 ```
 
+### Query: `OrderByToken`
+
+**Section**: Customer (requires auth)
+
+**Description**: Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted.
+
+**Variables**:
+- `$token`: `String!`
+- `$email`: `String`
+
+**Fragments used**: `Order`
+
+**GraphQL**:
+```graphql
+query OrderByToken($token: String!, $email: String) {
+  orderByToken(token: $token, email: $email) {
+    ...Order
+  }
+}
+```
+
 ### Query: `CartValidateDiscountCode`
 
 **Section**: Discount Code Validation
@@ -2782,6 +2803,7 @@ fragment Customer on Customer {
 fragment Order on Order {
   id
   orderNumber
+  accessToken
   totals {
     total {
       ...Money

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "11.3.1",
+  "schemaVersion": "11.5.0",
   "queries": [
     {
       "name": "Shop",
@@ -324,6 +324,28 @@
       ],
       "body": "query CustomerOrder($orderId: ID!) {\n  customerOrder(orderId: $orderId) {\n    ...Order\n  }\n}"
     },
+    {
+      "name": "OrderByToken",
+      "kind": "query",
+      "section": "Customer (requires auth)",
+      "description": "Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish \"token valid, wrong email\" from \"token invalid\"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted.",
+      "variables": [
+        {
+          "name": "token",
+          "type": "String!",
+          "defaultValue": null
+        },
+        {
+          "name": "email",
+          "type": "String",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Order"
+      ],
+      "body": "query OrderByToken($token: String!, $email: String) {\n  orderByToken(token: $token, email: $email) {\n    ...Order\n  }\n}"
+    },
     {
       "name": "CartValidateDiscountCode",
       "kind": "query",
@@ -1995,7 +2017,7 @@
         "MailingAddress",
         "Money"
       ],
-      "body": "fragment Order on Order {\n  id\n  orderNumber\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  canCreatePayment\n  paymentMethodType\n}",
+      "body": "fragment Order on Order {\n  id\n  orderNumber\n  accessToken\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  canCreatePayment\n  paymentMethodType\n}",
       "onType": "Order"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "11.3.1",
+  "version": "11.5.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/queries.graphql

@@ -231,6 +231,13 @@ query CustomerOrder($orderId: ID!) {
   }
 }
 
+# Fetch a single order using its opaque access token (`Order.accessToken`) — designed for guest order summary pages where the buyer has not signed in. The token is returned in `cartComplete.order.accessToken` immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or `sessionStorage` for the post-checkout page (NEVER `localStorage`). Optional `email` parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns `null` exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with `extensions.code: THROTTLED`. The response is marked `Cache-Control: no-store` so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted.
+query OrderByToken($token: String!, $email: String) {
+  orderByToken(token: $token, email: $email) {
+    ...Order
+  }
+}
+
 # ============================================
 # Discount Code Validation
 # ============================================

package/schema.graphql

@@ -3571,6 +3571,11 @@ enum NodeType {
 
 """Customer order summary"""
 type Order implements Node {
+  """
+  Opaque access token (UUID v4) umożliwiający dostęp do podsumowania zamówienia bez sesji (guest order access via orderByToken query). Trwały per order — share dla forwarded receipts. Storefront powinien przechowywać HTTP-only cookie / sessionStorage (NIGDY localStorage). Defense-in-depth: orderByToken akceptuje opcjonalny email guard żeby ograniczyć blast radius kompromisu.
+  """
+  accessToken: String!
+
   """Czy storefront może zainicjować płatność dla tego order"""
   canCreatePayment: Boolean!
 
@@ -3592,6 +3597,11 @@ type Order implements Node {
   """Line items count"""
   itemCount: Int!
 
+  """
+  Pozycje zamówienia (top-level connection) — eliminuje N+1 vs Order.shipments.items
+  """
+  lineItems(after: String, first: Int = 10): OrderLineItemConnection!
+
   """Lista meta properties (Relay Connection)"""
   metaProperties(first: Int = 10, namespace: String): MetaPropertyConnection!
 
@@ -3625,9 +3635,12 @@ type Order implements Node {
 
 """Paginated order connection"""
 type OrderConnection {
-  """Order edges"""
+  """Order edges with cursors"""
   edges: [OrderEdge!]!
 
+  """Order nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [Order!]!
+
   """Pagination info"""
   pageInfo: PageInfo!
 
@@ -3656,6 +3669,69 @@ enum OrderFulfillmentStatus {
   UNFULFILLED
 }
 
+"""Pozycja zamówienia (line item) z variant snapshot i live enrichment"""
+type OrderLineItem {
+  """Unique identifier"""
+  id: ID!
+
+  """
+  Całkowita cena linii z momentu zakupu (unitPrice × quantity, minor units)
+  """
+  originalTotalPrice: Money!
+
+  """
+  Cena jednostkowa z momentu zakupu (minor units, include BUNDLED surcharges)
+  """
+  originalUnitPrice: Money!
+
+  """Ilość zamówiona (snapshot z checkout)"""
+  quantity: Int!
+
+  """Ilość już zrealizowana (shipped — per-item fulfillment tracking)"""
+  quantityFulfilled: Int!
+
+  """
+  Ilość pozostała do zwrotu/refund (quantity - returnedQuantity, clamp ≥ 0). Industry-standard semantyka dla refund tracking.
+  """
+  refundableQuantity: Int!
+
+  """
+  Nazwa produktu z momentu zakupu (snapshot). NIE live `Product.name` — preserved nawet po edycji produktu (KSeF/invoice compliance).
+  """
+  title: String!
+
+  """
+  Live wariant produktu (fresh image/price). Null jeśli wariant został usunięty po zakupie — consumer powinien użyć `title` jako fallback.
+  """
+  variant: ProductVariant
+}
+
+"""Paginated order line items (Relay Connection)"""
+type OrderLineItemConnection {
+  """Order line item edges with cursors"""
+  edges: [OrderLineItemEdge!]!
+
+  """Order line item nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [OrderLineItem!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """
+  Total count of line items in the order (convention parity z OrderConnection/MailingAddressConnection)
+  """
+  totalCount: Int!
+}
+
+"""Order line item edge"""
+type OrderLineItemEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """Order line item node"""
+  node: OrderLineItem!
+}
+
 """Payment status of an order"""
 enum OrderPaymentStatus {
   AUTHORIZED
@@ -4701,6 +4777,19 @@ type Query {
   """
   nodes(ids: [ID!]!, type: NodeType!): [Node]!
 
+  """
+  Fetch a single order by its opaque access token (guest order access without a session). Optional `email` argument enables defense-in-depth: if provided, must match the order buyer email (case-insensitive); on mismatch the query returns null exactly like an invalid token. Rate-limited to 5 requests per minute per IP+shop. Response carries Cache-Control: no-store.
+  """
+  orderByToken(
+    """
+    Optional email guard (case-insensitive). When provided, must match the order buyer email; on mismatch returns null (same shape as invalid token). The storefront decides per threat model.
+    """
+    email: String
+
+    """Opaque access token from Order.accessToken"""
+    token: String!
+  ): Order
+
   """Get a page by handle or ID"""
   page(
     """Page handle"""