@openparachute/agent 0.1.0

package/src/oauth/app-configs.ts

@@ -0,0 +1,114 @@
+/**
+ * BYOC client config DB layer — one row per provider.
+ *
+ * `client_secret` is encrypted at rest. The plaintext is materialized
+ * only at authorize-URL build time (`buildAuthorizeUrl`) and at token
+ * exchange (`exchangeCode`); never returned through the API.
+ */
+import crypto from 'crypto';
+
+import { getDb } from '../db/connection.js';
+import type { Database } from '../db/connection.js';
+import { decryptOauthClient, encryptOauthClient } from './crypto.js';
+
+export interface AppConfigRow {
+  id: string;
+  provider: string;
+  client_id: string;
+  scopes_default: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface RawAppConfigRow extends AppConfigRow {
+  client_secret_encrypted: string;
+}
+
+function db(): Database {
+  return getDb();
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+const PUBLIC_COLS = `id, provider, client_id, scopes_default, created_at, updated_at`;
+
+/** Returns the public (non-secret) shape; never decrypts. */
+export function getAppConfig(provider: string): AppConfigRow | undefined {
+  return db()
+    .prepare<AppConfigRow>(`SELECT ${PUBLIC_COLS} FROM app_configs WHERE provider = @provider`)
+    .get({ provider });
+}
+
+/** Returns the decrypted client_secret + public fields. Internal use only. */
+export function getAppConfigWithSecret(provider: string): (AppConfigRow & { client_secret: string }) | undefined {
+  const row = db().prepare<RawAppConfigRow>(`SELECT * FROM app_configs WHERE provider = @provider`).get({ provider });
+  if (!row) return undefined;
+  const { client_secret_encrypted, ...rest } = row;
+  return { ...rest, client_secret: decryptOauthClient(client_secret_encrypted) };
+}
+
+export function listAppConfigs(): AppConfigRow[] {
+  return db().prepare<AppConfigRow>(`SELECT ${PUBLIC_COLS} FROM app_configs ORDER BY provider`).all();
+}
+
+export interface PutAppConfigOpts {
+  client_id: string;
+  client_secret: string;
+  scopes_default?: string;
+}
+
+/** Insert or update a provider's client config. Returns the row's id. */
+export function putAppConfig(provider: string, opts: PutAppConfigOpts): string {
+  const ct = encryptOauthClient(opts.client_secret);
+  const scopes = opts.scopes_default ?? '';
+  const existing = db()
+    .prepare<{ id: string }>(`SELECT id FROM app_configs WHERE provider = @provider`)
+    .get({ provider });
+
+  const now = nowIso();
+  if (existing) {
+    db()
+      .prepare(
+        `UPDATE app_configs
+            SET client_id               = @client_id,
+                client_secret_encrypted = @client_secret_encrypted,
+                scopes_default          = @scopes_default,
+                updated_at              = @updated_at
+          WHERE id = @id`,
+      )
+      .run({
+        id: existing.id,
+        client_id: opts.client_id,
+        client_secret_encrypted: ct,
+        scopes_default: scopes,
+        updated_at: now,
+      });
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  db()
+    .prepare(
+      `INSERT INTO app_configs
+         (id, provider, client_id, client_secret_encrypted, scopes_default, created_at, updated_at)
+       VALUES
+         (@id, @provider, @client_id, @client_secret_encrypted, @scopes_default, @created_at, @updated_at)`,
+    )
+    .run({
+      id,
+      provider,
+      client_id: opts.client_id,
+      client_secret_encrypted: ct,
+      scopes_default: scopes,
+      created_at: now,
+      updated_at: now,
+    });
+  return id;
+}
+
+export function deleteAppConfig(provider: string): boolean {
+  const r = db().prepare(`DELETE FROM app_configs WHERE provider = @provider`).run({ provider });
+  return r.changes > 0;
+}

package/src/oauth/app-connections.test.ts

@@ -0,0 +1,109 @@
+import crypto from 'crypto';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { closeDb, initTestDb, runMigrations } from '../db/index.js';
+import { _setMasterKeyForTest } from '../secrets/master-key.js';
+import { putAppConfig } from './app-configs.js';
+import {
+  deleteAppConnection,
+  getAppConnection,
+  getAppConnectionWithTokens,
+  listAppConnections,
+  upsertAppConnection,
+} from './app-connections.js';
+
+let configId: string;
+
+beforeEach(() => {
+  const db = initTestDb();
+  runMigrations(db);
+  _setMasterKeyForTest(crypto.randomBytes(32));
+  configId = putAppConfig('google', { client_id: 'cid', client_secret: 'csec' });
+});
+
+afterEach(() => closeDb());
+
+describe('app_connections DB layer', () => {
+  it('inserts and round-trips encrypted tokens', () => {
+    const id = upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-1',
+      account_email: 'a@example.com',
+      access_token: 'access-1',
+      refresh_token: 'refresh-1',
+      label: 'a@example.com',
+    });
+    const decrypted = getAppConnectionWithTokens(id);
+    expect(decrypted?.access_token).toBe('access-1');
+    expect(decrypted?.refresh_token).toBe('refresh-1');
+    expect(decrypted?.account_email).toBe('a@example.com');
+  });
+
+  it('hides token columns from public reads', () => {
+    const id = upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-1',
+      access_token: 'access-1',
+      label: 'a',
+    });
+    const row = getAppConnection(id) as Record<string, unknown> | undefined;
+    expect(row).toBeDefined();
+    expect(row).not.toHaveProperty('access_token');
+    expect(row).not.toHaveProperty('access_token_encrypted');
+    expect(row).not.toHaveProperty('refresh_token');
+  });
+
+  it('upserts on (app_config_id, account_id) — same id, refreshed tokens', () => {
+    const id1 = upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-1',
+      access_token: 'old',
+      label: 'a',
+    });
+    const id2 = upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-1',
+      access_token: 'new',
+      refresh_token: 'rnew',
+      label: 'a',
+    });
+    expect(id1).toBe(id2);
+    expect(getAppConnectionWithTokens(id1)?.access_token).toBe('new');
+    expect(getAppConnectionWithTokens(id1)?.refresh_token).toBe('rnew');
+  });
+
+  it('treats different account_ids as separate connections', () => {
+    upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-1',
+      access_token: 't1',
+      label: 'a',
+    });
+    upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-2',
+      access_token: 't2',
+      label: 'b',
+    });
+    expect(listAppConnections()).toHaveLength(2);
+  });
+
+  it('deletes by id', () => {
+    const id = upsertAppConnection({
+      app_config_id: configId,
+      provider: 'google',
+      account_id: 'sub-1',
+      access_token: 'access',
+      label: 'a',
+    });
+    expect(deleteAppConnection(id)).toBe(true);
+    expect(getAppConnection(id)).toBeUndefined();
+    expect(deleteAppConnection(id)).toBe(false);
+  });
+});

package/src/oauth/app-connections.ts

@@ -0,0 +1,178 @@
+/**
+ * OAuth grant DB layer — one row per (provider × authorized account).
+ *
+ * `provider` is denormalized onto this table (mig 022) for query speed
+ * and to avoid a join on every list call. `app_config_id` remains the
+ * authoritative FK; provider is just a copy of `app_configs.provider`
+ * filled at upsert time.
+ *
+ * Token columns are AES-GCM ciphertext at rest, encrypted under
+ * domain-separated keys (`paraclaw.oauth.access.v1` /
+ * `paraclaw.oauth.refresh.v1` — see oauth/crypto.ts). The list/get
+ * views in this module strip those columns; only
+ * `getAppConnectionWithTokens` (used by the runtime injection seam,
+ * not the API) decrypts them.
+ */
+import crypto from 'crypto';
+
+import { getDb } from '../db/connection.js';
+import type { Database } from '../db/connection.js';
+import { decryptOauthAccess, decryptOauthRefresh, encryptOauthAccess, encryptOauthRefresh } from './crypto.js';
+
+export interface AppConnectionRow {
+  id: string;
+  app_config_id: string;
+  provider: string;
+  account_email: string | null;
+  account_id: string;
+  scopes_granted: string;
+  expires_at: string | null;
+  label: string;
+  metadata_json: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface AppConnectionWithTokens extends AppConnectionRow {
+  access_token: string;
+  refresh_token: string | null;
+}
+
+interface RawAppConnectionRow extends AppConnectionRow {
+  access_token_encrypted: string;
+  refresh_token_encrypted: string | null;
+}
+
+function db(): Database {
+  return getDb();
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+const PUBLIC_COLS = `
+  id, app_config_id, provider, account_email, account_id, scopes_granted,
+  expires_at, label, metadata_json, created_at, updated_at
+`;
+
+export function listAppConnections(): AppConnectionRow[] {
+  return db().prepare<AppConnectionRow>(`SELECT ${PUBLIC_COLS} FROM app_connections ORDER BY created_at DESC`).all();
+}
+
+export function getAppConnection(id: string): AppConnectionRow | undefined {
+  return db().prepare<AppConnectionRow>(`SELECT ${PUBLIC_COLS} FROM app_connections WHERE id = @id`).get({ id });
+}
+
+/** Internal: returns decrypted tokens. Callers MUST NOT serialize the result. */
+export function getAppConnectionWithTokens(id: string): AppConnectionWithTokens | undefined {
+  const row = db().prepare<RawAppConnectionRow>(`SELECT * FROM app_connections WHERE id = @id`).get({ id });
+  if (!row) return undefined;
+  const { access_token_encrypted, refresh_token_encrypted, ...rest } = row;
+  return {
+    ...rest,
+    access_token: decryptOauthAccess(access_token_encrypted),
+    refresh_token: refresh_token_encrypted ? decryptOauthRefresh(refresh_token_encrypted) : null,
+  };
+}
+
+export interface UpsertConnectionOpts {
+  app_config_id: string;
+  provider: string;
+  account_id: string;
+  account_email?: string | null;
+  access_token: string;
+  refresh_token?: string | null;
+  scopes_granted?: string;
+  expires_at?: string | null;
+  label: string;
+  metadata_json?: string | null;
+}
+
+/**
+ * Upsert a connection keyed on (app_config_id, account_id). Re-authorizing
+ * the same account refreshes tokens + scopes in place rather than creating
+ * a duplicate row.
+ */
+export function upsertAppConnection(opts: UpsertConnectionOpts): string {
+  const accessCt = encryptOauthAccess(opts.access_token);
+  const refreshCt = opts.refresh_token ? encryptOauthRefresh(opts.refresh_token) : null;
+  const scopes = opts.scopes_granted ?? '';
+  const accountEmail = opts.account_email ?? null;
+  const expiresAt = opts.expires_at ?? null;
+  const metadata = opts.metadata_json ?? null;
+
+  const existing = db()
+    .prepare<{ id: string }>(
+      `SELECT id FROM app_connections
+        WHERE app_config_id = @app_config_id AND account_id = @account_id`,
+    )
+    .get({ app_config_id: opts.app_config_id, account_id: opts.account_id });
+
+  const now = nowIso();
+  if (existing) {
+    db()
+      .prepare(
+        `UPDATE app_connections
+            SET provider                = @provider,
+                account_email           = @account_email,
+                access_token_encrypted  = @access_token_encrypted,
+                refresh_token_encrypted = @refresh_token_encrypted,
+                scopes_granted          = @scopes_granted,
+                expires_at              = @expires_at,
+                label                   = @label,
+                metadata_json           = @metadata_json,
+                updated_at              = @updated_at
+          WHERE id = @id`,
+      )
+      .run({
+        id: existing.id,
+        provider: opts.provider,
+        account_email: accountEmail,
+        access_token_encrypted: accessCt,
+        refresh_token_encrypted: refreshCt,
+        scopes_granted: scopes,
+        expires_at: expiresAt,
+        label: opts.label,
+        metadata_json: metadata,
+        updated_at: now,
+      });
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  db()
+    .prepare(
+      `INSERT INTO app_connections
+         (id, app_config_id, provider, account_email, account_id,
+          access_token_encrypted, refresh_token_encrypted,
+          scopes_granted, expires_at, label, metadata_json,
+          created_at, updated_at)
+       VALUES
+         (@id, @app_config_id, @provider, @account_email, @account_id,
+          @access_token_encrypted, @refresh_token_encrypted,
+          @scopes_granted, @expires_at, @label, @metadata_json,
+          @created_at, @updated_at)`,
+    )
+    .run({
+      id,
+      app_config_id: opts.app_config_id,
+      provider: opts.provider,
+      account_email: accountEmail,
+      account_id: opts.account_id,
+      access_token_encrypted: accessCt,
+      refresh_token_encrypted: refreshCt,
+      scopes_granted: scopes,
+      expires_at: expiresAt,
+      label: opts.label,
+      metadata_json: metadata,
+      created_at: now,
+      updated_at: now,
+    });
+  return id;
+}
+
+export function deleteAppConnection(id: string): boolean {
+  const r = db().prepare(`DELETE FROM app_connections WHERE id = @id`).run({ id });
+  return r.changes > 0;
+}

package/src/oauth/crypto.ts

@@ -0,0 +1,56 @@
+/**
+ * Three domain-separated HKDF-derived keys for OAuth secrets:
+ *
+ *   - paraclaw.oauth.client.v1   → app_configs.client_secret_encrypted
+ *   - paraclaw.oauth.access.v1   → app_connections.access_token_encrypted
+ *   - paraclaw.oauth.refresh.v1  → app_connections.refresh_token_encrypted
+ *
+ * Three subkeys instead of one because compromise of one rotation surface
+ * (e.g. refresh tokens accidentally surfaced in a log) shouldn't yield
+ * decryption power on the others. Bumping any `v<n>` suffix is a
+ * per-domain key rotation.
+ *
+ * ⚠ The `paraclaw.` prefix is a cryptographic domain separator and is
+ * intentionally retained across the paraclaw → parachute-agent rename.
+ * The HKDF info string is mixed into key derivation; renaming it would
+ * derive a different key and render every existing OAuth ciphertext row
+ * (client secrets, access tokens, refresh tokens) undecryptable. The
+ * brand sweep is operator-visible only — these bytes are forever.
+ */
+import { deriveKey, encryptSecret, decryptSecret } from '../secrets/crypto.js';
+import { loadOrCreateMasterKey } from '../secrets/master-key.js';
+
+const CLIENT_INFO = 'paraclaw.oauth.client.v1';
+const ACCESS_INFO = 'paraclaw.oauth.access.v1';
+const REFRESH_INFO = 'paraclaw.oauth.refresh.v1';
+
+function clientKey(): Buffer {
+  return deriveKey(loadOrCreateMasterKey(), CLIENT_INFO);
+}
+function accessKey(): Buffer {
+  return deriveKey(loadOrCreateMasterKey(), ACCESS_INFO);
+}
+function refreshKey(): Buffer {
+  return deriveKey(loadOrCreateMasterKey(), REFRESH_INFO);
+}
+
+export function encryptOauthClient(plaintext: string): string {
+  return encryptSecret(plaintext, clientKey());
+}
+export function decryptOauthClient(ciphertext: string): string {
+  return decryptSecret(ciphertext, clientKey());
+}
+
+export function encryptOauthAccess(plaintext: string): string {
+  return encryptSecret(plaintext, accessKey());
+}
+export function decryptOauthAccess(ciphertext: string): string {
+  return decryptSecret(ciphertext, accessKey());
+}
+
+export function encryptOauthRefresh(plaintext: string): string {
+  return encryptSecret(plaintext, refreshKey());
+}
+export function decryptOauthRefresh(ciphertext: string): string {
+  return decryptSecret(ciphertext, refreshKey());
+}

package/src/oauth/flow.ts

@@ -0,0 +1,104 @@
+/**
+ * Provider-agnostic OAuth flow primitives.
+ *
+ *   1. `buildAuthorizeUrl` — assembles the redirect URL the user's
+ *      browser hits to consent. Includes client_id, scope, state,
+ *      redirect_uri, plus provider-specific extras (e.g. Google's
+ *      `access_type=offline`).
+ *   2. `exchangeCode` — POST to the token endpoint with the auth code
+ *      from the callback. Returns the raw token payload.
+ *   3. `fetchUserinfo` — pulls the provider's userinfo with the
+ *      newly-minted access token; the caller passes it through
+ *      `provider.extractAccount` to derive the row's `label` /
+ *      `account_email` / `account_id`.
+ *   4. `revokeToken` — best-effort; provider returning non-2xx is logged
+ *      but doesn't block local row deletion.
+ */
+import { log } from '../log.js';
+import type { ProviderSpec } from './providers/index.js';
+
+export interface TokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+  token_type?: string;
+  id_token?: string;
+}
+
+export function buildAuthorizeUrl(opts: {
+  provider: ProviderSpec;
+  clientId: string;
+  scopes: string;
+  state: string;
+  redirectUri: string;
+}): string {
+  const u = new URL(opts.provider.authUrl);
+  u.searchParams.set('client_id', opts.clientId);
+  u.searchParams.set('redirect_uri', opts.redirectUri);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('scope', opts.scopes || opts.provider.defaultScopes);
+  u.searchParams.set('state', opts.state);
+  for (const [k, v] of Object.entries(opts.provider.extraAuthParams ?? {})) {
+    u.searchParams.set(k, v);
+  }
+  return u.toString();
+}
+
+export async function exchangeCode(opts: {
+  provider: ProviderSpec;
+  clientId: string;
+  clientSecret: string;
+  code: string;
+  redirectUri: string;
+}): Promise<TokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: opts.code,
+    client_id: opts.clientId,
+    client_secret: opts.clientSecret,
+    redirect_uri: opts.redirectUri,
+  });
+  const res = await fetch(opts.provider.tokenUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+    body,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`token exchange ${res.status}: ${text}`);
+  }
+  return (await res.json()) as TokenResponse;
+}
+
+export async function fetchUserinfo(opts: { provider: ProviderSpec; accessToken: string }): Promise<unknown> {
+  const res = await fetch(opts.provider.userinfoUrl, {
+    headers: { authorization: `Bearer ${opts.accessToken}`, accept: 'application/json' },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`userinfo ${res.status}: ${text}`);
+  }
+  return await res.json();
+}
+
+/** Best-effort. Returns true on 2xx, false otherwise (and logs). */
+export async function revokeToken(opts: { provider: ProviderSpec; accessToken: string }): Promise<boolean> {
+  if (!opts.provider.revokeUrl) return false;
+  try {
+    const u = new URL(opts.provider.revokeUrl);
+    u.searchParams.set('token', opts.accessToken);
+    const res = await fetch(u.toString(), { method: 'POST' });
+    if (!res.ok) {
+      log.warn('oauth revoke non-2xx', { provider: opts.provider.slug, status: res.status });
+      return false;
+    }
+    return true;
+  } catch (err) {
+    log.warn('oauth revoke failed', {
+      provider: opts.provider.slug,
+      err: err instanceof Error ? err.message : String(err),
+    });
+    return false;
+  }
+}

package/src/oauth/providers/google.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { GoogleProvider } from './google.js';
+import { getProvider, listProviderSlugs } from './index.js';
+
+describe('GoogleProvider', () => {
+  it('is registered under slug "google"', () => {
+    expect(getProvider('google')).toBe(GoogleProvider);
+    expect(listProviderSlugs()).toContain('google');
+  });
+
+  it('extracts account from a typical userinfo response', () => {
+    const got = GoogleProvider.extractAccount({
+      sub: '108234567890',
+      email: 'alice@example.com',
+      name: 'Alice',
+    });
+    expect(got.accountId).toBe('108234567890');
+    expect(got.accountEmail).toBe('alice@example.com');
+    expect(got.label).toBe('alice@example.com');
+  });
+
+  it('falls back to name then "google:<sub>" when email is missing', () => {
+    expect(GoogleProvider.extractAccount({ sub: '1', name: 'Bob' }).label).toBe('Bob');
+    expect(GoogleProvider.extractAccount({ sub: '2' }).label).toBe('google:2');
+  });
+
+  it('throws when sub is missing', () => {
+    expect(() => GoogleProvider.extractAccount({ email: 'no-sub@example.com' })).toThrow(/missing `sub`/);
+  });
+
+  it('declares offline access + consent so refresh_token is always issued', () => {
+    expect(GoogleProvider.extraAuthParams).toMatchObject({
+      access_type: 'offline',
+      prompt: 'consent',
+    });
+  });
+});

package/src/oauth/providers/google.ts

@@ -0,0 +1,46 @@
+/**
+ * Google OAuth provider — covers Gmail, Calendar, Drive, Docs, Sheets,
+ * etc. all under one client. Operator registers a single Google Cloud
+ * Console OAuth 2.0 client and grants whatever scopes the agent needs;
+ * paraclaw stores the resulting tokens once.
+ *
+ * Userinfo response shape (from `https://openidconnect.googleapis.com/v1/userinfo`):
+ *   { "sub": "123…", "email": "alice@example.com", "name": "Alice", … }
+ *
+ * `sub` is Google's stable account ID and is what we key on. `email`
+ * goes into both `account_email` and the auto-generated `label`.
+ */
+import type { ProviderSpec, UserinfoExtract } from './index.js';
+
+interface GoogleUserinfo {
+  sub?: string;
+  email?: string;
+  name?: string;
+  picture?: string;
+}
+
+export const GoogleProvider: ProviderSpec = {
+  slug: 'google',
+  displayName: 'Google',
+  authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+  tokenUrl: 'https://oauth2.googleapis.com/token',
+  userinfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+  revokeUrl: 'https://oauth2.googleapis.com/revoke',
+  defaultScopes: 'openid email profile',
+  // access_type=offline + prompt=consent ensures Google issues a
+  // refresh_token even on subsequent authorizations of the same account.
+  extraAuthParams: {
+    access_type: 'offline',
+    prompt: 'consent',
+    include_granted_scopes: 'true',
+  },
+  extractAccount(userinfo: unknown): UserinfoExtract {
+    const u = (userinfo ?? {}) as GoogleUserinfo;
+    if (!u.sub) {
+      throw new Error('google userinfo response missing `sub` (account id)');
+    }
+    const email = u.email ?? null;
+    const label = email ?? u.name ?? `google:${u.sub}`;
+    return { accountId: u.sub, accountEmail: email, label };
+  },
+};

package/src/oauth/providers/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Provider registry. New providers (Slack, GitHub, Notion, …) plug in
+ * by exporting a `ProviderSpec` and adding it to `PROVIDERS` below.
+ */
+import { GoogleProvider } from './google.js';
+
+export interface UserinfoExtract {
+  accountId: string;
+  accountEmail: string | null;
+  label: string;
+}
+
+export interface ProviderSpec {
+  /** Slug used in URLs: `/api/apps/:provider/...` */
+  slug: string;
+  /** Human-readable name for the UI. */
+  displayName: string;
+  /** OAuth 2.0 authorization endpoint. */
+  authUrl: string;
+  /** OAuth 2.0 token endpoint. */
+  tokenUrl: string;
+  /** Userinfo endpoint — called post-token-exchange to populate label/email. */
+  userinfoUrl: string;
+  /** Provider-specific token revocation endpoint, or null if not supported. */
+  revokeUrl: string | null;
+  /** Default scope string (space-separated) when the operator doesn't override. */
+  defaultScopes: string;
+  /** Optional extra params on the authorize URL (e.g. Google's access_type=offline). */
+  extraAuthParams?: Record<string, string>;
+  /** Parse the userinfo JSON into account_id + email + label. */
+  extractAccount(userinfo: unknown): UserinfoExtract;
+}
+
+const PROVIDERS: Record<string, ProviderSpec> = {
+  [GoogleProvider.slug]: GoogleProvider,
+};
+
+export function getProvider(slug: string): ProviderSpec | undefined {
+  return PROVIDERS[slug];
+}
+
+export function listProviderSlugs(): string[] {
+  return Object.keys(PROVIDERS).sort();
+}
+
+export function listProviders(): ProviderSpec[] {
+  return Object.values(PROVIDERS).sort((a, b) => a.slug.localeCompare(b.slug));
+}