@mupt-ai/dari-gateway 0.2.0 → 0.2.1

package/dist/self_host/subscriptions/http.js

@@ -0,0 +1,187 @@
+/**
+ * The subscription endpoints the Dari CLI calls, with the same paths and JSON
+ * shapes as the hosted API. The gateway is single-tenant: `current` is the
+ * only organization, and every caller that passes the gateway's own auth owns
+ * every subscription. Errors are `{"detail": "..."}`, which the CLI prints.
+ */
+import { SUBSCRIPTION_PROVIDERS, SubscriptionOAuthInputError, SubscriptionOAuthProviderError, completeOAuth, startOAuth, } from "./oauth.js";
+import { isHeld } from "./store.js";
+const BASE = "/v1/organizations/current/credentials";
+// Subscription names are env-var-style, which keeps other credential routes
+// such as `provider-credentials/...` out of these matches.
+const NAMED = /^\/([A-Za-z_][A-Za-z0-9_]*)(\/label|\/mark-available|\/auto-reset)?$/;
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Handle a subscription route, or return null when the request is not one. */
+export async function handleSubscriptionRequest(request, deps) {
+    const url = new URL(request.url);
+    if (url.pathname !== BASE && !url.pathname.startsWith(`${BASE}/`))
+        return null;
+    const path = url.pathname.slice(BASE.length);
+    const now = deps.now?.() ?? new Date();
+    try {
+        if (path === "" && request.method === "GET")
+            return json(200, listBody(deps.store, now));
+        if (path === "/oauth/sessions" && request.method === "POST") {
+            return json(201, await startSession(deps, await readBody(request), now));
+        }
+        if (path === "/oauth/sessions/complete" && request.method === "POST") {
+            return json(200, await completeSession(deps, await readBody(request), now));
+        }
+        const named = NAMED.exec(path);
+        if (named === null)
+            return null;
+        const name = named[1];
+        const action = named[2];
+        if (action === undefined && request.method === "DELETE") {
+            // The hosted API requires `scope=user` so an old client deleting an
+            // organization secret by name never disconnects a subscription.
+            if (url.searchParams.get("scope") !== "user")
+                throw new HttpError(400, "scope=user is required.");
+            const removed = deps.store.disconnect(name);
+            return json(200, credentialBody(found(removed, name), false, now));
+        }
+        if (action === "/label" && request.method === "PUT") {
+            const body = await readBody(request);
+            const label = body.label ?? null;
+            if (label !== null && typeof label !== "string")
+                throw new HttpError(400, "label must be a string.");
+            let renamed;
+            try {
+                renamed = deps.store.rename(name, label, now);
+            }
+            catch (error) {
+                if (error instanceof RangeError)
+                    throw new HttpError(400, error.message);
+                throw error;
+            }
+            return json(200, summary(deps.store, found(renamed, name), now));
+        }
+        if (action === "/mark-available" && request.method === "POST") {
+            return json(200, summary(deps.store, found(deps.store.markAvailable(name, now), name), now));
+        }
+        if (action === "/auto-reset" && request.method === "POST") {
+            throw new HttpError(400, "Spending banked Codex resets is not supported by this gateway.");
+        }
+        return null;
+    }
+    catch (error) {
+        if (error instanceof HttpError)
+            return json(error.status, { detail: error.message });
+        if (error instanceof SubscriptionOAuthInputError)
+            return json(400, { detail: error.message });
+        if (error instanceof SubscriptionOAuthProviderError)
+            return json(502, { detail: error.message });
+        throw error;
+    }
+}
+function listBody(store, now) {
+    const active = new Set(SUBSCRIPTION_PROVIDERS.map((provider) => store.activeCredential(provider, now)?.id));
+    return {
+        credentials: store.list().map((credential) => credentialBody(credential, active.has(credential.id), now)),
+        // Plan gating is hosted-only; a self-hosted gateway always allows routing.
+        autorouting_allowed: true,
+    };
+}
+async function startSession(deps, body, now) {
+    const provider = body.provider;
+    if (typeof provider !== "string" || !SUBSCRIPTION_PROVIDERS.includes(provider)) {
+        throw new HttpError(400, `provider must be one of: ${SUBSCRIPTION_PROVIDERS.join(", ")}.`);
+    }
+    const credentialName = body.credential_name ?? null;
+    if (credentialName !== null && (typeof credentialName !== "string" || !credentialName.trim())) {
+        throw new HttpError(400, "credential_name must be a non-empty string.");
+    }
+    if (credentialName !== null && deps.store.getByName(credentialName)?.provider !== provider) {
+        throw new HttpError(404, `Unknown subscription credential ${JSON.stringify(credentialName)}.`);
+    }
+    const authorization = await startOAuth(provider, { fetch: deps.fetch, now });
+    const session = deps.store.createSession({
+        provider: provider,
+        flow: authorization.flow,
+        credentialName,
+        expiresAt: authorization.expiresAt,
+    }, now);
+    return {
+        provider,
+        session_token: session.token,
+        authorization_url: authorization.authorizationUrl,
+        expires_at: authorization.expiresAt.toISOString(),
+        user_code: authorization.userCode,
+    };
+}
+async function completeSession(deps, body, now) {
+    const token = body.session_token;
+    const authorizationResponse = body.authorization_response ?? "";
+    if (typeof token !== "string" || !token || typeof authorizationResponse !== "string") {
+        throw new HttpError(400, "session_token and authorization_response must be strings.");
+    }
+    const session = deps.store.getSession(token);
+    if (session === null)
+        throw new HttpError(400, "Invalid subscription authorization session.");
+    if (session.expiresAt <= now) {
+        deps.store.deleteSession(token);
+        throw new HttpError(400, "Subscription authorization session has expired. Start again.");
+    }
+    // A pending device approval keeps the session so the CLI can retry.
+    const tokens = await completeOAuth(session.provider, session.flow, authorizationResponse, {
+        fetch: deps.fetch,
+        now,
+    });
+    deps.store.deleteSession(token);
+    const stored = deps.store.connect(tokens, session.credentialName, now);
+    if (stored === null) {
+        throw new HttpError(404, `Unknown subscription credential ${JSON.stringify(session.credentialName)}.`);
+    }
+    return summary(deps.store, stored, now);
+}
+function summary(store, credential, now) {
+    return credentialBody(credential, store.activeCredential(credential.provider, now)?.id === credential.id, now);
+}
+/** The fields the CLI reads from a credential, never its tokens. */
+function credentialBody(credential, active, now) {
+    const held = isHeld(credential, now);
+    return {
+        id: credential.id,
+        name: credential.name,
+        label: credential.label,
+        safe_metadata: credential.accountEmail === null ? {} : { account_email: credential.accountEmail },
+        // Hosted organizations also hold organization-scoped secrets; every
+        // subscription here belongs to the gateway's one user.
+        credential_scope: "user",
+        oauth_provider: credential.provider,
+        created_at: credential.createdAt.toISOString(),
+        last_used_at: credential.lastUsedAt?.toISOString() ?? null,
+        unavailable_until: held ? credential.unavailableUntil.toISOString() : null,
+        unavailable_reason: held ? credential.unavailableReason : null,
+        subscription_active: active,
+        // Spending banked Codex resets is hosted-only.
+        auto_redeem_resets: false,
+    };
+}
+function found(credential, name) {
+    if (credential === null)
+        throw new HttpError(404, `Unknown subscription credential ${JSON.stringify(name)}.`);
+    return credential;
+}
+async function readBody(request) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        throw new HttpError(400, "Request body must be JSON.");
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw new HttpError(400, "Request body must be a JSON object.");
+    }
+    return body;
+}
+function json(status, body) {
+    return Response.json(body, { status });
+}

package/dist/self_host/subscriptions/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Personal subscriptions for a self-hosted, single-tenant gateway: Claude Code
+ * (Max/Pro) and ChatGPT (Codex) plans connected over OAuth and used in place
+ * of API keys.
+ *
+ * - `oauth.ts`: the providers' OAuth protocols (Claude Code PKCE with a
+ *   pasted `code#state`, ChatGPT device code) and token refresh.
+ * - `store.ts`: SQLite storage. Tokens are plaintext in the gateway's own
+ *   database file; protect that file like a secret.
+ * - `access.ts`: `freshAccessToken` refreshes a token expiring within five
+ *   minutes before handing it out, one refresh per credential at a time.
+ * - `http.ts`: `handleSubscriptionRequest` serves the credential endpoints the
+ *   Dari CLI uses to connect, list, rename, release, and disconnect
+ *   subscriptions. The caller authenticates the request first.
+ *
+ * Routing picks `store.activeCredential(provider)`: the subscription in use
+ * while it serves, then the next one in connection order that is not held. When a provider reports a usage limit,
+ * `store.markUnavailable` holds that subscription until its reset and says
+ * whether another one can serve the retry.
+ */
+export { freshAccessToken } from "./access.js";
+export { handleSubscriptionRequest, type SubscriptionHttpDeps } from "./http.js";
+export { CODEX_APPROVAL_PENDING, SUBSCRIPTION_PROVIDERS, SubscriptionOAuthInputError, SubscriptionOAuthProviderError, completeOAuth, parseAuthorizationResponse, refreshOAuth, startOAuth, type OAuthAuthorization, type OAuthFetch, type OAuthOptions, type OAuthTokens, type SubscriptionProvider, } from "./oauth.js";
+export { SubscriptionStore, isHeld, type PendingOAuthSession, type SubscriptionCredential, } from "./store.js";

package/dist/self_host/subscriptions/index.js

@@ -0,0 +1,24 @@
+/**
+ * Personal subscriptions for a self-hosted, single-tenant gateway: Claude Code
+ * (Max/Pro) and ChatGPT (Codex) plans connected over OAuth and used in place
+ * of API keys.
+ *
+ * - `oauth.ts`: the providers' OAuth protocols (Claude Code PKCE with a
+ *   pasted `code#state`, ChatGPT device code) and token refresh.
+ * - `store.ts`: SQLite storage. Tokens are plaintext in the gateway's own
+ *   database file; protect that file like a secret.
+ * - `access.ts`: `freshAccessToken` refreshes a token expiring within five
+ *   minutes before handing it out, one refresh per credential at a time.
+ * - `http.ts`: `handleSubscriptionRequest` serves the credential endpoints the
+ *   Dari CLI uses to connect, list, rename, release, and disconnect
+ *   subscriptions. The caller authenticates the request first.
+ *
+ * Routing picks `store.activeCredential(provider)`: the subscription in use
+ * while it serves, then the next one in connection order that is not held. When a provider reports a usage limit,
+ * `store.markUnavailable` holds that subscription until its reset and says
+ * whether another one can serve the retry.
+ */
+export { freshAccessToken } from "./access.js";
+export { handleSubscriptionRequest } from "./http.js";
+export { CODEX_APPROVAL_PENDING, SUBSCRIPTION_PROVIDERS, SubscriptionOAuthInputError, SubscriptionOAuthProviderError, completeOAuth, parseAuthorizationResponse, refreshOAuth, startOAuth, } from "./oauth.js";
+export { SubscriptionStore, isHeld, } from "./store.js";

package/dist/self_host/subscriptions/oauth.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OAuth protocols for personal subscriptions: Claude Code (PKCE, the user
+ * pastes back the `code#state` Anthropic shows) and ChatGPT/Codex (device
+ * code, the gateway polls for approval). Every network call goes through the
+ * injected `fetch`.
+ */
+export type SubscriptionProvider = "anthropic_claude_code" | "openai_codex";
+export declare const SUBSCRIPTION_PROVIDERS: readonly SubscriptionProvider[];
+export type OAuthFetch = (url: string, init: RequestInit) => Promise<Response>;
+export type OAuthOptions = {
+    fetch: OAuthFetch;
+    now?: Date;
+};
+/** The provider refused or could not be reached (HTTP 502 at the edge). */
+export declare class SubscriptionOAuthProviderError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** The user's input or flow state is wrong (HTTP 400 at the edge). */
+export declare class SubscriptionOAuthInputError extends Error {
+    constructor(message: string);
+}
+export type OAuthAuthorization = {
+    authorizationUrl: string;
+    expiresAt: Date;
+    userCode: string | null;
+    flow: Record<string, string>;
+};
+export type OAuthTokens = {
+    provider: SubscriptionProvider;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: Date;
+    accountId: string | null;
+    accountEmail: string | null;
+};
+export declare const CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const CODEX_APPROVAL_PENDING = "OpenAI approval is still pending. Enter the code at OpenAI, finish approval, then try again.";
+export declare function startOAuth(provider: SubscriptionProvider, options: OAuthOptions): Promise<OAuthAuthorization>;
+/**
+ * Finish a flow. Claude Code needs the pasted authorization response; the
+ * device-code flow ignores it and asks OpenAI whether the user approved.
+ */
+export declare function completeOAuth(provider: SubscriptionProvider, flow: Record<string, string>, authorizationResponse: string, options: OAuthOptions): Promise<OAuthTokens>;
+export declare function refreshOAuth(credential: {
+    provider: SubscriptionProvider;
+    refreshToken: string;
+    accountId: string | null;
+}, options: OAuthOptions): Promise<OAuthTokens>;
+/** Accepts the full callback URL, `code#state`, a `code=...&state=...` query, or a bare code. */
+export declare function parseAuthorizationResponse(value: string): {
+    code: string;
+    state: string | null;
+};

package/dist/self_host/subscriptions/oauth.js

@@ -0,0 +1,281 @@
+import { createHash, randomBytes } from "node:crypto";
+export const SUBSCRIPTION_PROVIDERS = [
+    "anthropic_claude_code",
+    "openai_codex",
+];
+/** The provider refused or could not be reached (HTTP 502 at the edge). */
+export class SubscriptionOAuthProviderError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "SubscriptionOAuthProviderError";
+    }
+}
+/** The user's input or flow state is wrong (HTTP 400 at the edge). */
+export class SubscriptionOAuthInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SubscriptionOAuthInputError";
+    }
+}
+const FLOW_TIMEOUT_MS = 15 * 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const INCOMPLETE = "Subscription OAuth provider returned an incomplete response.";
+export const CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const CLAUDE_AUTHORIZE_URL = "https://claude.com/cai/oauth/authorize";
+const CLAUDE_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+// Anthropic shows `code#state` on its own callback page for the user to paste back.
+const CLAUDE_REDIRECT_URI = "https://platform.claude.com/oauth/code/callback";
+const CLAUDE_CODE_SCOPES = "user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload";
+export const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const OPENAI_AUTH_BASE_URL = "https://auth.openai.com";
+const CODEX_AUTHORIZE_URL = `${OPENAI_AUTH_BASE_URL}/codex/device`;
+const CODEX_DEVICE_AUTH_URL = `${OPENAI_AUTH_BASE_URL}/api/accounts/deviceauth`;
+const CODEX_TOKEN_URL = `${OPENAI_AUTH_BASE_URL}/oauth/token`;
+const CODEX_REDIRECT_URI = `${OPENAI_AUTH_BASE_URL}/deviceauth/callback`;
+const CODEX_ACCOUNT_CLAIM = "https://api.openai.com/auth";
+export const CODEX_APPROVAL_PENDING = "OpenAI approval is still pending. Enter the code at OpenAI, finish approval, then try again.";
+export async function startOAuth(provider, options) {
+    const expiresAt = new Date((options.now ?? new Date()).getTime() + FLOW_TIMEOUT_MS);
+    if (provider === "anthropic_claude_code") {
+        const verifier = randomUrlSafe(32);
+        const challenge = base64Url(createHash("sha256").update(verifier).digest());
+        // The pasted `code#state` is shown to the user, so state must not be the verifier.
+        const state = randomUrlSafe(32);
+        const query = new URLSearchParams({
+            code: "true",
+            client_id: CLAUDE_CODE_CLIENT_ID,
+            response_type: "code",
+            redirect_uri: CLAUDE_REDIRECT_URI,
+            scope: CLAUDE_CODE_SCOPES,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+            state,
+        });
+        return {
+            authorizationUrl: `${CLAUDE_AUTHORIZE_URL}?${query}`,
+            expiresAt,
+            userCode: null,
+            flow: { code_verifier: verifier, state },
+        };
+    }
+    const payload = await postJson(options.fetch, `${CODEX_DEVICE_AUTH_URL}/usercode`, { client_id: CODEX_CLIENT_ID }, "OpenAI device code request");
+    const userCode = requiredString({ user_code: payload.user_code || payload.usercode }, "user_code");
+    return {
+        authorizationUrl: CODEX_AUTHORIZE_URL,
+        expiresAt,
+        userCode,
+        flow: { device_auth_id: requiredString(payload, "device_auth_id"), user_code: userCode },
+    };
+}
+/**
+ * Finish a flow. Claude Code needs the pasted authorization response; the
+ * device-code flow ignores it and asks OpenAI whether the user approved.
+ */
+export async function completeOAuth(provider, flow, authorizationResponse, options) {
+    const now = options.now ?? new Date();
+    if (provider === "anthropic_claude_code") {
+        const verifier = requiredString(flow, "code_verifier");
+        const expectedState = requiredString(flow, "state");
+        if (!authorizationResponse.trim()) {
+            throw new SubscriptionOAuthInputError("Anthropic authorization code is required.");
+        }
+        const { code, state } = parseAuthorizationResponse(authorizationResponse);
+        if (state !== null && state !== expectedState) {
+            throw new SubscriptionOAuthInputError("Anthropic authorization state does not match. Start again.");
+        }
+        const token = await postJson(options.fetch, CLAUDE_TOKEN_URL, {
+            grant_type: "authorization_code",
+            client_id: CLAUDE_CODE_CLIENT_ID,
+            code,
+            state: state ?? expectedState,
+            redirect_uri: CLAUDE_REDIRECT_URI,
+            code_verifier: verifier,
+        }, "Anthropic subscription token exchange");
+        return claudeTokens(token, now, null);
+    }
+    // The provider, not user-supplied input, supplies the authorization code.
+    let approval;
+    try {
+        approval = await postJson(options.fetch, `${CODEX_DEVICE_AUTH_URL}/token`, {
+            device_auth_id: requiredString(flow, "device_auth_id"),
+            user_code: requiredString(flow, "user_code"),
+        }, "OpenAI device approval check");
+    }
+    catch (error) {
+        if (error instanceof SubscriptionOAuthProviderError && (error.status === 403 || error.status === 404)) {
+            throw new SubscriptionOAuthInputError(CODEX_APPROVAL_PENDING);
+        }
+        throw error;
+    }
+    const token = await postForm(options.fetch, CODEX_TOKEN_URL, {
+        grant_type: "authorization_code",
+        client_id: CODEX_CLIENT_ID,
+        code: requiredString(approval, "authorization_code"),
+        code_verifier: requiredString(approval, "code_verifier"),
+        redirect_uri: CODEX_REDIRECT_URI,
+    }, "OpenAI subscription token exchange");
+    return codexTokens(token, now, null, null);
+}
+export async function refreshOAuth(credential, options) {
+    const now = options.now ?? new Date();
+    if (credential.provider === "anthropic_claude_code") {
+        const token = await postJson(options.fetch, CLAUDE_TOKEN_URL, {
+            grant_type: "refresh_token",
+            client_id: CLAUDE_CODE_CLIENT_ID,
+            refresh_token: credential.refreshToken,
+            scope: CLAUDE_CODE_SCOPES,
+        }, "Anthropic subscription token refresh");
+        return claudeTokens(token, now, credential.refreshToken);
+    }
+    const token = await postJson(options.fetch, CODEX_TOKEN_URL, {
+        grant_type: "refresh_token",
+        refresh_token: credential.refreshToken,
+        client_id: CODEX_CLIENT_ID,
+    }, "OpenAI subscription token refresh");
+    return codexTokens(token, now, credential.refreshToken, credential.accountId);
+}
+/** Accepts the full callback URL, `code#state`, a `code=...&state=...` query, or a bare code. */
+export function parseAuthorizationResponse(value) {
+    const normalized = value.trim();
+    if (URL.canParse(normalized)) {
+        const parsed = new URL(normalized);
+        const code = parsed.searchParams.get("code");
+        if (parsed.host && code)
+            return { code, state: parsed.searchParams.get("state") || null };
+    }
+    const hash = normalized.indexOf("#");
+    if (hash > 0) {
+        return { code: normalized.slice(0, hash), state: normalized.slice(hash + 1) || null };
+    }
+    if (normalized.includes("code=")) {
+        const query = new URLSearchParams(normalized);
+        const code = query.get("code");
+        if (code)
+            return { code, state: query.get("state") || null };
+    }
+    if (normalized)
+        return { code: normalized, state: null };
+    throw new SubscriptionOAuthInputError("Authorization code or redirect URL is required.");
+}
+function claudeTokens(payload, now, fallbackRefreshToken) {
+    const account = payload.account;
+    const email = isRecord(account) ? account.email_address : undefined;
+    return {
+        provider: "anthropic_claude_code",
+        accessToken: requiredString(payload, "access_token"),
+        refreshToken: refreshTokenFrom(payload, fallbackRefreshToken),
+        expiresAt: new Date(now.getTime() + positiveInt(payload.expires_in) * 1000),
+        accountId: null,
+        accountEmail: typeof email === "string" && email ? email : null,
+    };
+}
+function codexTokens(payload, now, fallbackRefreshToken, fallbackAccountId) {
+    const accessToken = requiredString(payload, "access_token");
+    const refreshToken = refreshTokenFrom(payload, fallbackRefreshToken);
+    const idToken = typeof payload.id_token === "string" ? payload.id_token : null;
+    const accountId = (idToken === null ? null : codexAccountId(idToken))
+        ?? codexAccountId(accessToken)
+        ?? fallbackAccountId;
+    if (accountId === null) {
+        throw new SubscriptionOAuthProviderError("OpenAI subscription token is missing its account identifier.");
+    }
+    const email = idToken === null ? undefined : jwtPayload(idToken)?.email;
+    return {
+        provider: "openai_codex",
+        accessToken,
+        refreshToken,
+        expiresAt: codexExpiration(payload, accessToken, now),
+        accountId,
+        accountEmail: typeof email === "string" && email ? email : null,
+    };
+}
+function codexAccountId(token) {
+    const auth = jwtPayload(token)?.[CODEX_ACCOUNT_CLAIM];
+    const accountId = isRecord(auth) ? auth.chatgpt_account_id : undefined;
+    return typeof accountId === "string" && accountId ? accountId : null;
+}
+function codexExpiration(payload, accessToken, now) {
+    if (payload.expires_in !== undefined && payload.expires_in !== null) {
+        return new Date(now.getTime() + positiveInt(payload.expires_in) * 1000);
+    }
+    const exp = jwtPayload(accessToken)?.exp;
+    if (typeof exp === "number" && Number.isFinite(exp))
+        return new Date(exp * 1000);
+    throw new SubscriptionOAuthProviderError("OpenAI subscription token is missing its expiration.");
+}
+function refreshTokenFrom(payload, fallback) {
+    const value = payload.refresh_token;
+    const refreshToken = typeof value === "string" && value ? value : fallback;
+    if (!refreshToken)
+        throw new SubscriptionOAuthProviderError(INCOMPLETE);
+    return refreshToken;
+}
+function requiredString(payload, name) {
+    const value = payload[name];
+    if (typeof value !== "string" || !value)
+        throw new SubscriptionOAuthProviderError(INCOMPLETE);
+    return value;
+}
+function positiveInt(value) {
+    const parsed = typeof value === "string" && /^\s*[+-]?\d+\s*$/.test(value) ? Number(value) : value;
+    if (typeof parsed === "number" && Number.isInteger(parsed) && parsed > 0)
+        return parsed;
+    throw new SubscriptionOAuthProviderError(INCOMPLETE);
+}
+function jwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const decoded = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        return isRecord(decoded) ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function postJson(fetch, url, payload, operation) {
+    return requestJson(fetch, url, JSON.stringify(payload), "application/json", operation);
+}
+function postForm(fetch, url, payload, operation) {
+    return requestJson(fetch, url, new URLSearchParams(payload).toString(), "application/x-www-form-urlencoded", operation);
+}
+async function requestJson(fetch, url, body, contentType, operation) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": contentType, "User-Agent": "Dari/1.0" },
+            body,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new SubscriptionOAuthProviderError(`${operation} could not reach the provider.`);
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new SubscriptionOAuthProviderError(`${operation} failed with provider status ${response.status}.`, response.status);
+    }
+    let decoded;
+    try {
+        decoded = await response.json();
+    }
+    catch {
+        throw new SubscriptionOAuthProviderError(`${operation} returned an invalid response.`);
+    }
+    if (!isRecord(decoded))
+        throw new SubscriptionOAuthProviderError(`${operation} returned an invalid response.`);
+    return decoded;
+}
+function randomUrlSafe(size) {
+    return base64Url(randomBytes(size));
+}
+function base64Url(value) {
+    return value.toString("base64url");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/self_host/subscriptions/store.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SQLite storage for personal subscription credentials and pending OAuth flows.
+ *
+ * Tokens are stored as PLAINTEXT in the gateway's own database file. Anyone
+ * who can read that file can use the connected subscriptions until the
+ * provider revokes them, so keep the file on storage only the gateway's
+ * operator can read, and treat backups of it as secrets.
+ *
+ * Connection order (`position`) is the order routing switches through: the
+ * active credential for a provider is the first one, in that order, that is
+ * not held. A hold ends on its own once `unavailable_until` passes.
+ */
+import type { Database } from "bun:sqlite";
+import type { OAuthTokens, SubscriptionProvider } from "./oauth.js";
+export type SubscriptionCredential = {
+    id: string;
+    provider: SubscriptionProvider;
+    name: string;
+    label: string | null;
+    accountEmail: string | null;
+    accountId: string | null;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: Date;
+    unavailableUntil: Date | null;
+    unavailableReason: string | null;
+    position: number;
+    createdAt: Date;
+    updatedAt: Date;
+    lastUsedAt: Date | null;
+};
+export type PendingOAuthSession = {
+    token: string;
+    provider: SubscriptionProvider;
+    flow: Record<string, string>;
+    credentialName: string | null;
+    expiresAt: Date;
+};
+export declare class SubscriptionStore {
+    private readonly db;
+    constructor(db: Database);
+    /** Every subscription, grouped by provider, in connection order. */
+    list(provider?: SubscriptionProvider): SubscriptionCredential[];
+    get(id: string): SubscriptionCredential | null;
+    getByName(name: string): SubscriptionCredential | null;
+    /** The credential routing uses now, or null when none is connected or every one is held. */
+    activeCredential(provider: SubscriptionProvider, now?: Date): SubscriptionCredential | null;
+    /**
+     * Store tokens from a completed OAuth flow. `reconnectName` replaces that
+     * subscription (null when it is not connected). Otherwise a subscription
+     * for the same account email is replaced, and anything else is connected
+     * last in order under the first free name.
+     */
+    connect(tokens: OAuthTokens, reconnectName: string | null, now?: Date): SubscriptionCredential | null;
+    /** Persist refreshed tokens. Keeps the stored account id when the refresh carries none. */
+    updateTokens(id: string, tokens: OAuthTokens, now?: Date): void;
+    touch(id: string, now?: Date): void;
+    /** An empty label clears it. Null when the subscription is not connected. */
+    rename(name: string, label: string | null, now?: Date): SubscriptionCredential | null;
+    /** Remove a subscription. Returns what was removed, or null when it was not connected. */
+    disconnect(name: string): SubscriptionCredential | null;
+    /**
+     * Hold an exhausted subscription until its reset. A hold only grows: a later
+     * report with an earlier reset never shortens a longer one. Returns whether
+     * a subscription for the same provider is available now.
+     */
+    markUnavailable(id: string, until: Date, reason: string, now?: Date): boolean;
+    /** Clear a usage-limit hold. Null when the subscription is not connected. */
+    markAvailable(name: string, now?: Date): SubscriptionCredential | null;
+    createSession(session: Omit<PendingOAuthSession, "token">, now?: Date): PendingOAuthSession;
+    /** A pending session, including an expired one so callers can say it expired. */
+    getSession(token: string): PendingOAuthSession | null;
+    deleteSession(token: string): void;
+    private freeName;
+}
+export declare function isHeld(credential: SubscriptionCredential, now: Date): boolean;
+/** Subscription names are env-var-style identifiers; matching is case-insensitive. */
+export declare function normalizeName(name: string): string;