@serialsubscriptions/platform-integration 0.0.8-5.1

package/lib/cache/SSICache.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSICache = void 0;
+const MemoryCacheBackend_1 = require("./backends/MemoryCacheBackend");
+const RedisCacheBackend_1 = require("./backends/RedisCacheBackend");
+function envBool(v) {
+    if (v === undefined)
+        return undefined;
+    return ['1', 'true', 'yes', 'on'].includes(v.toLowerCase());
+}
+/**
+ * Creates a namespaced key according to the required format:
+ * container:prefix:key
+ */
+function keyFor(container, prefix, key) {
+    const safePrefix = (prefix && prefix.length > 0) ? prefix : '_';
+    return `${container}:${safePrefix}:${key}`;
+}
+class SSICache {
+    constructor(backend, container, prefix) {
+        this.backend = backend;
+        this.container = container;
+        this.prefix = prefix;
+    }
+    static fromEnv() {
+        if (SSICache.__shared)
+            return SSICache.__shared;
+        const backend = process.env.SSI_CACHE_BACKEND || 'memory';
+        const container = process.env.SSI_CACHE_CONTAINER || 'ssi';
+        SSICache.__shared = SSICache.init({
+            backend,
+            container,
+            url: process.env.SSI_CACHE_URL,
+            host: process.env.SSI_CACHE_HOST,
+            port: process.env.SSI_CACHE_PORT ? Number(process.env.SSI_CACHE_PORT) : undefined,
+            user: process.env.SSI_CACHE_USER,
+            password: process.env.SSI_CACHE_PASSWORD,
+            tls: envBool(process.env.SSI_CACHE_SSL),
+        });
+        return SSICache.__shared;
+    }
+    static init(opts) {
+        const t = opts.backend || 'memory';
+        const container = opts.container;
+        let backend;
+        if (t === 'memory') {
+            backend = new MemoryCacheBackend_1.MemoryCacheBackend();
+        }
+        else if (t === 'redis') {
+            backend = new RedisCacheBackend_1.RedisCacheBackend({
+                url: opts.url,
+                host: opts.host,
+                port: opts.port,
+                user: opts.user,
+                password: opts.password,
+                tls: opts.tls,
+            });
+        }
+        else {
+            throw new Error(`Unsupported cache backend: ${t}`);
+        }
+        return new SSICache(backend, container);
+    }
+    /**
+     * Returns a cache instance pinned to a prefix ("jwks", "oidc", "rl", etc.).
+     */
+    withPrefix(prefix) {
+        return new SSICache(this.backend, this.container, prefix);
+        // shares the same backend connection; creates a new namespacer
+    }
+    k(key) {
+        return keyFor(this.container, this.prefix, key);
+    }
+    async get(key) {
+        return this.backend.get(this.k(key));
+    }
+    async set(key, value, ttlSec) {
+        await this.backend.set(this.k(key), value, ttlSec);
+    }
+    async del(key) {
+        await this.backend.del(this.k(key));
+    }
+    async mget(keys) {
+        return this.backend.mget(keys.map((k) => this.k(k)));
+    }
+    async mset(entries) {
+        return this.backend.mset(entries.map((e) => ({ key: this.k(e.key), value: e.value, ttlSec: e.ttlSec })));
+    }
+    async incrby(key, by, ttlSec) {
+        return this.backend.incrby(this.k(key), by, ttlSec);
+    }
+    async ttl(key) {
+        return this.backend.ttl(this.k(key));
+    }
+    /**
+     * compute-if-absent: get from cache or compute and cache the value
+     */
+    async remember(key, ttlSec, loader) {
+        const cached = await this.get(key);
+        if (cached !== null)
+            return cached;
+        const value = await loader();
+        await this.set(key, value, ttlSec);
+        return value;
+    }
+    /**
+     * Simple distributed lock (best-effort): returns lock token if acquired
+     * Only works properly with Redis backend; memory backend returns a naive token
+     */
+    async acquireLock(key, ttlMs) {
+        const token = Math.random().toString(36).slice(2);
+        if (typeof this.backend.tryLock === 'function') {
+            const ok = await this.backend.tryLock(this.k(`lock:${key}`), ttlMs, token);
+            return ok ? token : null;
+        }
+        return token; // naive fallback for memory backend
+    }
+    /**
+     * Release a lock acquired via acquireLock
+     */
+    async releaseLock(key, token) {
+        if (typeof this.backend.unlock === 'function') {
+            await this.backend.unlock(this.k(`lock:${key}`), token);
+        }
+    }
+    async close() {
+        if (this.prefix)
+            return; // only root closes the connection
+        if (this.backend.close)
+            await this.backend.close();
+        SSICache.__shared = undefined;
+    }
+}
+exports.SSICache = SSICache;

package/lib/cache/backends/MemoryCacheBackend.d.ts

@@ -0,0 +1,15 @@
+import type { CacheBackend } from '../types';
+export declare class MemoryCacheBackend implements CacheBackend {
+    private store;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlSec: number): Promise<void>;
+    del(key: string): Promise<void>;
+    mget<T = unknown>(keys: string[]): Promise<(T | null)[]>;
+    mset<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        ttlSec: number;
+    }>): Promise<void>;
+    incrby(key: string, by?: number, ttlSec?: number): Promise<number>;
+    ttl(key: string): Promise<number | null>;
+}

package/lib/cache/backends/MemoryCacheBackend.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCacheBackend = void 0;
+class MemoryCacheBackend {
+    constructor() {
+        this.store = new Map();
+    }
+    async get(key) {
+        const it = this.store.get(key);
+        if (!it)
+            return null;
+        if (Date.now() > it.exp) {
+            this.store.delete(key);
+            return null;
+        }
+        return it.v;
+    }
+    async set(key, value, ttlSec) {
+        this.store.set(key, { v: value, exp: Date.now() + ttlSec * 1000 });
+    }
+    async del(key) {
+        this.store.delete(key);
+    }
+    async mget(keys) {
+        return Promise.all(keys.map((k) => this.get(k)));
+    }
+    async mset(entries) {
+        for (const e of entries) {
+            await this.set(e.key, e.value, e.ttlSec);
+        }
+    }
+    async incrby(key, by = 1, ttlSec) {
+        const cur = (await this.get(key)) ?? 0;
+        const next = cur + by;
+        await this.set(key, next, ttlSec ?? 60);
+        return next;
+    }
+    async ttl(key) {
+        const it = this.store.get(key);
+        if (!it)
+            return null;
+        const ms = it.exp - Date.now();
+        return ms > 0 ? Math.ceil(ms / 1000) : null;
+    }
+}
+exports.MemoryCacheBackend = MemoryCacheBackend;

package/lib/cache/backends/RedisCacheBackend.d.ts

@@ -0,0 +1,27 @@
+import type { CacheBackend } from '../types';
+export declare class RedisCacheBackend implements CacheBackend {
+    private client;
+    constructor(opts: {
+        url?: string;
+        host?: string;
+        port?: number;
+        user?: string;
+        password?: string;
+        tls?: boolean;
+    });
+    private ensure;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlSec: number): Promise<void>;
+    del(key: string): Promise<void>;
+    mget<T = unknown>(keys: string[]): Promise<(T | null)[]>;
+    mset<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        ttlSec: number;
+    }>): Promise<void>;
+    incrby(key: string, by?: number, ttlSec?: number): Promise<number>;
+    ttl(key: string): Promise<number | null>;
+    close(): Promise<void>;
+    tryLock(key: string, ttlMs: number, token: string): Promise<boolean>;
+    unlock(key: string, token: string): Promise<void>;
+}

package/lib/cache/backends/RedisCacheBackend.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheBackend = void 0;
+const ioredis_1 = require("ioredis");
+class RedisCacheBackend {
+    constructor(opts) {
+        if (opts.url) {
+            this.client = new ioredis_1.Redis(opts.url, { lazyConnect: true });
+        }
+        else {
+            this.client = new ioredis_1.Redis({
+                host: opts.host ?? 'localhost',
+                port: opts.port ?? 6379,
+                username: opts.user,
+                password: opts.password,
+                tls: opts.tls ? {} : undefined,
+                lazyConnect: true,
+            });
+        }
+    }
+    async ensure() {
+        if (this.client.status === 'wait')
+            await this.client.connect();
+    }
+    async get(key) {
+        await this.ensure();
+        const s = await this.client.get(key);
+        return s ? JSON.parse(s) : null;
+    }
+    async set(key, value, ttlSec) {
+        await this.ensure();
+        await this.client.set(key, JSON.stringify(value), 'EX', ttlSec);
+    }
+    async del(key) {
+        await this.ensure();
+        await this.client.del(key);
+    }
+    async mget(keys) {
+        await this.ensure();
+        if (!keys.length)
+            return [];
+        const res = await this.client.mget(...keys);
+        return res.map((s) => (s ? JSON.parse(s) : null));
+    }
+    async mset(entries) {
+        await this.ensure();
+        // Use pipeline to preserve per-key TTLs
+        const p = this.client.pipeline();
+        for (const e of entries) {
+            p.set(e.key, JSON.stringify(e.value), 'EX', e.ttlSec);
+        }
+        await p.exec();
+    }
+    async incrby(key, by = 1, ttlSec) {
+        await this.ensure();
+        const p = this.client.pipeline();
+        p.incrby(key, by);
+        if (ttlSec)
+            p.expire(key, ttlSec);
+        const results = await p.exec();
+        if (!results || results.length === 0) {
+            throw new Error('Pipeline exec failed');
+        }
+        const [error, val] = results[0];
+        if (error) {
+            throw error;
+        }
+        return val;
+    }
+    async ttl(key) {
+        await this.ensure();
+        const t = await this.client.ttl(key);
+        return t >= 0 ? t : null;
+    }
+    async close() {
+        await this.client.quit();
+    }
+    // Simple locks (SET NX PX)
+    async tryLock(key, ttlMs, token) {
+        await this.ensure();
+        const r = await this.client.set(key, token, 'PX', ttlMs, 'NX');
+        return r === 'OK';
+    }
+    async unlock(key, token) {
+        await this.ensure();
+        // Lua compare-and-del
+        const lua = `
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+      else return 0 end
+    `;
+        await this.client.eval(lua, 1, key, token);
+    }
+}
+exports.RedisCacheBackend = RedisCacheBackend;

package/lib/cache/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Recommended default TTLs for cache operations
+ */
+export declare const TTL_SHORT = 60;
+export declare const TTL_DEFAULT = 300;
+export declare const TTL_LONG = 3600;
+export declare const TTL_JWKS = 43200;

package/lib/cache/constants.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTL_JWKS = exports.TTL_LONG = exports.TTL_DEFAULT = exports.TTL_SHORT = void 0;
+/**
+ * Recommended default TTLs for cache operations
+ */
+exports.TTL_SHORT = 60; // rate-limit buckets, nonces
+exports.TTL_DEFAULT = 300; // API responses
+exports.TTL_LONG = 3600; // discovery docs
+exports.TTL_JWKS = 43200; // 12h; rotate if kid miss

package/lib/cache/types.d.ts

@@ -0,0 +1,27 @@
+export type CacheBackendType = 'memory' | 'redis';
+export interface CacheInitOpts {
+    backend?: CacheBackendType;
+    container: string;
+    url?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    tls?: boolean;
+}
+export interface CacheBackend {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlSec: number): Promise<void>;
+    del(key: string): Promise<void>;
+    mget<T = unknown>(keys: string[]): Promise<(T | null)[]>;
+    mset<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        ttlSec: number;
+    }>): Promise<void>;
+    incrby(key: string, by?: number, ttlSec?: number): Promise<number>;
+    ttl(key: string): Promise<number | null>;
+    close?(): Promise<void>;
+    tryLock?(key: string, ttlMs: number, token: string): Promise<boolean>;
+    unlock?(key: string, token: string): Promise<void>;
+}

package/lib/cache/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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

@@ -0,0 +1,36 @@
+import { type SSIClientConfig } from '../../clientConfig';
+export declare class SessionClient {
+    private readonly cookieHeader?;
+    private readonly baseUrl;
+    private claims;
+    private ttl;
+    private initPromise;
+    private static normalizeBaseUrl;
+    constructor(baseUrl?: string, cookieHeader?: string | null | undefined);
+    /**
+     * 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>;
+    get(claimName: string): Promise<unknown>;
+    /**
+     * Get a specific claim from the session.
+     * Alias for `get()` method for consistency with SessionManager.
+     */
+    getClaim(claimName: string): Promise<unknown>;
+    getAll(): Promise<unknown | null>;
+    private withSession;
+    private loadClaims;
+}
+export default SessionClient;