@serialsubscriptions/platform-integration 0.0.84 → 0.85.4

package/lib/SubscribedPlanManager.d.ts

@@ -36,9 +36,16 @@ import { type JsonApiResource } from './SSISubscribedPlanApi';
  * Attributes for a subscribed_plan--subscribed_plan resource.
  * Based on your JSON sample; extra fields will still be present in the raw JSON:API resource.
  */
+/**
+ * Known values for subscribed plan `status` (and for project `subscription_status`
+ * when synced from the platform). Document the full list in SUBSCRIBEDPLAN_MANAGER.md.
+ */
+export declare const SUBSCRIPTION_STATUS: {};
+export type SubscriptionStatusValue = (typeof SUBSCRIPTION_STATUS)[keyof typeof SUBSCRIPTION_STATUS] | string;
 export interface SubscribedPlanAttributes {
     drupal_internal__id: number;
     name: string;
+    /** Plan status from the platform. See SUBSCRIBEDPLAN_MANAGER.md for possible values. */
     status: string;
     subscription_period: string;
     name_subscript: string | null;

package/lib/SubscribedPlanManager.js

@@ -33,11 +33,26 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubscribedPlanManager = void 0;
+exports.SubscribedPlanManager = exports.SUBSCRIPTION_STATUS = void 0;
 const SSISubscribedPlanApi_1 = require("./SSISubscribedPlanApi");
 const SSISubscribedFeatureApi_1 = require("./SSISubscribedFeatureApi");
 const SSISubscribedLimitApi_1 = require("./SSISubscribedLimitApi");
 const SSICache_1 = require("./cache/SSICache");
+/**
+ * Attributes for a subscribed_plan--subscribed_plan resource.
+ * Based on your JSON sample; extra fields will still be present in the raw JSON:API resource.
+ */
+/**
+ * Known values for subscribed plan `status` (and for project `subscription_status`
+ * when synced from the platform). Document the full list in SUBSCRIBEDPLAN_MANAGER.md.
+ */
+exports.SUBSCRIPTION_STATUS = {
+// Add values as the platform defines them, e.g.:
+// ACTIVE: 'active',
+// CANCELLED: 'cancelled',
+// TRIALING: 'trialing',
+// PAST_DUE: 'past_due',
+};
 /**
  * SubscribedPlanManager
  *

package/lib/auth.server.d.ts

@@ -1,7 +1,16 @@
 import { SSIStorage } from "./storage/SSIStorage";
+import type { AuthConfigInput } from "./requestConfig";
 export declare const scopes: {
     readonly defaultScopes: "openid profile email view_project create_project delete_project update_project view_subscribed_plan view_subscribed_feature view_subscribed_limit access_subscription_usage";
 };
+/**
+ * Get client id and secret for an audience from env (for token endpoint use).
+ * If aud != SSI_CLIENT_ID, uses SSI_CLIENT_ID_<UPPERCASE(aud)> and SSI_CLIENT_SECRET_<UPPERCASE(aud)> when set.
+ */
+export declare function getClientCredentialsForAudience(aud: string, defaultClientId: string, defaultClientSecret: string): {
+    clientId: string;
+    clientSecret: string;
+};
 /**
  * Check if a JWT is expired (or within bufferSeconds of expiry) by decoding its payload.
  * Does not verify the signature — use only for expiry checks (e.g. "should I refresh?").
@@ -67,7 +76,8 @@ export declare class AuthServer {
     private stateStorage;
     private jwksCache;
     private lastTokens?;
-    constructor(config?: AuthConfig);
+    /** Accepts AuthConfig or SSIRequestConfig (e.g. from getRequestConfig(req)). */
+    constructor(config?: AuthConfigInput);
     /**
      * Build the authorization URL and persist a CSRF state for the callback.
      * Returns: { url, stateKey, stateValue }

package/lib/auth.server.js

@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthServer = exports.scopes = void 0;
+exports.getClientCredentialsForAudience = getClientCredentialsForAudience;
 exports.isJwtExpired = isJwtExpired;
 exports.getJwtExpirySeconds = getJwtExpirySeconds;
 const crypto = __importStar(require("crypto"));
@@ -43,6 +44,7 @@ const jose_1 = require("jose");
 const stateStore_1 = require("./stateStore");
 const SSICache_1 = require("./cache/SSICache");
 const constants_1 = require("./cache/constants");
+const requestConfig_1 = require("./requestConfig");
 exports.scopes = {
     defaultScopes: "openid profile email view_project create_project delete_project update_project view_subscribed_plan view_subscribed_feature view_subscribed_limit access_subscription_usage"
 };
@@ -50,6 +52,61 @@ exports.scopes = {
 function normalizeIssuer(url) {
     return url.replace(/\/+$/, "");
 }
+/**
+ * Build env key for alternate client id/secret by audience.
+ * e.g. aud "scheduled_job_client" -> "SSI_CLIENT_ID_SCHEDULED_JOB_CLIENT"
+ */
+function audienceToEnvSuffix(aud) {
+    return String(aud).toUpperCase().replace(/-/g, "_");
+}
+/**
+ * Resolve allowed audiences for JWT verification.
+ * If token aud != default client id, check SSI_CLIENT_ID_<UPPERCASE(aud)>; if set, that value is accepted as audience.
+ */
+function getAllowedAudiences(jwt, defaultClientId) {
+    const allowed = [defaultClientId];
+    let payload;
+    try {
+        payload = (0, jose_1.decodeJwt)(jwt);
+    }
+    catch {
+        return allowed;
+    }
+    const aud = payload.aud;
+    const audList = aud == null ? [] : Array.isArray(aud) ? aud.map(String) : [String(aud)];
+    for (const a of audList) {
+        if (a && a !== defaultClientId) {
+            const envKey = `SSI_CLIENT_ID_${audienceToEnvSuffix(a)}`;
+            const alt = process.env[envKey]?.trim();
+            if (alt) {
+                if (!allowed.includes(alt))
+                    allowed.push(alt);
+                // Also accept the token's aud value so verification passes when issuer puts aud in token
+                if (a !== alt && !allowed.includes(a))
+                    allowed.push(a);
+            }
+        }
+    }
+    return allowed;
+}
+/**
+ * Get client id and secret for an audience from env (for token endpoint use).
+ * If aud != SSI_CLIENT_ID, uses SSI_CLIENT_ID_<UPPERCASE(aud)> and SSI_CLIENT_SECRET_<UPPERCASE(aud)> when set.
+ */
+function getClientCredentialsForAudience(aud, defaultClientId, defaultClientSecret) {
+    if (!aud || aud === defaultClientId)
+        return { clientId: defaultClientId, clientSecret: defaultClientSecret };
+    const suffix = audienceToEnvSuffix(aud);
+    const clientId = process.env[`SSI_CLIENT_ID_${suffix}`]?.trim();
+    const clientSecret = process.env[`SSI_CLIENT_SECRET_${suffix}`]?.trim();
+    if (clientId) {
+        return {
+            clientId,
+            clientSecret: clientSecret ?? defaultClientSecret,
+        };
+    }
+    return { clientId: defaultClientId, clientSecret: defaultClientSecret };
+}
 /**
  * Check if a JWT is expired (or within bufferSeconds of expiry) by decoding its payload.
  * Does not verify the signature — use only for expiry checks (e.g. "should I refresh?").
@@ -93,9 +150,9 @@ function getJwtExpirySeconds(jwt) {
     }
 }
 class AuthServer {
+    /** Accepts AuthConfig or SSIRequestConfig (e.g. from getRequestConfig(req)). */
     constructor(config) {
-        // Use empty object as default if config is not provided
-        const cfg = config ?? {};
+        const cfg = (0, requestConfig_1.normalizeAuthConfig)(config) ?? {};
         let scopesString;
         if (cfg.scopes === undefined || cfg.scopes === null) {
             scopesString = exports.scopes.defaultScopes;
@@ -441,6 +498,7 @@ class AuthServer {
      * @private
      */
     async verifyWithIssuer(jwt) {
+        const allowedAudiences = getAllowedAudiences(jwt, this.cfg.clientId);
         // If static JWKS provided, use jose's importJWK for each key
         if (this.cfg.jwks && Array.isArray(this.cfg.jwks.keys)) {
             // For static JWKS, we need to import and try each key
@@ -449,7 +507,7 @@ class AuthServer {
                     const publicKey = await (0, jose_1.importJWK)(key, "RS256");
                     const { payload } = await (0, jose_1.jwtVerify)(jwt, publicKey, {
                         issuer: this.cfg.issuerAccepted,
-                        audience: this.cfg.clientId,
+                        audience: allowedAudiences,
                         algorithms: ["RS256"],
                     });
                     return payload;
@@ -469,7 +527,7 @@ class AuthServer {
                 const publicKey = await (0, jose_1.importJWK)(key, "RS256");
                 const { payload } = await (0, jose_1.jwtVerify)(jwt, publicKey, {
                     issuer: this.cfg.issuerAccepted,
-                    audience: this.cfg.clientId,
+                    audience: allowedAudiences,
                     algorithms: ["RS256"],
                 });
                 return payload;

package/lib/clientConfig.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Config shape that host apps use in the browser (e.g. from getClientConfig()).
+ *
+ * Derived from public env (NEXT_PUBLIC_*) and optionally window.location.
+ * Use this type for the return value of your client config helper so SessionClient
+ * and other client code stay typed.
+ *
+ * - **baseUrl**: App origin (e.g. window.location.origin or NEXT_PUBLIC_APP_URL).
+ * - **apiUrl**: App API base; where your app's routes live (e.g. /api/v1/auth/session).
+ *   Pass to SessionClient.getSessionClient(config.apiUrl ?? config.baseUrl).
+ * - **ssiApiUrl**: SSI Platform API base (for links, account portal, etc.).
+ * - **ssiIssuerBaseUrl**: SSI issuer URL (often same as ssiApiUrl; e.g. for /pricing links).
+ */
+export type SSIClientConfig = {
+    baseUrl: string | null;
+    apiUrl?: string | null;
+    ssiApiUrl?: string | null;
+    ssiIssuerBaseUrl?: string | null;
+};
+/**
+ * Base app URL (client): NEXT_PUBLIC_APP_URL or (in browser) window.location.origin.
+ */
+export declare function getClientBaseUrl(): string | null;
+/**
+ * App API base URL (client): NEXT_PUBLIC_API_URL or baseUrl.
+ */
+export declare function getClientApiUrl(baseUrl: string | null): string | null;
+/**
+ * SSI Platform API base URL (client): NEXT_PUBLIC_SSI_API_BASE_URL or derived from baseUrl
+ * hostname (e.g. https://<subdomain>.cerealstackdev.com on known domains).
+ */
+export declare function getClientSsiApiUrl(baseUrl: string | null): string | null;
+/**
+ * Build SSIClientConfig from public env and (in browser) window.location.
+ * Use in client components; for SessionClient pass the result to getSessionClient(config).
+ */
+export declare function getClientConfig(): SSIClientConfig;
+/**
+ * Returns the URL to pass to SessionClient (app base so it can call the app's session endpoint).
+ * Prefers apiUrl so the session route is resolved correctly when app and API differ.
+ */
+export declare function getSessionClientBaseUrl(config: SSIClientConfig | undefined | null): string | undefined;

package/lib/clientConfig.js

@@ -0,0 +1,80 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientBaseUrl = getClientBaseUrl;
+exports.getClientApiUrl = getClientApiUrl;
+exports.getClientSsiApiUrl = getClientSsiApiUrl;
+exports.getClientConfig = getClientConfig;
+exports.getSessionClientBaseUrl = getSessionClientBaseUrl;
+function trimTrailingSlash(url) {
+    return url.replace(/\/$/, "");
+}
+/**
+ * Base app URL (client): NEXT_PUBLIC_APP_URL or (in browser) window.location.origin.
+ */
+function getClientBaseUrl() {
+    const baseUrl = process.env.NEXT_PUBLIC_APP_URL ||
+        (typeof window !== "undefined" ? window.location.origin : null);
+    return baseUrl ? trimTrailingSlash(baseUrl) : null;
+}
+/**
+ * App API base URL (client): NEXT_PUBLIC_API_URL or baseUrl.
+ */
+function getClientApiUrl(baseUrl) {
+    const apiUrl = process.env.NEXT_PUBLIC_API_URL || (baseUrl ?? null);
+    return apiUrl ? trimTrailingSlash(apiUrl) : null;
+}
+/**
+ * SSI Platform API base URL (client): NEXT_PUBLIC_SSI_API_BASE_URL or derived from baseUrl
+ * hostname (e.g. https://<subdomain>.cerealstackdev.com on known domains).
+ */
+function getClientSsiApiUrl(baseUrl) {
+    if (!baseUrl)
+        return null;
+    if (process.env.NEXT_PUBLIC_SSI_API_BASE_URL) {
+        return trimTrailingSlash(process.env.NEXT_PUBLIC_SSI_API_BASE_URL);
+    }
+    try {
+        const url = new URL(baseUrl);
+        const hostname = url.hostname;
+        const validDomain = hostname.endsWith(".cerealstackdev.com") ||
+            hostname.endsWith(".cerealstackqa.com") ||
+            hostname.endsWith(".cerealstack.com");
+        if (!validDomain)
+            return null;
+        const parts = hostname.split(".");
+        if (parts.length < 3)
+            return null;
+        const subdomain = parts[parts.length - 3];
+        const domain = parts.slice(-2).join(".");
+        return `https://${subdomain}.${domain}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build SSIClientConfig from public env and (in browser) window.location.
+ * Use in client components; for SessionClient pass the result to getSessionClient(config).
+ */
+function getClientConfig() {
+    const baseUrl = getClientBaseUrl();
+    const apiUrl = getClientApiUrl(baseUrl);
+    const ssiApiUrl = getClientSsiApiUrl(baseUrl);
+    return {
+        baseUrl,
+        apiUrl,
+        ssiApiUrl,
+        ssiIssuerBaseUrl: ssiApiUrl,
+    };
+}
+/**
+ * Returns the URL to pass to SessionClient (app base so it can call the app's session endpoint).
+ * Prefers apiUrl so the session route is resolved correctly when app and API differ.
+ */
+function getSessionClientBaseUrl(config) {
+    if (config == null)
+        return undefined;
+    const url = config.apiUrl ?? config.baseUrl;
+    return url != null && url !== "" ? url : undefined;
+}

package/lib/frontend/index.d.ts

@@ -1 +1,3 @@
 export { SessionClient } from './session/SessionClient';
+export type { SSIClientConfig } from '../clientConfig';
+export { getClientConfig, getSessionClientBaseUrl, getClientBaseUrl, getClientApiUrl, getClientSsiApiUrl, } from '../clientConfig';

package/lib/frontend/index.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionClient = void 0;
-// Browser/middleware-safe exports only
+exports.getClientSsiApiUrl = exports.getClientApiUrl = exports.getClientBaseUrl = exports.getSessionClientBaseUrl = exports.getClientConfig = exports.SessionClient = void 0;
+// Browser/middleware-safe exports only (no auth.server / requestConfig)
 var SessionClient_1 = require("./session/SessionClient");
 Object.defineProperty(exports, "SessionClient", { enumerable: true, get: function () { return SessionClient_1.SessionClient; } });
+var clientConfig_1 = require("../clientConfig");
+Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return clientConfig_1.getClientConfig; } });
+Object.defineProperty(exports, "getSessionClientBaseUrl", { enumerable: true, get: function () { return clientConfig_1.getSessionClientBaseUrl; } });
+Object.defineProperty(exports, "getClientBaseUrl", { enumerable: true, get: function () { return clientConfig_1.getClientBaseUrl; } });
+Object.defineProperty(exports, "getClientApiUrl", { enumerable: true, get: function () { return clientConfig_1.getClientApiUrl; } });
+Object.defineProperty(exports, "getClientSsiApiUrl", { enumerable: true, get: function () { return clientConfig_1.getClientSsiApiUrl; } });

package/lib/frontend/session/SessionClient.d.ts

@@ -1,13 +1,25 @@
+import { type SSIClientConfig } from '../../clientConfig';
 export declare class SessionClient {
     private readonly cookieHeader?;
-    private static readonly instances;
     private readonly baseUrl;
     private claims;
     private ttl;
     private initPromise;
     private static normalizeBaseUrl;
     constructor(baseUrl?: string, cookieHeader?: string | null | undefined);
-    static getSessionClient(baseUrl?: string): SessionClient;
+    /**
+     * Returns a new SessionClient for this request. Call once per request (or per user
+     * context) so session is not shared across requests.
+     *
+     * Accepts a base URL string or an SSIClientConfig (e.g. from getClientConfig());
+     * when given config, uses config.apiUrl ?? config.baseUrl.
+     *
+     * In Next.js server components/route handlers you can omit cookieHeader: the client
+     * will automatically use the current request's session cookie (via next/headers).
+     * In other server contexts (e.g. middleware, non-Next), pass the request's Cookie
+     * header so this client is bound to that request's session.
+     */
+    static getSessionClient(baseUrlOrConfig?: string | SSIClientConfig, cookieHeader?: string | null): SessionClient;
     isLoggedIn(): Promise<boolean>;
     warmup(): void;
     getTtl(): Promise<number | null>;

package/lib/frontend/session/SessionClient.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionClient = void 0;
+const clientConfig_1 = require("../../clientConfig");
+/** Session cookie name; must match SessionManager (SSI_COOKIE_NAME env or default). */
+const SESSION_COOKIE_NAME = process.env.SSI_COOKIE_NAME ?? "ssi_session";
 class SessionClient {
     static normalizeBaseUrl(baseUrl) {
         if (!baseUrl) {
@@ -30,16 +33,21 @@ class SessionClient {
         }
         this.initPromise = this.loadClaims();
     }
-    static getSessionClient(baseUrl) {
-        const resolvedBaseUrl = baseUrl ?? process.env.NEXT_PUBLIC_BASE_URL ?? "";
-        const normalizedBaseUrl = SessionClient.normalizeBaseUrl(resolvedBaseUrl);
-        if (!normalizedBaseUrl || !normalizedBaseUrl.startsWith("http://") && !normalizedBaseUrl.startsWith("https://")) {
-            console.error(`You must set baseUrl to SessionClient or you must set env variable NEXT_PUBLIC_BASE_URL. Incorrect value \`${resolvedBaseUrl}\``);
-        }
-        if (!SessionClient.instances.has(normalizedBaseUrl)) {
-            SessionClient.instances.set(normalizedBaseUrl, new SessionClient(baseUrl));
-        }
-        return SessionClient.instances.get(normalizedBaseUrl);
+    /**
+     * Returns a new SessionClient for this request. Call once per request (or per user
+     * context) so session is not shared across requests.
+     *
+     * Accepts a base URL string or an SSIClientConfig (e.g. from getClientConfig());
+     * when given config, uses config.apiUrl ?? config.baseUrl.
+     *
+     * In Next.js server components/route handlers you can omit cookieHeader: the client
+     * will automatically use the current request's session cookie (via next/headers).
+     * In other server contexts (e.g. middleware, non-Next), pass the request's Cookie
+     * header so this client is bound to that request's session.
+     */
+    static getSessionClient(baseUrlOrConfig, cookieHeader) {
+        const baseUrl = typeof baseUrlOrConfig === 'string' ? baseUrlOrConfig : (0, clientConfig_1.getSessionClientBaseUrl)(baseUrlOrConfig);
+        return new SessionClient(baseUrl, cookieHeader);
     }
     async isLoggedIn() {
         await this.initPromise;
@@ -87,14 +95,13 @@ class SessionClient {
             return init;
         }
         try {
-            // Dynamic import of next/headers - only available in Next.js server context
-            // @ts-expect-error - next/headers types are available at runtime but TypeScript can't resolve them during package build
+            // Dynamic import of next/headers - only available in Next.js server context (request-scoped)
             const { cookies } = await import("next/headers");
             const cookieStore = await cookies();
-            const serializedCookies = cookieStore
-                .getAll()
-                .map((cookie) => `${cookie.name}=${cookie.value}`)
-                .join("; ");
+            const sessionCookie = cookieStore.get(SESSION_COOKIE_NAME);
+            const serializedCookies = sessionCookie
+                ? `${sessionCookie.name}=${sessionCookie.value}`
+                : "";
             if (!serializedCookies) {
                 return init;
             }
@@ -141,5 +148,4 @@ class SessionClient {
     }
 }
 exports.SessionClient = SessionClient;
-SessionClient.instances = new Map();
 exports.default = SessionClient;

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 export * from './auth.server';
+export * from './requestConfig';
+export * from './clientConfig';
 export * from './stateStore';
 export * from './storage/SSIStorage';
 export * from './storage/types';

package/lib/index.js

@@ -16,6 +16,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SSISubscribedPlanApi = exports.SSISubscribedLimitApi = exports.SSISubscribedFeatureApi = exports.SessionClient = void 0;
 __exportStar(require("./auth.server"), exports);
+__exportStar(require("./requestConfig"), exports);
+__exportStar(require("./clientConfig"), exports);
 __exportStar(require("./stateStore"), exports);
 __exportStar(require("./storage/SSIStorage"), exports);
 __exportStar(require("./storage/types"), exports);

package/lib/requestConfig.d.ts

@@ -0,0 +1,61 @@
+import type { AuthConfig } from './auth.server';
+/**
+ * SSI-related config that host apps typically derive from the current request
+ * (e.g. via getRequestConfig(req)) and pass to the library.
+ *
+ * Use this type when building a "request config" in your app so SessionManager,
+ * AuthServer, UsageApi, and SubscribedPlanManager get a consistent, typed shape.
+ *
+ * - **ssiIssuerBaseUrl**, **ssiRedirectUri**, **ssiClientId**: passed to
+ *   AuthServer and SessionManager.fromEnv(cookieHeader, config).
+ * - **ssiApiUrl**: base URL for SSI Platform API (UsageApi, SubscribedPlanManager,
+ *   SSIProjectApi, etc.).
+ * - **baseUrl** / **apiUrl**: optional; for app use (e.g. redirect after login).
+ *   The library does not use these; they are included so apps can use this type
+ *   as the SSI subset of a larger RequestConfig.
+ */
+export type SSIRequestConfig = {
+    baseUrl?: string | null;
+    apiUrl?: string | null;
+    ssiApiUrl: string | null;
+    ssiIssuerBaseUrl: string | null;
+    ssiRedirectUri: string | null;
+    ssiClientId: string | null;
+};
+/**
+ * Get the base URL from environment or request headers.
+ * If NEXT_PUBLIC_APP_URL is set, returns it; otherwise derives from
+ * x-forwarded-proto, x-forwarded-host, origin, or host.
+ */
+export declare function getBaseUrl(req: Request): string | null;
+/** When baseUrl is a single URL or comma-separated list, return the first URL. */
+export declare function firstBaseUrl(baseUrl: string | null): string | null;
+/** App API base URL: NEXT_PUBLIC_API_URL or baseUrl. */
+export declare function getBaseApiUrl(req: Request): string | null;
+/** SSI client id: SSI_CLIENT_ID env or subdomain on known Cereal Stack domains. */
+export declare function getSsiClientId(baseUrl: string): string | null;
+/** SSI issuer base URL: SSI_ISSUER_BASE_URL env or derived from host (getSsiApiUrl). */
+export declare function getIssuerBaseUrl(baseUrl: string): string | null;
+/**
+ * SSI Platform API base URL: SSI_API_BASE_URL env or derived from host
+ * (e.g. https://<subdomain>.cerealstackdev.com on known domains).
+ */
+export declare function getSsiApiUrl(baseUrl: string): string | null;
+/** SSI redirect URI: SSI_REDIRECT_URI env or `${baseUrl}/api/v1/auth/callback`. */
+export declare function getSsiRedirectUri(baseUrl: string): string | null;
+export declare function getRequestConfig(req: Request): SSIRequestConfig;
+export declare function getRequestConfig(headers: Headers): SSIRequestConfig;
+/**
+ * Union type accepted anywhere AuthConfig is accepted (AuthServer, SessionManager).
+ */
+export type AuthConfigInput = AuthConfig | SSIRequestConfig;
+/**
+ * Converts SSIRequestConfig to AuthConfig for use with AuthServer and SessionManager.
+ * Drops null/undefined so the library can fall back to env vars where appropriate.
+ */
+export declare function toAuthConfig(rc: SSIRequestConfig): AuthConfig;
+/**
+ * Normalizes AuthConfigInput to AuthConfig. Use internally so AuthServer and SessionManager
+ * accept both AuthConfig and SSIRequestConfig.
+ */
+export declare function normalizeAuthConfig(input: AuthConfigInput | undefined): AuthConfig | undefined;

package/lib/requestConfig.js

@@ -0,0 +1,145 @@
+"use strict";
+// requestConfig.ts
+// Types and helpers for config that host apps derive per-request and pass into AuthServer, SessionManager, and SSI API clients.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBaseUrl = getBaseUrl;
+exports.firstBaseUrl = firstBaseUrl;
+exports.getBaseApiUrl = getBaseApiUrl;
+exports.getSsiClientId = getSsiClientId;
+exports.getIssuerBaseUrl = getIssuerBaseUrl;
+exports.getSsiApiUrl = getSsiApiUrl;
+exports.getSsiRedirectUri = getSsiRedirectUri;
+exports.getRequestConfig = getRequestConfig;
+exports.toAuthConfig = toAuthConfig;
+exports.normalizeAuthConfig = normalizeAuthConfig;
+// --- Helpers used by getRequestConfig (env: NEXT_PUBLIC_APP_URL, SSI_*, request headers) ---
+/**
+ * Get the base URL from environment or request headers.
+ * If NEXT_PUBLIC_APP_URL is set, returns it; otherwise derives from
+ * x-forwarded-proto, x-forwarded-host, origin, or host.
+ */
+function getBaseUrl(req) {
+    const fromEnv = process.env.NEXT_PUBLIC_APP_URL?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const proto = req.headers.get('x-forwarded-proto') || 'https';
+    const forwardedHost = req.headers.get('x-forwarded-host');
+    if (forwardedHost)
+        return `${proto}://${forwardedHost}`;
+    const origin = req.headers.get('origin');
+    if (origin)
+        return origin;
+    const host = req.headers.get('host');
+    const hostWithoutPort = host ? host.split(':')[0] : undefined;
+    if (hostWithoutPort)
+        return `${proto}://${hostWithoutPort}`;
+    return null;
+}
+/** When baseUrl is a single URL or comma-separated list, return the first URL. */
+function firstBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return null;
+    const first = baseUrl.split(',')[0].trim();
+    return first || null;
+}
+/** App API base URL: NEXT_PUBLIC_API_URL or baseUrl. */
+function getBaseApiUrl(req) {
+    return process.env.NEXT_PUBLIC_API_URL || getBaseUrl(req) || null;
+}
+/** SSI client id: SSI_CLIENT_ID env or subdomain on known Cereal Stack domains. */
+function getSsiClientId(baseUrl) {
+    if (process.env.SSI_CLIENT_ID)
+        return process.env.SSI_CLIENT_ID;
+    try {
+        const url = new URL(baseUrl);
+        url.pathname = url.pathname.replace(/\/$/, '');
+        const hostname = url.hostname;
+        if (hostname.endsWith('.cerealstackdev.com') || hostname.endsWith('.cerealstackqa.com') || hostname.endsWith('.cerealstack.com')) {
+            const domainParts = hostname.split('.');
+            const subdomain = domainParts[domainParts.length - 3];
+            return subdomain ?? null;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+/** SSI issuer base URL: SSI_ISSUER_BASE_URL env or derived from host (getSsiApiUrl). */
+function getIssuerBaseUrl(baseUrl) {
+    return process.env.SSI_ISSUER_BASE_URL || getSsiApiUrl(baseUrl) || null;
+}
+/**
+ * SSI Platform API base URL: SSI_API_BASE_URL env or derived from host
+ * (e.g. https://<subdomain>.cerealstackdev.com on known domains).
+ */
+function getSsiApiUrl(baseUrl) {
+    if (process.env.SSI_API_BASE_URL)
+        return process.env.SSI_API_BASE_URL;
+    try {
+        const url = new URL(baseUrl);
+        url.pathname = url.pathname.replace(/\/$/, '');
+        const hostname = url.hostname;
+        if (hostname.endsWith('.cerealstackdev.com') || hostname.endsWith('.cerealstackqa.com') || hostname.endsWith('.cerealstack.com')) {
+            const domainParts = hostname.split('.');
+            const subdomain = domainParts[domainParts.length - 3];
+            const domain = domainParts[domainParts.length - 2] + '.' + domainParts[domainParts.length - 1];
+            return `https://${subdomain}.${domain}`;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+/** SSI redirect URI: SSI_REDIRECT_URI env or `${baseUrl}/api/v1/auth/callback`. */
+function getSsiRedirectUri(baseUrl) {
+    return process.env.SSI_REDIRECT_URI || `${baseUrl}/api/v1/auth/callback`;
+}
+/**
+ * Build SSIRequestConfig from the current request (or headers).
+ * Uses env vars (NEXT_PUBLIC_APP_URL, SSI_*, etc.) and request headers for base URL and SSI URLs.
+ * Apps can use this as-is or extend the result with app-specific fields (e.g. prisma, dbUrl).
+ */
+function getRequestConfig(arg) {
+    const req = arg instanceof Headers ? new Request('http://local', { headers: arg }) : arg;
+    const rawBaseUrl = getBaseUrl(req);
+    const baseUrl = firstBaseUrl(rawBaseUrl);
+    const fallback = baseUrl || '';
+    return {
+        baseUrl: baseUrl ?? null,
+        apiUrl: getBaseApiUrl(req),
+        ssiApiUrl: getSsiApiUrl(fallback),
+        ssiIssuerBaseUrl: getIssuerBaseUrl(fallback),
+        ssiRedirectUri: getSsiRedirectUri(fallback),
+        ssiClientId: getSsiClientId(fallback),
+    };
+}
+function isSSIRequestConfig(x) {
+    return x != null && typeof x === 'object' && 'ssiIssuerBaseUrl' in x;
+}
+/**
+ * Converts SSIRequestConfig to AuthConfig for use with AuthServer and SessionManager.
+ * Drops null/undefined so the library can fall back to env vars where appropriate.
+ */
+function toAuthConfig(rc) {
+    const auth = {};
+    if (rc.ssiIssuerBaseUrl != null && rc.ssiIssuerBaseUrl !== '')
+        auth.issuerBaseUrl = rc.ssiIssuerBaseUrl;
+    if (rc.ssiRedirectUri != null && rc.ssiRedirectUri !== '')
+        auth.redirectUri = rc.ssiRedirectUri;
+    if (rc.ssiClientId != null && rc.ssiClientId !== '')
+        auth.clientId = rc.ssiClientId;
+    return auth;
+}
+/**
+ * Normalizes AuthConfigInput to AuthConfig. Use internally so AuthServer and SessionManager
+ * accept both AuthConfig and SSIRequestConfig.
+ */
+function normalizeAuthConfig(input) {
+    if (input == null)
+        return undefined;
+    if (isSSIRequestConfig(input))
+        return toAuthConfig(input);
+    return input;
+}

package/lib/session/SessionManager.d.ts

@@ -1,6 +1,7 @@
 import { SSIStorage } from '../storage/SSIStorage';
 import type { KVValue } from '../storage/types';
-import { AuthServer, type TokenResponse, type AuthConfig } from '../auth.server';
+import { AuthServer, type TokenResponse } from '../auth.server';
+import { type AuthConfigInput } from '../requestConfig';
 export declare const sessionRoles: {
     allRoles: string[];
     adminRoles: string[];
@@ -41,13 +42,22 @@ export declare class SessionManager {
     private auth?;
     private _sessionId?;
     private authConfig?;
+    private bearerSession?;
+    private pendingBearerToken?;
     private static inFlightRefresh;
     private freshnessOnce;
-    constructor(storage: SSIStorage, authConfig?: AuthConfig);
+    /** Accepts AuthConfig or SSIRequestConfig (e.g. from getRequestConfig(req)). */
+    constructor(storage: SSIStorage, authConfig?: AuthConfigInput);
+    /**
+     * Create a session from environment: cookie or Authorization: Bearer JWT.
+     * When a Request is passed and contains "Authorization: Bearer <token>", the token is verified
+     * (valid and not expired); a session id is generated but not cached. Cookie is used only when
+     * no Bearer header is present.
+     */
     static fromEnv(): SessionManager;
-    static fromEnv(cookieHeader: string | null, authConfig?: AuthConfig): SessionManager;
-    static fromEnv(request: Request, authConfig?: AuthConfig): SessionManager;
-    static fromEnv(authConfig: AuthConfig): SessionManager;
+    static fromEnv(cookieHeader: string | null, authConfig?: AuthConfigInput): SessionManager;
+    static fromEnv(request: Request, authConfig?: AuthConfigInput): SessionManager;
+    static fromEnv(authConfig: AuthConfigInput): SessionManager;
     /**
      * Async version that attempts to auto-detect the cookie header from Next.js context
      * when called with no arguments. Falls back gracefully if not in a Next.js context.
@@ -65,9 +75,20 @@ export declare class SessionManager {
      * const session = await SessionManager.fromEnvAsync(request, { clientId: 'my-client-id' });
      */
     static fromEnvAsync(): Promise<SessionManager>;
-    static fromEnvAsync(cookieHeader: string | null, authConfig?: AuthConfig): Promise<SessionManager>;
-    static fromEnvAsync(request: Request, authConfig?: AuthConfig): Promise<SessionManager>;
-    static fromEnvAsync(authConfig: AuthConfig): Promise<SessionManager>;
+    static fromEnvAsync(cookieHeader: string | null, authConfig?: AuthConfigInput): Promise<SessionManager>;
+    static fromEnvAsync(request: Request, authConfig?: AuthConfigInput): Promise<SessionManager>;
+    static fromEnvAsync(authConfig: AuthConfigInput): Promise<SessionManager>;
+    /**
+     * Parse Authorization: Bearer <token> from Request or Headers.
+     * Returns the JWT string or null if missing/invalid format.
+     */
+    private static parseBearerToken;
+    /**
+     * Verify the Bearer JWT and set ephemeral session (not cached).
+     * When token is provided (async path), generates a new sessionId.
+     * When called with no args, uses pendingBearerToken (sync path, lazy verification).
+     */
+    private verifyAndSetBearerSession;
     private parseCookies;
     get sessionId(): string | undefined;
     /** Cryptographically strong, URL-safe session id */
@@ -110,11 +131,13 @@ export declare class SessionManager {
     /**
      * Get session data by key. For 'claims', decodes the id_token payload
      * WITHOUT verification (use your verifier upstream for security).
+     * Bearer JWT sessions: returns from verified ephemeral data (not cached).
      */
     getSessionData(sessionId: string, dataKey: SessionDataKey): Promise<KVValue | null>;
     private ensureFreshOnce;
     /**
      * Delete all keys under this session object (id/access/refresh).
+     * For Bearer sessions, clears in-memory state only (nothing was cached).
      */
     clearSession(sessionId: string): Promise<string>;
     /**

package/lib/session/SessionManager.js

@@ -4,6 +4,7 @@ exports.SessionManager = exports.sessionRoles = void 0;
 const SSIStorage_1 = require("../storage/SSIStorage");
 const crypto_1 = require("crypto");
 const auth_server_1 = require("../auth.server");
+const requestConfig_1 = require("../requestConfig");
 exports.sessionRoles = {
     allRoles: ['platform_admin', 'member', 'owner', 'admin', 'billing', 'readonly'],
     adminRoles: ['platform_admin', 'owner', 'admin'],
@@ -35,33 +36,37 @@ function resolveCookieDomain() {
     }
 }
 class SessionManager {
+    /** Accepts AuthConfig or SSIRequestConfig (e.g. from getRequestConfig(req)). */
     constructor(storage, authConfig) {
         // Per-request-instance guard so TTL/refresh is evaluated at most once per session
         this.freshnessOnce = new Map();
         this.storage = storage.withClass('session'); // pin class="session"
-        this.authConfig = authConfig;
+        this.authConfig = (0, requestConfig_1.normalizeAuthConfig)(authConfig);
     }
     static fromEnv(cookieHeaderOrRequestOrConfig, authConfig) {
-        // Handle case where first arg is AuthConfig (no cookie header/request)
         let actualAuthConfig;
         let cookieHeaderOrRequest;
-        if (cookieHeaderOrRequestOrConfig &&
-            typeof cookieHeaderOrRequestOrConfig === 'object' &&
-            !(cookieHeaderOrRequestOrConfig instanceof Request) &&
-            ('clientId' in cookieHeaderOrRequestOrConfig || 'issuerBaseUrl' in cookieHeaderOrRequestOrConfig)) {
-            // First arg is AuthConfig
+        const isConfigLike = (x) => x != null && typeof x === 'object' && !(x instanceof Request) &&
+            ('clientId' in x || 'issuerBaseUrl' in x || 'ssiClientId' in x || 'ssiIssuerBaseUrl' in x);
+        if (cookieHeaderOrRequestOrConfig && isConfigLike(cookieHeaderOrRequestOrConfig)) {
             actualAuthConfig = cookieHeaderOrRequestOrConfig;
         }
         else {
-            // First arg is cookie header/request, second is optional AuthConfig
             cookieHeaderOrRequest = cookieHeaderOrRequestOrConfig;
             actualAuthConfig = authConfig;
         }
         const session = new SessionManager(SSIStorage_1.SSIStorage.fromEnv(), actualAuthConfig);
         if (cookieHeaderOrRequest instanceof Request) {
-            const cookieHeader = cookieHeaderOrRequest.headers.get('cookie');
-            if (cookieHeader) {
-                session._sessionId = session.parseCookies(cookieHeader);
+            const bearerToken = SessionManager.parseBearerToken(cookieHeaderOrRequest);
+            if (bearerToken) {
+                session._sessionId = session.generateSessionId();
+                session.pendingBearerToken = bearerToken;
+            }
+            else {
+                const cookieHeader = cookieHeaderOrRequest.headers.get('cookie');
+                if (cookieHeader) {
+                    session._sessionId = session.parseCookies(cookieHeader);
+                }
             }
         }
         else if (cookieHeaderOrRequest) {
@@ -73,52 +78,102 @@ class SessionManager {
         return session;
     }
     static async fromEnvAsync(cookieHeaderOrRequestOrConfig, authConfig) {
-        // Handle case where first arg is AuthConfig (no cookie header/request)
         let actualAuthConfig;
         let cookieHeaderOrRequest;
-        if (cookieHeaderOrRequestOrConfig &&
-            typeof cookieHeaderOrRequestOrConfig === 'object' &&
-            !(cookieHeaderOrRequestOrConfig instanceof Request) &&
-            ('clientId' in cookieHeaderOrRequestOrConfig || 'issuerBaseUrl' in cookieHeaderOrRequestOrConfig)) {
-            // First arg is AuthConfig
+        const isConfigLike = (x) => x != null && typeof x === 'object' && !(x instanceof Request) &&
+            ('clientId' in x || 'issuerBaseUrl' in x || 'ssiClientId' in x || 'ssiIssuerBaseUrl' in x);
+        if (cookieHeaderOrRequestOrConfig && isConfigLike(cookieHeaderOrRequestOrConfig)) {
             actualAuthConfig = cookieHeaderOrRequestOrConfig;
         }
         else {
-            // First arg is cookie header/request, second is optional AuthConfig
             cookieHeaderOrRequest = cookieHeaderOrRequestOrConfig;
             actualAuthConfig = authConfig;
         }
         const session = new SessionManager(SSIStorage_1.SSIStorage.fromEnv(), actualAuthConfig);
         if (cookieHeaderOrRequest instanceof Request) {
-            const cookieHeader = cookieHeaderOrRequest.headers.get('cookie');
-            if (cookieHeader) {
-                session._sessionId = session.parseCookies(cookieHeader);
+            const bearerToken = SessionManager.parseBearerToken(cookieHeaderOrRequest);
+            if (bearerToken) {
+                await session.verifyAndSetBearerSession(bearerToken);
+            }
+            else {
+                const cookieHeader = cookieHeaderOrRequest.headers.get('cookie');
+                if (cookieHeader) {
+                    session._sessionId = session.parseCookies(cookieHeader);
+                }
             }
         }
         else if (cookieHeaderOrRequest) {
             session._sessionId = session.parseCookies(cookieHeaderOrRequest);
         }
         else {
-            // When called with no arguments, try to auto-detect cookie header from Next.js context
+            // When called with no arguments, try to auto-detect from Next.js context
             try {
-                // Dynamic import of next/headers - only available in Next.js server context
-                // @ts-expect-error - next/headers types are available at runtime but TypeScript can't resolve them during package build
                 const { headers } = await import('next/headers');
                 const headersList = await headers();
                 if (headersList && typeof headersList.get === 'function') {
-                    const cookieHeader = headersList.get('cookie');
-                    if (cookieHeader) {
-                        session._sessionId = session.parseCookies(cookieHeader);
+                    const authHeader = headersList.get('authorization');
+                    const bearerToken = authHeader?.trim().toLowerCase().startsWith('bearer ')
+                        ? authHeader.trim().slice(7).trim() || null
+                        : null;
+                    if (bearerToken) {
+                        await session.verifyAndSetBearerSession(bearerToken);
+                    }
+                    else {
+                        const cookieHeader = headersList.get('cookie');
+                        if (cookieHeader) {
+                            session._sessionId = session.parseCookies(cookieHeader);
+                        }
                     }
                 }
             }
             catch {
                 // Not in Next.js context or headers() not available - silently continue
-                // This is expected when called outside of Next.js or when creating new sessions
             }
         }
         return session;
     }
+    /**
+     * Parse Authorization: Bearer <token> from Request or Headers.
+     * Returns the JWT string or null if missing/invalid format.
+     */
+    static parseBearerToken(requestOrHeaders) {
+        const auth = requestOrHeaders instanceof Request
+            ? requestOrHeaders.headers.get('authorization')
+            : requestOrHeaders.get('authorization');
+        if (!auth || typeof auth !== 'string')
+            return null;
+        const trimmed = auth.trim();
+        if (!trimmed.toLowerCase().startsWith('bearer '))
+            return null;
+        const token = trimmed.slice(7).trim();
+        return token || null;
+    }
+    /**
+     * Verify the Bearer JWT and set ephemeral session (not cached).
+     * When token is provided (async path), generates a new sessionId.
+     * When called with no args, uses pendingBearerToken (sync path, lazy verification).
+     */
+    async verifyAndSetBearerSession(token) {
+        const raw = token ?? this.pendingBearerToken;
+        if (!raw)
+            return;
+        const auth = this.getAuth();
+        let claims;
+        try {
+            claims = (await auth.verifyAndDecodeJwt(raw));
+        }
+        catch {
+            this._sessionId = undefined;
+            this.pendingBearerToken = undefined;
+            throw new Error('Invalid or expired Bearer JWT');
+        }
+        const exp = typeof claims.exp === 'number' ? claims.exp : 0;
+        const sessionId = token ? this.generateSessionId() : this._sessionId;
+        if (token)
+            this._sessionId = sessionId;
+        this.bearerSession = { sessionId, accessToken: raw, claims, exp };
+        this.pendingBearerToken = undefined;
+    }
     parseCookies(header) {
         const cookieName = process.env.SSI_COOKIE_NAME ?? 'ssi_session';
         for (const part of header.split(/;\s*/)) {
@@ -219,8 +274,43 @@ class SessionManager {
     /**
      * Get session data by key. For 'claims', decodes the id_token payload
      * WITHOUT verification (use your verifier upstream for security).
+     * Bearer JWT sessions: returns from verified ephemeral data (not cached).
      */
     async getSessionData(sessionId, dataKey) {
+        if (this.bearerSession?.sessionId === sessionId) {
+            const b = this.bearerSession;
+            if (dataKey === 'claims')
+                return b.claims;
+            if (dataKey === 'access_token')
+                return b.accessToken;
+            if (dataKey === 'id_token')
+                return b.accessToken;
+            if (dataKey === 'refresh_token')
+                return null;
+            return null;
+        }
+        if (this.pendingBearerToken && this._sessionId === sessionId) {
+            try {
+                await this.verifyAndSetBearerSession();
+            }
+            catch {
+                this._sessionId = undefined;
+                this.pendingBearerToken = undefined;
+                return null;
+            }
+            if (this.bearerSession?.sessionId === sessionId) {
+                const b = this.bearerSession;
+                if (dataKey === 'claims')
+                    return b.claims;
+                if (dataKey === 'access_token')
+                    return b.accessToken;
+                if (dataKey === 'id_token')
+                    return b.accessToken;
+                if (dataKey === 'refresh_token')
+                    return null;
+                return null;
+            }
+        }
         const keyToCheck = dataKey === 'claims' ? 'id_token' : dataKey;
         try {
             await this.ensureFreshOnce(sessionId);
@@ -256,6 +346,11 @@ class SessionManager {
         return value;
     }
     ensureFreshOnce(sessionId) {
+        if (this.bearerSession?.sessionId === sessionId)
+            return Promise.resolve();
+        if (this.pendingBearerToken && this._sessionId === sessionId) {
+            return this.verifyAndSetBearerSession();
+        }
         const existing = this.freshnessOnce.get(sessionId);
         if (existing)
             return existing;
@@ -326,9 +421,17 @@ class SessionManager {
     }
     /**
      * Delete all keys under this session object (id/access/refresh).
+     * For Bearer sessions, clears in-memory state only (nothing was cached).
      */
     async clearSession(sessionId) {
         const deleteCookieHeader = this.buildSessionCookie('', { maxAge: 0 });
+        if (this.bearerSession?.sessionId === sessionId || (this.pendingBearerToken && this._sessionId === sessionId)) {
+            this.bearerSession = undefined;
+            this.pendingBearerToken = undefined;
+            if (this._sessionId === sessionId)
+                this._sessionId = undefined;
+            return deleteCookieHeader;
+        }
         const keys = (await this.storage.keysForObject(sessionId)) ?? [];
         if (!keys.length)
             return deleteCookieHeader;
@@ -355,11 +458,33 @@ class SessionManager {
     }
     /** Returns remaining TTL in seconds for this session's id_token, or null if none */
     async getSessionTtlSeconds(sessionId) {
+        if (this.bearerSession?.sessionId === sessionId) {
+            const secs = this.bearerSession.exp - Math.floor(Date.now() / 1000);
+            return Math.max(0, secs);
+        }
+        if (this.pendingBearerToken && this._sessionId === sessionId) {
+            await this.verifyAndSetBearerSession();
+            if (this.bearerSession?.sessionId === sessionId) {
+                const secs = this.bearerSession.exp - Math.floor(Date.now() / 1000);
+                return Math.max(0, secs);
+            }
+        }
         return this.storage.getRemainingTtl(sessionId, 'id_token');
     }
     async getVerifiedClaims(sessionId) {
         if (!sessionId)
             return null;
+        if (this.bearerSession?.sessionId === sessionId)
+            return this.bearerSession.claims;
+        if (this.pendingBearerToken && this._sessionId === sessionId) {
+            try {
+                await this.verifyAndSetBearerSession();
+                return this.bearerSession?.sessionId === sessionId ? this.bearerSession.claims : null;
+            }
+            catch {
+                return null;
+            }
+        }
         try {
             await this.ensureFreshOnce(sessionId);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@serialsubscriptions/platform-integration",
-    "version": "0.0.84",
+    "version": "0.85.4",
     "description": "Serial Subscriptions Libraries",
     "main": "lib/index.js",
     "types": "lib/index.d.ts",
@@ -67,5 +67,8 @@
     "peerDependencies": {
         "next": "^15.0.0"
     },
+    "optionalDependencies": {
+        "next": "^15.0.0"
+    },
     "license": "MIT"
 }