@moxxy/plugin-oauth 0.0.33

package/src/ensure-fresh.test.ts

@@ -0,0 +1,279 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ensureFreshTokens } from './ensure-fresh.js';
+import { withCredentialLock } from './credential-lock.js';
+import { storeTokenSet, type OAuthVault } from './storage.js';
+import type { OAuthProviderProfile } from './profile.js';
+
+// The refresh path takes a cross-process lockfile under `<moxxy home>/locks`;
+// point MOXXY_HOME at a temp dir so tests never touch the real ~/.moxxy.
+let moxxyHomeTmp: string;
+const priorMoxxyHome = process.env.MOXXY_HOME;
+beforeAll(async () => {
+  moxxyHomeTmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-ensure-fresh-'));
+  process.env.MOXXY_HOME = moxxyHomeTmp;
+});
+afterAll(async () => {
+  if (priorMoxxyHome === undefined) delete process.env.MOXXY_HOME;
+  else process.env.MOXXY_HOME = priorMoxxyHome;
+  await fs.rm(moxxyHomeTmp, { recursive: true, force: true });
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+interface FakeVault extends OAuthVault {
+  readonly store: Map<string, string>;
+}
+
+function makeVault(): FakeVault {
+  const store = new Map<string, string>();
+  return {
+    store,
+    get: async (k) => store.get(k) ?? null,
+    set: async (k, v) => {
+      store.set(k, v);
+    },
+    delete: async (k) => store.delete(k),
+  };
+}
+
+const profile: OAuthProviderProfile = {
+  id: 'test-rotating',
+  displayName: 'Test',
+  authUrl: 'https://idp.example/authorize',
+  tokenUrl: 'https://idp.example/token',
+  clientId: 'client-1',
+  scopes: ['openid'],
+};
+
+const META = { clientId: profile.clientId, tokenUrl: profile.tokenUrl };
+
+function tokenResponse(obj: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => obj,
+    text: async () => JSON.stringify(obj),
+  } as unknown as Response;
+}
+
+async function seedExpired(vault: OAuthVault, refreshToken: string): Promise<void> {
+  await storeTokenSet(
+    vault,
+    profile.id,
+    { accessToken: 'old', refreshToken, expiresAt: Date.now() - 1000, tokenType: 'Bearer' },
+    META,
+  );
+}
+
+describe('ensureFreshTokens — rotating refresh-token serialization', () => {
+  it('coalesces concurrent refreshes into one IdP call; both consumers get the rotated token', async () => {
+    const vault = makeVault();
+    await seedExpired(vault, 'r-old');
+    let refreshCalls = 0;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        refreshCalls++;
+        return tokenResponse({ access_token: 'new', refresh_token: 'r-new', expires_in: 3600 });
+      }),
+    );
+
+    const [a, b] = await Promise.all([
+      ensureFreshTokens(profile, vault),
+      ensureFreshTokens(profile, vault),
+    ]);
+
+    expect(refreshCalls).toBe(1);
+    expect(a.tokens.accessToken).toBe('new');
+    expect(b.tokens.accessToken).toBe('new');
+    expect(vault.store.get(`oauth/${profile.id}/refresh_token`)).toBe('r-new');
+  });
+
+  it('force=true coalesces too when another refresher already rotated the token', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      profile.id,
+      { accessToken: 'a1', refreshToken: 'r1', expiresAt: Date.now() + 3_600_000, tokenType: 'Bearer' },
+      META,
+    );
+    let refreshCalls = 0;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        refreshCalls++;
+        return tokenResponse({ access_token: `a${refreshCalls + 1}`, refresh_token: `r${refreshCalls + 1}`, expires_in: 3600 });
+      }),
+    );
+
+    // Two 401-recovery refreshes racing: the loser must reuse the winner's
+    // rotated token instead of burning the single-use refresh_token again.
+    const [a, b] = await Promise.all([
+      ensureFreshTokens(profile, vault, { force: true }),
+      ensureFreshTokens(profile, vault, { force: true }),
+    ]);
+
+    expect(refreshCalls).toBe(1);
+    expect(a.tokens.accessToken).toBe('a2');
+    expect(b.tokens.accessToken).toBe('a2');
+  });
+
+  it('recovers from invalid_grant by retrying once with the refresh_token another process rotated in', async () => {
+    const vault = makeVault();
+    await seedExpired(vault, 'r-dead');
+    const attempted: string[] = [];
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (_url: unknown, init?: RequestInit) => {
+        const rt = new URLSearchParams(String(init?.body ?? '')).get('refresh_token') ?? '';
+        attempted.push(rt);
+        if (rt === 'r-dead') {
+          // Simulate the cross-process race: another moxxy rotated the stored
+          // bundle after we read it, so OUR refresh token is already spent.
+          vault.store.set(`oauth/${profile.id}/refresh_token`, 'r-fresh');
+          return tokenResponse({ error: 'invalid_grant' }, 400);
+        }
+        return tokenResponse({ access_token: 'new-2', refresh_token: 'r-next', expires_in: 3600 });
+      }),
+    );
+
+    const res = await ensureFreshTokens(profile, vault);
+
+    expect(attempted).toEqual(['r-dead', 'r-fresh']);
+    expect(res.tokens.accessToken).toBe('new-2');
+    expect(vault.store.get(`oauth/${profile.id}/refresh_token`)).toBe('r-next');
+  });
+
+  it('does NOT retry an invalid_grant when the stored refresh_token is unchanged (true re-auth case)', async () => {
+    const vault = makeVault();
+    await seedExpired(vault, 'r-revoked');
+    let calls = 0;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        calls++;
+        return tokenResponse({ error: 'invalid_grant' }, 400);
+      }),
+    );
+    await expect(ensureFreshTokens(profile, vault)).rejects.toThrow(/400/);
+    expect(calls).toBe(1);
+  });
+});
+
+describe('withCredentialLock', () => {
+  it('serializes same-key sections and runs different keys independently', async () => {
+    const order: string[] = [];
+    const gate = new Promise<void>((r) => setTimeout(r, 30));
+    const first = withCredentialLock('lock-test-a', async () => {
+      order.push('a1-start');
+      await gate;
+      order.push('a1-end');
+    });
+    const second = withCredentialLock('lock-test-a', async () => {
+      order.push('a2');
+    });
+    const other = withCredentialLock('lock-test-b', async () => {
+      order.push('b');
+    });
+    await Promise.all([first, second, other]);
+    // b (different key) is free to run before a1 finishes; a2 is not.
+    expect(order.indexOf('a1-end')).toBeLessThan(order.indexOf('a2'));
+  });
+
+  it('creates and removes an O_EXCL lockfile in the lock dir', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-lockdir-'));
+    let seenDuring: string[] = [];
+    await withCredentialLock(
+      'lock-test-file',
+      async () => {
+        seenDuring = await fs.readdir(dir);
+      },
+      { dir },
+    );
+    expect(seenDuring).toEqual(['lock-test-file.lock']);
+    expect(await fs.readdir(dir)).toEqual([]);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('takes over a stale lockfile left behind by a crashed holder', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-lockstale-'));
+    const lockPath = path.join(dir, 'lock-test-stale.lock');
+    await fs.writeFile(lockPath, '999999 crashed\n');
+    const old = new Date(Date.now() - 120_000);
+    await fs.utimes(lockPath, old, old);
+
+    let ran = false;
+    await withCredentialLock(
+      'lock-test-stale',
+      async () => {
+        ran = true;
+      },
+      { dir, staleMs: 60_000, pollMs: 5, waitMs: 500 },
+    );
+    expect(ran).toBe(true);
+    expect(await fs.readdir(dir)).toEqual([]);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('proceeds without the lock (best effort) when a live holder outlasts waitMs', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-lockwait-'));
+    const lockPath = path.join(dir, 'lock-test-held.lock');
+    await fs.writeFile(lockPath, `${process.pid} live\n`); // fresh mtime = live holder
+    let ran = false;
+    await withCredentialLock(
+      'lock-test-held',
+      async () => {
+        ran = true;
+      },
+      { dir, staleMs: 60_000, pollMs: 5, waitMs: 50 },
+    );
+    expect(ran).toBe(true);
+    // The foreign lockfile must be left alone (we never owned it).
+    expect(await fs.readdir(dir)).toEqual(['lock-test-held.lock']);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('stale takeover leaves no `.stale-*` temp litter (rename target is cleaned up)', async () => {
+    // The rename-based takeover moves the stale lock to a unique temp then rm()s
+    // it. A dropped cleanup would accumulate `<lock>.stale-<pid>-<rand>` files in
+    // the lock dir forever. Assert the dir holds nothing but the caller's own
+    // (already-released) lock — i.e. zero temp residue.
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-lockstaletmp-'));
+    const lockPath = path.join(dir, 'lock-test-staletmp.lock');
+    await fs.writeFile(lockPath, '424242 crashed\n');
+    const old = new Date(Date.now() - 300_000);
+    await fs.utimes(lockPath, old, old);
+
+    await withCredentialLock('lock-test-staletmp', async () => {}, {
+      dir,
+      staleMs: 60_000,
+      pollMs: 5,
+      waitMs: 500,
+    });
+    const left = await fs.readdir(dir);
+    expect(left.filter((f) => f.includes('.stale-'))).toEqual([]);
+    expect(left).toEqual([]); // own lock released too
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('isAuthRejection — gates the rotation-race retry', () => {
+  it('is true only for deterministic credential-rejection codes', async () => {
+    const { MoxxyError } = await import('@moxxy/sdk');
+    const { isAuthRejection } = await import('./credential-lock.js');
+    for (const code of ['AUTH_INVALID', 'AUTH_DENIED', 'AUTH_EXPIRED', 'PROVIDER_BAD_REQUEST']) {
+      expect(isAuthRejection(new MoxxyError({ code: code as never, message: 'x' }))).toBe(true);
+    }
+    // Transient / unrelated failures must NOT trigger the single-use-token retry.
+    for (const code of ['NETWORK_ABORTED', 'INTERNAL', 'PROVIDER_UNKNOWN_RESPONSE', 'OAUTH_FLOW_TIMEOUT']) {
+      expect(isAuthRejection(new MoxxyError({ code: code as never, message: 'x' }))).toBe(false);
+    }
+    expect(isAuthRejection(new Error('plain'))).toBe(false);
+    expect(isAuthRejection(undefined)).toBe(false);
+    expect(isAuthRejection('invalid_grant')).toBe(false);
+  });
+});

package/src/ensure-fresh.ts

@@ -0,0 +1,178 @@
+/**
+ * Pre-request token freshness helper. Reads stored creds, refreshes when
+ * within `skewMs` of expiry (or forced), persists the rotated tokens BEFORE
+ * returning so a crash mid-flight can't strand a single-use refresh_token.
+ *
+ * The refresh + persist critical section runs under the per-credential lock
+ * (`withCredentialLock`): concurrent consumers — in this process or another
+ * moxxy process — coalesce into a single IdP refresh, with the followers
+ * re-reading the winner's rotated tokens from the vault instead of burning
+ * the (single-use, rotating) refresh_token a second time.
+ *
+ * Returns the live TokenSet + extras the provider can use to build headers
+ * (e.g. ChatGPT-Account-Id). Throws when no credential is stored or the
+ * refresh fails permanently.
+ */
+
+import { MoxxyError, classifyNetworkError } from '@moxxy/sdk';
+import { isExpired, readStoredCreds, storeTokenSet, type OAuthVault, type StoredCreds } from './storage.js';
+import { refreshAccessToken } from './oauth/token-exchange.js';
+import { isAuthRejection, withCredentialLock } from './credential-lock.js';
+import type { TokenSet } from './oauth/types.js';
+import type { OAuthProviderProfile } from './profile.js';
+
+/**
+ * Single refresh-and-persist critical section shared by `ensureFreshTokens`
+ * (provider profiles) and `oauth_get_token` (raw stored creds). Encodes the
+ * security-critical sequence ONCE — refresh-token guard, rotation-race
+ * recovery, refresh_token preservation (RFC 6749 §6), atomic re-persist —
+ * and lets each caller plug in its own provider key, error wording, and
+ * extras handling via a {@link RefreshSpec}. MUST run inside
+ * `withCredentialLock`: it is a writer to the `oauth/<provider>/*` keys.
+ */
+export interface RefreshSpec {
+  /** Vault namespace + lock key for this credential. */
+  readonly provider: string;
+  /** Raised when the stored creds carry no refresh_token to spend. */
+  noRefreshTokenError(): MoxxyError;
+  /**
+   * Wrap a non-network refresh failure (after `classifyNetworkError` declined
+   * it). Return a MoxxyError to surface a friendly message, or the original
+   * error to re-throw it verbatim.
+   */
+  wrapRefreshFailure(err: unknown): unknown;
+  /**
+   * Compute the extras to persist alongside the refreshed tokens, given the
+   * merged token set and the previously-stored extras. Return `undefined` to
+   * omit the extras key entirely (matching `storeTokenSet`'s present-only
+   * write semantics).
+   */
+  resolveExtras(merged: TokenSet, storedExtras: Readonly<Record<string, string>>): Record<string, string> | undefined;
+}
+
+export async function refreshAndStore(
+  vault: OAuthVault,
+  spec: RefreshSpec,
+  stored: StoredCreds,
+  retried = false,
+): Promise<{ tokens: TokenSet; extras: Readonly<Record<string, string>> }> {
+  if (!stored.tokenSet.refreshToken) {
+    throw spec.noRefreshTokenError();
+  }
+  let refreshed: TokenSet;
+  try {
+    refreshed = await refreshAccessToken({
+      tokenUrl: stored.tokenUrl,
+      clientId: stored.clientId,
+      ...(stored.clientSecret ? { clientSecret: stored.clientSecret } : {}),
+      refreshToken: stored.tokenSet.refreshToken,
+    });
+  } catch (err) {
+    // Rotation-race recovery: an invalid_grant-style rejection with a
+    // DIFFERENT refresh_token now on disk means another process rotated ours
+    // away after we read it. Retry once with the fresher token before
+    // declaring re-auth necessary. Transient (network/5xx) failures are not
+    // recovered here — they aren't evidence of rotation.
+    if (!retried && isAuthRejection(err)) {
+      const latest = await readStoredCreds(vault, spec.provider);
+      if (
+        latest?.tokenSet.refreshToken &&
+        latest.tokenSet.refreshToken !== stored.tokenSet.refreshToken
+      ) {
+        return refreshAndStore(vault, spec, latest, true);
+      }
+    }
+    const net = classifyNetworkError(err, { url: stored.tokenUrl, provider: spec.provider });
+    if (net) throw net;
+    throw spec.wrapRefreshFailure(err);
+  }
+  // Providers MAY rotate refresh_token — preserve the prior one if not.
+  const merged: TokenSet = {
+    ...refreshed,
+    refreshToken: refreshed.refreshToken ?? stored.tokenSet.refreshToken,
+  };
+  const extras = spec.resolveExtras(merged, stored.extras);
+  await storeTokenSet(vault, spec.provider, merged, {
+    clientId: stored.clientId,
+    ...(stored.clientSecret ? { clientSecret: stored.clientSecret } : {}),
+    tokenUrl: stored.tokenUrl,
+    ...(extras ? { extras } : {}),
+  });
+  return { tokens: merged, extras: extras ?? stored.extras };
+}
+
+export interface EnsureFreshOptions {
+  /** Force a refresh even if the access token hasn't expired. */
+  readonly force?: boolean;
+  /** Refresh when within this many ms of expiry. Default 60_000. */
+  readonly skewMs?: number;
+}
+
+export interface EnsureFreshResult {
+  readonly tokens: TokenSet;
+  readonly extras: Readonly<Record<string, string>>;
+}
+
+export async function ensureFreshTokens(
+  profile: OAuthProviderProfile,
+  vault: OAuthVault,
+  opts: EnsureFreshOptions = {},
+): Promise<EnsureFreshResult> {
+  const stored = await readStoredCreds(vault, profile.id);
+  if (!stored) {
+    throw new MoxxyError({
+      code: 'AUTH_NO_CREDENTIALS',
+      message: `No stored OAuth credentials for "${profile.id}".`,
+      hint: `Run \`moxxy login ${profile.id}\` to sign in.`,
+      context: { provider: profile.id },
+    });
+  }
+  if (!opts.force && !isExpired(stored.tokenSet, opts.skewMs)) {
+    return { tokens: stored.tokenSet, extras: stored.extras };
+  }
+  return withCredentialLock(`oauth-${profile.id}`, async () => {
+    // Re-read under the lock: another consumer/process may have refreshed
+    // while we waited. If the vault now holds a different, still-fresh access
+    // token, reuse it — even under `force`, which exists for 401 recovery and
+    // is satisfied by ANY rotation, not specifically ours.
+    const current = (await readStoredCreds(vault, profile.id)) ?? stored;
+    const rotatedMeanwhile = current.tokenSet.accessToken !== stored.tokenSet.accessToken;
+    if (!isExpired(current.tokenSet, opts.skewMs) && (!opts.force || rotatedMeanwhile)) {
+      return { tokens: current.tokenSet, extras: current.extras };
+    }
+    return refreshAndStore(vault, profileRefreshSpec(profile), current);
+  });
+}
+
+/**
+ * RefreshSpec for a provider profile: friendly `moxxy login`-flavored errors
+ * and extras re-derived from the fresh tokens (id_token re-issuance varies by
+ * provider, so fall back to stored extras for fields like account_id).
+ */
+function profileRefreshSpec(profile: OAuthProviderProfile): RefreshSpec {
+  return {
+    provider: profile.id,
+    noRefreshTokenError: () =>
+      new MoxxyError({
+        code: 'AUTH_EXPIRED',
+        message: `OAuth token for "${profile.id}" expired and no refresh_token is stored.`,
+        hint: `Re-run \`moxxy login ${profile.id}\` to sign in again.`,
+        context: { provider: profile.id },
+      }),
+    wrapRefreshFailure: (err) =>
+      new MoxxyError({
+        code: 'AUTH_EXPIRED',
+        message: `Couldn't refresh the OAuth token for "${profile.id}".`,
+        hint: `Re-run \`moxxy login ${profile.id}\` to sign in again.`,
+        context: { provider: profile.id },
+        cause: err,
+      }),
+    resolveExtras: (merged, storedExtras) => {
+      const freshAccountId = profile.extractAccountId?.(merged);
+      const freshExtras = profile.extractExtras?.(merged) ?? {};
+      const mergedExtras: Record<string, string> = { ...storedExtras, ...freshExtras };
+      if (freshAccountId) mergedExtras.account_id = freshAccountId;
+      return mergedExtras;
+    },
+  };
+}

package/src/flow.ts

@@ -0,0 +1,9 @@
+export { buildAuthUrl, runAuthorizationCodeFlow, type BuildAuthUrlInput } from './oauth/browser-flow.js';
+export { runDeviceCodeFlow } from './oauth/device-flow.js';
+export {
+  exchangeCodeForToken,
+  parseTokenResponse,
+  refreshAccessToken,
+} from './oauth/token-exchange.js';
+export type { DeviceFlowOptions, DevicePrompt, OAuthFlowOptions, TokenSet } from './oauth/types.js';
+export { pollUntil, type PollOutcome, type PollState, type PollUntilOpts } from './oauth/poll-until.js';

package/src/index.ts

@@ -0,0 +1,153 @@
+import { definePlugin, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import {
+  buildOauthAuthorizeTool,
+  buildOauthClearTool,
+  buildOauthGetTokenTool,
+  type OAuthToolDeps,
+} from './tools.js';
+
+// Low-level flow primitives — useful for ad-hoc usage or custom adapters.
+export {
+  buildAuthUrl,
+  exchangeCodeForToken,
+  parseTokenResponse,
+  refreshAccessToken,
+  runAuthorizationCodeFlow,
+  runDeviceCodeFlow,
+  pollUntil,
+} from './flow.js';
+export type {
+  BuildAuthUrlInput,
+  DeviceFlowOptions,
+  DevicePrompt,
+  OAuthFlowOptions,
+  PollOutcome,
+  PollState,
+  PollUntilOpts,
+  TokenSet,
+} from './flow.js';
+
+export { computeCodeChallenge, generateCodeVerifier, generateState } from './pkce.js';
+export { openInBrowser } from './open-browser.js';
+
+// Storage (vault-backed; extras-aware).
+export {
+  clearStoredCreds,
+  isExpired,
+  readStoredCreds,
+  storeTokenSet,
+  validateProvider,
+  type OAuthVault,
+  type StoreTokenSetMeta,
+  type StoredCreds,
+} from './storage.js';
+
+// Provider framework — declare a profile, plug in a device adapter,
+// orchestrate via runOauthLogin / ensureFreshTokens.
+export type {
+  DeviceFlowAdapter,
+  DeviceFlowInit,
+  DeviceFlowStartArgs,
+  OAuthProviderProfile,
+  RunOauthLoginCtx,
+  RunOauthLoginResult,
+} from './profile.js';
+export { runOauthLogin } from './run-login.js';
+export {
+  ensureFreshTokens,
+  type EnsureFreshOptions,
+  type EnsureFreshResult,
+} from './ensure-fresh.js';
+
+// Per-credential refresh serialization (in-process mutex + best-effort
+// cross-process lockfile) for providers with single-use rotating
+// refresh tokens.
+export {
+  isAuthRejection,
+  withCredentialLock,
+  type CredentialLockOptions,
+} from './credential-lock.js';
+
+// Bundled device-flow adapters. Custom dialects implement `DeviceFlowAdapter`.
+export { rfc8628DeviceFlow, type Rfc8628AdapterOpts } from './adapters/rfc8628-device-flow.js';
+export { openaiDeviceFlow, type OpenaiDeviceFlowOpts } from './adapters/openai-device-flow.js';
+
+// Tools layer — `oauth_authorize`, `oauth_get_token`, `oauth_clear_token`.
+export {
+  buildOauthAuthorizeTool,
+  buildOauthClearTool,
+  buildOauthGetTokenTool,
+  type OAuthToolDeps,
+} from './tools.js';
+
+export interface BuildOauthPluginOpts {
+  readonly vault: VaultStore;
+}
+
+/**
+ * `@moxxy/plugin-oauth` — generic OAuth 2.0 + PKCE provider framework.
+ *
+ * Two surfaces:
+ *   1. **Tools** — `oauth_authorize`, `oauth_get_token`, `oauth_clear_token`.
+ *      Model-callable; suits ad-hoc usage and MCP server wiring.
+ *   2. **Provider framework** — declare an `OAuthProviderProfile`, plug in
+ *      (or write) a `DeviceFlowAdapter`, drive with `runOauthLogin(profile, ctx)`
+ *      and `ensureFreshTokens(profile, vault)`. Suits LLM providers (e.g.
+ *      `@moxxy/plugin-provider-openai-codex`) that own their auth lifecycle.
+ *
+ * Tokens persist in the vault under `oauth/<provider>/*`. Bundled device
+ * adapters: `rfc8628DeviceFlow` (standards-compliant), `openaiDeviceFlow`
+ * (OpenAI's non-standard flavor). New dialects ship their own adapter.
+ */
+export function buildOauthPlugin(opts: BuildOauthPluginOpts): Plugin {
+  // Host-injected vault (available immediately).
+  return makeOauthPlugin(() => opts.vault);
+}
+
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`), so its `onInit` registers the service before this one
+ * consumes it. The tools read `deps.vault` lazily via a getter, so they resolve
+ * the store at call time — after `onInit` has wired it.
+ */
+export const oauthPlugin: Plugin = (() => {
+  let resolved: VaultStore | null = null;
+  const getVault = (): VaultStore => {
+    if (!resolved) {
+      throw new Error(
+        '@moxxy/plugin-oauth: the "vault" service is unavailable — @moxxy/plugin-vault must load first',
+      );
+    }
+    return resolved;
+  };
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      resolved = ctx.services.require<VaultStore>('vault');
+    },
+  };
+  return makeOauthPlugin(getVault, hooks);
+})();
+
+function makeOauthPlugin(getVault: () => VaultStore, hooks?: LifecycleHooks): Plugin {
+  // The getter satisfies `OAuthToolDeps.vault` while deferring resolution to call
+  // time, so the same tools work whether the vault is host-injected or resolved
+  // from the service registry in onInit.
+  const deps: OAuthToolDeps = {
+    get vault(): VaultStore {
+      return getVault();
+    },
+  };
+  return definePlugin({
+    name: '@moxxy/plugin-oauth',
+    version: '0.0.0',
+    tools: [
+      buildOauthAuthorizeTool(deps),
+      buildOauthGetTokenTool(deps),
+      buildOauthClearTool(deps),
+    ],
+    ...(hooks ? { hooks } : {}),
+  });
+}