@moxxy/plugin-oauth 0.0.33

package/src/profile.test.ts

@@ -0,0 +1,331 @@
+import { describe, expect, it, vi } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import {
+  openaiDeviceFlow,
+  pollUntil,
+  readStoredCreds,
+  rfc8628DeviceFlow,
+  storeTokenSet,
+  type OAuthVault,
+  type PollOutcome,
+  type TokenSet,
+} from './index.js';
+
+function newFakeVault(): OAuthVault & { dump(): Record<string, string> } {
+  const store = new Map<string, string>();
+  return {
+    async get(key) {
+      return store.has(key) ? store.get(key)! : null;
+    },
+    async set(key, value) {
+      store.set(key, value);
+    },
+    async delete(key) {
+      return store.delete(key);
+    },
+    dump() {
+      return Object.fromEntries(store);
+    },
+  };
+}
+
+describe('pollUntil', () => {
+  it('returns the first `done` value', async () => {
+    let calls = 0;
+    const result = await pollUntil<string>(
+      async () => {
+        calls += 1;
+        if (calls < 3) return { pending: true };
+        return { done: 'ok' };
+      },
+      { intervalMs: 1, timeoutMs: 1000, leadingWait: false },
+    );
+    expect(result).toBe('ok');
+    expect(calls).toBe(3);
+  });
+
+  it('throws a typed OAUTH_FLOW_TIMEOUT MoxxyError when the deadline elapses', async () => {
+    const err = await pollUntil<string>(
+      async () => ({ pending: true }),
+      { intervalMs: 1, timeoutMs: 5, leadingWait: false },
+    ).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('OAUTH_FLOW_TIMEOUT');
+    expect((err as MoxxyError).message).toMatch(/timed out/);
+  });
+
+  it('respects an in-flight abort signal (typed NETWORK_ABORTED MoxxyError)', async () => {
+    const ctrl = new AbortController();
+    const p = pollUntil<string>(
+      async () => ({ pending: true }),
+      { intervalMs: 100, timeoutMs: 1000, signal: ctrl.signal, leadingWait: false },
+    );
+    setTimeout(() => ctrl.abort(), 10);
+    const err = await p.catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('NETWORK_ABORTED');
+    expect((err as MoxxyError).message).toMatch(/aborted/);
+  });
+
+  it('throws a typed NETWORK_ABORTED MoxxyError when the signal is already aborted', async () => {
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const err = await pollUntil<string>(
+      async () => ({ pending: true }),
+      { intervalMs: 1, timeoutMs: 1000, signal: ctrl.signal },
+    ).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('NETWORK_ABORTED');
+  });
+
+  it('lets the polling fn bump state.intervalMs', async () => {
+    let bumpedOnce = false;
+    const calls: number[] = [];
+    await pollUntil<string>(
+      async (state) => {
+        calls.push(state.intervalMs);
+        if (!bumpedOnce) {
+          state.intervalMs += 50;
+          bumpedOnce = true;
+          return { pending: true };
+        }
+        return { done: 'x' };
+      },
+      { intervalMs: 1, timeoutMs: 1000, leadingWait: false },
+    );
+    expect(calls).toEqual([1, 51]);
+  });
+});
+
+describe('storage extras round-trip', () => {
+  it('persists + restores arbitrary string extras', async () => {
+    const vault = newFakeVault();
+    const tokens: TokenSet = {
+      accessToken: 'AT',
+      refreshToken: 'RT',
+      expiresAt: Date.now() + 60_000,
+      tokenType: 'Bearer',
+    };
+    await storeTokenSet(vault, 'demo', tokens, {
+      clientId: 'CID',
+      tokenUrl: 'https://example.test/token',
+      extras: { account_id: 'acct_123', team_slug: 'eng' },
+    });
+    const stored = await readStoredCreds(vault, 'demo');
+    expect(stored).not.toBeNull();
+    expect(stored!.extras).toEqual({ account_id: 'acct_123', team_slug: 'eng' });
+    expect(stored!.tokenSet.accessToken).toBe('AT');
+  });
+
+  it('returns an empty extras map when none were stored', async () => {
+    const vault = newFakeVault();
+    await storeTokenSet(vault, 'demo', { accessToken: 'AT', tokenType: 'Bearer' }, {
+      clientId: 'CID',
+      tokenUrl: 'https://example.test/token',
+    });
+    const stored = await readStoredCreds(vault, 'demo');
+    expect(stored!.extras).toEqual({});
+  });
+});
+
+describe('rfc8628DeviceFlow adapter', () => {
+  it('start() POSTs form-encoded client_id+scope and parses the init', async () => {
+    const fetchSpy = vi.fn(async (url: RequestInfo | URL, init: RequestInit) => {
+      expect(String(url)).toBe('https://example.test/device/code');
+      expect(init.method).toBe('POST');
+      const body = new URLSearchParams(String(init.body ?? ''));
+      expect(body.get('client_id')).toBe('CID');
+      expect(body.get('scope')).toBe('openid email');
+      return new Response(
+        JSON.stringify({
+          device_code: 'DEV',
+          user_code: 'AB-CD',
+          verification_uri: 'https://example.test/device',
+          interval: 3,
+          expires_in: 600,
+        }),
+        { status: 200 },
+      );
+    });
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = fetchSpy as unknown as typeof fetch;
+    try {
+      const adapter = rfc8628DeviceFlow({
+        deviceUrl: 'https://example.test/device/code',
+        tokenUrl: 'https://example.test/token',
+      });
+      const init = await adapter.start({ clientId: 'CID', scopes: ['openid', 'email'] });
+      expect(init.userCode).toBe('AB-CD');
+      expect(init.verificationUri).toBe('https://example.test/device');
+      expect(init.intervalMs).toBe(3000);
+      expect(init.expiresInMs).toBe(600_000);
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+
+  it('poll() classifies authorization_pending / slow_down / done', async () => {
+    const adapter = rfc8628DeviceFlow({
+      deviceUrl: 'https://example.test/device/code',
+      tokenUrl: 'https://example.test/token',
+    });
+    const init = {
+      userCode: 'X',
+      verificationUri: 'https://example.test/device',
+      intervalMs: 5000,
+      expiresInMs: 60_000,
+      providerData: { deviceCode: 'DEV' },
+    };
+
+    const realFetch = globalThis.fetch;
+    const responses: Array<() => Response> = [
+      () =>
+        new Response(JSON.stringify({ error: 'authorization_pending' }), { status: 400 }),
+      () => new Response(JSON.stringify({ error: 'slow_down' }), { status: 400 }),
+      () =>
+        new Response(
+          JSON.stringify({ access_token: 'AT', refresh_token: 'RT', expires_in: 3600 }),
+          { status: 200 },
+        ),
+    ];
+    globalThis.fetch = (async () => responses.shift()!()) as unknown as typeof fetch;
+    try {
+      const state = { intervalMs: 5000 };
+      const r1 = await adapter.poll(init, state);
+      expect('pending' in r1 && r1.pending).toBe(true);
+      const r2 = await adapter.poll(init, state);
+      expect('pending' in r2 && r2.pending).toBe(true);
+      expect(state.intervalMs).toBe(10_000);
+      const r3 = (await adapter.poll(init, state)) as Extract<
+        PollOutcome<TokenSet>,
+        { done: TokenSet }
+      >;
+      expect(r3.done.accessToken).toBe('AT');
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+});
+
+describe('openaiDeviceFlow adapter', () => {
+  it('start() POSTs JSON client_id and stashes device_auth_id', async () => {
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: RequestInfo | URL, init: RequestInit) => {
+      expect(String(url)).toBe('https://issuer.test/api/accounts/deviceauth/usercode');
+      expect(init.headers).toMatchObject({ 'Content-Type': 'application/json' });
+      const parsed = JSON.parse(String(init.body ?? '{}'));
+      expect(parsed.client_id).toBe('CID');
+      return new Response(
+        JSON.stringify({ device_auth_id: 'DA', user_code: 'XYZ', interval: 4 }),
+        { status: 200 },
+      );
+    }) as unknown as typeof fetch;
+    try {
+      const adapter = openaiDeviceFlow({
+        issuer: 'https://issuer.test',
+        tokenUrl: 'https://issuer.test/oauth/token',
+        verificationUri: 'https://issuer.test/codex/device',
+      });
+      const init = await adapter.start({ clientId: 'CID', scopes: ['openid'] });
+      expect(init.userCode).toBe('XYZ');
+      expect(init.verificationUri).toBe('https://issuer.test/codex/device');
+      expect(init.intervalMs).toBe(4000);
+      expect((init.providerData as { deviceAuthId: string }).deviceAuthId).toBe('DA');
+      expect((init.providerData as { clientId: string }).clientId).toBe('CID');
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+
+  it('poll() returns pending on 403/404 and exchanges authorization_code on success', async () => {
+    const adapter = openaiDeviceFlow({
+      issuer: 'https://issuer.test',
+      tokenUrl: 'https://issuer.test/oauth/token',
+      verificationUri: 'https://issuer.test/codex/device',
+    });
+    const init = {
+      userCode: 'XYZ',
+      verificationUri: 'https://issuer.test/codex/device',
+      intervalMs: 4000,
+      expiresInMs: 600_000,
+      providerData: { deviceAuthId: 'DA', userCode: 'XYZ', clientId: 'CID' },
+    };
+
+    const realFetch = globalThis.fetch;
+    let call = 0;
+    globalThis.fetch = (async (url: RequestInfo | URL, init?: RequestInit) => {
+      call += 1;
+      if (call === 1) {
+        expect(String(url)).toBe('https://issuer.test/api/accounts/deviceauth/token');
+        return new Response('', { status: 403 });
+      }
+      if (call === 2) {
+        return new Response(
+          JSON.stringify({ authorization_code: 'CODE', code_verifier: 'V' }),
+          { status: 200 },
+        );
+      }
+      // Third call: exchange via /oauth/token
+      expect(String(url)).toBe('https://issuer.test/oauth/token');
+      const body = new URLSearchParams(String(init?.body ?? ''));
+      expect(body.get('grant_type')).toBe('authorization_code');
+      expect(body.get('code')).toBe('CODE');
+      expect(body.get('code_verifier')).toBe('V');
+      expect(body.get('client_id')).toBe('CID');
+      expect(body.get('redirect_uri')).toBe('https://issuer.test/deviceauth/callback');
+      return new Response(
+        JSON.stringify({ access_token: 'AT', refresh_token: 'RT', expires_in: 3600 }),
+        { status: 200 },
+      );
+    }) as unknown as typeof fetch;
+    try {
+      const state = { intervalMs: 4000 };
+      const pending = await adapter.poll(init, state);
+      expect('pending' in pending && pending.pending).toBe(true);
+      const done = (await adapter.poll(init, state)) as Extract<
+        PollOutcome<TokenSet>,
+        { done: TokenSet }
+      >;
+      expect(done.done.accessToken).toBe('AT');
+      expect(done.done.refreshToken).toBe('RT');
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+
+  it('poll() surfaces a classified MoxxyError when the shared exchange returns non-ok', async () => {
+    const adapter = openaiDeviceFlow({
+      issuer: 'https://issuer.test',
+      tokenUrl: 'https://issuer.test/oauth/token',
+      verificationUri: 'https://issuer.test/codex/device',
+    });
+    const init = {
+      userCode: 'XYZ',
+      verificationUri: 'https://issuer.test/codex/device',
+      intervalMs: 4000,
+      expiresInMs: 600_000,
+      providerData: { deviceAuthId: 'DA', userCode: 'XYZ', clientId: 'CID' },
+    };
+
+    const realFetch = globalThis.fetch;
+    let call = 0;
+    globalThis.fetch = (async () => {
+      call += 1;
+      // 1st: poll returns the authorization_code; 2nd: the exchange rejects.
+      if (call === 1) {
+        return new Response(
+          JSON.stringify({ authorization_code: 'CODE', code_verifier: 'V' }),
+          { status: 200 },
+        );
+      }
+      return new Response('bad request', { status: 400 });
+    }) as unknown as typeof fetch;
+    try {
+      const state = { intervalMs: 4000 };
+      const err = await adapter.poll(init, state).catch((e) => e);
+      expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+});

package/src/profile.ts

@@ -0,0 +1,135 @@
+/**
+ * Provider-framework types. A new OAuth provider plugs in by exporting an
+ * `OAuthProviderProfile` and (if it supports device-flow) one of the bundled
+ * adapters — or a custom adapter for a non-standard dialect.
+ *
+ * The host then calls `runOauthLogin(profile, ctx)` to drive the full dance
+ * and `ensureFreshTokens(profile, vault)` before each upstream request to
+ * keep the access token fresh.
+ */
+
+import type { PollOutcome, PollState } from './oauth/poll-until.js';
+import type { TokenSet } from './oauth/types.js';
+
+/**
+ * Single source of truth for everything OAuth-related about a provider.
+ * Constants + extraction logic live here; the framework handles the
+ * actual HTTP / vault / refresh plumbing.
+ */
+export interface OAuthProviderProfile {
+  /**
+   * Stable namespace under `oauth/<id>/*` in the vault. Lowercase,
+   * digits, dot/dash/underscore only — same rules as `validateProvider`.
+   * Example: `'openai-codex'`, `'google'`, `'github'`.
+   */
+  readonly id: string;
+  /** Authorization endpoint, e.g. https://accounts.google.com/o/oauth2/v2/auth */
+  readonly authUrl: string;
+  /** Token endpoint, e.g. https://oauth2.googleapis.com/token */
+  readonly tokenUrl: string;
+  readonly clientId: string;
+  /** Confidential clients only — loopback flows usually omit. */
+  readonly clientSecret?: string;
+  readonly scopes: ReadonlyArray<string>;
+  /**
+   * Provider-specific auth-URL params. Google wants
+   * `access_type=offline` + `prompt=consent` for a refresh_token; Codex
+   * wants `id_token_add_organizations=true` etc.
+   */
+  readonly extraAuthParams?: Readonly<Record<string, string>>;
+  /**
+   * Loopback callback config. Provider's registered redirect URI must
+   * match `http://localhost:<port><path>` EXACTLY.
+   */
+  readonly redirect?: {
+    readonly port?: number;
+    readonly path?: string;
+  };
+  /**
+   * Device-flow adapter. Omit when the provider doesn't support a
+   * headless flow — `runOauthLogin` will reject `headless=true` with a
+   * helpful message.
+   */
+  readonly deviceFlow?: DeviceFlowAdapter;
+  /**
+   * Pull a stable per-account identifier out of the token set. Codex
+   * extracts `chatgpt_account_id` from the id_token; Google could
+   * extract `email`. Returned value is shown to the user post-login and
+   * persisted under `extras.account_id`. Optional — providers that
+   * don't expose a useful identifier skip it.
+   */
+  readonly extractAccountId?: (tokens: TokenSet) => string | undefined;
+  /**
+   * Extract extra provider-specific fields to persist alongside the
+   * token set (e.g. `team_slug`, `org_id`). Merged with the account_id
+   * (if any) into the `extras` map under `oauth/<id>/extras`.
+   */
+  readonly extractExtras?: (tokens: TokenSet) => Readonly<Record<string, string>>;
+  /**
+   * Human-readable name used in prompts and success messages, e.g.
+   * "ChatGPT Pro/Plus", "Google Workspace". Falls back to `id` when omitted.
+   */
+  readonly displayName?: string;
+}
+
+/**
+ * Pluggable device-flow contract. Implementations encode a single dialect
+ * (RFC 8628, OpenAI's flavor, ...). The framework calls `start()` once,
+ * surfaces the returned prompt to the user, then modes on `poll()` via
+ * the shared `pollUntil` primitive.
+ */
+export interface DeviceFlowAdapter {
+  start(args: DeviceFlowStartArgs): Promise<DeviceFlowInit>;
+  /**
+   * Single poll attempt against the provider's poll endpoint. May
+   * mutate `state.intervalMs` to honour a `slow_down` from the server.
+   * Resolves to `{done}` with the issued TokenSet, or `{pending: true}`
+   * to keep polling. Throws on fatal errors (denied / expired).
+   */
+  poll(init: DeviceFlowInit, state: PollState): Promise<PollOutcome<TokenSet>>;
+}
+
+export interface DeviceFlowStartArgs {
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly scopes: ReadonlyArray<string>;
+  readonly signal?: AbortSignal;
+}
+
+export interface DeviceFlowInit {
+  /** Short code the user enters at `verificationUri`. */
+  readonly userCode: string;
+  readonly verificationUri: string;
+  /** Some providers return a URL that already embeds the user_code. */
+  readonly verificationUriComplete?: string;
+  /** Initial poll interval. The framework honours `slow_down` bumps. */
+  readonly intervalMs: number;
+  /** Hard deadline (ms from now) before the device_code dies. */
+  readonly expiresInMs: number;
+  /**
+   * Opaque data the adapter threads from `start()` to `poll()` —
+   * device_code, server-assigned ids, code_verifier, etc. The framework
+   * never inspects this.
+   */
+  readonly providerData: unknown;
+}
+
+export interface RunOauthLoginCtx {
+  readonly vault: {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, tags?: ReadonlyArray<string>): Promise<void>;
+    delete?(key: string): Promise<boolean>;
+  };
+  /** True ⇒ choose the device flow. False ⇒ open a browser. */
+  readonly headless: boolean;
+  /** Progress-message sink. The host wires this to its preferred renderer. */
+  readonly write: (chunk: string) => void;
+  readonly signal?: AbortSignal;
+}
+
+export interface RunOauthLoginResult {
+  readonly tokens: TokenSet;
+  /** Convenience surface for `ProviderOAuthResult.accountId`. */
+  readonly accountId?: string;
+  readonly extras: Readonly<Record<string, string>>;
+}

package/src/run-login.ts

@@ -0,0 +1,123 @@
+/**
+ * High-level orchestrator. Drives the full login dance for any provider
+ * declared via `OAuthProviderProfile` — picks browser or device flow based
+ * on `ctx.headless`, surfaces the user-facing prompt, persists the result
+ * (token set + extras) under `oauth/<profile.id>/*`.
+ */
+
+import { MoxxyError } from '@moxxy/sdk';
+import { runAuthorizationCodeFlow } from './oauth/browser-flow.js';
+import { pollUntil } from './oauth/poll-until.js';
+import { storeTokenSet } from './storage.js';
+import type { TokenSet } from './oauth/types.js';
+import type {
+  DeviceFlowAdapter,
+  DeviceFlowInit,
+  OAuthProviderProfile,
+  RunOauthLoginCtx,
+  RunOauthLoginResult,
+} from './profile.js';
+
+const DEFAULT_BROWSER_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_DEVICE_TIMEOUT_MS = 10 * 60 * 1000;
+const DEVICE_POLL_SAFETY_MARGIN_MS = 3000;
+
+export async function runOauthLogin(
+  profile: OAuthProviderProfile,
+  ctx: RunOauthLoginCtx,
+): Promise<RunOauthLoginResult> {
+  const tokens = ctx.headless
+    ? await runDeviceFlow(profile, ctx)
+    : await runBrowserFlow(profile, ctx);
+
+  const accountId = profile.extractAccountId?.(tokens);
+  const customExtras = profile.extractExtras?.(tokens) ?? {};
+  const extras: Record<string, string> = { ...customExtras };
+  if (accountId) extras.account_id = accountId;
+
+  await storeTokenSet(ctx.vault, profile.id, tokens, {
+    clientId: profile.clientId,
+    ...(profile.clientSecret ? { clientSecret: profile.clientSecret } : {}),
+    tokenUrl: profile.tokenUrl,
+    extras,
+  });
+
+  return {
+    tokens,
+    ...(accountId ? { accountId } : {}),
+    extras,
+  };
+}
+
+async function runBrowserFlow(
+  profile: OAuthProviderProfile,
+  ctx: RunOauthLoginCtx,
+): Promise<TokenSet> {
+  const port = profile.redirect?.port ?? 8765;
+  const path = profile.redirect?.path ?? '/callback';
+  const serviceName = profile.displayName ?? profile.id;
+  return runAuthorizationCodeFlow({
+    authUrl: profile.authUrl,
+    tokenUrl: profile.tokenUrl,
+    clientId: profile.clientId,
+    ...(profile.clientSecret ? { clientSecret: profile.clientSecret } : {}),
+    scopes: profile.scopes,
+    redirectPort: port,
+    redirectPath: path,
+    ...(profile.extraAuthParams ? { extraAuthParams: profile.extraAuthParams } : {}),
+    timeoutMs: DEFAULT_BROWSER_TIMEOUT_MS,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
+    onAuthUrl: (url) => {
+      ctx.write(
+        `\nSign in to ${serviceName} to authorize moxxy\n\n` +
+          `If your browser doesn't open automatically, paste this URL:\n\n  ${url}\n\n` +
+          `Waiting for callback on http://localhost:${port}${path} (5 min timeout)…\n\n`,
+      );
+    },
+  });
+}
+
+async function runDeviceFlow(
+  profile: OAuthProviderProfile,
+  ctx: RunOauthLoginCtx,
+): Promise<TokenSet> {
+  if (!profile.deviceFlow) {
+    throw new MoxxyError({
+      code: 'OAUTH_FLOW_NOT_SUPPORTED',
+      message: `Provider "${profile.id}" doesn't expose a headless (device-code) flow.`,
+      hint:
+        'Run this command on a host with a browser, or ask the provider plugin author to ' +
+        'add a deviceFlow adapter to the profile.',
+      context: { provider: profile.id },
+    });
+  }
+  const adapter: DeviceFlowAdapter = profile.deviceFlow;
+  const init: DeviceFlowInit = await adapter.start({
+    clientId: profile.clientId,
+    ...(profile.clientSecret ? { clientSecret: profile.clientSecret } : {}),
+    scopes: profile.scopes,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
+  });
+  const serviceName = profile.displayName ?? profile.id;
+  ctx.write(
+    `\nSign in to ${serviceName} (headless / device code flow)\n\n` +
+      `  1. On any browser-capable device, open:\n` +
+      `       ${init.verificationUriComplete ?? init.verificationUri}\n\n` +
+      `  2. Enter this code:\n` +
+      `       ${init.userCode}\n\n` +
+      `Polling every ${Math.round(init.intervalMs / 1000)}s ` +
+      `(${Math.round(init.expiresInMs / 60000)} min timeout)…\n\n`,
+  );
+
+  // Cap the polling deadline by the device_code's own expiry — once it
+  // dies, any further poll is wasted.
+  const timeoutMs = Math.min(init.expiresInMs, DEFAULT_DEVICE_TIMEOUT_MS);
+
+  return pollUntil((state) => adapter.poll(init, state), {
+    intervalMs: init.intervalMs + DEVICE_POLL_SAFETY_MARGIN_MS,
+    timeoutMs,
+    label: `${profile.id} device flow`,
+    leadingWait: true,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
+  });
+}