@doswiftly/storefront-sdk 22.0.0 → 22.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 22.1.0
+
+### Minor Changes
+
+- 32ee745: Forward the real buyer IP from server-rendered storefronts (per-buyer rate limiting)
+
+  A server-rendered (BFF) storefront fetches from its own server, so the API sees one
+  source IP for every buyer and per-IP rate limits collapse onto that single address.
+  The server client now forwards the real buyer IP to the API so rate limiting applies
+  per buyer again.
+
+  **Automatic on the server — no wiring, fully backward-compatible.** Call
+  `getStorefrontClient({ apiUrl, shopSlug })` as before; forwarding configures itself
+  and stays inert when it cannot apply, so existing setups are unaffected. Server-only.
+
+  Non-Next server runtimes can supply the buyer IP explicitly via `getBuyerIp` (and
+  `getForwardedIpSecret`). The lower-level `forwardedIpMiddleware` is also exported.
+
+  (`@doswiftly/storefront-operations` is a version-sync bump — no code change.)
+
 ## 22.0.0
 
 ### Major Changes

package/README.md

@@ -772,6 +772,11 @@ Middleware that reads mutable state takes a **lazy getter**
 (`authMiddleware(() => store.getState().accessToken)`) so rotated values are
 picked up without rebuilding the client.
 
+A server-only `forwardedIpMiddleware` is also available for server-rendered (BFF)
+storefronts — it forwards the real buyer IP to the backend so per-IP rate limits
+do not collapse onto the storefront server's address. See
+[Server-side](#server-side-reactserver).
+
 ## Core API
 
 ### createStorefrontClient
@@ -1070,6 +1075,40 @@ middleware: [
 ],
 ```
 
+### Forwarding the buyer IP for rate limiting
+
+When a storefront fetches on the server, the API sees the storefront server's IP for
+every buyer, so per-IP rate limits collapse onto a single address. The server client
+forwards the buyer's real IP so rate limiting applies per buyer again.
+
+**Automatic on the server — nothing to wire.** Call `getStorefrontClient` as usual:
+
+```typescript
+const client = getStorefrontClient({
+  apiUrl: process.env.DOSWIFTLY_API_URL!,
+  shopSlug: process.env.DOSWIFTLY_SHOP_SLUG!,
+});
+```
+
+It applies only inside a server request with forwarding configured by your
+deployment, and is otherwise an inert pass-through — existing setups are unaffected.
+**Server-only**: nothing IP-related reaches the browser.
+
+**Non-Next server runtimes** — supply the buyer IP yourself (e.g. from
+`cf-connecting-ip`), plus the signing secret if your runtime has no `process.env`:
+
+```typescript
+const client = getStorefrontClient({
+  apiUrl,
+  shopSlug,
+  getBuyerIp: () => incomingRequest.headers.get('cf-connecting-ip'),
+  // getForwardedIpSecret: () => ...
+});
+```
+
+The lower-level `forwardedIpMiddleware({ getBuyerIp, getSecret })` is also exported
+for fully custom clients.
+
 ## Caching
 
 ```typescript

package/dist/core/index.d.ts

@@ -41,6 +41,7 @@ export { authMiddleware } from './middleware/auth';
 export { cartSecretMiddleware, serverCartSecretMiddleware, CART_SECRET_HEADER, } from './middleware/cart-secret';
 export { currencyMiddleware } from './middleware/currency';
 export { languageMiddleware } from './middleware/language';
+export { forwardedIpMiddleware, forwardedIpSignedMessage, FORWARDED_IP_HEADER, FORWARDED_IP_TS_HEADER, FORWARDED_IP_SIG_HEADER, type ForwardedIpMiddlewareOptions, } from './middleware/forwarded-ip';
 export { botProtectionMiddleware, BOT_PROTECTION_HEADER, type BotProtectionTokenProvider, type BotProtectionConfig, type BotProtectionProviderConfig, type BotProtectionMiddlewareOptions, type FailStrategy, } from './middleware/bot-protection';
 export { retryMiddleware, type RetryOptions } from './middleware/retry';
 export { timeoutMiddleware, type TimeoutOptions } from './middleware/timeout';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -43,6 +43,7 @@ export { authMiddleware } from './middleware/auth';
 export { cartSecretMiddleware, serverCartSecretMiddleware, CART_SECRET_HEADER, } from './middleware/cart-secret';
 export { currencyMiddleware } from './middleware/currency';
 export { languageMiddleware } from './middleware/language';
+export { forwardedIpMiddleware, forwardedIpSignedMessage, FORWARDED_IP_HEADER, FORWARDED_IP_TS_HEADER, FORWARDED_IP_SIG_HEADER, } from './middleware/forwarded-ip';
 export { botProtectionMiddleware, BOT_PROTECTION_HEADER, } from './middleware/bot-protection';
 export { retryMiddleware } from './middleware/retry';
 export { timeoutMiddleware } from './middleware/timeout';

package/dist/core/middleware/forwarded-ip.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Forwarded-IP middleware — lets a SERVER-SIDE (BFF) storefront forward the real
+ * buyer IP to the backend, so per-buyer rate limiting works even though the
+ * backend's connection comes from the storefront server, not the browser.
+ *
+ * Why this exists: when a storefront renders/fetches on the server (server
+ * components, route handlers, server actions), the backend sees ONE source IP —
+ * the storefront server's — for every buyer. Per-IP limits then collapse onto
+ * that single address. This middleware carries the buyer's real IP (read from the
+ * incoming request, e.g. the `cf-connecting-ip` header) in a signed header the
+ * backend can trust.
+ *
+ * Trust model: the header is signed with HMAC-SHA256 over `${ip}.${ts}.${shopSlug}`
+ * using a shared platform secret. The backend recomputes the signature and only
+ * trusts the IP when it matches and the timestamp is fresh. Binding the shop slug
+ * stops a signature from one shop being replayed against another; the timestamp
+ * bounds replay. A spoofed header without a valid signature is ignored by the
+ * backend (it falls back to the connection IP).
+ *
+ * SERVER-ONLY: the secret must never reach the browser. Use this middleware only
+ * in server-side clients (`getStorefrontClient`), never in the browser pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { forwardedIpMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * // `buyerIp` comes from your server framework's incoming request — typically the
+ * // `cf-connecting-ip` request header. `serverSecret` is a server-only env value.
+ * getStorefrontClient({
+ *   apiUrl,
+ *   shopSlug,
+ *   middleware: [
+ *     forwardedIpMiddleware({
+ *       getBuyerIp: () => buyerIp,
+ *       getSecret: () => serverSecret,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+import type { Middleware } from '../client/types';
+/** Header carrying the buyer's real IP, forwarded by a server-side storefront. */
+export declare const FORWARDED_IP_HEADER = "x-doswiftly-buyer-ip";
+/** Header carrying the signature timestamp (unix milliseconds) — bounds replay. */
+export declare const FORWARDED_IP_TS_HEADER = "x-doswiftly-fwd-ts";
+/** Header carrying the hex HMAC-SHA256 signature over `${ip}.${ts}.${shopSlug}`. */
+export declare const FORWARDED_IP_SIG_HEADER = "x-doswiftly-fwd-sig";
+/**
+ * Canonical signed message. The backend MUST build this identically before
+ * verifying the signature. Order and separators are load-bearing.
+ */
+export declare function forwardedIpSignedMessage(ip: string, timestamp: string, shopSlug: string): string;
+/** A getter that may be sync or async (e.g. `async () => (await headers()).get('cf-connecting-ip')`). */
+type MaybeAsyncGetter = () => string | null | undefined | Promise<string | null | undefined>;
+export interface ForwardedIpMiddlewareOptions {
+    /** Real buyer IP from the incoming request (e.g. the `cf-connecting-ip` header). */
+    getBuyerIp: MaybeAsyncGetter;
+    /** Shared platform secret used to sign. Server-side only — never expose to the browser. */
+    getSecret: MaybeAsyncGetter;
+    /**
+     * OPTIONAL override for the shop slug bound into the signature. Defaults to the
+     * `X-Shop-Slug` header the client already sends — so you normally don't pass it,
+     * and the signed slug is guaranteed to match what the backend verifies. Provide
+     * only for non-standard transports that don't set that header.
+     */
+    getShopSlug?: MaybeAsyncGetter;
+    /** Clock source (unix milliseconds). Injectable for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Server-side forwarded-IP middleware. On every request it reads the buyer IP,
+ * shop slug and secret (lazy getters — a rotated secret is picked up without
+ * rebuilding the pipeline), signs `${ip}.${ts}.${shopSlug}` with HMAC-SHA256 and
+ * adds the three forwarded-IP headers. When any input is missing it adds nothing
+ * — the backend then keys the connection IP (the server-side default).
+ *
+ * The HMAC key is imported once per distinct secret value and reused across
+ * requests (re-imported only on rotation).
+ */
+export declare function forwardedIpMiddleware(options: ForwardedIpMiddlewareOptions): Middleware;
+export {};
+//# sourceMappingURL=forwarded-ip.d.ts.map

package/dist/core/middleware/forwarded-ip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarded-ip.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/forwarded-ip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAC1D,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAC3D,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAQ7D;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED,yGAAyG;AACzG,KAAK,gBAAgB,GAAG,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAE7F,MAAM,WAAW,4BAA4B;IAC3C,oFAAoF;IACpF,UAAU,EAAE,gBAAgB,CAAC;IAC7B,2FAA2F;IAC3F,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,UAAU,CAiCvF"}

package/dist/core/middleware/forwarded-ip.js

@@ -0,0 +1,109 @@
+/**
+ * Forwarded-IP middleware — lets a SERVER-SIDE (BFF) storefront forward the real
+ * buyer IP to the backend, so per-buyer rate limiting works even though the
+ * backend's connection comes from the storefront server, not the browser.
+ *
+ * Why this exists: when a storefront renders/fetches on the server (server
+ * components, route handlers, server actions), the backend sees ONE source IP —
+ * the storefront server's — for every buyer. Per-IP limits then collapse onto
+ * that single address. This middleware carries the buyer's real IP (read from the
+ * incoming request, e.g. the `cf-connecting-ip` header) in a signed header the
+ * backend can trust.
+ *
+ * Trust model: the header is signed with HMAC-SHA256 over `${ip}.${ts}.${shopSlug}`
+ * using a shared platform secret. The backend recomputes the signature and only
+ * trusts the IP when it matches and the timestamp is fresh. Binding the shop slug
+ * stops a signature from one shop being replayed against another; the timestamp
+ * bounds replay. A spoofed header without a valid signature is ignored by the
+ * backend (it falls back to the connection IP).
+ *
+ * SERVER-ONLY: the secret must never reach the browser. Use this middleware only
+ * in server-side clients (`getStorefrontClient`), never in the browser pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { forwardedIpMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * // `buyerIp` comes from your server framework's incoming request — typically the
+ * // `cf-connecting-ip` request header. `serverSecret` is a server-only env value.
+ * getStorefrontClient({
+ *   apiUrl,
+ *   shopSlug,
+ *   middleware: [
+ *     forwardedIpMiddleware({
+ *       getBuyerIp: () => buyerIp,
+ *       getSecret: () => serverSecret,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+/** Header carrying the buyer's real IP, forwarded by a server-side storefront. */
+export const FORWARDED_IP_HEADER = 'x-doswiftly-buyer-ip';
+/** Header carrying the signature timestamp (unix milliseconds) — bounds replay. */
+export const FORWARDED_IP_TS_HEADER = 'x-doswiftly-fwd-ts';
+/** Header carrying the hex HMAC-SHA256 signature over `${ip}.${ts}.${shopSlug}`. */
+export const FORWARDED_IP_SIG_HEADER = 'x-doswiftly-fwd-sig';
+/**
+ * Shop routing header the client already attaches to every request (see
+ * `create-client.ts`). The signature binds to THIS slug by default, so the signed
+ * value always matches what the backend verifies from the same header.
+ */
+const SHOP_SLUG_HEADER = 'X-Shop-Slug';
+/**
+ * Canonical signed message. The backend MUST build this identically before
+ * verifying the signature. Order and separators are load-bearing.
+ */
+export function forwardedIpSignedMessage(ip, timestamp, shopSlug) {
+    return `${ip}.${timestamp}.${shopSlug}`;
+}
+async function importHmacKey(secret) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+    ]);
+}
+async function signHex(key, message) {
+    const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(message));
+    return Array.from(new Uint8Array(signature))
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Server-side forwarded-IP middleware. On every request it reads the buyer IP,
+ * shop slug and secret (lazy getters — a rotated secret is picked up without
+ * rebuilding the pipeline), signs `${ip}.${ts}.${shopSlug}` with HMAC-SHA256 and
+ * adds the three forwarded-IP headers. When any input is missing it adds nothing
+ * — the backend then keys the connection IP (the server-side default).
+ *
+ * The HMAC key is imported once per distinct secret value and reused across
+ * requests (re-imported only on rotation).
+ */
+export function forwardedIpMiddleware(options) {
+    const { getBuyerIp, getShopSlug, getSecret, now = () => Date.now() } = options;
+    let cachedSecret = null;
+    let cachedKey = null;
+    return async (request, next) => {
+        // Getters may be async (e.g. reading the IP from `headers()` per request);
+        // `await` resolves sync values unchanged, so sync getters keep working.
+        const ip = await getBuyerIp();
+        // Slug defaults to the routing header the client already sends — so it always
+        // matches what the backend verifies. The optional getter only overrides it.
+        const shopSlug = (await getShopSlug?.()) ?? request.headers[SHOP_SLUG_HEADER];
+        const secret = await getSecret();
+        // Forward only when everything needed for a trusted, shop-bound signature is
+        // present. Missing any piece -> send nothing (backend falls back to conn IP).
+        if (ip && shopSlug && secret) {
+            const timestamp = String(now());
+            if (cachedSecret !== secret || cachedKey === null) {
+                cachedSecret = secret;
+                cachedKey = importHmacKey(secret);
+            }
+            const key = await cachedKey;
+            const signature = await signHex(key, forwardedIpSignedMessage(ip, timestamp, shopSlug));
+            request.headers[FORWARDED_IP_HEADER] = ip;
+            request.headers[FORWARDED_IP_TS_HEADER] = timestamp;
+            request.headers[FORWARDED_IP_SIG_HEADER] = signature;
+        }
+        return next(request);
+    };
+}

package/dist/react/server/get-storefront-client.d.ts

@@ -40,11 +40,29 @@ export interface ServerClientOptions extends Omit<StorefrontClientConfig, 'middl
      * ```
      */
     middleware?: Middleware[];
+    /**
+     * OPTIONAL override for the buyer-IP source. Forwarded-IP signing is
+     * auto-configured: by default the SDK reads the request's `cf-connecting-ip`
+     * via `next/headers` (a server-rendered storefront would otherwise collapse
+     * every buyer onto its own server IP for rate limiting). Provide this only for
+     * non-Next server runtimes where `next/headers` is unavailable. May be async.
+     * Server-side only.
+     */
+    getBuyerIp?: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * OPTIONAL override for the forwarded-IP signing secret. By default it is read
+     * from `process.env.DOSWIFTLY_FORWARDED_IP_SECRET`, set in your DoSwiftly
+     * deployment environment. Provide this getter only to override the env source —
+     * e.g. a runtime that does not expose the secret on `process.env`. Lazy getter —
+     * a rotated secret is picked up without rebuilding the client. NEVER expose this
+     * to the browser. Sync or async.
+     */
+    getForwardedIpSecret?: () => string | null | undefined | Promise<string | null | undefined>;
 }
 /**
  * Create a StorefrontClient for server-side use.
  *
- * Includes default middleware: retry → timeout → errors.
+ * Includes default middleware: forwarded-IP → retry → timeout → errors.
  * Does NOT include auth/currency middleware (server has no Zustand stores).
  * Pass headers via config.defaultHeaders or getHeaders option.
  */

package/dist/react/server/get-storefront-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-storefront-client.d.ts","sourceRoot":"","sources":["../../../src/react/server/get-storefront-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpG,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC;IACrF;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAYlF"}
+{"version":3,"file":"get-storefront-client.d.ts","sourceRoot":"","sources":["../../../src/react/server/get-storefront-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpG,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC;IACrF;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAE1B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAElF;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC7F;AAqBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CA4BlF"}

package/dist/react/server/get-storefront-client.js

@@ -23,18 +23,52 @@ import { createStorefrontClient } from '../../core/client/create-client';
 import { retryMiddleware } from '../../core/middleware/retry';
 import { timeoutMiddleware } from '../../core/middleware/timeout';
 import { errorMiddleware } from '../../core/middleware/errors';
+import { forwardedIpMiddleware } from '../../core/middleware/forwarded-ip';
+/**
+ * Default buyer-IP source: the request's `cf-connecting-ip` header, read via
+ * `next/headers` (the same dynamic-import pattern used to read request cookies — a
+ * graceful no-op outside a Next request scope or in runtimes without
+ * `next/headers`). Override via `getBuyerIp` for other server frameworks.
+ */
+async function readCfConnectingIp() {
+    try {
+        const { headers } = await import('next/headers');
+        const store = await headers();
+        // Prefer a forwarded client-IP header when present: if the request was
+        // proxied, the direct `cf-connecting-ip` is the proxy's address while this
+        // header carries the original client IP. Fall back to the direct connection IP.
+        return store.get('x-doswiftly-client-ip') ?? store.get('cf-connecting-ip');
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Create a StorefrontClient for server-side use.
  *
- * Includes default middleware: retry → timeout → errors.
+ * Includes default middleware: forwarded-IP → retry → timeout → errors.
  * Does NOT include auth/currency middleware (server has no Zustand stores).
  * Pass headers via config.defaultHeaders or getHeaders option.
  */
 export function getStorefrontClient(options) {
-    const { middleware: customMiddleware = [], ...config } = options;
+    const { middleware: customMiddleware = [], getBuyerIp, getForwardedIpSecret, ...config } = options;
+    // Forward the real buyer IP for per-buyer rate limiting — fully self-configured,
+    // nothing for the storefront to wire. Buyer IP defaults to the request's
+    // `cf-connecting-ip` (via next/headers); the signing secret defaults to
+    // `process.env.DOSWIFTLY_FORWARDED_IP_SECRET` (set in the DoSwiftly deployment
+    // environment). The slug comes from the `X-Shop-Slug` header the client already
+    // sends, so the
+    // signed value matches what the backend verifies. The middleware signs ONLY when
+    // BOTH a buyer IP and a secret resolve at request time — so with no secret
+    // configured (or outside a Next request) it is an inert pass-through. Both
+    // getters can be overridden for non-Next runtimes.
+    const resolveBuyerIp = getBuyerIp ?? readCfConnectingIp;
+    const resolveSecret = getForwardedIpSecret ??
+        (() => (typeof process !== 'undefined' ? process.env?.DOSWIFTLY_FORWARDED_IP_SECRET : undefined));
     return createStorefrontClient({
         ...config,
         middleware: [
+            forwardedIpMiddleware({ getBuyerIp: resolveBuyerIp, getSecret: resolveSecret }),
             ...customMiddleware,
             retryMiddleware({ maxRetries: 2 }),
             timeoutMiddleware({ timeout: 10000 }), // Server-side: 10s timeout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,