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

package/dist/errors.d.ts

@@ -0,0 +1,82 @@
+export type AuthAiErrorDetails = Readonly<Record<string, string | number | boolean | null>>;
+export interface AuthAiErrorOptions {
+    readonly details?: AuthAiErrorDetails;
+    readonly cause?: unknown;
+}
+declare const DEFAULT_MESSAGES: {
+    readonly CFG_001: "Invalid SDK configuration";
+    readonly OIDC_001: "Identity provider discovery failed";
+    readonly OIDC_002: "Invalid authorization response";
+    readonly OIDC_003: "Token request failed";
+    readonly OIDC_004: "The identity provider does not support this operation";
+    readonly TOK_001: "Token verification failed";
+    readonly TOK_002: "No usable grant for this user: sign in again";
+    readonly TOK_003: "Missing or malformed bearer credentials";
+    readonly TOK_004: "Insufficient scope";
+    readonly API_001: "auth-service rejected the request";
+    readonly API_002: "Unexpected response from auth-service";
+    readonly GW_001: "Insufficient credit: the wallet cannot pay for this call";
+    readonly GW_002: "The gateway rate limit was reached";
+    readonly GW_003: "The gateway refused the credentials or the resource";
+    readonly GW_004: "The gateway is temporarily unavailable";
+    readonly GW_005: "Unexpected response from the gateway";
+    readonly SES_001: "Not signed in";
+    readonly SES_002: "The sign-in attempt is missing, expired or was tampered with";
+    readonly SES_003: "Sign-in could not be completed";
+    readonly SES_004: "Cross-origin request refused";
+    readonly SES_005: "Sign-in failed";
+    readonly REQ_001: "Invalid request";
+    readonly SRV_001: "Internal error";
+};
+export type AuthAiErrorCode = keyof typeof DEFAULT_MESSAGES;
+export declare function isAuthAiErrorCode(value: unknown): value is AuthAiErrorCode;
+/**
+ * Every failure raised by the SDK. `details` must never carry tokens, secrets
+ * or other credentials: it is meant to be logged and serialised.
+ */
+export declare class AuthAiError extends Error {
+    readonly code: AuthAiErrorCode;
+    readonly details: AuthAiErrorDetails | undefined;
+    constructor(code: AuthAiErrorCode, message: string, options?: AuthAiErrorOptions);
+    /**
+     * What may reach an end user: the code and the registry's generic message.
+     * `message` and `details` carry what a developer needs (a provider's
+     * description, a scope name) and belong in logs, not in responses.
+     */
+    toPublicJSON(): {
+        code: AuthAiErrorCode;
+        message: string;
+    };
+    toJSON(): {
+        code: AuthAiErrorCode;
+        message: string;
+        details?: AuthAiErrorDetails;
+    };
+}
+type ErrorFactory = (message?: string, options?: AuthAiErrorOptions) => AuthAiError;
+export declare const ERR: {
+    readonly CFG_001: ErrorFactory;
+    readonly OIDC_001: ErrorFactory;
+    readonly OIDC_002: ErrorFactory;
+    readonly OIDC_003: ErrorFactory;
+    readonly OIDC_004: ErrorFactory;
+    readonly TOK_001: ErrorFactory;
+    readonly TOK_002: ErrorFactory;
+    readonly TOK_003: ErrorFactory;
+    readonly TOK_004: ErrorFactory;
+    readonly API_001: ErrorFactory;
+    readonly API_002: ErrorFactory;
+    readonly GW_001: ErrorFactory;
+    readonly GW_002: ErrorFactory;
+    readonly GW_003: ErrorFactory;
+    readonly GW_004: ErrorFactory;
+    readonly GW_005: ErrorFactory;
+    readonly SES_001: ErrorFactory;
+    readonly SES_002: ErrorFactory;
+    readonly SES_003: ErrorFactory;
+    readonly SES_004: ErrorFactory;
+    readonly SES_005: ErrorFactory;
+    readonly REQ_001: ErrorFactory;
+    readonly SRV_001: ErrorFactory;
+};
+export {};

package/dist/errors.js

@@ -0,0 +1,87 @@
+const DEFAULT_MESSAGES = {
+    CFG_001: "Invalid SDK configuration",
+    OIDC_001: "Identity provider discovery failed",
+    OIDC_002: "Invalid authorization response",
+    OIDC_003: "Token request failed",
+    OIDC_004: "The identity provider does not support this operation",
+    TOK_001: "Token verification failed",
+    TOK_002: "No usable grant for this user: sign in again",
+    TOK_003: "Missing or malformed bearer credentials",
+    TOK_004: "Insufficient scope",
+    API_001: "auth-service rejected the request",
+    API_002: "Unexpected response from auth-service",
+    GW_001: "Insufficient credit: the wallet cannot pay for this call",
+    GW_002: "The gateway rate limit was reached",
+    GW_003: "The gateway refused the credentials or the resource",
+    GW_004: "The gateway is temporarily unavailable",
+    GW_005: "Unexpected response from the gateway",
+    SES_001: "Not signed in",
+    SES_002: "The sign-in attempt is missing, expired or was tampered with",
+    SES_003: "Sign-in could not be completed",
+    SES_004: "Cross-origin request refused",
+    SES_005: "Sign-in failed",
+    REQ_001: "Invalid request",
+    SRV_001: "Internal error",
+};
+export function isAuthAiErrorCode(value) {
+    return typeof value === "string" && Object.hasOwn(DEFAULT_MESSAGES, value);
+}
+/**
+ * Every failure raised by the SDK. `details` must never carry tokens, secrets
+ * or other credentials: it is meant to be logged and serialised.
+ */
+export class AuthAiError extends Error {
+    code;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "AuthAiError";
+        this.code = code;
+        this.details = options.details;
+    }
+    /**
+     * What may reach an end user: the code and the registry's generic message.
+     * `message` and `details` carry what a developer needs (a provider's
+     * description, a scope name) and belong in logs, not in responses.
+     */
+    toPublicJSON() {
+        return { code: this.code, message: DEFAULT_MESSAGES[this.code] };
+    }
+    toJSON() {
+        return this.details
+            ? { code: this.code, message: this.message, details: this.details }
+            : { code: this.code, message: this.message };
+    }
+}
+function factory(code) {
+    return (message = DEFAULT_MESSAGES[code], options) => new AuthAiError(code, message, options);
+}
+// Domain prefixes mirror auth-service: CFG_ configuration, OIDC_ protocol
+// exchanges with the identity provider, TOK_ token and grant handling, API_ calls to the auth-service REST API,
+// GW_ calls to the LiteLLM gateway, SES_ browser sessions, REQ_ invalid requests to the SDK's own routes, SRV_ unexpected
+// failures of the SDK's own HTTP handlers.
+export const ERR = {
+    CFG_001: factory("CFG_001"),
+    OIDC_001: factory("OIDC_001"),
+    OIDC_002: factory("OIDC_002"),
+    OIDC_003: factory("OIDC_003"),
+    OIDC_004: factory("OIDC_004"),
+    TOK_001: factory("TOK_001"),
+    TOK_002: factory("TOK_002"),
+    TOK_003: factory("TOK_003"),
+    TOK_004: factory("TOK_004"),
+    API_001: factory("API_001"),
+    API_002: factory("API_002"),
+    GW_001: factory("GW_001"),
+    GW_002: factory("GW_002"),
+    GW_003: factory("GW_003"),
+    GW_004: factory("GW_004"),
+    GW_005: factory("GW_005"),
+    SES_001: factory("SES_001"),
+    SES_002: factory("SES_002"),
+    SES_003: factory("SES_003"),
+    SES_004: factory("SES_004"),
+    SES_005: factory("SES_005"),
+    REQ_001: factory("REQ_001"),
+    SRV_001: factory("SRV_001"),
+};

package/dist/fastify/index.d.ts

@@ -0,0 +1,21 @@
+import type { FastifyPluginAsync, preHandlerAsyncHookHandler } from "fastify";
+import type { AuthHandlers } from "../web/handlers.js";
+import type { Session } from "../web/sessions.js";
+declare module "fastify" {
+    interface FastifyRequest {
+        /** Set by `requireAuth` and `loadSession`; null when signed out. */
+        authSession: Session | null;
+    }
+}
+export interface AuthPluginOptions {
+    readonly handlers: AuthHandlers;
+}
+/**
+ * Serves the sign-in routes below `handlers.basePath` and decorates requests
+ * with `authSession`. Register it once; protect routes with `requireAuth`.
+ */
+export declare const authPlugin: FastifyPluginAsync<AuthPluginOptions>;
+/** Answers 401 `SES_001` to signed-out requests, and sets `request.authSession` for the others. */
+export declare function requireAuth(handlers: AuthHandlers): preHandlerAsyncHookHandler;
+/** Sets `request.authSession` when signed in and leaves it null otherwise. */
+export declare function loadSession(handlers: AuthHandlers): preHandlerAsyncHookHandler;

package/dist/fastify/index.js

@@ -0,0 +1,88 @@
+import { ERR } from "../errors.js";
+import { errorResponse } from "../web/http.js";
+// A Web Request is built on the registered origin: the Host header is not trusted.
+function toWebRequest(request, origin) {
+    const path = request.raw.url ?? "/";
+    if (!path.startsWith("/"))
+        return null;
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        // HTTP/2 pseudo-headers are not valid Headers names.
+        if (name.startsWith(":") || value === undefined)
+            continue;
+        headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+    }
+    const hasBody = request.method !== "GET" && request.method !== "HEAD";
+    return new Request(`${origin}${path}`, {
+        method: request.method,
+        headers,
+        ...(hasBody && typeof request.body === "string"
+            ? { body: request.body }
+            : {}),
+    });
+}
+async function send(reply, response) {
+    reply.status(response.status);
+    for (const [name, value] of response.headers) {
+        if (name !== "set-cookie")
+            void reply.header(name, value);
+    }
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length > 0)
+        void reply.header("set-cookie", cookies);
+    const body = await response.text();
+    await (body === "" ? reply.send() : reply.send(body));
+}
+/**
+ * Serves the sign-in routes below `handlers.basePath` and decorates requests
+ * with `authSession`. Register it once; protect routes with `requireAuth`.
+ */
+export const authPlugin = async (fastify, { handlers }) => {
+    fastify.decorateRequest("authSession", null);
+    // Scoped: the back-channel endpoint receives a form, which Fastify does not parse by default,
+    // and an application's own parser must not clash with this one.
+    await fastify.register(async (scope) => {
+        scope.addContentTypeParser("application/x-www-form-urlencoded", { parseAs: "string", bodyLimit: 16_384 }, (_request, body, done) => done(null, body));
+        scope.all(`${handlers.basePath}/*`, async (request, reply) => {
+            const webRequest = toWebRequest(request, handlers.origin);
+            const response = webRequest ? await handlers.handle(webRequest) : null;
+            if (!response)
+                return reply.callNotFound();
+            return send(reply, response);
+        });
+    });
+};
+// Without it the decorator is scoped to the plugin and invisible to the application's routes.
+authPlugin[Symbol.for("skip-override")] = true;
+async function fail(reply, err) {
+    await send(reply, errorResponse(err, undefined));
+    return reply;
+}
+/** Answers 401 `SES_001` to signed-out requests, and sets `request.authSession` for the others. */
+export function requireAuth(handlers) {
+    return async (request, reply) => {
+        try {
+            const webRequest = toWebRequest(request, handlers.origin);
+            if (!webRequest)
+                throw ERR.SES_001();
+            request.authSession = await handlers.requireSession(webRequest);
+        }
+        catch (err) {
+            return fail(reply, err);
+        }
+    };
+}
+/** Sets `request.authSession` when signed in and leaves it null otherwise. */
+export function loadSession(handlers) {
+    return async (request, reply) => {
+        try {
+            const webRequest = toWebRequest(request, handlers.origin);
+            request.authSession = webRequest
+                ? await handlers.getSession(webRequest)
+                : null;
+        }
+        catch (err) {
+            return fail(reply, err);
+        }
+    };
+}

package/dist/gateway-errors.d.ts

@@ -0,0 +1,14 @@
+import { AuthAiError } from "./errors.js";
+/**
+ * Maps a failed gateway answer to the SDK registry. Branch on the status first:
+ * LiteLLM serialises the final body itself, so only the status is a contract.
+ * The message is the gateway's own and carries no credential.
+ */
+export declare function toGatewayError(status: number, body: unknown, headers?: Headers): AuthAiError;
+/** True for the error of a call refused because the wallet is empty. */
+export declare function isInsufficientCredit(err: unknown): boolean;
+/**
+ * Same test for the error of an OpenAI-compatible SDK, which exposes the HTTP
+ * status as `status`: the gateway answers 402 when the balance is zero or negative.
+ */
+export declare function isInsufficientCreditStatus(err: unknown): boolean;

package/dist/gateway-errors.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { AuthAiError, ERR } from "./errors.js";
+const gatewayErrorBodySchema = z.object({
+    error: z.object({
+        message: z.string().optional(),
+        type: z.string().optional(),
+    }),
+});
+/**
+ * Maps a failed gateway answer to the SDK registry. Branch on the status first:
+ * LiteLLM serialises the final body itself, so only the status is a contract.
+ * The message is the gateway's own and carries no credential.
+ */
+export function toGatewayError(status, body, headers) {
+    const parsed = gatewayErrorBodySchema.safeParse(body);
+    const type = parsed.success ? parsed.data.error.type : undefined;
+    const message = parsed.success ? parsed.data.error.message : undefined;
+    const details = { status };
+    if (type)
+        details["type"] = type;
+    const retryAfter = Number(headers?.get("retry-after"));
+    if (status === 429 && Number.isFinite(retryAfter) && retryAfter >= 0) {
+        details["retryAfterSeconds"] = retryAfter;
+    }
+    if (status === 402)
+        return ERR.GW_001(message, { details });
+    if (status === 429)
+        return ERR.GW_002(message, { details });
+    if (status === 401 || status === 403)
+        return ERR.GW_003(message, { details });
+    if (status === 503)
+        return ERR.GW_004(message, { details });
+    return ERR.GW_005(message ?? `The gateway answered ${status}`, { details });
+}
+/** True for the error of a call refused because the wallet is empty. */
+export function isInsufficientCredit(err) {
+    return err instanceof AuthAiError && err.code === "GW_001";
+}
+/**
+ * Same test for the error of an OpenAI-compatible SDK, which exposes the HTTP
+ * status as `status`: the gateway answers 402 when the balance is zero or negative.
+ */
+export function isInsufficientCreditStatus(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "status" in err &&
+        err.status === 402);
+}

package/dist/gateway.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const gatewayModelSchema: z.ZodObject<{
+    id: z.ZodString;
+    object: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodNumber>;
+    owned_by: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const gatewayAgentSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+    agent_name: z.ZodString;
+}, z.core.$loose>;
+export declare const gatewayMcpServerSchema: z.ZodObject<{
+    server_id: z.ZodString;
+    server_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    alias: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transport: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type GatewayModel = z.infer<typeof gatewayModelSchema>;
+export type GatewayAgent = z.infer<typeof gatewayAgentSchema>;
+export type GatewayMcpServer = z.infer<typeof gatewayMcpServerSchema>;
+/** Supplies the access token minted for the gateway audience. */
+export interface GatewayTokens {
+    getToken(): Promise<string>;
+    /** Drops the token the gateway refused, so the next call mints a fresh one. */
+    invalidate(): void;
+}
+export interface GatewayClientOptions {
+    /** Public URL of the gateway: the token audience, with no trailing slash. */
+    readonly gatewayUrl: string;
+    readonly tokens: GatewayTokens;
+    readonly fetch: typeof fetch;
+    readonly timeoutMs: number;
+}
+/**
+ * The LiteLLM gateway on behalf of a signed-in user. The user's access token
+ * is the API key: it lives one hour, so it is minted per call (and cached by
+ * the grant manager) and never stored. The gateway bills the user's wallet.
+ */
+export declare class GatewayClient {
+    #private;
+    constructor(options: GatewayClientOptions);
+    /** `baseURL` of an OpenAI-compatible SDK. */
+    get openAiBaseUrl(): string;
+    /**
+     * `fetch` that signs requests to the gateway with a fresh user token. Pass it
+     * to an OpenAI-compatible SDK together with `baseURL: openAiBaseUrl` and any
+     * placeholder `apiKey`; it refuses any other origin so the token cannot leak.
+     * A 401 drops the cached token: retrying the call mints a new one.
+     */
+    readonly fetch: typeof fetch;
+    /** A fresh access token, for clients that cannot take a custom `fetch`. */
+    getAccessToken(): Promise<string>;
+    /** The models the user's plan may call. */
+    listModels(): Promise<GatewayModel[]>;
+    /** The agents the user's plan may reach. */
+    listAgents(): Promise<GatewayAgent[]>;
+    /** The MCP servers the user's plan may reach. */
+    listMcpServers(): Promise<GatewayMcpServer[]>;
+    /**
+     * Endpoint of the gateway's MCP server, or of one registered server: connect
+     * an MCP client to it with the `Authorization: Bearer` header of
+     * `getAccessToken()`.
+     */
+    mcpUrl(serverName?: string): string;
+    /**
+     * POSTs JSON to a gateway route (`/v1/chat/completions`, `/v1/embeddings`…)
+     * and returns the parsed answer, which the caller validates. A refusal
+     * becomes a gateway error: GW_001 when the wallet cannot pay (402).
+     */
+    postJson(path: string, body: unknown): Promise<unknown>;
+}

package/dist/gateway.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { ERR } from "./errors.js";
+import { toGatewayError } from "./gateway-errors.js";
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+export const gatewayModelSchema = z.looseObject({
+    id: z.string(),
+    object: z.string().optional(),
+    created: z.number().optional(),
+    owned_by: z.string().optional(),
+});
+const modelListSchema = z.object({ data: z.array(gatewayModelSchema) });
+export const gatewayAgentSchema = z.looseObject({
+    agent_id: z.string(),
+    agent_name: z.string(),
+});
+export const gatewayMcpServerSchema = z.looseObject({
+    server_id: z.string(),
+    server_name: z.string().nullish(),
+    alias: z.string().nullish(),
+    description: z.string().nullish(),
+    transport: z.string().nullish(),
+});
+/**
+ * The LiteLLM gateway on behalf of a signed-in user. The user's access token
+ * is the API key: it lives one hour, so it is minted per call (and cached by
+ * the grant manager) and never stored. The gateway bills the user's wallet.
+ */
+export class GatewayClient {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** `baseURL` of an OpenAI-compatible SDK. */
+    get openAiBaseUrl() {
+        return `${this.#options.gatewayUrl}/v1`;
+    }
+    /**
+     * `fetch` that signs requests to the gateway with a fresh user token. Pass it
+     * to an OpenAI-compatible SDK together with `baseURL: openAiBaseUrl` and any
+     * placeholder `apiKey`; it refuses any other origin so the token cannot leak.
+     * A 401 drops the cached token: retrying the call mints a new one.
+     */
+    fetch = async (input, init) => {
+        const request = new Request(input, init);
+        if (new URL(request.url).origin !== new URL(this.#options.gatewayUrl).origin) {
+            throw ERR.CFG_001("This fetch only serves requests to the gateway");
+        }
+        request.headers.set("authorization", `Bearer ${await this.#options.tokens.getToken()}`);
+        const response = await this.#options.fetch(request);
+        if (response.status === 401)
+            this.#options.tokens.invalidate();
+        return response;
+    };
+    /** A fresh access token, for clients that cannot take a custom `fetch`. */
+    getAccessToken() {
+        return this.#options.tokens.getToken();
+    }
+    /** The models the user's plan may call. */
+    async listModels() {
+        return (await this.#getJson("/v1/models", modelListSchema)).data;
+    }
+    /** The agents the user's plan may reach. */
+    listAgents() {
+        return this.#getJson("/v1/agents", z.array(gatewayAgentSchema));
+    }
+    /** The MCP servers the user's plan may reach. */
+    listMcpServers() {
+        return this.#getJson("/v1/mcp/server", z.array(gatewayMcpServerSchema));
+    }
+    /**
+     * Endpoint of the gateway's MCP server, or of one registered server: connect
+     * an MCP client to it with the `Authorization: Bearer` header of
+     * `getAccessToken()`.
+     */
+    mcpUrl(serverName) {
+        if (serverName === undefined)
+            return `${this.#options.gatewayUrl}/mcp`;
+        if (!SERVER_NAME_PATTERN.test(serverName)) {
+            throw ERR.CFG_001("Invalid MCP server name");
+        }
+        return `${this.#options.gatewayUrl}/${serverName}/mcp`;
+    }
+    /**
+     * POSTs JSON to a gateway route (`/v1/chat/completions`, `/v1/embeddings`…)
+     * and returns the parsed answer, which the caller validates. A refusal
+     * becomes a gateway error: GW_001 when the wallet cannot pay (402).
+     */
+    async postJson(path, body) {
+        return this.#send(path, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    async #getJson(path, schema) {
+        const parsed = schema.safeParse(await this.#send(path, {}));
+        if (!parsed.success) {
+            throw ERR.GW_005(undefined, { cause: parsed.error });
+        }
+        return parsed.data;
+    }
+    async #send(path, init) {
+        const response = await this.fetch(`${this.#options.gatewayUrl}${path}`, {
+            ...init,
+            headers: { accept: "application/json", ...init.headers },
+            redirect: "error",
+            signal: AbortSignal.timeout(this.#options.timeoutMs),
+        });
+        const body = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            throw toGatewayError(response.status, body, response.headers);
+        }
+        return body;
+    }
+}

package/dist/grants.d.ts

@@ -0,0 +1,72 @@
+import type { AuthClient } from "./client.js";
+import type { TokenSet } from "./types.js";
+/**
+ * Persists the single refresh-token chain of a user. The provider rotates it
+ * on every use, so a store must hold exactly one value per grant. Encrypt it
+ * at rest: it is a long-lived credential.
+ */
+export interface GrantStore {
+    get(grantId: string): Promise<string | undefined>;
+    set(grantId: string, refreshToken: string): Promise<void>;
+    delete(grantId: string): Promise<void>;
+}
+/**
+ * Serialises the refreshes of one grant. The default lock only covers a single
+ * process: replicas need a distributed lock (or a row lock in the store).
+ */
+export interface GrantLock {
+    run<T>(grantId: string, task: () => Promise<T>): Promise<T>;
+}
+export interface AccessToken {
+    readonly accessToken: string;
+    /** Unix seconds. */
+    readonly expiresAt: number;
+}
+export interface GrantManagerOptions {
+    readonly auth: Pick<AuthClient, "refresh" | "revoke">;
+    readonly store: GrantStore;
+    readonly lock?: GrantLock;
+    /** A cached access token is renewed this long before it expires. */
+    readonly expirySkewSeconds?: number;
+}
+export declare class MemoryGrantStore implements GrantStore {
+    #private;
+    get(grantId: string): Promise<string | undefined>;
+    set(grantId: string, refreshToken: string): Promise<void>;
+    delete(grantId: string): Promise<void>;
+}
+export declare class InProcessGrantLock implements GrantLock {
+    #private;
+    run<T>(grantId: string, task: () => Promise<T>): Promise<T>;
+}
+/**
+ * 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 declare class GrantManager {
+    #private;
+    constructor(options: GrantManagerOptions);
+    /** Stores the refresh token obtained at sign-in, replacing any older chain. */
+    save(grantId: string, refreshToken: string): Promise<void>;
+    has(grantId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    getAccessToken(grantId: string, options?: {
+        readonly resource?: string;
+    }): Promise<AccessToken>;
+    /**
+     * 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`.
+     */
+    refreshTokens(grantId: string): Promise<TokenSet>;
+    /** Drops a cached access token the API refused, so the next call mints a fresh one. */
+    invalidate(grantId: string, resource?: string): void;
+    /** Revokes the refresh token at the provider, then forgets the grant. */
+    revoke(grantId: string): Promise<void>;
+}
+export declare function createGrantManager(options: GrantManagerOptions): GrantManager;