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

package/dist/grants.js

@@ -0,0 +1,157 @@
+import { ERR } from "./errors.js";
+import { isInvalidGrant } from "./oauth-errors.js";
+const DEFAULT_EXPIRY_SKEW_SECONDS = 30;
+export class MemoryGrantStore {
+    #grants = new Map();
+    get(grantId) {
+        return Promise.resolve(this.#grants.get(grantId));
+    }
+    set(grantId, refreshToken) {
+        this.#grants.set(grantId, refreshToken);
+        return Promise.resolve();
+    }
+    delete(grantId) {
+        this.#grants.delete(grantId);
+        return Promise.resolve();
+    }
+}
+export class InProcessGrantLock {
+    #tails = new Map();
+    async run(grantId, task) {
+        const previous = this.#tails.get(grantId) ?? Promise.resolve();
+        const current = previous.then(task, task);
+        const tail = current.catch(() => undefined);
+        this.#tails.set(grantId, tail);
+        try {
+            return await current;
+        }
+        finally {
+            if (this.#tails.get(grantId) === tail)
+                this.#tails.delete(grantId);
+        }
+    }
+}
+/**
+ * The only place that refreshes tokens. Access tokens are minted per resource
+ * (RFC 8707) from the stored refresh token and cached in memory until shortly
+ * before they expire; they are never persisted.
+ */
+export class GrantManager {
+    #auth;
+    #store;
+    #lock;
+    #skewSeconds;
+    #cache = new Map();
+    constructor(options) {
+        this.#auth = options.auth;
+        this.#store = options.store;
+        this.#lock = options.lock ?? new InProcessGrantLock();
+        this.#skewSeconds =
+            options.expirySkewSeconds ?? DEFAULT_EXPIRY_SKEW_SECONDS;
+    }
+    /** Stores the refresh token obtained at sign-in, replacing any older chain. */
+    async save(grantId, refreshToken) {
+        await this.#lock.run(grantId, async () => {
+            await this.#store.set(grantId, refreshToken);
+            this.#forget(grantId);
+        });
+    }
+    async has(grantId) {
+        return (await this.#store.get(grantId)) !== undefined;
+    }
+    /**
+     * Returns an access token for `resource` (or for the whole sign-in set when
+     * omitted). Throws TOK_002 when the user has no grant or the provider
+     * rejected it: the grant is then dropped and only a new sign-in restores it.
+     */
+    async getAccessToken(grantId, options = {}) {
+        const key = cacheKey(grantId, options.resource);
+        const cached = this.#cached(key);
+        if (cached)
+            return cached;
+        return this.#lock.run(grantId, async () => {
+            // Another caller may have refreshed while this one waited for the lock.
+            const refreshed = this.#cached(key);
+            if (refreshed)
+                return refreshed;
+            const tokens = await this.#rotate(grantId, options.resource ? { resource: options.resource } : {});
+            const token = {
+                accessToken: tokens.accessToken,
+                expiresAt: tokens.expiresAt,
+            };
+            this.#cache.set(key, token);
+            return token;
+        });
+    }
+    /**
+     * Refreshes without narrowing to a resource and returns the whole token set,
+     * ID token included: the way to renew the claims of a session. The rotated
+     * refresh token is stored. Failures are those of `getAccessToken`.
+     */
+    async refreshTokens(grantId) {
+        return this.#lock.run(grantId, () => this.#rotate(grantId, {}));
+    }
+    /** Drops a cached access token the API refused, so the next call mints a fresh one. */
+    invalidate(grantId, resource) {
+        this.#cache.delete(cacheKey(grantId, resource));
+    }
+    /** Revokes the refresh token at the provider, then forgets the grant. */
+    async revoke(grantId) {
+        await this.#lock.run(grantId, async () => {
+            const refreshToken = await this.#store.get(grantId);
+            try {
+                if (refreshToken !== undefined) {
+                    await this.#auth.revoke(refreshToken, "refresh_token");
+                }
+            }
+            finally {
+                // An unreachable provider must not keep the user signed in locally.
+                await this.#store.delete(grantId);
+                this.#forget(grantId);
+            }
+        });
+    }
+    /** One refresh under the grant lock the caller already holds. */
+    async #rotate(grantId, options) {
+        const refreshToken = await this.#store.get(grantId);
+        if (refreshToken === undefined)
+            throw ERR.TOK_002();
+        let tokens;
+        try {
+            tokens = await this.#auth.refresh(refreshToken, options);
+        }
+        catch (err) {
+            if (isInvalidGrant(err)) {
+                await this.#store.delete(grantId);
+                this.#forget(grantId);
+                throw ERR.TOK_002(undefined, { cause: err });
+            }
+            throw err;
+        }
+        // Providers may omit the refresh token when they do not rotate it.
+        await this.#store.set(grantId, tokens.refreshToken ?? refreshToken);
+        return tokens;
+    }
+    #cached(key) {
+        const token = this.#cache.get(key);
+        if (!token)
+            return undefined;
+        if (token.expiresAt - this.#skewSeconds > Date.now() / 1000)
+            return token;
+        this.#cache.delete(key);
+        return undefined;
+    }
+    #forget(grantId) {
+        const prefix = `${grantId}\0`;
+        for (const key of this.#cache.keys()) {
+            if (key.startsWith(prefix))
+                this.#cache.delete(key);
+        }
+    }
+}
+function cacheKey(grantId, resource) {
+    return `${grantId}\0${resource ?? ""}`;
+}
+export function createGrantManager(options) {
+    return new GrantManager(options);
+}

package/dist/http.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/** Supplies the Bearer token of a call, by the scope or audience the endpoint requires. */
+export interface HttpTokens {
+    getToken(key: string): Promise<string>;
+    /** Drops a token the API refused, so the retry mints a fresh one. */
+    invalidate(key: string): void;
+}
+export interface JsonHttpOptions {
+    /** Origin the request paths are resolved against: no trailing slash. */
+    readonly baseUrl: string;
+    readonly fetch: typeof fetch;
+    readonly timeoutMs: number;
+    readonly tokens: HttpTokens;
+}
+export interface ApiRequest<T> {
+    readonly method: "GET" | "POST";
+    /** Path below the base URL; segments must already be URL-encoded. */
+    readonly path: string;
+    /** Key passed to the token supplier: a machine scope, or an audience. */
+    readonly scope: string;
+    readonly query?: Readonly<Record<string, string | number | undefined>>;
+    readonly body?: unknown;
+    readonly schema: z.ZodType<T>;
+}
+/** Authenticated JSON calls to the auth-service REST API. */
+export declare class JsonHttp {
+    #private;
+    constructor(options: JsonHttpOptions);
+    request<T>(request: ApiRequest<T>): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { ERR } from "./errors.js";
+const apiErrorSchema = z.object({
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+    }),
+});
+/** Authenticated JSON calls to the auth-service REST API. */
+export class JsonHttp {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    async request(request) {
+        let response = await this.#send(request);
+        // A revoked or rotated credential surfaces as 401: retry once with a fresh token.
+        if (response.status === 401) {
+            this.#options.tokens.invalidate(request.scope);
+            response = await this.#send(request);
+        }
+        if (!response.ok)
+            throw await this.#toError(response);
+        const parsed = request.schema.safeParse(await response.json());
+        if (!parsed.success) {
+            throw ERR.API_002(undefined, { cause: parsed.error });
+        }
+        return parsed.data;
+    }
+    async #send(request) {
+        const url = new URL(`${this.#options.baseUrl}${request.path}`);
+        for (const [name, value] of Object.entries(request.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(name, String(value));
+        }
+        const token = await this.#options.tokens.getToken(request.scope);
+        return this.#options.fetch(url, {
+            method: request.method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...(request.body === undefined
+                    ? {}
+                    : { "content-type": "application/json" }),
+            },
+            ...(request.body === undefined
+                ? {}
+                : { body: JSON.stringify(request.body) }),
+            redirect: "error",
+            signal: AbortSignal.timeout(this.#options.timeoutMs),
+        });
+    }
+    async #toError(response) {
+        const body = apiErrorSchema.safeParse(await response.json().catch(() => undefined));
+        if (!body.success) {
+            return ERR.API_001(`auth-service answered ${response.status}`, {
+                details: { status: response.status },
+            });
+        }
+        const { code, message } = body.data.error;
+        return ERR.API_001(`auth-service answered ${response.status} ${code}: ${message}`, { details: { status: response.status, apiCode: code } });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { AuthClient, createAuthClient } from "./client.js";
+export type { AuthClientOptions } from "./client.js";
+export { DEFAULT_SCOPES } from "./config.js";
+export type { AuthClientConfig, ResolvedAuthClientConfig } from "./config.js";
+export { getFeature, hasFeature, hasPermission, accessTokenClaimsSchema, hasRole, idTokenClaimsSchema, } from "./claims.js";
+export type { FeatureValue, IdTokenClaims, PermissionAction, } from "./claims.js";
+export { AuthAiError, ERR } from "./errors.js";
+export type { AuthAiErrorCode, AuthAiErrorDetails, AuthAiErrorOptions, } from "./errors.js";
+export { GrantManager, InProcessGrantLock, MemoryGrantStore, createGrantManager, } from "./grants.js";
+export type { AccessToken, GrantLock, GrantManagerOptions, GrantStore, } from "./grants.js";
+export type { IntrospectionResult } from "./introspection.js";
+export type { ClientCredentialsOptions, LoginHandshake, LoginRequest, LoginResult, LogoutUrlOptions, RefreshOptions, StartLoginOptions, TokenSet, TokenTypeHint, } from "./types.js";
+export { AiClient, UserAi, createAiClient } from "./ai.js";
+export type { AiClientOptions } from "./ai.js";
+export { GatewayClient } from "./gateway.js";
+export type { GatewayAgent, GatewayClientOptions, GatewayMcpServer, GatewayModel, GatewayTokens, } from "./gateway.js";
+export { isInsufficientCredit, isInsufficientCreditStatus, toGatewayError, } from "./gateway-errors.js";
+export { MICRO_PER_EUR, WalletClient, formatEuros } from "./wallet.js";
+export type { ListTransactionsOptions, TopupOptions, WalletAccount, WalletSessionUsage, WalletSessionUsageOptions, WalletStats, WalletStatsOptions, WalletTransaction, WalletTransactionPage, WalletTransactionType, } from "./wallet.js";
+export { WALLET_SELF_SCOPE } from "./config.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { AuthClient, createAuthClient } from "./client.js";
+export { DEFAULT_SCOPES } from "./config.js";
+export { getFeature, hasFeature, hasPermission, accessTokenClaimsSchema, hasRole, idTokenClaimsSchema, } from "./claims.js";
+export { AuthAiError, ERR } from "./errors.js";
+export { GrantManager, InProcessGrantLock, MemoryGrantStore, createGrantManager, } from "./grants.js";
+export { AiClient, UserAi, createAiClient } from "./ai.js";
+export { GatewayClient } from "./gateway.js";
+export { isInsufficientCredit, isInsufficientCreditStatus, toGatewayError, } from "./gateway-errors.js";
+export { MICRO_PER_EUR, WalletClient, formatEuros } from "./wallet.js";
+export { WALLET_SELF_SCOPE } from "./config.js";

package/dist/introspection.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const introspectionSchema: z.ZodObject<{
+    active: z.ZodBoolean;
+    scope: z.ZodOptional<z.ZodString>;
+    client_id: z.ZodOptional<z.ZodString>;
+    sub: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    iss: z.ZodOptional<z.ZodString>;
+    aud: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    exp: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type IntrospectionResult = z.infer<typeof introspectionSchema>;

package/dist/introspection.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export const introspectionSchema = z.looseObject({
+    active: z.boolean(),
+    scope: z.string().optional(),
+    client_id: z.string().optional(),
+    sub: z.string().optional(),
+    username: z.string().optional(),
+    iss: z.string().optional(),
+    aud: z.union([z.string(), z.array(z.string())]).optional(),
+    exp: z.number().optional(),
+    iat: z.number().optional(),
+});

package/dist/jwt.d.ts

@@ -0,0 +1,16 @@
+import type { JWTPayload } from "jose";
+export interface JwtVerifierOptions {
+    readonly issuer: string;
+    readonly jwksUri: string;
+    /** Pinned to the algorithms the provider declares: `none` and HMAC never qualify. */
+    readonly algorithms: readonly string[];
+    readonly clockToleranceSeconds: number;
+    readonly timeoutMs: number;
+    readonly fetch: typeof fetch | undefined;
+}
+export interface VerifyJwtOptions {
+    readonly audience: string;
+    readonly typ?: string;
+}
+export type JwtVerifier = (token: string, options: VerifyJwtOptions) => Promise<JWTPayload>;
+export declare function createJwtVerifier(options: JwtVerifierOptions): JwtVerifier;

package/dist/jwt.js

@@ -0,0 +1,35 @@
+import { createRemoteJWKSet, customFetch, errors as joseErrors, jwtVerify, } from "jose";
+import { ERR } from "./errors.js";
+// Re-fetch an unknown `kid` (key rotation) at most once per cooldown.
+const JWKS_COOLDOWN_MS = 30_000;
+const JWKS_MAX_AGE_MS = 3_600_000;
+export function createJwtVerifier(options) {
+    const jwks = createRemoteJWKSet(new URL(options.jwksUri), {
+        cooldownDuration: JWKS_COOLDOWN_MS,
+        cacheMaxAge: JWKS_MAX_AGE_MS,
+        timeoutDuration: options.timeoutMs,
+        ...(options.fetch ? { [customFetch]: options.fetch } : {}),
+    });
+    return async (token, { audience, typ }) => {
+        try {
+            const { payload } = await jwtVerify(token, jwks, {
+                issuer: options.issuer,
+                audience,
+                algorithms: [...options.algorithms],
+                clockTolerance: options.clockToleranceSeconds,
+                requiredClaims: ["exp", "iss", "sub"],
+                ...(typ ? { typ } : {}),
+            });
+            return payload;
+        }
+        catch (err) {
+            if (err instanceof joseErrors.JOSEError) {
+                throw ERR.TOK_001(`Token verification failed: ${err.message}`, {
+                    details: { reason: err.code },
+                    cause: err,
+                });
+            }
+            throw ERR.TOK_001(undefined, { cause: err });
+        }
+    };
+}

package/dist/oauth-errors.d.ts

@@ -0,0 +1,9 @@
+import { AuthAiError } from "./errors.js";
+export type OAuthContext = "discovery" | "authorization-response" | "token-request";
+/**
+ * Maps an openid-client failure to the SDK registry. Response bodies are
+ * reduced to the RFC 6749 `error` and `error_description` fields, which carry
+ * no credential.
+ */
+export declare function toAuthAiError(err: unknown, context: OAuthContext): AuthAiError;
+export declare function isInvalidGrant(err: unknown): boolean;

package/dist/oauth-errors.js

@@ -0,0 +1,50 @@
+import { AuthorizationResponseError, ClientError, ResponseBodyError, WWWAuthenticateChallengeError, } from "openid-client";
+import { AuthAiError, ERR } from "./errors.js";
+/**
+ * Maps an openid-client failure to the SDK registry. Response bodies are
+ * reduced to the RFC 6749 `error` and `error_description` fields, which carry
+ * no credential.
+ */
+export function toAuthAiError(err, context) {
+    if (err instanceof AuthAiError)
+        return err;
+    if (context === "discovery") {
+        return ERR.OIDC_001(undefined, { cause: err });
+    }
+    if (err instanceof ResponseBodyError) {
+        const details = {
+            oauthError: err.error,
+            status: err.status,
+        };
+        if (err.error_description)
+            details["description"] = err.error_description;
+        return ERR.OIDC_003(`Token endpoint rejected the request: ${err.error}`, {
+            details,
+            cause: err,
+        });
+    }
+    // The provider answers 401 with a Basic challenge when client authentication fails.
+    if (err instanceof WWWAuthenticateChallengeError) {
+        return ERR.OIDC_003(`Token endpoint challenged the request (HTTP ${err.status}): check clientId and clientSecret`, { details: { status: err.status }, cause: err });
+    }
+    if (err instanceof AuthorizationResponseError) {
+        const details = { oauthError: err.error };
+        return ERR.OIDC_002(`Authorization failed: ${err.error}`, {
+            details,
+            cause: err,
+        });
+    }
+    if (context === "authorization-response" && err instanceof ClientError) {
+        return ERR.OIDC_002(undefined, {
+            details: err.code ? { reason: err.code } : {},
+            cause: err,
+        });
+    }
+    return context === "authorization-response"
+        ? ERR.OIDC_002(undefined, { cause: err })
+        : ERR.OIDC_003(undefined, { cause: err });
+}
+export function isInvalidGrant(err) {
+    return (err instanceof AuthAiError &&
+        err.details?.["oauthError"] === "invalid_grant");
+}

package/dist/provider.d.ts

@@ -0,0 +1,8 @@
+import * as oidc from "openid-client";
+import type { ResolvedAuthClientConfig } from "./config.js";
+import type { JwtVerifier } from "./jwt.js";
+export interface Provider {
+    readonly configuration: oidc.Configuration;
+    readonly verifyJwt: JwtVerifier;
+}
+export declare function createProviderLoader(config: ResolvedAuthClientConfig, fetchImpl: typeof fetch | undefined): () => Promise<Provider>;

package/dist/provider.js

@@ -0,0 +1,86 @@
+import * as oidc from "openid-client";
+import { ERR } from "./errors.js";
+import { createJwtVerifier } from "./jwt.js";
+import { toAuthAiError } from "./oauth-errors.js";
+// Discovery and keys change rarely; an hour keeps rotation picked up without a restart.
+const PROVIDER_TTL_MS = 3_600_000;
+const ASYMMETRIC_ALGORITHMS = new Set([
+    "EdDSA",
+    "ES256",
+    "ES384",
+    "ES512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "PS256",
+    "PS384",
+    "PS512",
+]);
+function clientAuthentication(config) {
+    if (!config.clientSecret)
+        return oidc.None();
+    return config.tokenEndpointAuthMethod === "client_secret_post"
+        ? oidc.ClientSecretPost(config.clientSecret)
+        : oidc.ClientSecretBasic(config.clientSecret);
+}
+// openid-client types its body wider than RequestInit under `exactOptionalPropertyTypes`
+// (it admits a Uint8Array over a SharedArrayBuffer), but only ever sends strings or form data.
+function asCustomFetch(fetchImpl) {
+    return (url, { body, ...init }) => fetchImpl(url, body === undefined ? init : { ...init, body: body });
+}
+async function loadProvider(config, fetchImpl) {
+    const timeoutSeconds = Math.ceil(config.timeoutMs / 1000);
+    const auth = clientAuthentication(config);
+    let discovered;
+    try {
+        discovered = await oidc.discovery(new URL(config.issuer), config.clientId, undefined, auth, {
+            timeout: timeoutSeconds,
+            ...(fetchImpl ? { [oidc.customFetch]: asCustomFetch(fetchImpl) } : {}),
+        });
+    }
+    catch (err) {
+        throw toAuthAiError(err, "discovery");
+    }
+    const server = discovered.serverMetadata();
+    const algorithms = (server.id_token_signing_alg_values_supported ?? []).filter((alg) => ASYMMETRIC_ALGORITHMS.has(alg));
+    const [idTokenAlgorithm] = algorithms;
+    if (!idTokenAlgorithm || !server.jwks_uri) {
+        throw ERR.OIDC_001("The provider advertises no asymmetric ID token algorithm or no jwks_uri");
+    }
+    // The library assumes RS256 unless told otherwise, whereas auth-service signs with EdDSA.
+    const configuration = new oidc.Configuration(server, config.clientId, {
+        id_token_signed_response_alg: idTokenAlgorithm,
+        [oidc.clockTolerance]: config.clockToleranceSeconds,
+    }, auth);
+    configuration.timeout = timeoutSeconds;
+    if (fetchImpl)
+        configuration[oidc.customFetch] = asCustomFetch(fetchImpl);
+    return {
+        configuration,
+        verifyJwt: createJwtVerifier({
+            issuer: config.issuer,
+            jwksUri: server.jwks_uri,
+            algorithms,
+            clockToleranceSeconds: config.clockToleranceSeconds,
+            timeoutMs: config.timeoutMs,
+            fetch: fetchImpl,
+        }),
+    };
+}
+export function createProviderLoader(config, fetchImpl) {
+    let cached;
+    return () => {
+        if (cached && Date.now() - cached.loadedAt < PROVIDER_TTL_MS) {
+            return cached.provider;
+        }
+        const provider = loadProvider(config, fetchImpl);
+        const entry = { loadedAt: Date.now(), provider };
+        cached = entry;
+        // A failed load is not cached: the next call retries.
+        provider.catch(() => {
+            if (cached === entry)
+                cached = undefined;
+        });
+        return provider;
+    };
+}

package/dist/react/index.d.ts

@@ -0,0 +1,44 @@
+import type { ReactNode } from "react";
+import type { BrowserAuth, WalletView } from "../browser/client.js";
+import type { AuthState, ResourceState } from "../browser/store.js";
+import type { FeatureValue, PermissionAction } from "../claims.js";
+import type { GatewayModel } from "../gateway.js";
+import type { SessionUser } from "../session-user.js";
+import type { WalletStats } from "../wallet.js";
+export interface AuthProviderProps {
+    /** Defaults to a client on `basePath`. */
+    readonly auth?: BrowserAuth;
+    readonly basePath?: string;
+    /** Re-reads the session when the tab becomes visible again. */
+    readonly refreshOnFocus?: boolean;
+    readonly children?: ReactNode;
+}
+export declare function AuthProvider(props: AuthProviderProps): ReactNode;
+export interface UseAuthResult extends AuthState {
+    readonly login: (next?: string) => void;
+    readonly logout: () => Promise<void>;
+    readonly refresh: () => Promise<void>;
+}
+export declare function useAuth(): UseAuthResult;
+/** The signed-in user, or null while loading and when signed out. */
+export declare function useUser(): SessionUser | null;
+export interface Entitlements {
+    hasRole(role: string): boolean;
+    hasPermission(resource: string, action?: PermissionAction): boolean;
+    hasFeature(key: string): boolean;
+    getFeature(key: string): FeatureValue | undefined;
+}
+/** Entitlement checks for the current user: all false when signed out. */
+export declare function useEntitlements(): Entitlements;
+export interface UseResourceResult<T> extends ResourceState<T> {
+    readonly refresh: () => Promise<void>;
+}
+export interface UseWalletOptions {
+    /** Reload the balance on this interval; 15 s is plenty. */
+    readonly pollIntervalMs?: number;
+}
+/** The user's credit; `data.canSpend` tells whether a paid action may start. */
+export declare function useWallet(options?: UseWalletOptions): UseResourceResult<WalletView>;
+export declare function useWalletStats(days?: number): UseResourceResult<WalletStats>;
+/** The models the user's plan may call on the gateway. */
+export declare function useModels(): UseResourceResult<GatewayModel[]>;

package/dist/react/index.js

@@ -0,0 +1,88 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore, } from "react";
+import { createBrowserAuth } from "../browser/client.js";
+import { createAuthStore, createResourceStore } from "../browser/store.js";
+import { getFeature, hasFeature, hasPermission, hasRole } from "../claims.js";
+const AuthContext = createContext(null);
+function useAuthContext() {
+    const context = useContext(AuthContext);
+    if (!context)
+        throw new Error("Wrap the application in <AuthProvider>");
+    return context;
+}
+export function AuthProvider(props) {
+    const { auth: provided, basePath, refreshOnFocus = true, children } = props;
+    const value = useMemo(() => {
+        const auth = provided ?? createBrowserAuth(basePath ? { basePath } : {});
+        return { auth, store: createAuthStore(auth) };
+    }, [provided, basePath]);
+    useEffect(() => {
+        void value.store.refresh();
+        if (!refreshOnFocus)
+            return undefined;
+        const onVisible = () => {
+            if (document.visibilityState === "visible")
+                void value.store.refresh();
+        };
+        document.addEventListener("visibilitychange", onVisible);
+        return () => document.removeEventListener("visibilitychange", onVisible);
+    }, [value, refreshOnFocus]);
+    return createElement(AuthContext.Provider, { value }, children);
+}
+export function useAuth() {
+    const { auth, store } = useAuthContext();
+    const state = useSyncExternalStore(store.state.subscribe, store.state.get, store.state.get);
+    return useMemo(() => ({
+        ...state,
+        login: (next) => auth.login(next),
+        logout: () => auth.logout(),
+        refresh: () => store.refresh(),
+    }), [state, auth, store]);
+}
+/** The signed-in user, or null while loading and when signed out. */
+export function useUser() {
+    return useAuth().user;
+}
+/** Entitlement checks for the current user: all false when signed out. */
+export function useEntitlements() {
+    const user = useUser();
+    return useMemo(() => {
+        const claims = user ?? {};
+        return {
+            hasRole: (role) => hasRole(claims, role),
+            hasPermission: (resource, action) => hasPermission(claims, resource, action),
+            hasFeature: (key) => hasFeature(claims, key),
+            getFeature: (key) => getFeature(claims, key),
+        };
+    }, [user]);
+}
+function useResource(load, options, deps) {
+    const { store: authStore } = useAuthContext();
+    const { pollIntervalMs } = options;
+    const resource = useMemo(() => createResourceStore(load, {
+        ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+        // A 401 means the session ended: let the auth state say so.
+        onError: (error) => {
+            if (error.code === "SES_001")
+                void authStore.refresh();
+        },
+    }), 
+    // `load` is rebuilt on every render: its inputs are the deps.
+    [authStore, pollIntervalMs, ...deps]);
+    useEffect(() => resource.start(), [resource]);
+    const state = useSyncExternalStore(resource.state.subscribe, resource.state.get, resource.state.get);
+    return useMemo(() => ({ ...state, refresh: resource.refresh }), [state, resource]);
+}
+/** The user's credit; `data.canSpend` tells whether a paid action may start. */
+export function useWallet(options = {}) {
+    const { auth } = useAuthContext();
+    return useResource(() => auth.getWallet(), options, [auth]);
+}
+export function useWalletStats(days) {
+    const { auth } = useAuthContext();
+    return useResource(() => auth.getWalletStats(days), {}, [auth, days]);
+}
+/** The models the user's plan may call on the gateway. */
+export function useModels() {
+    const { auth } = useAuthContext();
+    return useResource(() => auth.listModels(), {}, [auth]);
+}