@qvac/core 0.0.0 → 0.1.1

package/dist-lib/lib/oauth/keys.js

@@ -0,0 +1,93 @@
+export const GMAIL_CREDENTIAL_KEY = 'gmail_access_token';
+export const GOOGLE_CALENDAR_CREDENTIAL_KEY = 'google_calendar_access_token';
+export const GOOGLE_DOCS_CREDENTIAL_KEY = 'google_docs_access_token';
+export const GOOGLE_DRIVE_CREDENTIAL_KEY = 'google_drive_access_token';
+export const GOOGLE_SHEETS_CREDENTIAL_KEY = 'google_sheets_access_token';
+export const SPOTIFY_CREDENTIAL_KEY = 'spotify_access_token';
+export const ASANA_MCP_CREDENTIAL_KEY = 'asana_mcp_access_token';
+export const NOTION_MCP_CREDENTIAL_KEY = 'notion_mcp_access_token';
+export const LEGACY_GOOGLE_CREDENTIAL_KEY = 'google_workspace_access_token';
+const DRIVE_SCOPE = 'https://www.googleapis.com/auth/drive';
+export const OAUTH_KEY_SPECS = [
+    {
+        credentialKey: GMAIL_CREDENTIAL_KEY,
+        stateKey: 'gmail_oauth',
+        provider: 'google',
+        scopes: ['https://www.googleapis.com/auth/gmail.modify']
+    },
+    {
+        credentialKey: GOOGLE_CALENDAR_CREDENTIAL_KEY,
+        stateKey: 'google_calendar_oauth',
+        provider: 'google',
+        scopes: ['https://www.googleapis.com/auth/calendar']
+    },
+    {
+        credentialKey: GOOGLE_DOCS_CREDENTIAL_KEY,
+        stateKey: 'google_docs_oauth',
+        provider: 'google',
+        scopes: ['https://www.googleapis.com/auth/documents', DRIVE_SCOPE]
+    },
+    {
+        credentialKey: GOOGLE_DRIVE_CREDENTIAL_KEY,
+        stateKey: 'google_drive_oauth',
+        provider: 'google',
+        scopes: [DRIVE_SCOPE]
+    },
+    {
+        credentialKey: GOOGLE_SHEETS_CREDENTIAL_KEY,
+        stateKey: 'google_sheets_oauth',
+        provider: 'google',
+        scopes: ['https://www.googleapis.com/auth/spreadsheets', DRIVE_SCOPE]
+    },
+    {
+        credentialKey: SPOTIFY_CREDENTIAL_KEY,
+        stateKey: 'spotify_oauth',
+        provider: 'spotify',
+        scopes: [
+            'user-read-playback-state',
+            'user-modify-playback-state',
+            'user-read-currently-playing',
+            'playlist-read-private',
+            'playlist-read-collaborative',
+            'user-library-read',
+            'user-top-read',
+            'user-read-recently-played'
+        ]
+    },
+    {
+        credentialKey: ASANA_MCP_CREDENTIAL_KEY,
+        stateKey: 'asana_oauth',
+        provider: 'asana',
+        scopes: []
+    },
+    {
+        credentialKey: NOTION_MCP_CREDENTIAL_KEY,
+        stateKey: 'notion_oauth',
+        provider: 'notion',
+        scopes: []
+    }
+];
+export function oauthKeySpec(credentialKey) {
+    return OAUTH_KEY_SPECS.find((spec) => spec.credentialKey === credentialKey) ?? null;
+}
+export function oauthStateKeyFor(credentialKey) {
+    return oauthKeySpec(credentialKey)?.stateKey ?? null;
+}
+export function defaultCredentialKeyFor(provider) {
+    const spec = OAUTH_KEY_SPECS.find((candidate) => candidate.provider === provider);
+    if (!spec)
+        throw new Error(`Unknown OAuth provider: ${String(provider)}`);
+    return spec.credentialKey;
+}
+export const GOOGLE_CREDENTIAL_KEYS = OAUTH_KEY_SPECS.filter((spec) => spec.provider === 'google').map((spec) => spec.credentialKey);
+export const OAUTH_PROVIDER_PORTS = {
+    google: 18978,
+    spotify: 18974,
+    asana: 18981,
+    notion: 18982
+};
+export const OAUTH_CALLBACK_PATH = '/callback';
+export const OAUTH_WAIT_FOR_CODE_TIMEOUT_MS = 120_000;
+export function oauthRedirectUri(port) {
+    return `http://127.0.0.1:${port}${OAUTH_CALLBACK_PATH}`;
+}

package/dist-lib/lib/oauth/loopback.d.ts

@@ -0,0 +1,3 @@
+import type { OAuthLoopbackServer } from './redirect-types.ts';
+export declare function abortOAuthLoopback(port: number): Promise<boolean>;
+export declare function startOAuthLoopback(port: number): Promise<OAuthLoopbackServer>;

package/dist-lib/lib/oauth/loopback.js

@@ -0,0 +1,119 @@
+import { createServer } from 'http';
+import { OAUTH_CALLBACK_PATH, OAUTH_WAIT_FOR_CODE_TIMEOUT_MS, oauthRedirectUri } from "./keys.js";
+const activeLoopbacks = new Map();
+function closeServer(server) {
+    return new Promise((resolve) => {
+        if (!server.listening) {
+            resolve();
+            return;
+        }
+        server.closeAllConnections?.();
+        server.close(() => resolve());
+    });
+}
+export async function abortOAuthLoopback(port) {
+    const handle = activeLoopbacks.get(port);
+    if (!handle)
+        return false;
+    await handle.abort(new Error('OAuth flow cancelled'));
+    return true;
+}
+export async function startOAuthLoopback(port) {
+    const stale = activeLoopbacks.get(port);
+    if (stale) {
+        await stale.abort(new Error('OAuth loopback superseded by a new connect attempt'));
+    }
+    let resolveCode = null;
+    let rejectCode = null;
+    let abortedReason = null;
+    let expectedState = null;
+    const rejectWaiter = (error) => {
+        const reject = rejectCode;
+        resolveCode = null;
+        rejectCode = null;
+        reject?.(error);
+    };
+    const settle = (error, code, state) => {
+        const resolve = resolveCode;
+        const reject = rejectCode;
+        resolveCode = null;
+        rejectCode = null;
+        if (error)
+            reject?.(new Error(`OAuth error: ${error}`));
+        else if (code && state)
+            resolve?.({ code, state });
+        else
+            reject?.(new Error('OAuth callback missing code or state'));
+    };
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`);
+        if (url.pathname !== OAUTH_CALLBACK_PATH) {
+            response.writeHead(404, { 'Content-Type': 'text/plain' });
+            response.end('Not found');
+            return;
+        }
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+        const error = url.searchParams.get('error');
+        if (expectedState !== null && state !== expectedState) {
+            response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            response.end('<html><body><p>This sign-in link is from an earlier attempt. ' +
+                'You can close this tab.</p></body></html>');
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        response.end('<html><body><p>Authorization complete. You may close this tab.</p>' +
+            '<script>window.close();</script></body></html>');
+        settle(error, code, state);
+        response.on('close', () => server.close());
+    });
+    return new Promise((resolve, reject) => {
+        let listenSettled = false;
+        const onError = (error) => {
+            if (listenSettled)
+                return;
+            listenSettled = true;
+            server.removeListener('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            if (listenSettled)
+                return;
+            listenSettled = true;
+            server.removeListener('error', onError);
+            const handle = {
+                abort: (reason) => {
+                    abortedReason = reason;
+                    rejectWaiter(reason);
+                    return closeServer(server);
+                }
+            };
+            activeLoopbacks.set(port, handle);
+            server.once('close', () => {
+                if (activeLoopbacks.get(port) === handle)
+                    activeLoopbacks.delete(port);
+            });
+            resolve({
+                redirectUri: oauthRedirectUri(port),
+                waitForCode(timeoutMs = OAUTH_WAIT_FOR_CODE_TIMEOUT_MS, expected) {
+                    if (abortedReason)
+                        throw abortedReason;
+                    expectedState = expected ?? null;
+                    return new Promise((resolveWait, rejectWait) => {
+                        resolveCode = resolveWait;
+                        rejectCode = rejectWait;
+                        const timeout = globalThis.setTimeout(() => {
+                            server.close();
+                            rejectWait(new Error('OAuth callback timed out'));
+                        }, timeoutMs);
+                        server.once('close', () => globalThis.clearTimeout(timeout));
+                    });
+                },
+                close: () => server.close()
+            });
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, '127.0.0.1');
+    });
+}

package/dist-lib/lib/oauth/loopback.stub.d.ts

@@ -0,0 +1,3 @@
+import type { OAuthLoopbackServer } from './redirect-types.ts';
+export declare function abortOAuthLoopback(_port: number): Promise<boolean>;
+export declare function startOAuthLoopback(_port: number): Promise<OAuthLoopbackServer>;

package/dist-lib/lib/oauth/loopback.stub.js

@@ -0,0 +1,6 @@
+export function abortOAuthLoopback(_port) {
+    return Promise.resolve(false);
+}
+export function startOAuthLoopback(_port) {
+    return Promise.reject(new Error('OAuth loopback is unavailable in this runtime; inject createRedirect instead'));
+}

package/dist-lib/lib/oauth/notion.d.ts

@@ -0,0 +1,34 @@
+import { type ConfigEngine, type Fetch, type OAuthTokens } from './common.ts';
+export declare const NOTION_MCP_CREDENTIAL_KEY = "notion_mcp_access_token";
+export declare const NOTION_OAUTH_STATE_KEY = "notion_oauth";
+export declare const NOTION_OAUTH_PORT = 18982;
+export type NotionTokens = OAuthTokens;
+export declare function registerNotionClient(fetchImpl?: Fetch): Promise<string>;
+export declare function buildNotionAuthUrl(opts: {
+    clientId: string;
+    state: string;
+    challenge: string;
+}): string;
+export declare function exchangeNotionCode(opts: {
+    clientId: string;
+    code: string;
+    verifier: string;
+    fetch?: Fetch;
+}): Promise<NotionTokens>;
+export declare function refreshNotionToken(opts: {
+    clientId: string;
+    refreshToken: string;
+    fetch?: Fetch;
+}): Promise<NotionTokens>;
+export declare function connectNotion(opts: {
+    openUrl: (url: string) => unknown;
+    fetch?: Fetch;
+    timeoutMs?: number;
+}): Promise<NotionTokens & {
+    clientId: string;
+}>;
+export declare function resolveNotionCredential(opts: {
+    engine: ConfigEngine;
+    agentId?: string;
+    fetch?: Fetch;
+}): Promise<string | null>;

package/dist-lib/lib/oauth/notion.js

@@ -0,0 +1,82 @@
+import { URLSearchParams } from 'url';
+import defaultFetch from '#fetch';
+import { runBrowserConnect } from "./browser-connect.js";
+import { oauthRedirectUri, tokenRequest } from "./common.js";
+import { resolveOAuthCredential } from "./resolve.js";
+export const NOTION_MCP_CREDENTIAL_KEY = 'notion_mcp_access_token';
+export const NOTION_OAUTH_STATE_KEY = 'notion_oauth';
+export const NOTION_OAUTH_PORT = 18982;
+const REDIRECT_URI = oauthRedirectUri(NOTION_OAUTH_PORT);
+const AUTH_URL = 'https://mcp.notion.com/authorize';
+const TOKEN_URL = 'https://mcp.notion.com/token';
+const REGISTER_URL = 'https://mcp.notion.com/register';
+export async function registerNotionClient(fetchImpl = defaultFetch) {
+    const response = await fetchImpl(REGISTER_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+            client_name: 'QV.AC assistant',
+            redirect_uris: [REDIRECT_URI],
+            token_endpoint_auth_method: 'none',
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code']
+        })
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Notion client registration failed (${response.status}): ${text.slice(0, 256)}`);
+    }
+    const raw = (await response.json());
+    if (!raw.client_id)
+        throw new Error('Notion registration returned no client_id');
+    return raw.client_id;
+}
+export function buildNotionAuthUrl(opts) {
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: opts.clientId,
+        redirect_uri: REDIRECT_URI,
+        state: opts.state,
+        code_challenge: opts.challenge,
+        code_challenge_method: 'S256'
+    });
+    return `${AUTH_URL}?${params.toString()}`;
+}
+export async function exchangeNotionCode(opts) {
+    return tokenRequest(opts.fetch ?? defaultFetch, TOKEN_URL, new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: opts.code,
+        redirect_uri: REDIRECT_URI,
+        client_id: opts.clientId,
+        code_verifier: opts.verifier
+    }), 'Notion');
+}
+export async function refreshNotionToken(opts) {
+    const tokens = await tokenRequest(opts.fetch ?? defaultFetch, TOKEN_URL, new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: opts.refreshToken,
+        client_id: opts.clientId
+    }), 'Notion');
+    return { ...tokens, refreshToken: tokens.refreshToken ?? opts.refreshToken };
+}
+export async function connectNotion(opts) {
+    const fetch = opts.fetch ?? defaultFetch;
+    const clientId = await registerNotionClient(fetch);
+    const tokens = await runBrowserConnect({
+        port: NOTION_OAUTH_PORT,
+        timeoutMs: opts.timeoutMs,
+        openUrl: opts.openUrl,
+        buildAuthUrl: ({ state, challenge }) => buildNotionAuthUrl({ clientId, state, challenge }),
+        exchange: ({ code, verifier }) => exchangeNotionCode({ clientId, code, verifier, fetch })
+    });
+    return { ...tokens, clientId };
+}
+export async function resolveNotionCredential(opts) {
+    return resolveOAuthCredential({
+        ...opts,
+        credentialKey: NOTION_MCP_CREDENTIAL_KEY,
+        stateKey: NOTION_OAUTH_STATE_KEY,
+        requireClientSecret: false,
+        refresh: async ({ clientId, refreshToken, fetch }) => refreshNotionToken({ clientId, refreshToken, fetch })
+    });
+}

package/dist-lib/lib/oauth/pkce-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { PkceChallenge } from './pkce.ts';
+import type { OAuthRuntime } from './types.ts';
+export declare function generateRuntimePkceChallenge(runtime: OAuthRuntime): Promise<PkceChallenge>;

package/dist-lib/lib/oauth/pkce-runtime.js

@@ -0,0 +1,5 @@
+export async function generateRuntimePkceChallenge(runtime) {
+    const verifier = runtime.randomBase64Url(32);
+    const challenge = await runtime.sha256Base64Url(verifier);
+    return { verifier, challenge, method: 'S256' };
+}

package/dist-lib/lib/oauth/pkce.d.ts

@@ -0,0 +1,8 @@
+type RandomBytes = (size: number) => Uint8Array;
+export type PkceChallenge = {
+    readonly verifier: string;
+    readonly challenge: string;
+    readonly method: 'S256';
+};
+export declare function generatePkceChallenge(randomBytes?: RandomBytes): PkceChallenge;
+export {};

package/dist-lib/lib/oauth/pkce.js

@@ -0,0 +1,6 @@
+import { bytesToBase64Url, randomBase64Url, sha256Base64Url } from '@qvac/core/oauth/runtime/crypto';
+export function generatePkceChallenge(randomBytes) {
+    const verifier = randomBytes ? bytesToBase64Url(randomBytes(32)) : randomBase64Url(32);
+    const challenge = sha256Base64Url(verifier);
+    return { verifier, challenge, method: 'S256' };
+}

package/dist-lib/lib/oauth/providers.d.ts

@@ -0,0 +1,5 @@
+import type { OAuthCredentials, OAuthProvider, OAuthProviderConfig } from './types.ts';
+export declare function providerRequiresSecret(provider: OAuthProvider): boolean;
+export declare function providerSupportsDcr(provider: OAuthProvider): boolean;
+export declare function providerSupportsSharedIosSession(provider: OAuthProvider): boolean;
+export declare function buildProviderConfig(credentialKey: string, credentials: OAuthCredentials): OAuthProviderConfig;

package/dist-lib/lib/oauth/providers.js

@@ -0,0 +1,73 @@
+import { OAUTH_PROVIDER_PORTS, oauthKeySpec } from "./keys.js";
+const ASANA_MCP_RESOURCE = 'https://mcp.asana.com/v2';
+export function providerRequiresSecret(provider) {
+    return provider === 'google' || provider === 'asana';
+}
+export function providerSupportsDcr(provider) {
+    return provider === 'notion';
+}
+export function providerSupportsSharedIosSession(provider) {
+    return provider === 'spotify' || provider === 'notion';
+}
+export function buildProviderConfig(credentialKey, credentials) {
+    const spec = oauthKeySpec(credentialKey);
+    if (!spec)
+        throw new Error(`Unknown OAuth credential key: ${credentialKey}`);
+    const { provider } = spec;
+    if (provider === 'google') {
+        return {
+            clientId: credentials.clientId,
+            clientSecret: requireSecret(credentials.clientSecret, provider),
+            tokenAuth: 'secret-in-body',
+            authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+            tokenUrl: 'https://oauth2.googleapis.com/token',
+            scopes: spec.scopes,
+            credentialKey: spec.credentialKey,
+            port: OAUTH_PROVIDER_PORTS[provider],
+            extraAuthParams: { access_type: 'offline', prompt: 'consent' }
+        };
+    }
+    if (provider === 'spotify') {
+        return {
+            clientId: credentials.clientId,
+            tokenAuth: 'pkce-only',
+            authUrl: 'https://accounts.spotify.com/authorize',
+            tokenUrl: 'https://accounts.spotify.com/api/token',
+            scopes: spec.scopes,
+            credentialKey: spec.credentialKey,
+            port: OAUTH_PROVIDER_PORTS[provider]
+        };
+    }
+    if (provider === 'asana') {
+        return {
+            clientId: credentials.clientId,
+            clientSecret: requireSecret(credentials.clientSecret, provider),
+            tokenAuth: 'secret-in-body',
+            authUrl: 'https://app.asana.com/-/oauth_authorize',
+            tokenUrl: 'https://app.asana.com/-/oauth_token',
+            scopes: spec.scopes,
+            credentialKey: spec.credentialKey,
+            port: OAUTH_PROVIDER_PORTS[provider],
+            extraAuthParams: { resource: ASANA_MCP_RESOURCE }
+        };
+    }
+    if (provider === 'notion') {
+        return {
+            clientId: credentials.clientId,
+            tokenAuth: 'pkce-only',
+            authUrl: 'https://mcp.notion.com/authorize',
+            tokenUrl: 'https://mcp.notion.com/token',
+            registrationEndpoint: 'https://mcp.notion.com/register',
+            dynamicRegistration: true,
+            scopes: spec.scopes,
+            credentialKey: spec.credentialKey,
+            port: OAUTH_PROVIDER_PORTS[provider]
+        };
+    }
+    throw new Error(`Unknown OAuth provider: ${String(provider)}`);
+}
+function requireSecret(secret, provider) {
+    if (!secret)
+        throw new Error(`Client secret is required for ${provider}.`);
+    return secret;
+}

package/dist-lib/lib/oauth/redirect-types.d.ts

@@ -0,0 +1,19 @@
+export type OAuthCallbackResult = {
+    readonly code: string;
+    readonly state: string;
+};
+export type OAuthLoopbackServer = {
+    readonly redirectUri: string;
+    readonly waitForCode: (timeoutMs?: number, expectedState?: string) => Promise<OAuthCallbackResult>;
+    readonly close: () => void;
+};
+export type OAuthRedirect = {
+    readonly redirectUri: string;
+    readonly authorize: (authUrl: string, timeoutMs?: number, expectedState?: string) => Promise<OAuthCallbackResult>;
+    readonly close: () => void;
+};
+export type OAuthRedirectFactory = (target: {
+    readonly port: number;
+}, deps: {
+    readonly openUrl: (url: string) => Promise<void>;
+}) => Promise<OAuthRedirect>;

package/dist-lib/lib/oauth/redirect-types.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/oauth/register.d.ts

@@ -0,0 +1,3 @@
+import type { OAuthFetch, OAuthFlowDeps, OAuthProviderConfig } from './types.ts';
+export declare function registerOAuthClient(config: OAuthProviderConfig, redirectUri: string, fetchImpl?: OAuthFetch): Promise<string>;
+export declare function resolveDynamicClientId(config: OAuthProviderConfig, redirectUri: string, deps: OAuthFlowDeps, fetchImpl?: OAuthFetch): Promise<string>;

package/dist-lib/lib/oauth/register.js

@@ -0,0 +1,34 @@
+import * as z from 'zod';
+const RegistrationResponseSchema = z.object({
+    client_id: z.string().min(1)
+});
+export async function registerOAuthClient(config, redirectUri, fetchImpl = globalThis.fetch) {
+    if (!config.registrationEndpoint) {
+        throw new Error('Dynamic client registration requested without a registration endpoint');
+    }
+    const response = await fetchImpl(config.registrationEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+            client_name: 'QV.AC',
+            redirect_uris: [redirectUri],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+            application_type: 'native'
+        })
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Client registration failed (${response.status}): ${text}`);
+    }
+    return RegistrationResponseSchema.parse(await response.json()).client_id;
+}
+export async function resolveDynamicClientId(config, redirectUri, deps, fetchImpl = globalThis.fetch) {
+    const cached = await deps.getClientId?.();
+    if (cached)
+        return cached;
+    const clientId = await registerOAuthClient(config, redirectUri, fetchImpl);
+    await deps.saveClientId?.(clientId);
+    return clientId;
+}

package/dist-lib/lib/oauth/resolve.d.ts

@@ -0,0 +1,17 @@
+import { type ConfigEngine, type Fetch, type OAuthTokens } from './common.ts';
+type RefreshFn = (opts: {
+    clientId: string;
+    clientSecret?: string;
+    refreshToken: string;
+    fetch?: Fetch;
+}) => Promise<OAuthTokens>;
+export declare function resolveOAuthCredential(opts: {
+    engine: ConfigEngine;
+    agentId?: string;
+    credentialKey: string;
+    stateKey: string;
+    refresh: RefreshFn;
+    requireClientSecret?: boolean;
+    fetch?: Fetch;
+}): Promise<string | null>;
+export {};

package/dist-lib/lib/oauth/resolve.js

@@ -0,0 +1,57 @@
+import { REFRESH_SKEW_MS, scopedKey } from "./common.js";
+const inFlightRefresh = new Map();
+export async function resolveOAuthCredential(opts) {
+    const { engine, agentId, credentialKey, stateKey, refresh, requireClientSecret = false } = opts;
+    const { value: token } = await engine.configGet({ key: scopedKey(agentId, credentialKey) });
+    if (typeof token !== 'string')
+        return null;
+    const { value: raw } = await engine.configGet({ key: scopedKey(agentId, stateKey) });
+    if (typeof raw !== 'string')
+        return token;
+    let stored;
+    try {
+        stored = JSON.parse(raw);
+    }
+    catch {
+        return token;
+    }
+    const { refreshToken, expiresAt, clientId, clientSecret } = stored ?? {};
+    if (!refreshToken || !clientId)
+        return token;
+    if (requireClientSecret && !clientSecret)
+        return token;
+    if (typeof expiresAt !== 'number' || expiresAt - REFRESH_SKEW_MS > Date.now())
+        return token;
+    const refreshKey = `${credentialKey}:${agentId ?? ''}`;
+    try {
+        let pending = inFlightRefresh.get(refreshKey);
+        if (!pending) {
+            pending = (async () => {
+                const refreshed = await refresh({
+                    clientId,
+                    clientSecret,
+                    refreshToken,
+                    fetch: opts.fetch
+                });
+                await engine.configSet({
+                    key: scopedKey(agentId, credentialKey),
+                    value: refreshed.accessToken
+                });
+                await engine.configSet({
+                    key: scopedKey(agentId, stateKey),
+                    value: JSON.stringify({
+                        ...stored,
+                        refreshToken: refreshed.refreshToken,
+                        expiresAt: refreshed.expiresAt
+                    })
+                });
+                return refreshed.accessToken;
+            })().finally(() => inFlightRefresh.delete(refreshKey));
+            inFlightRefresh.set(refreshKey, pending);
+        }
+        return await pending;
+    }
+    catch {
+        return token;
+    }
+}

package/dist-lib/lib/oauth/spotify.d.ts

@@ -0,0 +1,32 @@
+import { type ConfigEngine, type Fetch, type OAuthTokens } from './common.ts';
+export declare const SPOTIFY_CREDENTIAL_KEY = "spotify_access_token";
+export declare const SPOTIFY_OAUTH_STATE_KEY = "spotify_oauth";
+export declare const SPOTIFY_OAUTH_PORT = 18974;
+export type SpotifyTokens = OAuthTokens;
+export declare function buildSpotifyAuthUrl(opts: {
+    clientId: string;
+    state: string;
+    challenge: string;
+}): string;
+export declare function exchangeSpotifyCode(opts: {
+    clientId: string;
+    code: string;
+    verifier: string;
+    fetch?: Fetch;
+}): Promise<SpotifyTokens>;
+export declare function refreshSpotifyToken(opts: {
+    clientId: string;
+    refreshToken: string;
+    fetch?: Fetch;
+}): Promise<SpotifyTokens>;
+export declare function connectSpotify(opts: {
+    clientId: string;
+    openUrl: (url: string) => unknown;
+    fetch?: Fetch;
+    timeoutMs?: number;
+}): Promise<SpotifyTokens>;
+export declare function resolveSpotifyCredential(opts: {
+    engine: ConfigEngine;
+    agentId?: string;
+    fetch?: Fetch;
+}): Promise<string | null>;