@swell/apps-sdk 2.0.0-alpha.0 → 2.0.0-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 The Swell Apps SDK is a TypeScript library for building server-side Swell apps. It
 provides access to the Backend and Storefront APIs, along with helpers for app
-configuration, customer sessions and staff identity.
+configuration, customer sessions and store user identity.
 
 Use it in Swell-hosted apps, Cloudflare Workers or Node.js servers. For browser
 applications, use [`swell-js`](https://github.com/swellstores/swell-js).
@@ -21,22 +21,30 @@ Version 2 replaces the 1.x theme API. Existing theme applications should remain
 
 ## Getting started
 
-### Headers and app proxying
+### Request context
 
-When your app runs on Swell, the platform supplies request headers with API
-credentials, store configuration and storefront context. Pass the request's headers
-to the SDK to work with the current store. Create clients for each incoming request.
+Swell supplies the current store's configuration, credentials and store user identity
+with each request. Verify this context once, then reuse it to create clients and check
+store user access. Use the same pattern for Swell-hosted and self-hosted frontends.
 
-Only use these headers when they come through Swell's trusted proxy. On other servers,
-use explicit credentials as shown below.
+```ts
+import { verifySwellContext } from '@swell/apps-sdk';
+
+const context = await verifySwellContext(request.headers, {
+  appId: 'my-app', // Your app's configured slug.
+});
+```
+
+In a server component, pass `await headers()`. Keep the context and clients on the
+server, scoped to the incoming request.
 
 ### Backend API calls
 
 ```ts
 import { SwellBackendAPI } from '@swell/apps-sdk';
 
-// Use the credentials supplied to your Swell-hosted app.
-const backend = new SwellBackendAPI({ headers: request.headers });
+// Reuse the context resolved for this request.
+const backend = new SwellBackendAPI({ context });
 
 // Fetch products from the Backend API.
 const products = await backend.get('/products', { limit: 10 });
@@ -58,8 +66,8 @@ pending writes and deletions.
 import { getStorefrontConfig } from '@swell/apps-sdk';
 import { createStorefrontClient } from '@swell/apps-sdk/storefront';
 
-// Build the storefront config from the platform headers.
-const config = getStorefrontConfig(request.headers);
+// Build public storefront configuration from the request context.
+const config = getStorefrontConfig(context);
 const storefront = createStorefrontClient(config, {
   cookies: {
     get: name => cookies.get(name)?.value,
@@ -86,33 +94,29 @@ import swell from 'swell-js';
 swell.init(config.storeId, config.publicKey, config);
 ```
 
-This config excludes backend credentials. For server-side metadata, use
-`parseSwellHeaders(headers)`. It reads headers without verifying their signature;
-keep its result on the server because it includes the backend token.
+Send only this public config to the browser; the request context contains server credentials.
 
-### Staff identity
+### Store users
 
-Use `requireStaff` to check that a request belongs to a staff member of the current
-store before applying your application's permission checks:
+A store user is someone signed in to the store's Swell dashboard. Use
+`requireStoreUser` to check that a request belongs to one before applying your
+application's permission checks:
 
 ```ts
-import { requireStaff } from '@swell/apps-sdk';
+import { requireStoreUser } from '@swell/apps-sdk';
 
-const staff = await requireStaff({
-  headers: request.headers,
-  method: request.method,
-  origin: appOrigin, // Your configured app origin.
-  cookies: { get: name => cookies.get(name)?.value },
-});
+const storeUser = requireStoreUser(context); // { userId, storeId }, or a 401 SwellError.
+const optional = context.storeUser; // null for a visitor; no exception needed.
 ```
 
 ## API reference
 
 ### Backend client
 
-`apiHost` is a required absolute HTTP(S) URL. Use either `secretKey` or `accessToken`;
-do not mix explicit credentials with `headers`. Invalid constructor options throw
-immediately. All backend methods return promises and reject on failure.
+Pass `{ context }` for a frontend request, or explicit credentials for an external
+server. Backend calls require an access token or secret key and an absolute HTTP(S)
+`apiHost`. Do not mix input sources. Invalid constructor options throw immediately;
+all backend methods return promises and reject on failure.
 
 | Method | Result |
 | --- | --- |
@@ -142,7 +146,7 @@ defaults: `limit` counts additional attempts, and delays are in milliseconds. On
 `transaction_conflict` and `transaction_throttled` retry. Ordinary requests and network
 failures are not retried.
 
-**Private functions:** use the app slug from `Swell-App-Id` and authorize the caller
+**Private functions:** use the app slug from `context.appId` and authorize the caller
 first. `options.method` defaults to `post`; `get`, `put` and `delete` are also supported.
 GET data must contain only flat string, number or boolean values. Caller headers are
 not forwarded; response status and headers are not returned. Function errors and
@@ -166,14 +170,45 @@ rotation during GET requests. A supplied writer may throw or skip a write; after
 its reader must still report the actual state. Writer return values are ignored.
 Persist cookies in writable route handlers or actions.
 
-For caching, replace `storefront.request` before first use. The SDK has no built-in cache.
+For API response caching, replace `storefront.request` before first use. The SDK
+leaves response caching to your application.
+
+### Request context options
+
+`verifySwellContext(headers, { env?, appId?, storeId?, vaultUrl? })` returns the request
+context or throws if verification fails. Set `appId` and, for a single-store app,
+`storeId` from trusted configuration to reject contexts intended for another app or
+store. Without these options, it verifies the source but does not restrict the
+destination. `vaultUrl` provides an optional vault endpoint override.
+
+Configuration is read from `process.env`, or from `env` when supplied. Workers without
+Node compatibility should pass their bindings as `env`.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SWELL_VERIFY_HEADERS` | enabled | Set exactly `"false"` to skip signature verification during local development. |
+| `SWELL_HEADERS_JWKS_URL` | `https://swell.store/.well-known/jwks.json` | Override the verification-key endpoint. |
+
+For local development against a local Swell instance, put `SWELL_VERIFY_HEADERS=false`
+in `.dev.vars`. Remove it or set it to `"true"` to restore verification. Token structure
+and claim validation still apply, but the context is no longer authenticated: anyone
+who can reach the frontend directly can supply forged context, including a store user.
+Use this bypass only for local development.
+
+For server integrations, construct `SwellBackendAPI` with explicit credentials and
+`createStorefrontClient` with explicit public configuration. These clients do not
+require an HTTP request or a store user.
+
+### Store users
 
-### Staff verification
+`requireStoreUser(context)` returns `{ userId, storeId }` or throws `SwellError` with
+status 401 and code `store_user_required`. For optional access, read
+`context.storeUser`, which is null for visitors.
 
-`requireStaff` verifies `_swell_admin_session` against the current store and returns
-`{ userId, storeId }`. Use a trusted `appOrigin`: every non-GET request requires a
-matching `Origin` and, when present, `Sec-Fetch-Site: same-origin`. Failures reject.
-The helper checks identity and request origin; your application enforces permissions.
+A store user is anyone signed in to the store's dashboard, including partners and Swell
+support, who may not appear in the store's own user list. Swell's proxy handles their
+authentication and write-origin checks; your application decides what each store user
+may do.
 
 ### Errors
 
@@ -185,8 +220,10 @@ error handling; `message` is for people and may change.
   `body`. Successful GET responses containing `errors` are returned as data.
 - Function invocation failures retain the response payload, or the invocation envelope
   when the payload is null or absent, in `body`.
-- Network errors remain native. Local configuration errors may be ordinary `Error`
-  instances; not every failure is a `SwellError`.
+- Header verification uses 401 / `invalid_swell_context` for absent, malformed, expired
+  or rejected tokens, and 503 / `swell_jwks_unavailable` for key-service failures.
+- Backend/storefront network errors remain native. Local configuration errors may be
+  ordinary `Error` instances; not every failure is a `SwellError`.
 
 ## Development
 

package/dist/backend.d.cts

@@ -1,7 +1,7 @@
-import type { HeaderReader } from './context.cjs';
+import type { SwellRequestContext } from './request-context.cjs';
 export type SwellData = Record<string, any>;
 export type BackendOptions = {
-    headers: HeaderReader;
+    context: SwellRequestContext;
     storeId?: never;
     apiHost?: never;
     accessToken?: never;
@@ -9,7 +9,7 @@ export type BackendOptions = {
     appId?: never;
     requestId?: never;
 } | ({
-    headers?: never;
+    context?: never;
     storeId: string;
     apiHost: string;
     appId?: string;
@@ -47,7 +47,7 @@ export interface TransactionOptions {
         jitter?: boolean;
     };
 }
-/** Per-request backend client. Use explicit credentials outside trusted platform ingress. */
+/** Backend client from a frontend request context or explicit server credentials. */
 export declare class SwellBackendAPI {
     #private;
     protected get userAgent(): string;
@@ -59,7 +59,7 @@ export declare class SwellBackendAPI {
         /**
          * Invokes an app's private function from server code and resolves to its response payload,
          * without the envelope's status or headers.
-         * `appId` is the app identifier from `Swell-App-Id` (`parseSwellHeaders(headers).appId`).
+         * `appId` is the app identifier from the request context (`context.appId`).
          * `method` (default `post`) selects the function's handler. GET data reaches the function
          * as query parameters, so its values must be flat strings, numbers or booleans.
          * Throws `SwellError` when the function reports a non-2xx status or an error.

package/dist/backend.d.ts

@@ -1,7 +1,7 @@
-import type { HeaderReader } from './context.js';
+import type { SwellRequestContext } from './request-context.js';
 export type SwellData = Record<string, any>;
 export type BackendOptions = {
-    headers: HeaderReader;
+    context: SwellRequestContext;
     storeId?: never;
     apiHost?: never;
     accessToken?: never;
@@ -9,7 +9,7 @@ export type BackendOptions = {
     appId?: never;
     requestId?: never;
 } | ({
-    headers?: never;
+    context?: never;
     storeId: string;
     apiHost: string;
     appId?: string;
@@ -47,7 +47,7 @@ export interface TransactionOptions {
         jitter?: boolean;
     };
 }
-/** Per-request backend client. Use explicit credentials outside trusted platform ingress. */
+/** Backend client from a frontend request context or explicit server credentials. */
 export declare class SwellBackendAPI {
     #private;
     protected get userAgent(): string;
@@ -59,7 +59,7 @@ export declare class SwellBackendAPI {
         /**
          * Invokes an app's private function from server code and resolves to its response payload,
          * without the envelope's status or headers.
-         * `appId` is the app identifier from `Swell-App-Id` (`parseSwellHeaders(headers).appId`).
+         * `appId` is the app identifier from the request context (`context.appId`).
          * `method` (default `post`) selects the function's handler. GET data reaches the function
          * as query parameters, so its values must be flat strings, numbers or booleans.
          * Throws `SwellError` when the function reports a non-2xx status or an error.

package/dist/backend.js

@@ -1,4 +1,4 @@
-import { parseSwellHeaders, requireString, validateUrl } from './context.js';
+import { requireString, validateUrl } from './context.js';
 import { SwellError } from './error.js';
 import { validateWorkflowParams } from './workflow.js';
 import { USER_AGENT } from './version.js';
@@ -17,7 +17,7 @@ function queryParts(query, prefix = '') {
             : [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
     });
 }
-/** Per-request backend client. Use explicit credentials outside trusted platform ingress. */
+/** Backend client from a frontend request context or explicit server credentials. */
 export class SwellBackendAPI {
     #baseUrl;
     #authorization;
@@ -37,7 +37,7 @@ export class SwellBackendAPI {
         /**
          * Invokes an app's private function from server code and resolves to its response payload,
          * without the envelope's status or headers.
-         * `appId` is the app identifier from `Swell-App-Id` (`parseSwellHeaders(headers).appId`).
+         * `appId` is the app identifier from the request context (`context.appId`).
          * `method` (default `post`) selects the function's handler. GET data reaches the function
          * as query parameters, so its values must be flat strings, numbers or booleans.
          * Throws `SwellError` when the function reports a non-2xx status or an error.
@@ -65,10 +65,12 @@ export class SwellBackendAPI {
         },
     };
     constructor(options) {
-        if (options.headers && ['storeId', 'apiHost', 'accessToken', 'secretKey', 'appId', 'requestId'].some(key => key in options)) {
-            throw new Error('headers and explicit backend credentials are mutually exclusive');
+        if ('headers' in options)
+            throw new Error('Pass a request context or explicit credentials, not raw headers');
+        if (options.context && ['storeId', 'apiHost', 'accessToken', 'secretKey', 'appId', 'requestId'].some(key => key in options)) {
+            throw new Error('context and explicit backend credentials are mutually exclusive');
         }
-        const config = options.headers ? parseSwellHeaders(options.headers) : options;
+        const config = options.context ?? options;
         const secretKey = 'secretKey' in config ? config.secretKey : undefined;
         requireString(config.storeId, 'storeId');
         if ((config.accessToken !== undefined) === (secretKey !== undefined))

package/dist/context.d.cts

@@ -1,21 +1,7 @@
 import type { PublicConfig } from 'swell-js';
+import type { SwellRequestContext } from './request-context.cjs';
 export type HeaderReader = Pick<Headers, 'get'>;
-export interface SwellContext {
-    storeId?: string;
-    appId?: string;
-    environmentId?: string;
-    storefrontId?: string;
-    accessToken?: string;
-    publicKey?: string;
-    apiHost?: string;
-    adminUrl?: string;
-    vaultUrl?: string;
-    requestId?: string;
-    isLocalDev: boolean;
-}
-/** Parses trusted ingress headers; does not verify their signature. */
-export declare function parseSwellHeaders(headers: HeaderReader): SwellContext;
 export declare function requireString(value: unknown, field: string): asserts value is string;
 export declare function validateUrl(value: unknown, field: string): string;
 /** Projects only public configuration. Deliver it with Cache-Control: private, no-store. */
-export declare function getStorefrontConfig(headers: HeaderReader): PublicConfig;
+export declare function getStorefrontConfig(context: SwellRequestContext): PublicConfig;

package/dist/context.d.ts

@@ -1,21 +1,7 @@
 import type { PublicConfig } from 'swell-js';
+import type { SwellRequestContext } from './request-context.js';
 export type HeaderReader = Pick<Headers, 'get'>;
-export interface SwellContext {
-    storeId?: string;
-    appId?: string;
-    environmentId?: string;
-    storefrontId?: string;
-    accessToken?: string;
-    publicKey?: string;
-    apiHost?: string;
-    adminUrl?: string;
-    vaultUrl?: string;
-    requestId?: string;
-    isLocalDev: boolean;
-}
-/** Parses trusted ingress headers; does not verify their signature. */
-export declare function parseSwellHeaders(headers: HeaderReader): SwellContext;
 export declare function requireString(value: unknown, field: string): asserts value is string;
 export declare function validateUrl(value: unknown, field: string): string;
 /** Projects only public configuration. Deliver it with Cache-Control: private, no-store. */
-export declare function getStorefrontConfig(headers: HeaderReader): PublicConfig;
+export declare function getStorefrontConfig(context: SwellRequestContext): PublicConfig;

package/dist/context.js

@@ -1,15 +1,3 @@
-/** Parses trusted ingress headers; does not verify their signature. */
-export function parseSwellHeaders(headers) {
-    const read = (name) => headers.get(`Swell-${name}`) ?? undefined;
-    return {
-        storeId: read('Store-Id'), appId: read('App-Id'),
-        environmentId: read('Environment-Id'), storefrontId: read('Storefront-Id'),
-        accessToken: read('Access-Token'), publicKey: read('Public-Key'),
-        apiHost: read('API-Host'), adminUrl: read('Admin-Url'),
-        vaultUrl: read('Vault-Url'), requestId: read('Request-ID'),
-        isLocalDev: read('Local-Dev') === 'true',
-    };
-}
 export function requireString(value, field) {
     if (typeof value !== 'string' || !value.trim())
         throw new Error(`Missing or invalid ${field}`);
@@ -29,8 +17,7 @@ export function validateUrl(value, field) {
     return url.href.replace(/\/$/, '');
 }
 /** Projects only public configuration. Deliver it with Cache-Control: private, no-store. */
-export function getStorefrontConfig(headers) {
-    const context = parseSwellHeaders(headers);
+export function getStorefrontConfig(context) {
     requireString(context.storeId, 'storeId');
     requireString(context.publicKey, 'publicKey');
     return {

package/dist/index.d.cts

@@ -1,9 +1,11 @@
 import './guard.cjs';
-export { parseSwellHeaders, getStorefrontConfig } from './context.cjs';
-export type { HeaderReader, SwellContext } from './context.cjs';
+export { getStorefrontConfig } from './context.cjs';
+export type { HeaderReader } from './context.cjs';
+export { verifySwellContext } from './request-context.cjs';
+export type { SwellRequestContext, SwellHeadersEnv, VerifySwellContextOptions } from './request-context.cjs';
 export { SwellBackendAPI } from './backend.cjs';
 export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.cjs';
 export { SwellError } from './error.cjs';
 export type { SwellErrorOptions } from './error.cjs';
-export { requireStaff } from './staff.cjs';
-export type { StaffIdentity, StaffOptions } from './staff.cjs';
+export { requireStoreUser } from './store-user.cjs';
+export type { StoreUser } from './store-user.cjs';

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import './guard.js';
-export { parseSwellHeaders, getStorefrontConfig } from './context.js';
-export type { HeaderReader, SwellContext } from './context.js';
+export { getStorefrontConfig } from './context.js';
+export type { HeaderReader } from './context.js';
+export { verifySwellContext } from './request-context.js';
+export type { SwellRequestContext, SwellHeadersEnv, VerifySwellContextOptions } from './request-context.js';
 export { SwellBackendAPI } from './backend.js';
 export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.js';
 export { SwellError } from './error.js';
 export type { SwellErrorOptions } from './error.js';
-export { requireStaff } from './staff.js';
-export type { StaffIdentity, StaffOptions } from './staff.js';
+export { requireStoreUser } from './store-user.js';
+export type { StoreUser } from './store-user.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 import './guard.js';
-export { parseSwellHeaders, getStorefrontConfig } from './context.js';
+export { getStorefrontConfig } from './context.js';
+export { verifySwellContext } from './request-context.js';
 export { SwellBackendAPI } from './backend.js';
 export { SwellError } from './error.js';
-export { requireStaff } from './staff.js';
+export { requireStoreUser } from './store-user.js';

package/dist/jwks.d.cts

@@ -0,0 +1 @@
+export declare function getVerificationKey(url: string, kid: string): Promise<CryptoKey>;

package/dist/jwks.d.ts

@@ -0,0 +1 @@
+export declare function getVerificationKey(url: string, kid: string): Promise<CryptoKey>;

package/dist/jwks.js

@@ -0,0 +1,70 @@
+import { SwellError } from './error.js';
+const CACHE_TTL = 300_000;
+const REFRESH_INTERVAL = 30_000;
+const FAILURE_RETRY_INTERVAL = 1000;
+const MAX_URLS = 8;
+// Public keys only: no tokens, credentials, identities or request results.
+const keySets = new Map();
+async function refresh(url, entry) {
+    entry.refreshAfter = Date.now() + REFRESH_INTERVAL;
+    try {
+        const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(5000) });
+        if (!response.ok)
+            throw new Error('JWKS request failed');
+        const body = await response.json();
+        if (!Array.isArray(body?.keys))
+            throw new Error('Invalid JWKS');
+        const keys = new Map();
+        for (const jwk of body.keys) {
+            if (!jwk || jwk.kty !== 'EC' || jwk.crv !== 'P-256' || (jwk.alg && jwk.alg !== 'ES256') || (jwk.use && jwk.use !== 'sig'))
+                continue;
+            if (typeof jwk.kid !== 'string' || !jwk.kid || keys.has(jwk.kid) || jwk.d)
+                throw new Error('Invalid JWKS key');
+            keys.set(jwk.kid, await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']));
+        }
+        if (!keys.size)
+            throw new Error('Empty JWKS');
+        entry.keys = keys;
+        entry.expiresAt = Date.now() + CACHE_TTL;
+        entry.error = undefined;
+    }
+    catch {
+        entry.refreshAfter = Date.now() + FAILURE_RETRY_INTERVAL;
+        entry.error = new SwellError('Swell verification keys unavailable', { status: 503, code: 'swell_jwks_unavailable' });
+        throw entry.error;
+    }
+}
+export async function getVerificationKey(url, kid) {
+    let entry = keySets.get(url);
+    if (!entry) {
+        if (keySets.size >= MAX_URLS)
+            keySets.delete(keySets.keys().next().value);
+        entry = { keys: new Map(), expiresAt: 0, refreshAfter: 0 };
+        keySets.set(url, entry);
+    }
+    const now = Date.now();
+    const cached = entry.keys.get(kid);
+    if (cached && now < entry.expiresAt)
+        return cached;
+    if (entry.pending) {
+        await entry.pending;
+    }
+    else if (now >= entry.expiresAt || !entry.keys.has(kid)) {
+        if (now >= entry.refreshAfter) {
+            entry.pending = refresh(url, entry);
+            try {
+                await entry.pending;
+            }
+            finally {
+                entry.pending = undefined;
+            }
+        }
+        else if (now >= entry.expiresAt) {
+            throw entry.error ?? new SwellError('Swell verification keys unavailable', { status: 503, code: 'swell_jwks_unavailable' });
+        }
+    }
+    const key = entry.keys.get(kid);
+    if (!key)
+        throw new SwellError('Unknown Swell signing key', { status: 401, code: 'invalid_swell_context' });
+    return key;
+}

package/dist/request-context.d.cts

@@ -0,0 +1,37 @@
+import type { HeaderReader } from './context.cjs';
+import type { StoreUser } from './store-user.cjs';
+export interface SwellHeadersEnv {
+    SWELL_VERIFY_HEADERS?: string;
+    SWELL_HEADERS_JWKS_URL?: string;
+}
+export interface VerifySwellContextOptions {
+    /** Explicit Worker bindings or server configuration. Omit to read process.env when available. */
+    env?: SwellHeadersEnv;
+    /** Expected destination IDs from trusted app configuration, never incoming headers. */
+    appId?: string;
+    storeId?: string;
+    /** Trusted vault override; the unsigned Swell-Vault-Url header is not used. */
+    vaultUrl?: string;
+}
+/** Request-local server data. Only getStorefrontConfig's projection may be sent to the browser. */
+export interface SwellRequestContext {
+    readonly storeId: string;
+    readonly appId: string;
+    readonly installationId: string;
+    readonly environmentId?: string;
+    readonly storefrontId?: string;
+    readonly apiHost: string;
+    readonly adminUrl: string;
+    readonly accessToken?: string;
+    readonly publicKey?: string;
+    readonly requestId?: string;
+    readonly vaultUrl?: string;
+    readonly storeUser: Readonly<StoreUser> | null;
+    /** False only when trusted runtime configuration explicitly disables verification. */
+    readonly signatureVerified: boolean;
+}
+/**
+ * Resolves Swell-Context once per request. Uses ES256 and a pinned JWKS endpoint;
+ * never discovers keys from the request. No fallback to plain headers or dashboard cookies.
+ */
+export declare function verifySwellContext(headers: HeaderReader, options?: VerifySwellContextOptions): Promise<SwellRequestContext>;

package/dist/request-context.d.ts

@@ -0,0 +1,37 @@
+import type { HeaderReader } from './context.js';
+import type { StoreUser } from './store-user.js';
+export interface SwellHeadersEnv {
+    SWELL_VERIFY_HEADERS?: string;
+    SWELL_HEADERS_JWKS_URL?: string;
+}
+export interface VerifySwellContextOptions {
+    /** Explicit Worker bindings or server configuration. Omit to read process.env when available. */
+    env?: SwellHeadersEnv;
+    /** Expected destination IDs from trusted app configuration, never incoming headers. */
+    appId?: string;
+    storeId?: string;
+    /** Trusted vault override; the unsigned Swell-Vault-Url header is not used. */
+    vaultUrl?: string;
+}
+/** Request-local server data. Only getStorefrontConfig's projection may be sent to the browser. */
+export interface SwellRequestContext {
+    readonly storeId: string;
+    readonly appId: string;
+    readonly installationId: string;
+    readonly environmentId?: string;
+    readonly storefrontId?: string;
+    readonly apiHost: string;
+    readonly adminUrl: string;
+    readonly accessToken?: string;
+    readonly publicKey?: string;
+    readonly requestId?: string;
+    readonly vaultUrl?: string;
+    readonly storeUser: Readonly<StoreUser> | null;
+    /** False only when trusted runtime configuration explicitly disables verification. */
+    readonly signatureVerified: boolean;
+}
+/**
+ * Resolves Swell-Context once per request. Uses ES256 and a pinned JWKS endpoint;
+ * never discovers keys from the request. No fallback to plain headers or dashboard cookies.
+ */
+export declare function verifySwellContext(headers: HeaderReader, options?: VerifySwellContextOptions): Promise<SwellRequestContext>;

package/dist/request-context.js

@@ -0,0 +1,95 @@
+import { requireString, validateUrl } from './context.js';
+import { SwellError } from './error.js';
+import { getVerificationKey } from './jwks.js';
+function invalidContext() {
+    return new SwellError('Missing or invalid Swell context', { status: 401, code: 'invalid_swell_context' });
+}
+function decode(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw invalidContext();
+    return Uint8Array.from(atob(value.replace(/-/g, '+').replace(/_/g, '/')), char => char.charCodeAt(0));
+}
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw invalidContext();
+}
+/**
+ * Resolves Swell-Context once per request. Uses ES256 and a pinned JWKS endpoint;
+ * never discovers keys from the request. No fallback to plain headers or dashboard cookies.
+ */
+export async function verifySwellContext(headers, options = {}) {
+    const runtime = globalThis;
+    const env = options.env ?? runtime.process?.env ?? {};
+    const verify = env.SWELL_VERIFY_HEADERS !== 'false';
+    const jwksUrl = validateUrl(env.SWELL_HEADERS_JWKS_URL ?? 'https://swell.store/.well-known/jwks.json', 'SWELL_HEADERS_JWKS_URL');
+    for (const field of ['appId', 'storeId']) {
+        if (options[field] !== undefined)
+            requireString(options[field], field);
+    }
+    const vaultUrl = options.vaultUrl === undefined ? undefined : validateUrl(options.vaultUrl, 'vaultUrl');
+    const token = headers.get('Swell-Context');
+    if (!token || token.length > 16_384)
+        throw invalidContext();
+    let payload;
+    let header;
+    let signature;
+    const parts = token.split('.');
+    try {
+        if (parts.length !== 3)
+            throw invalidContext();
+        header = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(decode(parts[0])));
+        payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(decode(parts[1])));
+        object(header);
+        object(payload);
+        signature = decode(parts[2]);
+        if (header.alg !== 'ES256' || typeof header.kid !== 'string' || !header.kid || header.crit !== undefined || header.b64 !== undefined || signature.length !== 64)
+            throw invalidContext();
+    }
+    catch {
+        throw invalidContext();
+    }
+    if (verify) {
+        const key = await getVerificationKey(jwksUrl, header.kid);
+        if (!await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, signature, new TextEncoder().encode(`${parts[0]}.${parts[1]}`)))
+            throw invalidContext();
+    }
+    try {
+        const now = Date.now() / 1000;
+        // The issuer controls token lifetime; allow five seconds for clock skew.
+        if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat) || payload.iat > now + 5 ||
+            typeof payload.exp !== 'number' || !Number.isFinite(payload.exp) || payload.exp <= now - 5 ||
+            payload.exp <= payload.iat)
+            throw invalidContext();
+        if (payload.nbf !== undefined && (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf) || payload.nbf > now + 5))
+            throw invalidContext();
+        for (const field of ['store_id', 'app_id', 'installation_id'])
+            requireString(payload[field], field);
+        if (payload.aud !== payload.app_id || (options.appId !== undefined && payload.aud !== options.appId) ||
+            (options.storeId !== undefined && payload.store_id !== options.storeId))
+            throw invalidContext();
+        for (const field of ['environment_id', 'storefront_id']) {
+            if (payload[field] != null)
+                requireString(payload[field], field);
+        }
+        let storeUser = null;
+        if (payload.admin !== null) {
+            object(payload.admin);
+            requireString(payload.admin.user_id, 'admin.user_id');
+            storeUser = Object.freeze({ userId: payload.admin.user_id, storeId: payload.store_id });
+        }
+        return Object.freeze({
+            storeId: payload.store_id, appId: payload.app_id,
+            installationId: payload.installation_id,
+            environmentId: payload.environment_id ?? undefined,
+            storefrontId: payload.storefront_id ?? undefined,
+            apiHost: validateUrl(payload.api_host, 'api_host'), adminUrl: validateUrl(payload.admin_url, 'admin_url'),
+            accessToken: headers.get('Swell-Access-Token') ?? undefined,
+            publicKey: headers.get('Swell-Public-Key') ?? undefined,
+            requestId: headers.get('Swell-Request-ID') ?? undefined,
+            vaultUrl, storeUser, signatureVerified: verify,
+        });
+    }
+    catch {
+        throw invalidContext();
+    }
+}

package/dist/store-user.d.cts

@@ -0,0 +1,7 @@
+import type { SwellRequestContext } from './request-context.cjs';
+export interface StoreUser {
+    readonly userId: string;
+    readonly storeId: string;
+}
+/** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
+export declare function requireStoreUser(context: SwellRequestContext): StoreUser;

package/dist/store-user.d.ts

@@ -0,0 +1,7 @@
+import type { SwellRequestContext } from './request-context.js';
+export interface StoreUser {
+    readonly userId: string;
+    readonly storeId: string;
+}
+/** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
+export declare function requireStoreUser(context: SwellRequestContext): StoreUser;

package/dist/store-user.js

@@ -0,0 +1,7 @@
+import { SwellError } from './error.js';
+/** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
+export function requireStoreUser(context) {
+    if (!context.storeUser)
+        throw new SwellError('Store user required', { status: 401, code: 'store_user_required' });
+    return context.storeUser;
+}

package/dist/version.d.cts

@@ -1 +1 @@
-export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.0";
+export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.2";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.0";
+export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Replaced with the package version by the build.
-export const USER_AGENT = 'swell-apps-sdk/2.0.0-alpha.0';
+export const USER_AGENT = 'swell-apps-sdk/2.0.0-alpha.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/apps-sdk",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.2",
   "description": "Server SDK for Swell apps.",
   "type": "module",
   "license": "MIT",

package/dist/staff.d.cts

@@ -1,16 +0,0 @@
-import type { HeaderReader } from './context.cjs';
-export interface StaffIdentity {
-    userId: string;
-    storeId: string;
-}
-export interface StaffOptions {
-    headers: HeaderReader;
-    method: string;
-    /** Trusted app/iframe origin, never an unchecked forwarded-host value. */
-    origin: string;
-    cookies: {
-        get(name: string): string | undefined;
-    };
-}
-/** Verifies store staff identity only. The application still owns authorization policy. */
-export declare function requireStaff({ headers, method, origin, cookies }: StaffOptions): Promise<StaffIdentity>;

package/dist/staff.d.ts

@@ -1,16 +0,0 @@
-import type { HeaderReader } from './context.js';
-export interface StaffIdentity {
-    userId: string;
-    storeId: string;
-}
-export interface StaffOptions {
-    headers: HeaderReader;
-    method: string;
-    /** Trusted app/iframe origin, never an unchecked forwarded-host value. */
-    origin: string;
-    cookies: {
-        get(name: string): string | undefined;
-    };
-}
-/** Verifies store staff identity only. The application still owns authorization policy. */
-export declare function requireStaff({ headers, method, origin, cookies }: StaffOptions): Promise<StaffIdentity>;

package/dist/staff.js

@@ -1,33 +0,0 @@
-import { parseSwellHeaders, requireString, validateUrl } from './context.js';
-import { SwellError } from './error.js';
-import { USER_AGENT } from './version.js';
-/** Verifies store staff identity only. The application still owns authorization policy. */
-export async function requireStaff({ headers, method, origin, cookies }) {
-    const { storeId, adminUrl } = parseSwellHeaders(headers);
-    requireString(storeId, 'storeId');
-    const url = validateUrl(adminUrl, 'adminUrl');
-    requireString(method, 'method');
-    if (method.toUpperCase() !== 'GET') {
-        const expected = validateUrl(origin, 'origin');
-        const supplied = headers.get('Origin');
-        if (new URL(expected).origin !== origin)
-            throw new Error('origin must be an absolute app origin');
-        if (supplied !== origin || (headers.get('Sec-Fetch-Site') !== null && headers.get('Sec-Fetch-Site') !== 'same-origin')) {
-            throw new SwellError('Staff request origin rejected', { status: 403 });
-        }
-    }
-    const sessionId = cookies.get('_swell_admin_session');
-    if (!sessionId)
-        throw new SwellError('Staff session required', { status: 401 });
-    const response = await fetch(new URL('/admin/api/session', url), {
-        headers: { 'X-Session': sessionId, 'User-Agent': USER_AGENT }, redirect: 'manual',
-    });
-    if (response.status === 401 || response.status === 403)
-        throw new SwellError('Invalid staff session', { status: 401 });
-    if (!response.ok)
-        throw new SwellError('Staff session verification failed', { status: response.status });
-    const session = await response.json();
-    if (typeof session?.user_id !== 'string' || !session.user_id || session.client_id !== storeId)
-        throw new SwellError('Invalid staff session', { status: 401 });
-    return { userId: session.user_id, storeId };
-}