@circle-rd/auth-ai 0.0.0-stage → 0.1.0

package/dist/web/ai-routes.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { ERR } from "../errors.js";
+import { jsonResponse } from "./http.js";
+const statsQuerySchema = z.object({
+    days: z.coerce.number().int().min(1).max(90).optional(),
+});
+/**
+ * Wallet and model reads for the application's own frontend, which holds no
+ * token: the backend calls auth-service and the gateway on the user's behalf.
+ */
+export function createAiRoutes(ai, requireSession) {
+    return {
+        "/wallet": async (request) => {
+            const { userId } = await requireSession(request);
+            const { wallet } = ai.forUser(userId);
+            return jsonResponse({
+                ...(await wallet.getAccount()),
+                topupUrl: wallet.topupUrl(),
+            });
+        },
+        "/wallet/stats": async (request) => {
+            const { userId } = await requireSession(request);
+            const query = statsQuerySchema.safeParse(Object.fromEntries(new URL(request.url).searchParams));
+            if (!query.success)
+                throw ERR.REQ_001();
+            const { days } = query.data;
+            return jsonResponse(await ai
+                .forUser(userId)
+                .wallet.getStats(days === undefined ? {} : { days }));
+        },
+        "/models": async (request) => {
+            const { userId } = await requireSession(request);
+            return jsonResponse({
+                models: await ai.forUser(userId).gateway.listModels(),
+            });
+        },
+    };
+}

package/dist/web/cookies.d.ts

@@ -0,0 +1,11 @@
+export interface CookieOptions {
+    /** Seconds; 0 expires the cookie at once. */
+    readonly maxAgeSeconds: number;
+    /** Adds `Secure` and the `__Host-` prefix, which pins the cookie to this host. */
+    readonly secure: boolean;
+}
+/** Name of a cookie of the SDK: `__Host-` needs `Secure`, so it only applies over https. */
+export declare function cookieName(base: string, secure: boolean): string;
+export declare function parseCookies(header: string | null): Map<string, string>;
+export declare function serializeCookie(name: string, value: string, options: CookieOptions): string;
+export declare function clearCookie(name: string, secure: boolean): string;

package/dist/web/cookies.js

@@ -0,0 +1,46 @@
+import { ERR } from "../errors.js";
+// Token characters only: the values handled here are base64url ids and compact JWEs.
+const COOKIE_VALUE = /^[A-Za-z0-9._~-]+$/;
+const COOKIE_NAME = /^[A-Za-z0-9_-]+$/;
+/** Name of a cookie of the SDK: `__Host-` needs `Secure`, so it only applies over https. */
+export function cookieName(base, secure) {
+    return secure ? `__Host-${base}` : base;
+}
+export function parseCookies(header) {
+    const cookies = new Map();
+    if (!header)
+        return cookies;
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator === -1)
+            continue;
+        const name = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        // The first occurrence wins, as it is the one scoped most specifically.
+        if (!cookies.has(name))
+            cookies.set(name, value);
+    }
+    return cookies;
+}
+export function serializeCookie(name, value, options) {
+    if (!COOKIE_NAME.test(name.replace(/^__Host-/, ""))) {
+        throw ERR.CFG_001("Invalid cookie name");
+    }
+    if (value !== "" && !COOKIE_VALUE.test(value)) {
+        throw ERR.CFG_001("Invalid cookie value");
+    }
+    const attributes = [
+        `${name}=${value}`,
+        "Path=/",
+        "HttpOnly",
+        // Lax still sends the cookie on the top-level GET that returns from the provider.
+        "SameSite=Lax",
+        `Max-Age=${Math.max(0, Math.floor(options.maxAgeSeconds))}`,
+    ];
+    if (options.secure)
+        attributes.push("Secure");
+    return attributes.join("; ");
+}
+export function clearCookie(name, secure) {
+    return serializeCookie(name, "", { maxAgeSeconds: 0, secure });
+}

package/dist/web/handlers.d.ts

@@ -0,0 +1,47 @@
+import type { AiClient } from "../ai.js";
+import type { AuthClient } from "../client.js";
+import type { GrantManager } from "../grants.js";
+import type { ReplayStore } from "../server/backchannel-logout.js";
+import type { Session, SessionStore } from "./sessions.js";
+export interface AuthHandlersOptions {
+    readonly auth: AuthClient;
+    readonly grants: GrantManager;
+    readonly sessions: SessionStore;
+    /** At least 32 random characters: seals the sign-in cookie. Keep it out of source control. */
+    readonly secret: string;
+    /** Path prefix of the routes; `redirectUri` must be `<origin><basePath>/callback`. */
+    readonly basePath?: string;
+    /** Where users land after sign-in or sign-out without a target. */
+    readonly defaultRedirect?: string;
+    /** Absolute lifetime of a session. */
+    readonly sessionTtlSeconds?: number;
+    /** How often claims (roles, features…) are renewed from the provider. */
+    readonly claimsRenewSeconds?: number;
+    /** Refuse an ID token without `sid`: no back-channel logout could ever reach it. */
+    readonly requireProviderSession?: boolean;
+    /** Redirect target of a failed sign-in, with `?error=<code>`; JSON when unset. */
+    readonly errorRedirect?: string;
+    /** Adds `/wallet`, `/wallet/stats` and `/models` for the frontend, read with the user's tokens. */
+    readonly ai?: AiClient;
+    readonly replayStore?: ReplayStore;
+    /** Called after sessions end (sign-out or back-channel logout): close sockets, drop caches. */
+    readonly onSessionsEnded?: (sessions: readonly Session[]) => Promise<void> | void;
+    /** Receives unexpected failures and the ones the response must not detail. */
+    readonly onError?: (error: unknown) => void;
+}
+export interface AuthHandlers {
+    /** Serves the routes below `basePath`; null for any other path. */
+    handle(request: Request): Promise<Response | null>;
+    /** The signed-in session of a request, with claims renewed when due; null when signed out. */
+    getSession(request: Request): Promise<Session | null>;
+    /** Like `getSession`, throwing SES_001 when signed out. */
+    requireSession(request: Request): Promise<Session>;
+    /** Origin the SDK builds URLs on: that of `redirectUri`, never a request header. */
+    readonly origin: string;
+    readonly basePath: string;
+}
+/**
+ * Backend-for-frontend sign-in: the browser holds an opaque session cookie and
+ * never sees a token. Mount `handle` on every request below `basePath`.
+ */
+export declare function createAuthHandlers(options: AuthHandlersOptions): Promise<AuthHandlers>;

package/dist/web/handlers.js

@@ -0,0 +1,290 @@
+import { z } from "zod";
+import { AuthAiError, ERR } from "../errors.js";
+import { toSessionUser } from "../session-user.js";
+import { MemoryReplayStore, createBackchannelLogoutHandler, } from "../server/backchannel-logout.js";
+import { clearCookie, cookieName, parseCookies, serializeCookie, } from "./cookies.js";
+import { errorResponse, isCrossSite, jsonResponse, redirectResponse, safeRedirectPath, } from "./http.js";
+import { createAiRoutes } from "./ai-routes.js";
+import { deriveSealKey, seal, unseal } from "./seal.js";
+const HANDSHAKE_TTL_SECONDS = 600;
+const DEFAULT_SESSION_TTL_SECONDS = 8 * 3600;
+const DEFAULT_CLAIMS_RENEW_SECONDS = 900;
+const PROMPTS = [
+    "login",
+    "consent",
+    "select_account",
+    "create",
+    "none",
+];
+const isPrompt = (value) => PROMPTS.some((prompt) => prompt === value);
+const handshakeSchema = z.object({
+    state: z.string(),
+    nonce: z.string(),
+    codeVerifier: z.string(),
+    next: z.string(),
+});
+function base64Url(bytes) {
+    return btoa(String.fromCharCode(...bytes))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
+async function sha256Base64Url(value) {
+    return base64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value))));
+}
+const randomId = () => base64Url(crypto.getRandomValues(new Uint8Array(32)));
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+/**
+ * Backend-for-frontend sign-in: the browser holds an opaque session cookie and
+ * never sees a token. Mount `handle` on every request below `basePath`.
+ */
+export async function createAuthHandlers(options) {
+    const { auth, grants, sessions } = options;
+    const basePath = options.basePath ?? "/auth";
+    const defaultRedirect = options.defaultRedirect ?? "/";
+    const sessionTtl = options.sessionTtlSeconds ?? DEFAULT_SESSION_TTL_SECONDS;
+    const renewSeconds = options.claimsRenewSeconds ?? DEFAULT_CLAIMS_RENEW_SECONDS;
+    const requireProviderSession = options.requireProviderSession ?? true;
+    const replayStore = options.replayStore ?? new MemoryReplayStore();
+    if (!/^\/[A-Za-z0-9/_-]*$/.test(basePath) || basePath.endsWith("/")) {
+        throw ERR.CFG_001("basePath must look like /auth, with no trailing slash");
+    }
+    const redirect = new URL(auth.config.redirectUri);
+    if (redirect.pathname !== `${basePath}/callback`) {
+        throw ERR.CFG_001(`redirectUri must end with ${basePath}/callback`);
+    }
+    const origin = redirect.origin;
+    const secure = redirect.protocol === "https:";
+    const key = await deriveSealKey(options.secret);
+    const sessionCookie = cookieName("aai_session", secure);
+    const loginCookie = cookieName("aai_login", secure);
+    const withCookies = (...cookies) => {
+        const headers = new Headers();
+        for (const cookie of cookies)
+            headers.append("set-cookie", cookie);
+        return headers;
+    };
+    async function readSession(request) {
+        const cookie = parseCookies(request.headers.get("cookie")).get(sessionCookie);
+        if (!cookie)
+            return null;
+        return (await sessions.get(await sha256Base64Url(cookie))) ?? null;
+    }
+    async function renewClaims(session) {
+        let tokens;
+        try {
+            tokens = await grants.refreshTokens(session.userId);
+        }
+        catch (err) {
+            if (err instanceof AuthAiError && err.code === "TOK_002") {
+                await endSessions([session]);
+                return null;
+            }
+            throw err;
+        }
+        if (!tokens.idToken) {
+            throw ERR.TOK_001("The provider returned no ID token on refresh");
+        }
+        const claims = await auth.verifyIdToken(tokens.idToken);
+        if (claims.sub !== session.userId) {
+            await endSessions([session]);
+            throw ERR.TOK_001("The refreshed ID token belongs to another user");
+        }
+        const renewed = {
+            ...session,
+            claims,
+            idToken: tokens.idToken,
+            renewAt: Math.min(nowSeconds() + renewSeconds, session.expiresAt),
+        };
+        await sessions.update(renewed);
+        return renewed;
+    }
+    // Two simultaneous requests of one session share a single renewal.
+    const renewing = new Map();
+    async function getSession(request) {
+        const session = await readSession(request);
+        if (!session || nowSeconds() < session.renewAt)
+            return session;
+        let pending = renewing.get(session.id);
+        if (!pending) {
+            pending = renewClaims(session).finally(() => renewing.delete(session.id));
+            renewing.set(session.id, pending);
+        }
+        return pending;
+    }
+    async function requireSession(request) {
+        const session = await getSession(request);
+        if (!session)
+            throw ERR.SES_001();
+        return session;
+    }
+    /** Ends sessions, and revokes the grant of every user left with none. */
+    async function endSessions(ended) {
+        for (const session of ended)
+            await sessions.delete(session.id);
+        await afterSessionsRemoved(ended);
+    }
+    async function afterSessionsRemoved(ended) {
+        for (const userId of new Set(ended.map((session) => session.userId))) {
+            if ((await sessions.countByUser(userId)) > 0)
+                continue;
+            try {
+                await grants.revoke(userId);
+            }
+            catch (err) {
+                // The grant is already gone locally: the provider will expire it.
+                options.onError?.(err);
+            }
+        }
+        if (ended.length > 0)
+            await options.onSessionsEnded?.(ended);
+    }
+    async function login(request) {
+        const url = new URL(request.url);
+        const prompt = url.searchParams.get("prompt");
+        const { url: authorizationUrl, handshake } = await auth.startLogin(isPrompt(prompt) ? { prompt } : {});
+        const sealed = await seal(key, {
+            ...handshake,
+            next: safeRedirectPath(url.searchParams.get("next"), defaultRedirect),
+        }, HANDSHAKE_TTL_SECONDS);
+        return redirectResponse(authorizationUrl, 302, withCookies(serializeCookie(loginCookie, sealed, {
+            maxAgeSeconds: HANDSHAKE_TTL_SECONDS,
+            secure,
+        })));
+    }
+    async function createSession(claims, idToken, hasRefreshToken) {
+        const now = nowSeconds();
+        const expiresAt = hasRefreshToken
+            ? now + sessionTtl
+            : Math.min(now + sessionTtl, claims.exp);
+        const cookie = randomId();
+        const session = {
+            id: await sha256Base64Url(cookie),
+            userId: claims.sub,
+            sessionId: claims.sid,
+            claims,
+            idToken,
+            createdAt: now,
+            expiresAt,
+            renewAt: hasRefreshToken
+                ? Math.min(now + renewSeconds, expiresAt)
+                : expiresAt,
+        };
+        await sessions.create(session);
+        return { session, cookie };
+    }
+    async function callback(request) {
+        const clear = clearCookie(loginCookie, secure);
+        try {
+            const sealed = parseCookies(request.headers.get("cookie")).get(loginCookie);
+            if (!sealed)
+                throw ERR.SES_002();
+            const { next, ...handshake } = await unseal(key, sealed, handshakeSchema);
+            // Rebuilt on the registered URI: the request's own host is not trusted.
+            const callbackUrl = new URL(auth.config.redirectUri);
+            callbackUrl.search = new URL(request.url).search;
+            const result = await auth.handleCallback(callbackUrl, handshake);
+            if (requireProviderSession && !result.sessionId) {
+                throw ERR.SES_003("The ID token carries no sid: enable end session or a back-channel logout URI on the application");
+            }
+            const { refreshToken } = result.tokens;
+            if (refreshToken)
+                await grants.save(result.claims.sub, refreshToken);
+            const { cookie } = await createSession(result.claims, result.tokens.idToken, refreshToken !== undefined);
+            return redirectResponse(next, 303, withCookies(clear, serializeCookie(sessionCookie, cookie, {
+                maxAgeSeconds: sessionTtl,
+                secure,
+            })));
+        }
+        catch (err) {
+            // Whatever failed (state, code, client credentials, claims), the browser
+            // learns one thing: the sign-in failed. Telling a rejected client secret
+            // from a forged state would help whoever probes the callback; the cause
+            // reaches the application's logs.
+            options.onError?.(err);
+            const failure = ERR.SES_005(undefined, { cause: err });
+            if (options.errorRedirect) {
+                return redirectResponse(`${options.errorRedirect}?error=${failure.code}`, 303, withCookies(clear));
+            }
+            return errorResponse(failure, undefined, withCookies(clear));
+        }
+    }
+    async function me(request) {
+        const session = await getSession(request);
+        if (!session)
+            return errorResponse(ERR.SES_001(), options.onError);
+        return jsonResponse({
+            user: toSessionUser(session.claims),
+            expiresAt: session.expiresAt,
+        });
+    }
+    async function logout(request) {
+        if (isCrossSite(request, origin)) {
+            return errorResponse(ERR.SES_004(), options.onError);
+        }
+        const session = await readSession(request);
+        let logoutUrl = null;
+        if (session) {
+            try {
+                logoutUrl = await auth.logoutUrl({ idTokenHint: session.idToken });
+            }
+            catch (err) {
+                // A provider without end-session still lets the local session end.
+                options.onError?.(err);
+            }
+            await endSessions([session]);
+        }
+        const headers = withCookies(clearCookie(sessionCookie, secure));
+        if (request.headers.get("accept")?.includes("application/json")) {
+            return jsonResponse({ logoutUrl }, 200, headers);
+        }
+        return redirectResponse(logoutUrl ?? defaultRedirect, 303, headers);
+    }
+    const backchannelLogout = createBackchannelLogoutHandler({
+        auth,
+        replayStore,
+        ...(options.onError ? { onError: options.onError } : {}),
+        onLogout: async ({ sid }) => {
+            await afterSessionsRemoved(await sessions.deleteByProviderSession(sid));
+        },
+    });
+    const routes = {
+        "/login": { method: "GET", run: login },
+        "/callback": { method: "GET", run: callback },
+        "/me": { method: "GET", run: me },
+        "/logout": { method: "POST", run: logout },
+        "/backchannel-logout": { method: "POST", run: backchannelLogout },
+    };
+    if (options.ai) {
+        const aiRoutes = createAiRoutes(options.ai, requireSession);
+        for (const [path, run] of Object.entries(aiRoutes)) {
+            routes[path] = { method: "GET", run };
+        }
+    }
+    return {
+        origin,
+        basePath,
+        getSession,
+        requireSession,
+        async handle(request) {
+            const { pathname } = new URL(request.url);
+            if (!pathname.startsWith(`${basePath}/`))
+                return null;
+            const route = routes[pathname.slice(basePath.length)];
+            if (!route)
+                return null;
+            if (request.method !== route.method) {
+                return new Response(null, {
+                    status: 405,
+                    headers: { allow: route.method, "cache-control": "no-store" },
+                });
+            }
+            try {
+                return await route.run(request);
+            }
+            catch (err) {
+                return errorResponse(err, options.onError);
+            }
+        },
+    };
+}

package/dist/web/http.d.ts

@@ -0,0 +1,24 @@
+export declare const NO_STORE: {
+    readonly "cache-control": "no-store";
+};
+export declare function jsonResponse(body: unknown, status?: number, headers?: Headers): Response;
+export declare function redirectResponse(location: string, status: 302 | 303, headers?: Headers): Response;
+/**
+ * Serialises a failure as the same `{ error: { code, message } }` envelope
+ * auth-service uses, with the code and a generic message only: the detailed
+ * message and the details stay in the error, for the application's logs. Any
+ * other failure is reported to `onError` and answered generically.
+ */
+export declare function errorResponse(err: unknown, onError: ((error: unknown) => void) | undefined, headers?: Headers): Response;
+/**
+ * A redirect target taken from a request, reduced to a same-origin path: an
+ * absolute URL, a protocol-relative one (`//host`) or anything odd falls back
+ * to `fallback`, so a login link cannot bounce users to another site.
+ */
+export declare function safeRedirectPath(candidate: string | null | undefined, fallback: string): string;
+/**
+ * Refuses a state-changing request that a browser sent from another site.
+ * Requests without `Origin` and `Sec-Fetch-Site` (non-browser clients) carry
+ * no ambient cookie to abuse and pass.
+ */
+export declare function isCrossSite(request: Request, expectedOrigin: string): boolean;

package/dist/web/http.js

@@ -0,0 +1,85 @@
+import { AuthAiError, ERR } from "../errors.js";
+const STATUS_BY_CODE = {
+    REQ_001: 400,
+    SES_001: 401,
+    SES_002: 400,
+    SES_004: 403,
+    SES_005: 403,
+    TOK_001: 401,
+    TOK_002: 401,
+    TOK_003: 401,
+    TOK_004: 403,
+    OIDC_002: 400,
+    OIDC_001: 502,
+    OIDC_003: 502,
+    OIDC_004: 501,
+    API_001: 502,
+    API_002: 502,
+    GW_001: 402,
+    GW_002: 429,
+    GW_003: 403,
+    GW_004: 503,
+    GW_005: 502,
+};
+export const NO_STORE = { "cache-control": "no-store" };
+// Wallet amounts are bigint micro-euros: they travel as integer strings.
+const bigintToString = (_key, value) => typeof value === "bigint" ? value.toString() : value;
+export function jsonResponse(body, status = 200, headers = new Headers()) {
+    headers.set("content-type", "application/json");
+    headers.set("cache-control", "no-store");
+    return new Response(JSON.stringify(body, bigintToString), {
+        status,
+        headers,
+    });
+}
+export function redirectResponse(location, status, headers = new Headers()) {
+    headers.set("location", location);
+    headers.set("cache-control", "no-store");
+    return new Response(null, { status, headers });
+}
+/**
+ * Serialises a failure as the same `{ error: { code, message } }` envelope
+ * auth-service uses, with the code and a generic message only: the detailed
+ * message and the details stay in the error, for the application's logs. Any
+ * other failure is reported to `onError` and answered generically.
+ */
+export function errorResponse(err, onError, headers) {
+    if (err instanceof AuthAiError) {
+        return jsonResponse({ error: err.toPublicJSON() }, STATUS_BY_CODE[err.code] ?? 500, headers);
+    }
+    onError?.(err);
+    return jsonResponse({ error: ERR.SRV_001().toPublicJSON() }, 500, headers);
+}
+// Control characters and backslashes make browsers read a "path" as another host.
+const hasUnsafeCharacter = (value) => [...value].some((char) => {
+    const code = char.charCodeAt(0);
+    return char === "\\" || code <= 0x1f || code === 0x7f;
+});
+/**
+ * A redirect target taken from a request, reduced to a same-origin path: an
+ * absolute URL, a protocol-relative one (`//host`) or anything odd falls back
+ * to `fallback`, so a login link cannot bounce users to another site.
+ */
+export function safeRedirectPath(candidate, fallback) {
+    if (!candidate?.startsWith("/") || candidate.startsWith("//")) {
+        return fallback;
+    }
+    if (hasUnsafeCharacter(candidate))
+        return fallback;
+    const probe = new URL(candidate, "https://placeholder.invalid");
+    if (probe.origin !== "https://placeholder.invalid")
+        return fallback;
+    return `${probe.pathname}${probe.search}${probe.hash}`;
+}
+/**
+ * Refuses a state-changing request that a browser sent from another site.
+ * Requests without `Origin` and `Sec-Fetch-Site` (non-browser clients) carry
+ * no ambient cookie to abuse and pass.
+ */
+export function isCrossSite(request, expectedOrigin) {
+    const origin = request.headers.get("origin");
+    if (origin !== null)
+        return origin !== expectedOrigin;
+    const site = request.headers.get("sec-fetch-site");
+    return site !== null && site !== "same-origin" && site !== "none";
+}

package/dist/web/index.d.ts

@@ -0,0 +1,7 @@
+export { createAuthHandlers } from "./handlers.js";
+export type { AuthHandlers, AuthHandlersOptions } from "./handlers.js";
+export { MemorySessionStore } from "./sessions.js";
+export type { Session, SessionStore } from "./sessions.js";
+export { safeRedirectPath } from "./http.js";
+export { sessionUserSchema, toSessionUser } from "../session-user.js";
+export type { SessionUser } from "../session-user.js";

package/dist/web/index.js

@@ -0,0 +1,4 @@
+export { createAuthHandlers } from "./handlers.js";
+export { MemorySessionStore } from "./sessions.js";
+export { safeRedirectPath } from "./http.js";
+export { sessionUserSchema, toSessionUser } from "../session-user.js";

package/dist/web/seal.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/**
+ * Derives the AES-256 key sealing the short-lived cookies from the
+ * application's secret. The secret must be long and random (for example 32
+ * bytes of base64): it is never stored or logged.
+ */
+export declare function deriveSealKey(secret: string): Promise<Uint8Array>;
+/** Encrypts and authenticates a JSON value into a compact token that expires. */
+export declare function seal(key: Uint8Array, data: unknown, ttlSeconds: number): Promise<string>;
+/** The value of `seal`, validated by `schema`; SES_002 for any tampered or expired token. */
+export declare function unseal<T>(key: Uint8Array, token: string, schema: z.ZodType<T>): Promise<T>;

package/dist/web/seal.js

@@ -0,0 +1,39 @@
+import { EncryptJWT, jwtDecrypt } from "jose";
+import { z } from "zod";
+import { ERR } from "../errors.js";
+const MIN_SECRET_LENGTH = 32;
+/**
+ * Derives the AES-256 key sealing the short-lived cookies from the
+ * application's secret. The secret must be long and random (for example 32
+ * bytes of base64): it is never stored or logged.
+ */
+export async function deriveSealKey(secret) {
+    if (secret.length < MIN_SECRET_LENGTH) {
+        throw ERR.CFG_001(`The secret must be at least ${MIN_SECRET_LENGTH} characters long`);
+    }
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`auth-ai:seal:${secret}`));
+    return new Uint8Array(digest);
+}
+const envelopeSchema = z.object({ data: z.unknown() });
+/** Encrypts and authenticates a JSON value into a compact token that expires. */
+export async function seal(key, data, ttlSeconds) {
+    return new EncryptJWT({ data })
+        .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
+        .setIssuedAt()
+        .setExpirationTime(`${ttlSeconds}s`)
+        .encrypt(key);
+}
+/** The value of `seal`, validated by `schema`; SES_002 for any tampered or expired token. */
+export async function unseal(key, token, schema) {
+    try {
+        const { payload } = await jwtDecrypt(token, key, {
+            keyManagementAlgorithms: ["dir"],
+            contentEncryptionAlgorithms: ["A256GCM"],
+        });
+        const envelope = envelopeSchema.parse(payload);
+        return schema.parse(envelope.data);
+    }
+    catch (err) {
+        throw ERR.SES_002(undefined, { cause: err });
+    }
+}

package/dist/web/sessions.d.ts

@@ -0,0 +1,43 @@
+import type { IdTokenClaims } from "../claims.js";
+/** A signed-in browser session, as kept by the application's backend. */
+export interface Session {
+    /** SHA-256 of the cookie value: a leaked store cannot be replayed as cookies. */
+    readonly id: string;
+    /** The provider's subject: also the key of the user's grant. */
+    readonly userId: string;
+    /** The provider session, which a back-channel logout names. */
+    readonly sessionId: string | undefined;
+    readonly claims: IdTokenClaims;
+    /** Hint for the provider's logout endpoint. */
+    readonly idToken: string;
+    /** Unix seconds. */
+    readonly createdAt: number;
+    /** Absolute end of the session, in unix seconds. */
+    readonly expiresAt: number;
+    /** When the claims are next renewed from the provider, in unix seconds. */
+    readonly renewAt: number;
+}
+/**
+ * Where sessions live. Implement it on the database of the application; it
+ * must survive restarts and be shared by every replica. Records are keyed by
+ * `Session.id`, and `sessionId` and `userId` must be indexed.
+ */
+export interface SessionStore {
+    create(session: Session): Promise<void>;
+    /** Returns undefined for an unknown or expired session. */
+    get(id: string): Promise<Session | undefined>;
+    update(session: Session): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Removes every session of a provider session and returns what was removed. */
+    deleteByProviderSession(sessionId: string): Promise<readonly Session[]>;
+    countByUser(userId: string): Promise<number>;
+}
+export declare class MemorySessionStore implements SessionStore {
+    #private;
+    create(session: Session): Promise<void>;
+    get(id: string): Promise<Session | undefined>;
+    update(session: Session): Promise<void>;
+    delete(id: string): Promise<void>;
+    deleteByProviderSession(sessionId: string): Promise<readonly Session[]>;
+    countByUser(userId: string): Promise<number>;
+}