@moxxy/plugin-oauth 0.0.33

package/src/adapters/openai-device-flow.ts

@@ -0,0 +1,179 @@
+/**
+ * Device-authorization adapter for OpenAI's non-standard flow (used by
+ * Codex/ChatGPT, opencode, codex-rs). Not RFC 8628 — speaks a JSON dialect:
+ *
+ *   1. POST `${issuer}/api/accounts/deviceauth/usercode` JSON `{client_id}`
+ *      → `{device_auth_id, user_code, interval}`.
+ *   2. Surface `user_code` + a product-specific verification URI
+ *      (`verificationUri`) to the user.
+ *   3. Poll `${issuer}/api/accounts/deviceauth/token` JSON
+ *      `{device_auth_id, user_code}`. 403/404 ⇒ keep polling. 200 returns
+ *      `{authorization_code, code_verifier}`.
+ *   4. Exchange that `authorization_code` + `code_verifier` for real tokens
+ *      via the standard `/oauth/token` endpoint with
+ *      `redirect_uri=${issuer}/deviceauth/callback` (not an actual redirect
+ *      target — just a registered value the server expects to see).
+ *
+ * Reusable for any OpenAI-issued client; product-specific bits are the
+ * verification URI and the `client_id`.
+ */
+
+import { classifyHttpStatus, MoxxyError } from '@moxxy/sdk';
+import type { TokenSet } from '../oauth/types.js';
+import { exchangeCodeForToken } from '../oauth/token-exchange.js';
+import type {
+  DeviceFlowAdapter,
+  DeviceFlowInit,
+  DeviceFlowStartArgs,
+} from '../profile.js';
+import type { PollOutcome, PollState } from '../oauth/poll-until.js';
+
+export interface OpenaiDeviceFlowOpts {
+  /** Auth issuer base URL, e.g. `https://auth.openai.com`. */
+  readonly issuer: string;
+  /** Standard OAuth token endpoint — `parseTokenResponse` consumes its reply. */
+  readonly tokenUrl: string;
+  /**
+   * URL the user opens to enter the device code. Product-specific —
+   * Codex uses `${issuer}/codex/device`. The init endpoint does NOT
+   * return one, so the caller supplies it.
+   */
+  readonly verificationUri: string;
+}
+
+interface OpenaiDeviceState {
+  readonly deviceAuthId: string;
+  readonly userCode: string;
+  readonly clientId: string;
+}
+
+export function openaiDeviceFlow(opts: OpenaiDeviceFlowOpts): DeviceFlowAdapter {
+  const initUrl = `${opts.issuer}/api/accounts/deviceauth/usercode`;
+  const pollUrl = `${opts.issuer}/api/accounts/deviceauth/token`;
+  const exchangeRedirectUri = `${opts.issuer}/deviceauth/callback`;
+
+  return {
+    async start(args: DeviceFlowStartArgs): Promise<DeviceFlowInit> {
+      const res = await fetch(initUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ client_id: args.clientId }),
+        ...(args.signal ? { signal: args.signal } : {}),
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw (
+          classifyHttpStatus(res.status, { url: initUrl, body: text || res.statusText }) ??
+          new MoxxyError({
+            code: 'AUTH_INVALID',
+            message: `device auth init failed: ${res.status} ${text || res.statusText}`,
+            context: { status: res.status, url: initUrl },
+          })
+        );
+      }
+      const data = (await res.json().catch(() => {
+        throw new MoxxyError({
+          code: 'PROVIDER_UNKNOWN_RESPONSE',
+          message: 'device-auth init returned a non-JSON success body',
+          context: { url: initUrl },
+        });
+      })) as {
+        device_auth_id?: unknown;
+        user_code?: unknown;
+        interval?: string | number;
+        expires_in?: string | number;
+      };
+      // Required-field validation: a 200 missing device_auth_id/user_code would
+      // otherwise produce a poll body of `{ device_auth_id: undefined }` that
+      // 403s forever until timeout. Reject clearly instead.
+      if (typeof data.device_auth_id !== 'string' || typeof data.user_code !== 'string') {
+        throw new MoxxyError({
+          code: 'PROVIDER_UNKNOWN_RESPONSE',
+          message: 'device-auth init response missing device_auth_id or user_code',
+          context: { url: initUrl },
+        });
+      }
+      // Coerce-then-validate: a malformed server value (e.g. interval:"" or a
+      // non-numeric string) parses to NaN, which would poison the poll timing
+      // (`setTimeout(_, NaN)` busy-loops; a NaN deadline aborts the flow). Only
+      // accept a finite number; otherwise fall back to the RFC-style defaults.
+      const rawInterval =
+        typeof data.interval === 'string' ? parseInt(data.interval, 10) : data.interval;
+      const intervalSec = Math.max(Number.isFinite(rawInterval) ? (rawInterval as number) : 5, 1);
+      const rawExpiresIn =
+        typeof data.expires_in === 'string' ? parseInt(data.expires_in, 10) : data.expires_in;
+      const expiresInSec = Number.isFinite(rawExpiresIn) ? (rawExpiresIn as number) : 600;
+      return {
+        userCode: data.user_code,
+        verificationUri: opts.verificationUri,
+        intervalMs: intervalSec * 1000,
+        expiresInMs: expiresInSec * 1000,
+        providerData: {
+          deviceAuthId: data.device_auth_id,
+          userCode: data.user_code,
+          clientId: args.clientId,
+        } satisfies OpenaiDeviceState,
+      };
+    },
+
+    async poll(init: DeviceFlowInit, state: PollState): Promise<PollOutcome<TokenSet>> {
+      const { deviceAuthId, userCode, clientId } = init.providerData as OpenaiDeviceState;
+      const res = await fetch(pollUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ device_auth_id: deviceAuthId, user_code: userCode }),
+        ...(state.signal ? { signal: state.signal } : {}),
+      });
+      if (res.ok) {
+        const data = (await res.json().catch(() => {
+          throw new MoxxyError({
+            code: 'PROVIDER_UNKNOWN_RESPONSE',
+            message: 'device-auth poll returned a non-JSON success body',
+            context: { url: pollUrl },
+          });
+        })) as {
+          authorization_code?: unknown;
+          code_verifier?: unknown;
+        };
+        // Required-field validation: without it a 200 omitting these would call
+        // exchangeCodeForToken with undefined, which URLSearchParams coerces to
+        // the literal 'undefined' — a wasted exchange that fails opaquely.
+        if (typeof data.authorization_code !== 'string' || typeof data.code_verifier !== 'string') {
+          throw new MoxxyError({
+            code: 'PROVIDER_UNKNOWN_RESPONSE',
+            message: 'device-auth poll response missing authorization_code or code_verifier',
+            context: { url: pollUrl },
+          });
+        }
+        // Two-step: poll returns a server-side authorization_code we
+        // exchange via the standard token endpoint. The redirect_uri
+        // here is the issuer's device callback — a registered value,
+        // not a URI we listen on. Route through the shared exchange
+        // helper so this dialect can't drift from browser-flow.
+        return {
+          done: await exchangeCodeForToken({
+            tokenUrl: opts.tokenUrl,
+            code: data.authorization_code,
+            redirectUri: exchangeRedirectUri,
+            clientId,
+            codeVerifier: data.code_verifier,
+            ...(state.signal ? { signal: state.signal } : {}),
+          }),
+        };
+      }
+      // OpenAI's "still waiting" signal — 403 or 404 with no further detail.
+      if (res.status === 403 || res.status === 404) {
+        return { pending: true };
+      }
+      const text = await res.text().catch(() => '');
+      throw (
+        classifyHttpStatus(res.status, { url: pollUrl, body: text || res.statusText }) ??
+        new MoxxyError({
+          code: 'AUTH_INVALID',
+          message: `Device auth poll failed: ${res.status} ${text || res.statusText}`,
+          context: { status: res.status, url: pollUrl },
+        })
+      );
+    },
+  };
+}

package/src/adapters/rfc8628-device-flow.ts

@@ -0,0 +1,75 @@
+/**
+ * Standards-compliant device-authorization adapter per RFC 8628.
+ *
+ * Phases:
+ *   1. POST `client_id` + `scope` to `deviceUrl` (form-encoded).
+ *   2. Surface `user_code` + `verification_uri` to the user.
+ *   3. Poll `tokenUrl` every `interval` with
+ *      `grant_type=urn:ietf:params:oauth:grant-type:device_code` + `device_code`.
+ *   4. Handle `authorization_pending` / `slow_down` / fatal codes per spec.
+ *
+ * The device-authorization request + poll-response classification are shared
+ * with the legacy `runDeviceCodeFlow` via `oauth/device-flow-shared`.
+ */
+
+import {
+  classifyDeviceTokenResponse,
+  requestDeviceAuthorization,
+} from '../oauth/device-flow-shared.js';
+import type { TokenSet } from '../oauth/types.js';
+import type {
+  DeviceFlowAdapter,
+  DeviceFlowInit,
+  DeviceFlowStartArgs,
+} from '../profile.js';
+import type { PollOutcome, PollState } from '../oauth/poll-until.js';
+
+export interface Rfc8628AdapterOpts {
+  readonly deviceUrl: string;
+  readonly tokenUrl: string;
+}
+
+interface Rfc8628State {
+  readonly deviceCode: string;
+}
+
+export function rfc8628DeviceFlow(opts: Rfc8628AdapterOpts): DeviceFlowAdapter {
+  return {
+    async start(args: DeviceFlowStartArgs): Promise<DeviceFlowInit> {
+      const auth = await requestDeviceAuthorization({
+        deviceUrl: opts.deviceUrl,
+        clientId: args.clientId,
+        scopes: args.scopes,
+        ...(args.signal ? { signal: args.signal } : {}),
+      });
+      return {
+        userCode: auth.userCode,
+        verificationUri: auth.verificationUri,
+        ...(auth.verificationUriComplete
+          ? { verificationUriComplete: auth.verificationUriComplete }
+          : {}),
+        intervalMs: auth.intervalSec * 1000,
+        expiresInMs: auth.expiresInSec * 1000,
+        providerData: { deviceCode: auth.deviceCode } satisfies Rfc8628State,
+      };
+    },
+
+    async poll(init: DeviceFlowInit, state: PollState): Promise<PollOutcome<TokenSet>> {
+      const { deviceCode } = init.providerData as Rfc8628State;
+      const body = new URLSearchParams();
+      body.set('grant_type', 'urn:ietf:params:oauth:grant-type:device_code');
+      body.set('device_code', deviceCode);
+      const res = await fetch(opts.tokenUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Accept: 'application/json',
+        },
+        body: body.toString(),
+        ...(state.signal ? { signal: state.signal } : {}),
+      });
+      const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      return classifyDeviceTokenResponse(res, json, state);
+    },
+  };
+}

package/src/credential-lock.ts

@@ -0,0 +1,183 @@
+/**
+ * Per-credential refresh serialization.
+ *
+ * OAuth providers with ROTATING single-use refresh tokens (Anthropic's Claude
+ * subscription, OpenAI's Codex/ChatGPT plan) invalidate the previous
+ * refresh_token on every refresh. Two concurrent refreshes with the same
+ * stored token therefore race: one wins, the other burns a now-dead token and
+ * logs the user out. `withCredentialLock` serializes "refresh + persist"
+ * critical sections at two levels:
+ *
+ *   1. In-process: a per-key `Mutex` (promise chain) so concurrent consumers
+ *      in one process (e.g. the chat provider and the whisper-stt transcriber
+ *      sharing the codex credential) coalesce into a single refresh — the
+ *      followers re-read the vault under the lock and reuse the winner's
+ *      rotated tokens.
+ *   2. Cross-process: a best-effort O_EXCL lockfile under
+ *      `<moxxy home>/locks/` with stale-lock takeover, so a TUI and a desktop
+ *      runner refreshing the same credential queue up instead of racing.
+ *
+ * The file lock is deliberately best-effort: if the lock directory is
+ * unusable, or a live-but-slow holder keeps it past `waitMs`, we proceed
+ * WITHOUT the lock rather than deadlocking auth — the vault's read-merge-write
+ * persistence and the callers' invalid_grant re-read-retry recovery keep the
+ * losing side recoverable even then.
+ */
+
+import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { MoxxyError, createMutex, type Mutex } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+
+export interface CredentialLockOptions {
+  /** Directory holding the lock files. Default `<moxxy home>/locks`. */
+  readonly dir?: string;
+  /**
+   * Take over a lock file whose mtime is older than this (holder crashed
+   * without releasing). Default 60s — comfortably above a worst-case retried
+   * token refresh.
+   */
+  readonly staleMs?: number;
+  /** Poll interval while waiting on a held lock. Default 150ms. */
+  readonly pollMs?: number;
+  /**
+   * Max time to wait for the file lock before proceeding WITHOUT it
+   * (best effort — never deadlock auth on a wedged lock). Default 30s.
+   */
+  readonly waitMs?: number;
+}
+
+const DEFAULT_STALE_MS = 60_000;
+const DEFAULT_POLL_MS = 150;
+const DEFAULT_WAIT_MS = 30_000;
+
+/**
+ * In-process locks, keyed by sanitized credential key. Module-level so every
+ * consumer of this package instance (providers, stt, tools) shares them.
+ */
+const inProcessLocks = new Map<string, Mutex>();
+
+/**
+ * Run `fn` while holding the per-credential lock (in-process mutex +
+ * best-effort cross-process lockfile). Callers should RE-READ their stored
+ * credential inside `fn` — a queued waiter usually finds the winner's
+ * freshly rotated tokens and can skip its own refresh entirely.
+ */
+export async function withCredentialLock<T>(
+  key: string,
+  fn: () => Promise<T>,
+  opts: CredentialLockOptions = {},
+): Promise<T> {
+  const safe = sanitizeKey(key);
+  let mutex = inProcessLocks.get(safe);
+  if (!mutex) {
+    mutex = createMutex();
+    inProcessLocks.set(safe, mutex);
+  }
+  return mutex.run(async () => {
+    const release = await acquireFileLock(
+      join(opts.dir ?? moxxyPath('locks'), `${safe}.lock`),
+      opts.staleMs ?? DEFAULT_STALE_MS,
+      opts.pollMs ?? DEFAULT_POLL_MS,
+      opts.waitMs ?? DEFAULT_WAIT_MS,
+    );
+    try {
+      return await fn();
+    } finally {
+      await release();
+    }
+  });
+}
+
+/**
+ * True for deterministic credential rejections from a token endpoint, as
+ * opposed to transient network/5xx failures. Covers the AUTH_* codes (401/403
+ * and refresh-specific failures) plus PROVIDER_BAD_REQUEST — `invalid_grant`
+ * is canonically an HTTP 400 (RFC 6749 §5.2), which `classifyHttpStatus` maps
+ * there. Used to decide whether a failed refresh is worth retrying with a
+ * fresher refresh_token re-read from the vault (another process may have
+ * rotated ours away).
+ */
+export function isAuthRejection(err: unknown): boolean {
+  return (
+    err instanceof MoxxyError &&
+    (err.code === 'AUTH_INVALID' ||
+      err.code === 'AUTH_DENIED' ||
+      err.code === 'AUTH_EXPIRED' ||
+      err.code === 'PROVIDER_BAD_REQUEST')
+  );
+}
+
+function sanitizeKey(key: string): string {
+  return key.replace(/[^a-zA-Z0-9._-]+/g, '_');
+}
+
+/**
+ * O_EXCL ('wx') lockfile acquisition with stale takeover. Returns a release
+ * function. Never throws: an unusable lock dir degrades to running unlocked.
+ */
+async function acquireFileLock(
+  lockPath: string,
+  staleMs: number,
+  pollMs: number,
+  waitMs: number,
+): Promise<() => Promise<void>> {
+  const deadline = Date.now() + waitMs;
+  try {
+    await mkdir(dirname(lockPath), { recursive: true });
+  } catch {
+    return async () => {};
+  }
+  for (;;) {
+    try {
+      const handle = await open(lockPath, 'wx');
+      try {
+        await handle.writeFile(`${process.pid} ${new Date().toISOString()}\n`, 'utf8');
+      } finally {
+        await handle.close().catch(() => {});
+      }
+      return async () => {
+        await rm(lockPath, { force: true }).catch(() => {});
+      };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
+        // Read-only FS, permissions, … — degrade to unlocked rather than
+        // blocking the user's auth on infrastructure trouble.
+        return async () => {};
+      }
+    }
+    // Lock held — take over if the holder looks dead, else wait and re-try.
+    // Takeover is made atomic via rename() to dodge the rm()+open() TOCTOU: a
+    // naive rm() lets two processes both judge the same lock stale and both
+    // delete it, and one could unlink a holder's freshly-recreated lock. POSIX
+    // rename is atomic and single-winner — only one racer's rename of the SAME
+    // inode succeeds; the loser's rename fails (ENOENT/the file moved) and it
+    // spins to re-acquire instead of clobbering the winner. We rename to a
+    // unique temp then rm that temp, so the original path is freed for the
+    // winner's `open('wx')` on the next spin. The file lock stays best-effort
+    // (see the module header): any failure degrades to the unlocked-but-
+    // recoverable path guarded by the in-process mutex + invalid_grant retry.
+    try {
+      const st = await stat(lockPath);
+      if (Date.now() - st.mtimeMs > staleMs) {
+        const tmp = `${lockPath}.stale-${process.pid}-${randomBytes(6).toString('hex')}`;
+        try {
+          await rename(lockPath, tmp);
+        } catch {
+          continue; // lost the takeover race (someone moved/recreated it) — respin
+        }
+        await rm(tmp, { force: true }).catch(() => {});
+        continue;
+      }
+    } catch {
+      continue; // released between open() and stat() — grab it on the next spin
+    }
+    if (Date.now() >= deadline) return async () => {};
+    await sleep(pollMs);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/discovery.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { oauthPlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves the vault from the inter-plugin
+ * service registry in onInit instead of a `build*({ vault })` closure. (The tool
+ * behaviour with an injected vault is covered by tools.test via buildOauthPlugin.)
+ */
+describe('oauthPlugin (discovery-loadable)', () => {
+  it('exposes the oauth tools and an onInit hook', () => {
+    expect(oauthPlugin.tools?.map((t) => t.name).sort()).toEqual([
+      'oauth_authorize',
+      'oauth_clear_token',
+      'oauth_get_token',
+    ]);
+    expect(typeof oauthPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves the "vault" service from the registry', () => {
+    const fakeVault = { tag: 'vault-store' };
+    const require = vi.fn((name: string) => {
+      if (name !== 'vault') throw new Error(`unexpected service: ${name}`);
+      return fakeVault;
+    });
+    const services = {
+      require,
+      get: () => fakeVault,
+      has: () => true,
+      register: () => {},
+    } as unknown as ServiceRegistry;
+    oauthPlugin.hooks!.onInit!({ services } as never);
+    expect(require).toHaveBeenCalledWith('vault');
+  });
+});