@numa-tech/numa 1.11.10

package/dist/oauth.d.ts

@@ -0,0 +1,30 @@
+import type { AuthConfig } from "./config.js";
+import type { LoginSession, OidcDiscovery, TokenCache } from "./types.js";
+export declare class AuthError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export declare class LoginRequiredError extends AuthError {
+    constructor(message?: string);
+}
+export declare function nowSeconds(): number;
+export declare function loadDiscovery(config: AuthConfig): Promise<OidcDiscovery>;
+export declare function readTokenCache(config: AuthConfig): Promise<TokenCache | undefined>;
+export declare function deleteTokenCache(config: AuthConfig): Promise<void>;
+export declare function getUserinfo(config: AuthConfig, discovery: OidcDiscovery, accessToken: string): Promise<Record<string, unknown>>;
+export declare function refreshAccessToken(config: AuthConfig, cache: TokenCache): Promise<TokenCache>;
+export declare function ensureAccessToken(config: AuthConfig, forceRefresh?: boolean): Promise<string>;
+export type KeycloakTokenProvider = (config: AuthConfig, forceRefresh?: boolean) => Promise<string>;
+export interface KeycloakFetchDependencies {
+    fetch?: typeof fetch;
+    tokenProvider?: KeycloakTokenProvider;
+}
+export declare function fetchWithKeycloakIdentity(config: AuthConfig, url: string, requestFactory: () => RequestInit, dependencies?: KeycloakFetchDependencies): Promise<Response>;
+export declare function whoami(config: AuthConfig, forceRefresh?: boolean): Promise<Record<string, unknown>>;
+export interface BrowserLoginOptions {
+    successRedirectUrl?: string;
+    failureRedirectUrl?: string;
+}
+export declare function startBrowserLogin(config: AuthConfig, options?: BrowserLoginOptions): Promise<LoginSession>;
+export declare function completeBrowserLogin(config: AuthConfig, session: LoginSession): Promise<Record<string, unknown>>;
+export declare function blockingBrowserLogin(config: AuthConfig, options?: BrowserLoginOptions): Promise<Record<string, unknown>>;

package/dist/oauth.js

@@ -0,0 +1,295 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { dirname } from "node:path";
+import open from "open";
+import { redirectUri } from "./config.js";
+const REFRESH_LEEWAY_SECONDS = 60;
+const LOGIN_SESSION_TTL_SECONDS = 300;
+export class AuthError extends Error {
+    code;
+    constructor(message, code = "auth_error") {
+        super(message);
+        this.code = code;
+    }
+}
+export class LoginRequiredError extends AuthError {
+    constructor(message = "No usable Keycloak login is available.") {
+        super(message, "login_required");
+    }
+}
+export function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+async function parseJsonResponse(response, url) {
+    const text = await response.text();
+    let parsed = {};
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { raw: text };
+        }
+    }
+    if (!response.ok) {
+        const body = parsed;
+        const detail = body.error_description ?? body.error ?? body.raw ?? response.statusText;
+        throw new AuthError(`HTTP ${response.status} from ${url}: ${String(detail)}`, "http_error");
+    }
+    return parsed;
+}
+async function requestJson(url, init) {
+    const response = await fetch(url, {
+        ...init,
+        headers: {
+            Accept: "application/json",
+            ...(init?.body ? { "Content-Type": "application/x-www-form-urlencoded" } : {}),
+            ...(init?.headers ?? {})
+        }
+    });
+    return parseJsonResponse(response, url);
+}
+function formBody(values) {
+    const body = new URLSearchParams();
+    for (const [key, value] of Object.entries(values)) {
+        if (value != null && value !== "")
+            body.set(key, value);
+    }
+    return body;
+}
+function addClientAuth(config, values) {
+    return formBody({
+        ...values,
+        client_id: config.clientId,
+        client_secret: config.clientSecret
+    });
+}
+export async function loadDiscovery(config) {
+    return requestJson(config.discoveryUrl);
+}
+function pkcePair() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+async function writeTokenCache(path, cache) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+    await rename(tmp, path);
+}
+export async function readTokenCache(config) {
+    try {
+        const raw = await readFile(config.tokenFile, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function deleteTokenCache(config) {
+    await rm(config.tokenFile, { force: true });
+}
+async function saveToken(config, discovery, token, userinfo, existingRefreshExpiresAt) {
+    const obtainedAt = nowSeconds();
+    const expiresAt = obtainedAt + (token.expires_in ?? 0);
+    const refreshExpiresAt = token.refresh_expires_in && token.refresh_expires_in > 0
+        ? obtainedAt + token.refresh_expires_in
+        : existingRefreshExpiresAt;
+    const cache = {
+        issuer: discovery.issuer,
+        discoveryUrl: config.discoveryUrl,
+        clientId: config.clientId,
+        scope: token.scope ?? config.scope,
+        obtainedAt,
+        expiresAt,
+        refreshExpiresAt,
+        token,
+        userinfo
+    };
+    await writeTokenCache(config.tokenFile, cache);
+    return cache;
+}
+export async function getUserinfo(config, discovery, accessToken) {
+    return requestJson(discovery.userinfo_endpoint, {
+        headers: { Authorization: `Bearer ${accessToken}` }
+    });
+}
+export async function refreshAccessToken(config, cache) {
+    if (!cache.token.refresh_token) {
+        throw new LoginRequiredError("Saved token has no refresh token. Start login again.");
+    }
+    const discovery = await loadDiscovery(config);
+    const refreshed = await requestJson(discovery.token_endpoint, {
+        method: "POST",
+        body: addClientAuth(config, {
+            grant_type: "refresh_token",
+            refresh_token: cache.token.refresh_token
+        })
+    });
+    const token = {
+        ...refreshed,
+        // Some OIDC servers reuse the existing refresh token instead of returning
+        // it again. Keep it until the server explicitly rejects the refresh grant.
+        refresh_token: refreshed.refresh_token ?? cache.token.refresh_token
+    };
+    const userinfo = await getUserinfo(config, discovery, token.access_token);
+    return saveToken(config, discovery, token, userinfo, cache.refreshExpiresAt);
+}
+export async function ensureAccessToken(config, forceRefresh = false) {
+    let cache = await readTokenCache(config);
+    if (!cache)
+        throw new LoginRequiredError("No token cache exists. Start login first.");
+    if (cache.discoveryUrl !== config.discoveryUrl || cache.clientId !== config.clientId) {
+        throw new LoginRequiredError("Token cache was created for a different Keycloak discovery URL or client.");
+    }
+    if (forceRefresh || cache.expiresAt <= nowSeconds() + REFRESH_LEEWAY_SECONDS) {
+        cache = await refreshAccessToken(config, cache);
+    }
+    return cache.token.access_token;
+}
+export async function fetchWithKeycloakIdentity(config, url, requestFactory, dependencies = {}) {
+    const fetchImpl = dependencies.fetch ?? fetch;
+    const tokenProvider = dependencies.tokenProvider ?? ensureAccessToken;
+    const send = async (forceRefresh) => {
+        const token = await tokenProvider(config, forceRefresh);
+        const init = requestFactory();
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${token}`);
+        return fetchImpl(url, { ...init, headers });
+    };
+    let response = await send(false);
+    if (response.status === 401) {
+        await response.body?.cancel().catch(() => undefined);
+        response = await send(true);
+    }
+    return response;
+}
+export async function whoami(config, forceRefresh = false) {
+    const discovery = await loadDiscovery(config);
+    if (forceRefresh)
+        await ensureAccessToken(config, true);
+    const response = await fetchWithKeycloakIdentity(config, discovery.userinfo_endpoint, () => ({ headers: { Accept: "application/json" } }));
+    const info = await parseJsonResponse(response, discovery.userinfo_endpoint);
+    const cache = await readTokenCache(config);
+    if (cache)
+        await writeTokenCache(config.tokenFile, { ...cache, userinfo: info });
+    return info;
+}
+export async function startBrowserLogin(config, options = {}) {
+    const discovery = await loadDiscovery(config);
+    const { verifier, challenge } = pkcePair();
+    const state = randomBytes(24).toString("base64url");
+    const callback = redirectUri(config);
+    const id = randomUUID();
+    let server;
+    const session = {
+        id,
+        authorizationUrl: "",
+        redirectUri: callback,
+        codeVerifier: verifier,
+        state,
+        createdAt: nowSeconds(),
+        expiresAt: nowSeconds() + LOGIN_SESSION_TTL_SECONDS,
+        close: async () => {
+            if (!server)
+                return;
+            await new Promise((resolve, reject) => {
+                server?.close((error) => (error ? reject(error) : resolve()));
+            });
+            server = undefined;
+        }
+    };
+    const authUrl = new URL(discovery.authorization_endpoint);
+    authUrl.searchParams.set("client_id", config.clientId);
+    authUrl.searchParams.set("redirect_uri", callback);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("scope", config.scope);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    session.authorizationUrl = authUrl.toString();
+    server = createServer((request, response) => {
+        const requestUrl = new URL(request.url ?? "/", callback);
+        if (requestUrl.pathname !== config.redirectPath) {
+            response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            response.end("Not found\n");
+            return;
+        }
+        const returnedState = requestUrl.searchParams.get("state");
+        if (returnedState !== state) {
+            session.error = "State mismatch";
+        }
+        else if (requestUrl.searchParams.get("error")) {
+            session.error = requestUrl.searchParams.get("error_description") ?? requestUrl.searchParams.get("error") ?? "Login failed";
+        }
+        else {
+            session.code = requestUrl.searchParams.get("code") ?? undefined;
+        }
+        const redirect = session.code ? options.successRedirectUrl : options.failureRedirectUrl;
+        if (redirect) {
+            response.writeHead(303, {
+                Location: redirect,
+                "Cache-Control": "no-store",
+                "Referrer-Policy": "no-referrer"
+            });
+            response.end();
+            return;
+        }
+        response.writeHead(session.code ? 200 : 400, {
+            "Content-Type": "text/plain; charset=utf-8",
+            "Cache-Control": "no-store"
+        });
+        response.end(session.code ? "Login complete. You may close this tab.\n" : `Login failed: ${session.error}\n`);
+    });
+    await new Promise((resolve, reject) => {
+        server?.once("error", reject);
+        server?.listen(config.redirectPort, config.redirectHost, () => resolve());
+    });
+    if (config.openBrowser) {
+        await open(session.authorizationUrl).catch(() => undefined);
+    }
+    return session;
+}
+export async function completeBrowserLogin(config, session) {
+    if (session.error)
+        throw new AuthError(session.error, "login_failed");
+    if (!session.code) {
+        if (session.expiresAt <= nowSeconds()) {
+            await session.close();
+            throw new AuthError("Login session expired before callback was received.", "login_expired");
+        }
+        throw new AuthError("Login callback has not been received yet.", "login_pending");
+    }
+    const discovery = await loadDiscovery(config);
+    const token = await requestJson(discovery.token_endpoint, {
+        method: "POST",
+        body: addClientAuth(config, {
+            grant_type: "authorization_code",
+            code: session.code,
+            redirect_uri: session.redirectUri,
+            code_verifier: session.codeVerifier
+        })
+    });
+    const info = await getUserinfo(config, discovery, token.access_token);
+    await saveToken(config, discovery, token, info);
+    await session.close();
+    return info;
+}
+export async function blockingBrowserLogin(config, options = {}) {
+    const session = await startBrowserLogin(config, options);
+    process.stderr.write(`Open this URL to log in:\n${session.authorizationUrl}\n`);
+    try {
+        while (!session.code && !session.error && session.expiresAt > nowSeconds()) {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        return await completeBrowserLogin(config, session);
+    }
+    finally {
+        await session.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/private-file.d.ts

@@ -0,0 +1,3 @@
+export declare function writePrivateText(path: string, content: string): Promise<void>;
+export declare function writePrivateJson(path: string, value: unknown): Promise<void>;
+export declare function readJsonIfExists(path: string): Promise<unknown | undefined>;

package/dist/private-file.js

@@ -0,0 +1,51 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const RETRYABLE_CODES = new Set(["EACCES", "EBUSY", "EAGAIN", "EPERM"]);
+function isRetryable(error) {
+    const code = error?.code;
+    return typeof code === "string" && RETRYABLE_CODES.has(code);
+}
+async function renameWithRetry(source, destination) {
+    let lastError;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+            await rename(source, destination);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryable(error) || attempt === 4)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 10 * 2 ** attempt));
+        }
+    }
+    throw lastError;
+}
+export async function writePrivateText(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+        await renameWithRetry(temporaryPath, path);
+        if (process.platform !== "win32")
+            await chmod(path, 0o600);
+    }
+    finally {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+export async function writePrivateJson(path, value) {
+    await writePrivateText(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function readJsonIfExists(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=private-file.js.map

package/dist/private-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-file.js","sourceRoot":"","sources":["../src/private-file.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,197 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { authenticatedBackendRequest } from "./backend.js";
+import { CLI_NAME, PACKAGE_VERSION, PRODUCT_NAME } from "./branding.js";
+import { COMMAND_CATALOG } from "./command-catalog.js";
+import { loadConfig } from "./config.js";
+import { currentIdentity, requireAnyRole, RoleRequiredError } from "./identity.js";
+import { AuthError, completeBrowserLogin, deleteTokenCache, readTokenCache, startBrowserLogin } from "./oauth.js";
+const sessions = new Map();
+function textResult(text, structuredContent, isError = false) {
+    return {
+        isError,
+        content: [{ type: "text", text }],
+        ...(structuredContent ? { structuredContent } : {})
+    };
+}
+function jsonResult(value) {
+    return textResult(JSON.stringify(value, null, 2), value);
+}
+function errorResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof AuthError || error instanceof RoleRequiredError ? error.code : "error";
+    return textResult(`Error: ${message}`, { ok: false, code, message }, true);
+}
+export function createServer() {
+    const server = new McpServer({
+        name: `${CLI_NAME}-platform-cli`,
+        version: PACKAGE_VERSION
+    });
+    server.registerTool("numa_command_catalog", {
+        title: `Get ${PRODUCT_NAME} CLI Command Catalog`,
+        description: "List CLI commands, authentication requirements, required roles, and examples for AI clients.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async () => jsonResult({ schema_version: 1, commands: COMMAND_CATALOG }));
+    server.registerTool("numa_auth_status", {
+        title: `Get ${PRODUCT_NAME} Auth Status`,
+        description: "Inspect local Keycloak authentication cache status without exposing tokens.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async () => {
+        try {
+            const config = loadConfig();
+            const cache = await readTokenCache(config);
+            return jsonResult({
+                logged_in: Boolean(cache),
+                token_file: config.tokenFile,
+                discovery_url: config.discoveryUrl,
+                client_id: config.clientId,
+                expires_at: cache?.expiresAt,
+                refresh_expires_at: cache?.refreshExpiresAt,
+                cached_user: cache?.userinfo
+            });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("numa_auth_start_login", {
+        title: `Start ${PRODUCT_NAME} Keycloak Login`,
+        description: "Start local browser-based Keycloak PKCE login. Returns an authorization URL and login_session_id; never returns tokens.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async () => {
+        try {
+            const session = await startBrowserLogin(loadConfig());
+            sessions.set(session.id, session);
+            return jsonResult({
+                login_session_id: session.id,
+                authorization_url: session.authorizationUrl,
+                redirect_uri: session.redirectUri,
+                expires_at: session.expiresAt,
+                instruction: "Open authorization_url in a browser, complete login, then call numa_auth_complete_login."
+            });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("numa_auth_complete_login", {
+        title: `Complete ${PRODUCT_NAME} Keycloak Login`,
+        description: "Complete a browser login after the local callback is received and save the token cache. Returns user identity, not tokens.",
+        inputSchema: {
+            login_session_id: z.string().min(1).describe("Session ID returned by numa_auth_start_login")
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async ({ login_session_id }) => {
+        try {
+            const session = sessions.get(login_session_id);
+            if (!session)
+                throw new AuthError("Unknown login_session_id.", "unknown_login_session");
+            const info = await completeBrowserLogin(loadConfig(), session);
+            sessions.delete(login_session_id);
+            return jsonResult({ ok: true, user: info });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("numa_auth_whoami", {
+        title: `Get Current ${PRODUCT_NAME} User`,
+        description: "Return the current Keycloak user identity from the userinfo endpoint. Refreshes saved access token if needed; never returns tokens.",
+        inputSchema: {
+            force_refresh: z.boolean().default(false).describe("Force refresh before reading userinfo")
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async ({ force_refresh }) => {
+        try {
+            const identity = await currentIdentity(loadConfig(), force_refresh);
+            const { raw: _raw, ...safeIdentity } = identity;
+            return jsonResult({ user: safeIdentity });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("numa_auth_logout", {
+        title: `Clear Local ${PRODUCT_NAME} Login`,
+        description: "Delete the local Keycloak token cache. This does not revoke server-side Keycloak sessions.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async () => {
+        try {
+            const config = loadConfig();
+            await deleteTokenCache(config);
+            return jsonResult({ ok: true, token_file: config.tokenFile });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("numa_backend_request", {
+        title: `Call ${PRODUCT_NAME} Backend With Keycloak Auth`,
+        description: "Proxy an HTTP request to a configured Numa backend and inject the saved Keycloak bearer token internally. Does not expose tokens.",
+        inputSchema: {
+            method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+            path: z.string().optional().describe("Backend path resolved against NUMA_BACKEND_BASE_URL"),
+            url: z.string().url().optional().describe("Absolute URL; disabled unless NUMA_BACKEND_ALLOW_ABSOLUTE_URLS=true"),
+            headers: z.record(z.string(), z.string()).optional().describe("Extra headers except Authorization"),
+            body: z.unknown().optional().describe("JSON-serializable request body or string"),
+            required_roles: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Require at least one Keycloak realm/client role before the request")
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (input) => {
+        try {
+            const { headers, required_roles, ...rest } = input;
+            if (required_roles?.length)
+                await requireAnyRole(loadConfig(), required_roles);
+            const safeHeaders = Object.fromEntries(Object.entries(headers ?? {}).filter(([key]) => key.toLowerCase() !== "authorization"));
+            const response = await authenticatedBackendRequest(loadConfig(), { ...rest, headers: safeHeaders });
+            return jsonResult({ ok: response.status >= 200 && response.status < 300, response });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+export interface OidcDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    device_authorization_endpoint?: string;
+    end_session_endpoint?: string;
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    refresh_expires_in?: number;
+    id_token?: string;
+    scope?: string;
+}
+export interface TokenCache {
+    issuer: string;
+    discoveryUrl: string;
+    clientId: string;
+    scope: string;
+    obtainedAt: number;
+    expiresAt: number;
+    refreshExpiresAt?: number;
+    token: TokenResponse;
+    userinfo?: Record<string, unknown>;
+}
+export interface LoginSession {
+    id: string;
+    authorizationUrl: string;
+    redirectUri: string;
+    codeVerifier: string;
+    state: string;
+    createdAt: number;
+    expiresAt: number;
+    code?: string;
+    error?: string;
+    close: () => Promise<void>;
+}