@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/auth/auth-flow.js

@@ -0,0 +1,189 @@
+/**
+ * PKCE auth flow orchestration.
+ *
+ * Drives the public-client OAuth dance: spawns a loopback HTTP server on
+ * 127.0.0.1, asks WorkOS for an authorize URL bound to that server's
+ * dynamic port, opens the user's browser at AuthKit, and waits for the
+ * callback. On callback, the returned `state` is checked against the SDK-
+ * generated value and the `code` is exchanged for `{ user, accessToken,
+ * refreshToken }` via `authenticateWithCode` with the stored `codeVerifier`.
+ *
+ * No part of this module touches `~/.interf/auth/*`. Callers (CLI today,
+ * desktop shell later) take the returned tokens and decide what to persist.
+ *
+ * The `transport` seam lets tests stand in for the WorkOS SDK without env
+ * config or live HTTP. Production callers use `defaultPkceTransport()`.
+ */
+import { createServer } from "node:http";
+import { URL } from "node:url";
+import open from "open";
+import { getWorkOS, workosConfig } from "./workos-client.js";
+/** Five minutes — generous enough for SSO redirects, short enough to bound
+ *  a hung browser session. Tests pass a tighter timeout. */
+const DEFAULT_CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_CALLBACK_HOST = "127.0.0.1";
+export class AuthFlowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthFlowError";
+    }
+}
+/**
+ * Default transport — proxies to the real WorkOS SDK. Lazy-loads the
+ * singleton client on first call so importing this module does not require
+ * env config.
+ */
+export function defaultPkceTransport() {
+    return {
+        getAuthorizationUrlWithPKCE: (input) => getWorkOS().userManagement.getAuthorizationUrlWithPKCE(input),
+        authenticateWithCode: (input) => getWorkOS().userManagement.authenticateWithCode(input),
+    };
+}
+/**
+ * Run the full PKCE flow end-to-end. Returns the WorkOS tokens + user.
+ * Always closes the loopback server before returning, even on error.
+ */
+export async function runPkceFlow(transport, options = {}) {
+    const callbackHost = options.callbackHost ?? DEFAULT_CALLBACK_HOST;
+    const callbackPort = options.callbackPort ?? 0;
+    const autoOpenBrowser = options.autoOpenBrowser ?? true;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS;
+    const cfg = workosConfig();
+    const bound = await bindCallbackServer(callbackHost, callbackPort, timeoutMs);
+    const { server, port, callbackPromise, close } = bound;
+    const redirectUri = `http://${callbackHost}:${port}/callback`;
+    try {
+        const authorize = await transport.getAuthorizationUrlWithPKCE({
+            provider: "authkit",
+            redirectUri,
+            clientId: cfg.clientId,
+            ...(options.loginHint ? { loginHint: options.loginHint } : {}),
+        });
+        if (options.onAuthorizeUrl) {
+            await options.onAuthorizeUrl(authorize.url, redirectUri);
+        }
+        if (autoOpenBrowser) {
+            try {
+                await open(authorize.url);
+            }
+            catch {
+                // Browser launch failed — fall back to print so the user can copy.
+                console.log(`\nOpen this URL to sign in:\n  ${authorize.url}\n`);
+            }
+        }
+        else {
+            console.log(`\nOpen this URL to sign in:\n  ${authorize.url}\n`);
+        }
+        const callback = await callbackPromise;
+        if (callback.state !== authorize.state) {
+            throw new AuthFlowError("State mismatch on auth callback — possible CSRF. Re-run `interf auth login`.");
+        }
+        const result = await transport.authenticateWithCode({
+            code: callback.code,
+            codeVerifier: authorize.codeVerifier,
+            clientId: cfg.clientId,
+        });
+        return result;
+    }
+    finally {
+        server.removeAllListeners();
+        await close();
+    }
+}
+function bindCallbackServer(host, port, timeoutMs) {
+    return new Promise((resolveBind, rejectBind) => {
+        let resolveCallback = () => { };
+        let rejectCallback = () => { };
+        const callbackPromise = new Promise((res, rej) => {
+            resolveCallback = res;
+            rejectCallback = rej;
+        });
+        // The server handler can reject the callback promise BEFORE the outer
+        // `await callbackPromise` runs (provider error / missing code path).
+        // Attach a noop handler so node's unhandled-rejection detector does not
+        // flag those rejections during the brief window between `rejectCallback`
+        // firing and the `await` later in `runPkceFlow`. The actual rejection
+        // still propagates when the original promise is awaited.
+        callbackPromise.catch(() => { });
+        const server = createServer((req, res) => {
+            const reqUrl = new URL(req.url ?? "/", `http://${host}:${port}`);
+            if (reqUrl.pathname !== "/callback") {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("Not found\n");
+                return;
+            }
+            const error = reqUrl.searchParams.get("error");
+            const errorDescription = reqUrl.searchParams.get("error_description");
+            if (error) {
+                const detail = errorDescription ? `${error}: ${errorDescription}` : error;
+                res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                res.end(callbackHtml("Sign-in failed", detail));
+                rejectCallback(new AuthFlowError(`provider returned error: ${detail}`));
+                return;
+            }
+            const code = reqUrl.searchParams.get("code");
+            const state = reqUrl.searchParams.get("state");
+            if (!code || !state) {
+                res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                res.end(callbackHtml("Sign-in failed", "Callback missing code or state."));
+                rejectCallback(new AuthFlowError("callback missing code or state"));
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(callbackHtml("Signed in to Interf", "You can close this window and return to your terminal."));
+            resolveCallback({ code, state });
+        });
+        const timeout = setTimeout(() => {
+            rejectCallback(new AuthFlowError(`Timed out waiting for auth callback after ${Math.round(timeoutMs / 1000)}s.`));
+        }, timeoutMs);
+        timeout.unref();
+        const close = () => new Promise((closed) => {
+            clearTimeout(timeout);
+            server.close(() => closed());
+        });
+        server.once("error", (error) => {
+            clearTimeout(timeout);
+            rejectBind(error);
+        });
+        server.listen(port, host, () => {
+            const address = server.address();
+            const actualPort = address && typeof address === "object" ? address.port : port;
+            resolveBind({ server, port: actualPort, callbackPromise, close });
+        });
+    });
+}
+function callbackHtml(title, body) {
+    const safeTitle = escapeHtml(title);
+    const safeBody = escapeHtml(body);
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>${safeTitle} — Interf</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; background: #fafaf9;
+           color: #1f2937; display: grid; place-items: center; height: 100vh;
+           margin: 0; padding: 1.5rem; }
+    .card { background: #fff; border: 1px solid #e5e7eb; border-radius: 12px;
+            padding: 2rem 2.25rem; max-width: 28rem; box-shadow: 0 1px 2px rgba(0,0,0,0.04); }
+    h1 { font-size: 1.125rem; margin: 0 0 0.5rem; }
+    p { margin: 0; color: #4b5563; line-height: 1.5; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>${safeTitle}</h1>
+    <p>${safeBody}</p>
+  </div>
+</body>
+</html>
+`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}

package/dist/packages/runtime/auth/jwt-validator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Access-token validation for the cloud engine binding.
+ *
+ * The loopback engine never calls this — its security boundary is the
+ * loopback bind + CORS allowlist + per-instance hex bearer in
+ * `isAuthorizedMutation`. The cloud variant runs `authMode: "jwt"` and
+ * requires `Authorization: Bearer <jwt>` on every mutating request.
+ *
+ * Validation uses `jose`'s `createRemoteJWKSet`, which fetches the WorkOS
+ * JWKS document, caches it in-process, and rotates keys when WorkOS
+ * publishes new ones. Verification covers signature, `exp`, and (optionally)
+ * `iss`. Audience is not pinned by WorkOS access tokens.
+ */
+import { jwtVerify } from "jose";
+/**
+ * Whatever jose accepts as its second `jwtVerify` argument — a
+ * `createRemoteJWKSet` function, a `createLocalJWKSet` function, a
+ * `CryptoKey`, or a `Uint8Array`. Tests inject the local variant; production
+ * uses the remote one.
+ */
+type JwtKeyResolver = Parameters<typeof jwtVerify>[1];
+export interface ValidatedAccessToken {
+    /** WorkOS user id (`user_01...`). */
+    sub: string;
+    /** Session id, when present in the token. */
+    sid: string | null;
+    /** Email, when included by AuthKit. */
+    email: string | null;
+    /** Organization id, when the access token is org-scoped. */
+    orgId: string | null;
+    /** Role string, when included. */
+    role: string | null;
+    /** Permissions list, when included. */
+    permissions: ReadonlyArray<string>;
+    /** Unix expiry (seconds). */
+    exp: number;
+    /** Unix issued-at (seconds). */
+    iat: number;
+}
+export declare class JwtValidationError extends Error {
+    constructor(message: string);
+}
+/** Reset cached JWKS resolver. Test seam. */
+export declare function resetJwtCache(): void;
+/**
+ * Inject a custom JWKS resolver (tests). Pass `null` to restore lazy init
+ * from the live WorkOS SDK.
+ */
+export declare function setJwksResolverForTests(resolver: JwtKeyResolver | null): void;
+/**
+ * Verify a WorkOS access token. Throws JwtValidationError on any failure
+ * (bad signature, expired, malformed). On success returns the claims we
+ * care about flattened into a stable shape.
+ */
+export declare function validateAccessToken(token: string): Promise<ValidatedAccessToken>;
+/** The JWKS URL the validator is currently bound to. Debug / observability. */
+export declare function currentJwksUrl(): string | null;
+export {};

package/dist/packages/runtime/auth/jwt-validator.js

@@ -0,0 +1,86 @@
+/**
+ * Access-token validation for the cloud engine binding.
+ *
+ * The loopback engine never calls this — its security boundary is the
+ * loopback bind + CORS allowlist + per-instance hex bearer in
+ * `isAuthorizedMutation`. The cloud variant runs `authMode: "jwt"` and
+ * requires `Authorization: Bearer <jwt>` on every mutating request.
+ *
+ * Validation uses `jose`'s `createRemoteJWKSet`, which fetches the WorkOS
+ * JWKS document, caches it in-process, and rotates keys when WorkOS
+ * publishes new ones. Verification covers signature, `exp`, and (optionally)
+ * `iss`. Audience is not pinned by WorkOS access tokens.
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { getWorkOS, workosConfig } from "./workos-client.js";
+export class JwtValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JwtValidationError";
+    }
+}
+let cachedResolver = null;
+let cachedJwksUrl = null;
+/** Reset cached JWKS resolver. Test seam. */
+export function resetJwtCache() {
+    cachedResolver = null;
+    cachedJwksUrl = null;
+}
+/**
+ * Inject a custom JWKS resolver (tests). Pass `null` to restore lazy init
+ * from the live WorkOS SDK.
+ */
+export function setJwksResolverForTests(resolver) {
+    if (resolver === null) {
+        cachedResolver = null;
+        cachedJwksUrl = null;
+        return;
+    }
+    cachedResolver = resolver;
+    cachedJwksUrl = "test://jwks";
+}
+function getResolver() {
+    if (cachedResolver)
+        return cachedResolver;
+    const cfg = workosConfig();
+    const jwksUrl = getWorkOS().userManagement.getJwksUrl(cfg.clientId);
+    cachedResolver = createRemoteJWKSet(new URL(jwksUrl));
+    cachedJwksUrl = jwksUrl;
+    return cachedResolver;
+}
+/**
+ * Verify a WorkOS access token. Throws JwtValidationError on any failure
+ * (bad signature, expired, malformed). On success returns the claims we
+ * care about flattened into a stable shape.
+ */
+export async function validateAccessToken(token) {
+    const resolver = getResolver();
+    let payload;
+    try {
+        const result = await jwtVerify(token, resolver);
+        payload = result.payload;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new JwtValidationError(`access token rejected: ${message}`);
+    }
+    if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+        throw new JwtValidationError("access token missing `sub` claim");
+    }
+    return {
+        sub: payload.sub,
+        sid: typeof payload.sid === "string" ? payload.sid : null,
+        email: typeof payload.email === "string" ? payload.email : null,
+        orgId: typeof payload.org_id === "string" ? payload.org_id : null,
+        role: typeof payload.role === "string" ? payload.role : null,
+        permissions: Array.isArray(payload.permissions)
+            ? payload.permissions.filter((value) => typeof value === "string")
+            : [],
+        exp: typeof payload.exp === "number" ? payload.exp : 0,
+        iat: typeof payload.iat === "number" ? payload.iat : 0,
+    };
+}
+/** The JWKS URL the validator is currently bound to. Debug / observability. */
+export function currentJwksUrl() {
+    return cachedJwksUrl;
+}

package/dist/packages/runtime/auth/keychain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Refresh-token storage backed by the system keychain.
+ *
+ * On macOS this lands in the user's Keychain; on Linux it uses libsecret /
+ * gnome-keyring; on Windows it uses the Credential Vault. The native
+ * `keytar` binding is loaded lazily so importing this module from contexts
+ * that never touch the keychain (the loopback engine, tests, CI) does not
+ * pay the dlopen cost.
+ *
+ * When the native binding fails to load (uncommon: corrupt prebuild, exotic
+ * platform, headless CI without libsecret), the in-memory fallback adapter
+ * keeps the auth flow alive for the current process. The user is warned —
+ * tokens won't survive a restart.
+ */
+export interface KeychainAdapter {
+    setPassword(account: string, password: string): Promise<void>;
+    getPassword(account: string): Promise<string | null>;
+    deletePassword(account: string): Promise<boolean>;
+}
+/**
+ * Inject a custom adapter (tests). Pass `null` to restore lazy init.
+ */
+export declare function setKeychainAdapterForTests(adapter: KeychainAdapter | null): void;
+/**
+ * Resolve the active adapter. Tries `keytar` first; falls back to an
+ * in-memory map on platforms where the native binding fails to load,
+ * with a one-time warning.
+ */
+export declare function getKeychainAdapter(): Promise<KeychainAdapter>;
+/** Persist a refresh token keyed on user_id. */
+export declare function setRefreshToken(userId: string, token: string): Promise<void>;
+/** Read a refresh token by user_id, or null if none is stored. */
+export declare function getRefreshToken(userId: string): Promise<string | null>;
+/** Remove a refresh token. Idempotent — returns false if nothing was stored. */
+export declare function deleteRefreshToken(userId: string): Promise<boolean>;

package/dist/packages/runtime/auth/keychain.js

@@ -0,0 +1,85 @@
+/**
+ * Refresh-token storage backed by the system keychain.
+ *
+ * On macOS this lands in the user's Keychain; on Linux it uses libsecret /
+ * gnome-keyring; on Windows it uses the Credential Vault. The native
+ * `keytar` binding is loaded lazily so importing this module from contexts
+ * that never touch the keychain (the loopback engine, tests, CI) does not
+ * pay the dlopen cost.
+ *
+ * When the native binding fails to load (uncommon: corrupt prebuild, exotic
+ * platform, headless CI without libsecret), the in-memory fallback adapter
+ * keeps the auth flow alive for the current process. The user is warned —
+ * tokens won't survive a restart.
+ */
+const KEYCHAIN_SERVICE = "interf";
+/** Account-key prefix for refresh tokens. Distinguishes them from any future
+ *  Vault entries (API keys, signing keys) we might also store. */
+const REFRESH_TOKEN_PREFIX = "refresh:";
+let cachedAdapter = null;
+let warnedAboutFallback = false;
+/**
+ * Inject a custom adapter (tests). Pass `null` to restore lazy init.
+ */
+export function setKeychainAdapterForTests(adapter) {
+    cachedAdapter = adapter;
+    warnedAboutFallback = false;
+}
+/**
+ * Resolve the active adapter. Tries `keytar` first; falls back to an
+ * in-memory map on platforms where the native binding fails to load,
+ * with a one-time warning.
+ */
+export async function getKeychainAdapter() {
+    if (cachedAdapter)
+        return cachedAdapter;
+    try {
+        const keytar = await import("keytar");
+        cachedAdapter = {
+            setPassword: (account, password) => keytar.setPassword(KEYCHAIN_SERVICE, account, password),
+            getPassword: (account) => keytar.getPassword(KEYCHAIN_SERVICE, account),
+            deletePassword: (account) => keytar.deletePassword(KEYCHAIN_SERVICE, account),
+        };
+        return cachedAdapter;
+    }
+    catch (error) {
+        if (!warnedAboutFallback) {
+            const reason = error instanceof Error ? error.message : String(error);
+            console.warn(`[interf auth] keychain unavailable (${reason}); ` +
+                "refresh tokens will not persist across restarts. " +
+                "Re-run `interf auth login` after the engine restarts.");
+            warnedAboutFallback = true;
+        }
+        cachedAdapter = createInMemoryAdapter();
+        return cachedAdapter;
+    }
+}
+function createInMemoryAdapter() {
+    const store = new Map();
+    return {
+        async setPassword(account, password) {
+            store.set(account, password);
+        },
+        async getPassword(account) {
+            return store.get(account) ?? null;
+        },
+        async deletePassword(account) {
+            return store.delete(account);
+        },
+    };
+}
+/** Persist a refresh token keyed on user_id. */
+export async function setRefreshToken(userId, token) {
+    const adapter = await getKeychainAdapter();
+    await adapter.setPassword(`${REFRESH_TOKEN_PREFIX}${userId}`, token);
+}
+/** Read a refresh token by user_id, or null if none is stored. */
+export async function getRefreshToken(userId) {
+    const adapter = await getKeychainAdapter();
+    return adapter.getPassword(`${REFRESH_TOKEN_PREFIX}${userId}`);
+}
+/** Remove a refresh token. Idempotent — returns false if nothing was stored. */
+export async function deleteRefreshToken(userId) {
+    const adapter = await getKeychainAdapter();
+    return adapter.deletePassword(`${REFRESH_TOKEN_PREFIX}${userId}`);
+}

package/dist/packages/runtime/auth/session-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Session store — read/write `~/.interf/auth/session.json`.
+ *
+ * The session file is the engine's view of the current account: who is
+ * signed in, what plan they are on, when the session was last refreshed.
+ * Refresh tokens live in the keychain (see `keychain.ts`), not here.
+ *
+ * The store is intentionally tiny — pure file IO + schema validation — so
+ * tests can swap `~/.interf/` via the `INTERF_USER_HOME` env var and
+ * exercise auth flows without touching the real home dir.
+ */
+import { z } from "zod";
+import { type CurrentAccount } from "./account-context.js";
+export declare const AUTH_DIR = "auth";
+export declare const SESSION_FILENAME = "session.json";
+declare const SessionFileSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-session">;
+    version: z.ZodLiteral<1>;
+    user_id: z.ZodString;
+    email: z.ZodString;
+    display_name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    plan: z.ZodEnum<{
+        free: "free";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    refreshed_at: z.ZodString;
+}, z.core.$strict>;
+export type SessionFile = z.infer<typeof SessionFileSchema>;
+export declare function authDir(): string;
+export declare function sessionPath(): string;
+/** Read the active session, or null if no session is on disk. */
+export declare function readSession(): CurrentAccount | null;
+/** Persist a session. Creates the auth dir if it does not exist. */
+export declare function writeSession(account: CurrentAccount): void;
+/** Clear the session (logout). Idempotent. */
+export declare function clearSession(): void;
+export {};

package/dist/packages/runtime/auth/session-store.js

@@ -0,0 +1,96 @@
+/**
+ * Session store — read/write `~/.interf/auth/session.json`.
+ *
+ * The session file is the engine's view of the current account: who is
+ * signed in, what plan they are on, when the session was last refreshed.
+ * Refresh tokens live in the keychain (see `keychain.ts`), not here.
+ *
+ * The store is intentionally tiny — pure file IO + schema validation — so
+ * tests can swap `~/.interf/` via the `INTERF_USER_HOME` env var and
+ * exercise auth flows without touching the real home dir.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { interfHomeRoot } from "../../contracts/lib/project-paths.js";
+import { entitlementsForPlan, } from "./account-context.js";
+export const AUTH_DIR = "auth";
+export const SESSION_FILENAME = "session.json";
+const SessionFileSchema = z.object({
+    kind: z.literal("interf-session"),
+    version: z.literal(1),
+    user_id: z.string().min(1),
+    email: z.string().min(1),
+    display_name: z.string().min(1).nullable().default(null),
+    plan: z.enum(["free", "pro", "enterprise"]),
+    refreshed_at: z.string().min(1),
+}).strict();
+export function authDir() {
+    return join(interfHomeRoot(), AUTH_DIR);
+}
+export function sessionPath() {
+    return join(authDir(), SESSION_FILENAME);
+}
+/** Read the active session, or null if no session is on disk. */
+export function readSession() {
+    const path = sessionPath();
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const result = SessionFileSchema.safeParse(parsed);
+    if (!result.success)
+        return null;
+    const session = result.data;
+    return {
+        user_id: session.user_id,
+        email: session.email,
+        display_name: session.display_name,
+        plan: session.plan,
+        entitlements: entitlementsForPlan(session.plan),
+        refreshed_at: session.refreshed_at,
+    };
+}
+/** Persist a session. Creates the auth dir if it does not exist. */
+export function writeSession(account) {
+    const path = sessionPath();
+    const dir = dirname(path);
+    // `mode` on mkdir/writeFile only applies when the entry is *created*; node
+    // ignores it when the dir/file already exists. A session file (or auth dir)
+    // left over from an earlier run with looser perms (e.g. 0o644) would never be
+    // re-tightened. chmod after the write so the PII session file is always 0o600
+    // inside a 0o700 dir, even when it pre-existed.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const file = {
+        kind: "interf-session",
+        version: 1,
+        user_id: account.user_id,
+        email: account.email,
+        display_name: account.display_name,
+        plan: account.plan === "anonymous" ? "free" : account.plan,
+        refreshed_at: account.refreshed_at,
+    };
+    const validated = SessionFileSchema.parse(file);
+    writeFileSync(path, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/** Clear the session (logout). Idempotent. */
+export function clearSession() {
+    const path = sessionPath();
+    if (existsSync(path)) {
+        rmSync(path, { force: true });
+    }
+}

package/dist/packages/runtime/auth/workos-client.d.ts

@@ -0,0 +1,58 @@
+/**
+ * WorkOS SDK wrapper.
+ *
+ * Reads config from env at lazy-init time. The engine and CLI never import
+ * `@workos-inc/node` directly — they go through `getWorkOS()` so the provider
+ * stays behind one seam.
+ *
+ * Two modes:
+ *   - **Public Client (CLI / desktop / loopback engine)**: only
+ *     `WORKOS_CLIENT_ID` required. PKCE replaces the missing client secret.
+ *     This is the path `interf auth login` drives.
+ *   - **Confidential Client (cloud control plane)**: both `WORKOS_API_KEY`
+ *     and `WORKOS_CLIENT_ID` required. Phase 2; not exercised by the local
+ *     engine.
+ *
+ * Optional `WORKOS_ISSUER` overrides the AuthKit base URL (defaults to the
+ * production WorkOS API). Used for the JWKS URL and for any direct HTTP
+ * call we make outside the SDK.
+ */
+import { WorkOS } from "@workos-inc/node";
+export interface WorkOSConfig {
+    /** Server-side API key. Present only in confidential client mode. */
+    apiKey: string | null;
+    /** Public client identifier. Always required. */
+    clientId: string;
+    /** AuthKit issuer base URL, no trailing slash. */
+    issuer: string;
+}
+export declare class WorkOSConfigError extends Error {
+    constructor(message: string);
+}
+/** Reset cached config + client. Test seam. */
+export declare function resetWorkOSCache(): void;
+/**
+ * Load + validate WorkOS config from the environment.
+ *
+ * `WORKOS_CLIENT_ID` is always required. `WORKOS_API_KEY` is optional —
+ * leave it unset for CLI/Public Client mode. Set it only on the cloud
+ * control plane.
+ *
+ * Throws WorkOSConfigError with an actionable message when the client id
+ * is missing.
+ */
+export declare function workosConfig(): WorkOSConfig;
+/**
+ * Get a singleton WorkOS SDK client.
+ *
+ * Public Client Mode is the default when no API key is configured —
+ * matches the upstream SDK pattern for browser / mobile / CLI / desktop
+ * apps that cannot securely store a client secret.
+ */
+export declare function getWorkOS(): WorkOS;
+/**
+ * Test seam — inject a stub `WorkOS` instance so tests can drive the
+ * auth flow without touching the live SDK or env. Pass `null` to
+ * restore lazy init.
+ */
+export declare function setWorkOSClientForTests(client: WorkOS | null): void;