@serialsubscriptions/platform-integration 0.0.79

package/lib/session/SessionManager.js

@@ -0,0 +1,443 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = exports.sessionRoles = void 0;
+const SSIStorage_1 = require("../storage/SSIStorage");
+const crypto_1 = require("crypto");
+const auth_server_1 = require("../auth.server");
+exports.sessionRoles = {
+    allRoles: ['platform_admin', 'member', 'owner', 'admin', 'billing', 'readonly'],
+    adminRoles: ['platform_admin', 'owner', 'admin'],
+    userRoles: ['member', 'owner', 'admin', 'billing', 'readonly'],
+    userAdminRoles: ['platform_admin', 'owner', 'admin']
+};
+/** Defaults & env */
+const DEFAULT_COOKIE_NAME = process.env.SSI_COOKIE_NAME ?? 'ssi_session';
+const DEFAULT_COOKIE_PATH = process.env.SSI_COOKIE_PATH ?? '/';
+const DEFAULT_COOKIE_SAMESITE = (process.env.SSI_COOKIE_SAMESITE ?? 'Lax');
+const DEFAULT_COOKIE_SECURE = (process.env.SSI_COOKIE_SECURE ?? 'true').toLowerCase() !== 'false';
+// 7 days (seconds)
+const DEFAULT_REFRESH_TTL_SECONDS = Number(process.env.SSI_SESSION_REFRESH_TTL_SECONDS ?? 60 * 60 * 24 * 7);
+// Domain resolution: explicit > derive from NEXTAUTH_URL > undefined
+function resolveCookieDomain() {
+    const fromEnv = process.env.SSI_COOKIE_DOMAIN?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const nextAuth = process.env.NEXTAUTH_URL?.trim();
+    if (!nextAuth)
+        return undefined;
+    try {
+        const u = new URL(nextAuth);
+        return u.hostname || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+class SessionManager {
+    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;
+    }
+    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
+            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);
+            }
+        }
+        else if (cookieHeaderOrRequest) {
+            session._sessionId = session.parseCookies(cookieHeaderOrRequest);
+        }
+        // When called with no arguments, we cannot auto-detect cookies synchronously
+        // because Next.js headers() is async. Use fromEnvAsync() for auto-detection,
+        // or pass the Request object or cookie header string explicitly.
+        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
+            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);
+            }
+        }
+        else if (cookieHeaderOrRequest) {
+            session._sessionId = session.parseCookies(cookieHeaderOrRequest);
+        }
+        else {
+            // When called with no arguments, try to auto-detect cookie header 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);
+                    }
+                }
+            }
+            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;
+    }
+    parseCookies(header) {
+        const cookieName = process.env.SSI_COOKIE_NAME ?? 'ssi_session';
+        for (const part of header.split(/;\s*/)) {
+            const idx = part.indexOf('=');
+            if (idx === -1)
+                continue;
+            const k = decodeURIComponent(part.slice(0, idx).trim());
+            const v = decodeURIComponent(part.slice(idx + 1).trim());
+            if (k === cookieName)
+                return v;
+        }
+        return undefined;
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Cryptographically strong, URL-safe session id */
+    generateSessionId() {
+        // 32 bytes => 43 char base64url
+        return (0, crypto_1.randomBytes)(32).toString('base64url');
+    }
+    async setSession(authOrInput, tokenResponseOrOptions, optionsMaybe) {
+        // Handle AuthServer overload (duck-typed to avoid cross-bundle instanceof issues)
+        const looksLikeAuthServer = !!authOrInput && typeof authOrInput.getLastTokenResponse === 'function';
+        if (looksLikeAuthServer) {
+            // Determine if second arg is TokenResponse or options
+            const isTokenResponse = tokenResponseOrOptions && 'raw' in tokenResponseOrOptions;
+            const tokenResponse = isTokenResponse ? tokenResponseOrOptions : authOrInput.getLastTokenResponse();
+            const options = isTokenResponse ? optionsMaybe : tokenResponseOrOptions;
+            if (!tokenResponse)
+                throw new Error('Missing TokenResponse: pass tokens explicitly or call after handleCallback/refreshTokens');
+            const sessionId = options?.sessionId ?? this.generateSessionId();
+            const refreshTtl = options?.refreshTtlSeconds ?? DEFAULT_REFRESH_TTL_SECONDS;
+            // Use provider's expires_in for access/id tokens when available; allow explicit overrides
+            const providerTtl = tokenResponse.expires_in && tokenResponse.expires_in > 0 ? tokenResponse.expires_in : undefined;
+            const accessTtl = options?.accessTokenTtlSeconds ?? providerTtl ?? 300;
+            const idTtl = options?.idTokenTtlSeconds ?? providerTtl ?? accessTtl;
+            if (!tokenResponse.id_token || !tokenResponse.access_token || !tokenResponse.refresh_token) {
+                throw new Error('TokenResponse must contain id_token, access_token, and refresh_token');
+            }
+            await Promise.all([
+                this.storage.set(sessionId, 'id_token', tokenResponse.id_token, idTtl),
+                this.storage.set(sessionId, 'access_token', tokenResponse.access_token, accessTtl),
+                this.storage.set(sessionId, 'refresh_token', tokenResponse.refresh_token, refreshTtl),
+            ]);
+            const setCookieHeader = this.buildSessionCookie(sessionId, {
+                maxAge: refreshTtl,
+                ...(options?.cookie ?? {}),
+            });
+            return { sessionId, setCookieHeader };
+        }
+        // Handle original SetSessionInput overload
+        const input = authOrInput;
+        const sessionId = input.sessionId ?? this.generateSessionId();
+        const refreshTtl = input.refreshTtlSeconds && input.refreshTtlSeconds > 0
+            ? input.refreshTtlSeconds
+            : DEFAULT_REFRESH_TTL_SECONDS;
+        const idTtl = input.idTokenTtlSeconds ?? refreshTtl;
+        const accessTtl = input.accessTokenTtlSeconds ?? refreshTtl;
+        await Promise.all([
+            this.storage.set(sessionId, 'id_token', input.id_token, idTtl),
+            this.storage.set(sessionId, 'access_token', input.access_token, accessTtl),
+            this.storage.set(sessionId, 'refresh_token', input.refresh_token, refreshTtl),
+        ]);
+        const setCookieHeader = this.buildSessionCookie(sessionId, {
+            maxAge: refreshTtl,
+            ...(input.cookie ?? {}),
+        });
+        return { sessionId, setCookieHeader };
+    }
+    /** Build a single Set-Cookie header string for the session id */
+    buildSessionCookie(sessionId, overrides) {
+        const opts = {
+            name: DEFAULT_COOKIE_NAME,
+            domain: resolveCookieDomain(),
+            path: DEFAULT_COOKIE_PATH,
+            sameSite: DEFAULT_COOKIE_SAMESITE,
+            secure: DEFAULT_COOKIE_SECURE,
+            httpOnly: true,
+            maxAge: DEFAULT_REFRESH_TTL_SECONDS,
+            ...overrides,
+        };
+        // If SameSite=None, Secure must be true (enforce for safety)
+        if (opts.sameSite === 'None')
+            opts.secure = true;
+        const parts = [
+            `${encodeURIComponent(opts.name)}=${encodeURIComponent(sessionId)}`,
+            `Path=${opts.path}`,
+            `Max-Age=${Math.max(0, Math.floor(opts.maxAge))}`,
+            `Expires=${new Date(Date.now() + opts.maxAge * 1000).toUTCString()}`,
+            `SameSite=${opts.sameSite}`,
+            opts.secure ? 'Secure' : '',
+            opts.httpOnly ? 'HttpOnly' : '',
+            opts.domain ? `Domain=${opts.domain}` : '',
+        ].filter(Boolean);
+        return parts.join('; ');
+    }
+    /**
+     * Get session data by key. For 'claims', decodes the id_token payload
+     * WITHOUT verification (use your verifier upstream for security).
+     */
+    async getSessionData(sessionId, dataKey) {
+        const keyToCheck = dataKey === 'claims' ? 'id_token' : dataKey;
+        try {
+            await this.ensureFreshOnce(sessionId);
+        }
+        catch {
+            return null;
+        }
+        const value = await this.storage.get(sessionId, keyToCheck);
+        if (dataKey === 'claims') {
+            const idToken = value;
+            if (!idToken)
+                return null;
+            const auth = this.getAuth();
+            try {
+                const claims = await auth.verifyAndDecodeJwt(idToken);
+                return claims;
+            }
+            catch {
+                try {
+                    const parts = idToken.split('.');
+                    if (parts.length !== 3)
+                        return null;
+                    const payload = parts[1];
+                    const json = Buffer.from(payload.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+                    const obj = JSON.parse(json);
+                    return (obj && typeof obj === 'object') ? obj : null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        return value;
+    }
+    ensureFreshOnce(sessionId) {
+        const existing = this.freshnessOnce.get(sessionId);
+        if (existing)
+            return existing;
+        const op = (async () => {
+            // Determine need based on id_token TTL once per request instance
+            const currentIdToken = (await this.storage.get(sessionId, 'id_token'));
+            let needsRefresh = false;
+            if (!currentIdToken)
+                needsRefresh = true;
+            else {
+                const ttl = await this.storage.getRemainingTtl(sessionId, 'id_token');
+                if (typeof ttl === 'number' && ttl < 60)
+                    needsRefresh = true;
+            }
+            if (!needsRefresh) {
+                // But if another instance is refreshing now, wait to avoid stale reads
+                const inflight = SessionManager.inFlightRefresh.get(sessionId);
+                if (inflight)
+                    await inflight;
+                return;
+            }
+            // Coordinate refresh across instances
+            const doRefresh = async () => {
+                const existingRefresh = SessionManager.inFlightRefresh.get(sessionId);
+                if (existingRefresh)
+                    return existingRefresh;
+                const p = (async () => {
+                    const refreshToken = (await this.storage.get(sessionId, 'refresh_token'));
+                    if (!refreshToken)
+                        throw new Error('Missing refresh_token');
+                    const auth = this.getAuth();
+                    const tokens = await auth.refreshTokens(refreshToken);
+                    if (!tokens || !tokens.id_token || !tokens.access_token || !tokens.refresh_token) {
+                        throw new Error('Incomplete token response');
+                    }
+                    const [prevAccessTtl, prevIdTtl, prevRefreshTtl] = await Promise.all([
+                        this.storage.getRemainingTtl(sessionId, 'access_token'),
+                        this.storage.getRemainingTtl(sessionId, 'id_token'),
+                        this.storage.getRemainingTtl(sessionId, 'refresh_token'),
+                    ]);
+                    const accessTtl = (typeof tokens.expires_in === 'number' && tokens.expires_in > 0)
+                        ? tokens.expires_in
+                        : (typeof prevAccessTtl === 'number' ? prevAccessTtl : 300);
+                    const idTtl = (typeof tokens.expires_in === 'number' && tokens.expires_in > 0)
+                        ? tokens.expires_in
+                        : (typeof prevIdTtl === 'number' ? prevIdTtl : accessTtl);
+                    const refreshTtl = (typeof prevRefreshTtl === 'number' && prevRefreshTtl > 0)
+                        ? prevRefreshTtl
+                        : DEFAULT_REFRESH_TTL_SECONDS;
+                    await Promise.all([
+                        this.storage.set(sessionId, 'id_token', tokens.id_token, idTtl),
+                        this.storage.set(sessionId, 'access_token', tokens.access_token, accessTtl),
+                        this.storage.set(sessionId, 'refresh_token', tokens.refresh_token, refreshTtl),
+                    ]);
+                })();
+                SessionManager.inFlightRefresh.set(sessionId, p);
+                try {
+                    await p;
+                }
+                finally {
+                    SessionManager.inFlightRefresh.delete(sessionId);
+                }
+            };
+            await doRefresh();
+        })();
+        this.freshnessOnce.set(sessionId, op);
+        return op;
+    }
+    /**
+     * Delete all keys under this session object (id/access/refresh).
+     */
+    async clearSession(sessionId) {
+        const deleteCookieHeader = this.buildSessionCookie('', { maxAge: 0 });
+        const keys = (await this.storage.keysForObject(sessionId)) ?? [];
+        if (!keys.length)
+            return deleteCookieHeader;
+        // Keys are fully-qualified: container/class/object_id/key
+        // Extract the trailing logical key and delete via the storage API
+        const deletions = keys.map(fullKey => {
+            const parts = fullKey.split('/');
+            const logicalKey = parts.slice(3).join('/');
+            return this.storage.del(sessionId, logicalKey);
+        });
+        await Promise.all(deletions);
+        // Return Set-Cookie header to clear the browser cookie
+        return deleteCookieHeader;
+    }
+    /**
+     * Refresh session (stub): you’ll likely:
+     * 1) read refresh_token
+     * 2) call your token endpoint
+     * 3) update stored tokens + extend TTL
+     * 4) optionally rotate session id & cookie
+     */
+    async refreshSession(_sessionId) {
+        throw new Error('refreshSession not implemented yet');
+    }
+    /** Returns remaining TTL in seconds for this session's id_token, or null if none */
+    async getSessionTtlSeconds(sessionId) {
+        return this.storage.getRemainingTtl(sessionId, 'id_token');
+    }
+    async getVerifiedClaims(sessionId) {
+        if (!sessionId)
+            return null;
+        try {
+            await this.ensureFreshOnce(sessionId);
+        }
+        catch {
+            return null;
+        }
+        const idToken = (await this.storage.get(sessionId, 'id_token'));
+        if (!idToken)
+            return null;
+        try {
+            const claims = await this.getAuth().verifyAndDecodeJwt(idToken);
+            return claims && typeof claims === 'object'
+                ? claims
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getRoles(sessionId) {
+        const claims = await this.getVerifiedClaims(sessionId);
+        if (!claims)
+            return null;
+        const roles = claims.roles;
+        if (Array.isArray(roles))
+            return roles.map(String);
+        if (typeof roles === 'string')
+            return [roles];
+        return null;
+    }
+    async hasRole(roleName) {
+        const sessionId = this.sessionId;
+        if (!sessionId)
+            throw new Error('SessionManager.hasRole requires sessionId; call SessionManager.fromEnv first.');
+        if (!roleName)
+            return false;
+        const roles = await this.getRoles(sessionId);
+        if (!roles)
+            return false;
+        return roles.includes(roleName);
+    }
+    async hasRoleOneOf(roleNames) {
+        const sessionId = this.sessionId;
+        if (!sessionId)
+            throw new Error('SessionManager.hasRoleOneOf requires sessionId; call SessionManager.fromEnv first.');
+        if (!roleNames?.length)
+            return false;
+        const roles = await this.getRoles(sessionId);
+        if (!roles)
+            return false;
+        for (const roleName of roleNames) {
+            if (roleName && roles.includes(roleName))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Get a specific claim from the session's ID token.
+     * Requires `sessionId` to be set (via `fromEnv()` with cookies).
+     */
+    async getClaim(claimName) {
+        const sessionId = this.sessionId;
+        if (!sessionId)
+            throw new Error('SessionManager.getClaim requires sessionId; call SessionManager.fromEnv first.');
+        if (!claimName)
+            return undefined;
+        const claims = await this.getVerifiedClaims(sessionId);
+        if (!claims || typeof claims !== 'object')
+            return undefined;
+        return claims[claimName];
+    }
+    getAuth() {
+        if (!this.auth) {
+            // Use provided authConfig or fall back to env-driven configuration inside AuthServer
+            this.auth = new auth_server_1.AuthServer(this.authConfig);
+        }
+        return this.auth;
+    }
+}
+exports.SessionManager = SessionManager;
+// Ensure only one refresh runs per session at a time
+SessionManager.inFlightRefresh = new Map();

package/lib/stateStore.d.ts

@@ -0,0 +1,5 @@
+import { SSIStorage } from "./storage/SSIStorage";
+declare global {
+    var __SSI_STATE_STORAGE__: SSIStorage | undefined;
+}
+export declare const stateStorage: SSIStorage;

package/lib/stateStore.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateStorage = void 0;
+// packages/platform-integration/src/stateStore.ts
+const SSIStorage_1 = require("./storage/SSIStorage");
+// Reuse across hot-reloads in dev and across imports.
+// Default state storage uses SSIStorage with 'state' class namespace
+exports.stateStorage = globalThis.__SSI_STATE_STORAGE__ ??
+    (globalThis.__SSI_STATE_STORAGE__ = SSIStorage_1.SSIStorage.fromEnv().withClass('state'));

package/lib/storage/SSIStorage.d.ts

@@ -0,0 +1,24 @@
+import type { KVValue, StorageInitOpts } from './types';
+export declare class SSIStorage {
+    private backend;
+    private container;
+    private cls?;
+    private static __shared?;
+    private constructor();
+    static fromEnv(): SSIStorage;
+    static init(opts: StorageInitOpts): SSIStorage;
+    /**
+     * Returns a storage instance pinned to a class ("session", "nonce", etc.).
+     */
+    withClass(cls?: string): SSIStorage;
+    private composeKey;
+    get(objectId: string, key: string): Promise<KVValue | null>;
+    set(objectId: string, key: string, value: KVValue, ttlSeconds?: number): Promise<void>;
+    del(objectId: string, key: string): Promise<void>;
+    getRemainingTtl(objectId: string, key: string): Promise<number | null>;
+    /**
+     * List all keys under this container/class/objectId (if backend supports it).
+     */
+    keysForObject(objectId: string): Promise<string[]>;
+    close(): Promise<void>;
+}

package/lib/storage/SSIStorage.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSIStorage = void 0;
+const MemoryBackend_1 = require("./backends/MemoryBackend");
+const RedisBackend_1 = require("./backends/RedisBackend");
+const PostgresBackend_1 = require("./backends/PostgresBackend");
+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/[class]/[object_id]/[key]
+ */
+function keyFor(container, cls, objectId, key) {
+    const safeClass = (cls && cls.length > 0) ? cls : '_';
+    return `${container}/${safeClass}/${objectId}/${key}`;
+}
+class SSIStorage {
+    constructor(backend, container, cls) {
+        this.backend = backend;
+        this.container = container;
+        this.cls = cls;
+    }
+    static fromEnv() {
+        if (SSIStorage.__shared)
+            return SSIStorage.__shared;
+        const backend = process.env.SSI_STORAGE_BACKEND || 'memory';
+        const container = process.env.SSI_STORAGE_CONTAINER || 'ssi_storage';
+        const host = process.env.SSI_STORAGE_HOST;
+        const user = process.env.SSI_STORAGE_USER;
+        const password = process.env.SSI_STORAGE_PASSWORD;
+        const port = process.env.SSI_STORAGE_PORT ? Number(process.env.SSI_STORAGE_PORT) : undefined;
+        const database = process.env.SSI_STORAGE_DATABASE;
+        const ssl = envBool(process.env.SSI_STORAGE_SSL);
+        const url = process.env.SSI_STORAGE_URL;
+        SSIStorage.__shared = SSIStorage.init({
+            backend, container, host, user, password, port, database, ssl, url,
+        });
+        return SSIStorage.__shared;
+    }
+    static init(opts) {
+        const backendType = opts.backend || 'memory';
+        const container = opts.container;
+        let backend;
+        if (backendType === 'memory') {
+            backend = new MemoryBackend_1.MemoryBackend();
+        }
+        else if (backendType === 'redis') {
+            backend = new RedisBackend_1.RedisBackend({
+                url: opts.url,
+                host: opts.host,
+                port: opts.port,
+                user: opts.user,
+                password: opts.password,
+                tls: opts.ssl,
+            });
+        }
+        else if (backendType === 'postgres') {
+            backend = new PostgresBackend_1.PostgresBackend({
+                url: opts.url,
+                host: opts.host,
+                port: opts.port,
+                user: opts.user,
+                password: opts.password,
+                database: opts.database,
+                ssl: opts.ssl,
+                table: container, // table name equals container
+            });
+        }
+        else {
+            throw new Error(`Unsupported backend: ${backendType}`);
+        }
+        return new SSIStorage(backend, container);
+    }
+    /**
+     * Returns a storage instance pinned to a class ("session", "nonce", etc.).
+     */
+    withClass(cls) {
+        return new SSIStorage(this.backend, this.container, cls);
+        // shares the same backend connection; creates a new namespacer
+    }
+    composeKey(objectId, key) {
+        return keyFor(this.container, this.cls, objectId, key);
+    }
+    async get(objectId, key) {
+        return this.backend.get(this.composeKey(objectId, key));
+    }
+    async set(objectId, key, value, ttlSeconds) {
+        await this.backend.set(this.composeKey(objectId, key), value, ttlSeconds);
+    }
+    async del(objectId, key) {
+        await this.backend.del(this.composeKey(objectId, key));
+    }
+    async getRemainingTtl(objectId, key) {
+        return this.backend.getRemainingTtl(this.composeKey(objectId, key));
+    }
+    /**
+     * List all keys under this container/class/objectId (if backend supports it).
+     */
+    async keysForObject(objectId) {
+        if (!this.backend.keys)
+            return [];
+        const prefix = `${this.container}/${this.cls ?? '_'}/${objectId}/`;
+        return this.backend.keys(prefix);
+    }
+    async close() {
+        if (this.backend.close)
+            await this.backend.close();
+        if (!this.cls) {
+            // Only clear singleton for the root instance
+            SSIStorage.__shared = undefined;
+        }
+    }
+}
+exports.SSIStorage = SSIStorage;

package/lib/storage/backends/MemoryBackend.d.ts

@@ -0,0 +1,10 @@
+import type { Backend, KVValue } from '../types';
+export declare class MemoryBackend implements Backend {
+    private cache;
+    constructor();
+    get(key: string): Promise<KVValue | null>;
+    set(key: string, value: KVValue, ttlSeconds?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    keys(prefix: string): Promise<string[]>;
+    getRemainingTtl(key: string): Promise<number | null>;
+}

package/lib/storage/backends/MemoryBackend.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryBackend = void 0;
+const node_cache_1 = __importDefault(require("node-cache"));
+class MemoryBackend {
+    constructor() {
+        // Share a single NodeCache across route bundles/process modules
+        const g = globalThis;
+        if (!g.__SSI_NODE_CACHE) {
+            // Checkperiod keeps stale entries tidy without extra timers
+            g.__SSI_NODE_CACHE = new node_cache_1.default({ stdTTL: 0, checkperiod: 120, useClones: false });
+        }
+        this.cache = g.__SSI_NODE_CACHE;
+    }
+    async get(key) {
+        const v = this.cache.get(key);
+        return typeof v === 'undefined' ? null : v;
+    }
+    async set(key, value, ttlSeconds) {
+        if (ttlSeconds && ttlSeconds > 0)
+            this.cache.set(key, value, ttlSeconds);
+        else
+            this.cache.set(key, value);
+    }
+    async del(key) {
+        this.cache.del(key);
+    }
+    async keys(prefix) {
+        return this.cache.keys().filter(k => k.startsWith(prefix));
+    }
+    async getRemainingTtl(key) {
+        const expiresAt = this.cache.getTtl(key);
+        if (typeof expiresAt === 'undefined' || expiresAt === 0)
+            return null;
+        const msRemaining = expiresAt - Date.now();
+        if (msRemaining <= 0)
+            return 0;
+        return Math.ceil(msRemaining / 1000);
+    }
+}
+exports.MemoryBackend = MemoryBackend;

package/lib/storage/backends/PostgresBackend.d.ts

@@ -0,0 +1,24 @@
+import type { Backend, KVValue } from '../types';
+type PgOpts = {
+    url?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    ssl?: boolean;
+    table: string;
+};
+export declare class PostgresBackend implements Backend {
+    private client;
+    private table;
+    constructor(opts: PgOpts);
+    private ensure;
+    private parsePrefixedKey;
+    get(prefixedKey: string): Promise<KVValue | null>;
+    set(prefixedKey: string, value: KVValue, ttlSeconds?: number): Promise<void>;
+    del(prefixedKey: string): Promise<void>;
+    close(): Promise<void>;
+    getRemainingTtl(prefixedKey: string): Promise<number | null>;
+}
+export {};