@moxxy/plugin-oauth 0.0.33

package/src/storage.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from 'vitest';
+import {
+  clearStoredCreds,
+  isExpired,
+  readStoredCreds,
+  storeTokenSet,
+  validateProvider,
+  type OAuthVault,
+} from './storage.js';
+import type { TokenSet } from './flow.js';
+
+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 META = { clientId: 'client-1', tokenUrl: 'https://idp.example/token' };
+
+describe('isExpired — hostile / corrupt expiry data degrades to a refresh', () => {
+  it('treats a token with no expiresAt as non-expiring', () => {
+    expect(isExpired({ accessToken: 'a', tokenType: 'Bearer' })).toBe(false);
+  });
+
+  it('treats a NaN expiresAt as EXPIRED, never as eternally fresh', () => {
+    // The trap: `Date.now() + skew >= NaN` is always false. A bare `>=` would
+    // mark a token with corrupt expiry as forever-valid and suppress every
+    // refresh — the user silently presents a possibly-dead token. It must read
+    // as expired so the caller refreshes (or fails loudly with AUTH_EXPIRED).
+    expect(isExpired({ accessToken: 'a', tokenType: 'Bearer', expiresAt: NaN })).toBe(true);
+  });
+
+  it('treats an Infinity expiresAt as EXPIRED (non-finite is corrupt)', () => {
+    expect(
+      isExpired({ accessToken: 'a', tokenType: 'Bearer', expiresAt: Number.POSITIVE_INFINITY }),
+    ).toBe(true);
+  });
+
+  it('honours the skew window for a finite expiresAt', () => {
+    const soon = Date.now() + 30_000; // 30s out, inside the default 60s skew
+    expect(isExpired({ accessToken: 'a', tokenType: 'Bearer', expiresAt: soon })).toBe(true);
+    const far = Date.now() + 3_600_000;
+    expect(isExpired({ accessToken: 'a', tokenType: 'Bearer', expiresAt: far })).toBe(false);
+    expect(isExpired({ accessToken: 'a', tokenType: 'Bearer', expiresAt: far }, 0)).toBe(false);
+  });
+});
+
+describe('readStoredCreds — sanitizes a corrupt persisted expires_at', () => {
+  it('drops a non-numeric expires_at instead of carrying NaN into the TokenSet', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      'p',
+      { accessToken: 'a', tokenType: 'Bearer', expiresAt: 123 },
+      META,
+    );
+    // Simulate corruption / a hand-edit / a partial flush on disk.
+    vault.store.set('oauth/p/expires_at', 'not-a-number');
+
+    const creds = await readStoredCreds(vault, 'p');
+    expect(creds).not.toBeNull();
+    // Poison must not survive: expiresAt is omitted, not NaN.
+    expect(creds?.tokenSet.expiresAt).toBeUndefined();
+    expect(Number.isNaN(creds?.tokenSet.expiresAt as number)).toBe(false);
+  });
+
+  it('round-trips a finite expires_at unchanged', async () => {
+    const vault = makeVault();
+    const at = Date.now() + 1_000_000;
+    await storeTokenSet(vault, 'p', { accessToken: 'a', tokenType: 'Bearer', expiresAt: at }, META);
+    const creds = await readStoredCreds(vault, 'p');
+    expect(creds?.tokenSet.expiresAt).toBe(at);
+  });
+
+  it('returns null when setup-meta (client_id/token_url) is missing — partial store is unusable', async () => {
+    const vault = makeVault();
+    vault.store.set('oauth/p/access_token', 'a'); // access token only, no client_id/token_url
+    expect(await readStoredCreds(vault, 'p')).toBeNull();
+  });
+});
+
+describe('readStoredCreds — parseExtras tolerates hostile / malformed JSON', () => {
+  async function seedExtras(raw: string): Promise<TokenSet | undefined> {
+    const vault = makeVault();
+    await storeTokenSet(vault, 'p', { accessToken: 'a', tokenType: 'Bearer' }, META);
+    vault.store.set('oauth/p/extras', raw);
+    const creds = await readStoredCreds(vault, 'p');
+    return creds?.tokenSet;
+  }
+
+  it('does not throw on invalid JSON in extras — degrades to {}', async () => {
+    const vault = makeVault();
+    await storeTokenSet(vault, 'p', { accessToken: 'a', tokenType: 'Bearer' }, META);
+    vault.store.set('oauth/p/extras', '{not json');
+    const creds = await readStoredCreds(vault, 'p');
+    expect(creds?.extras).toEqual({});
+  });
+
+  it('ignores a JSON array (non-object) in extras', async () => {
+    await seedExtras('[1,2,3]');
+    const vault = makeVault();
+    await storeTokenSet(vault, 'p', { accessToken: 'a', tokenType: 'Bearer' }, META);
+    vault.store.set('oauth/p/extras', '["evil"]');
+    const creds = await readStoredCreds(vault, 'p');
+    expect(creds?.extras).toEqual({});
+  });
+
+  it('keeps only string-valued fields from an extras object', async () => {
+    const vault = makeVault();
+    await storeTokenSet(vault, 'p', { accessToken: 'a', tokenType: 'Bearer' }, META);
+    vault.store.set(
+      'oauth/p/extras',
+      JSON.stringify({ account_id: 'acc-1', n: 42, nested: { x: 1 }, ok: 'yes' }),
+    );
+    const creds = await readStoredCreds(vault, 'p');
+    expect(creds?.extras).toEqual({ account_id: 'acc-1', ok: 'yes' });
+  });
+});
+
+describe('storeTokenSet — mirrors the live TokenSet (deletes stale optional keys)', () => {
+  it('clears a previously-stored expires_at/scope/id_token when the new set omits them', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      'p',
+      {
+        accessToken: 'a1',
+        refreshToken: 'r1',
+        expiresAt: Date.now() + 1000,
+        scope: 'a b',
+        idToken: 'idt',
+        tokenType: 'Bearer',
+      },
+      META,
+    );
+    expect(vault.store.has('oauth/p/expires_at')).toBe(true);
+    expect(vault.store.has('oauth/p/scope')).toBe(true);
+    expect(vault.store.has('oauth/p/id_token')).toBe(true);
+
+    // A refresh that returns only access_token (RFC 6749 §5.1 permits this).
+    await storeTokenSet(vault, 'p', { accessToken: 'a2', tokenType: 'Bearer' }, META);
+    expect(vault.store.has('oauth/p/expires_at')).toBe(false);
+    expect(vault.store.has('oauth/p/scope')).toBe(false);
+    expect(vault.store.has('oauth/p/id_token')).toBe(false);
+    expect(vault.store.get('oauth/p/access_token')).toBe('a2');
+  });
+});
+
+describe('validateProvider — rejects keys that could escape the vault namespace', () => {
+  it('rejects path-traversal and separator characters', () => {
+    for (const bad of ['../etc', 'a/b', 'a b', 'UPPER', 'a:b', '', 'a\\b']) {
+      expect(() => validateProvider(bad)).toThrow();
+    }
+  });
+
+  it('storeTokenSet / readStoredCreds / clearStoredCreds all reject a bad provider', async () => {
+    const vault = makeVault();
+    await expect(
+      storeTokenSet(vault, '../escape', { accessToken: 'a', tokenType: 'Bearer' }, META),
+    ).rejects.toThrow();
+    await expect(readStoredCreds(vault, 'a/b')).rejects.toThrow();
+    await expect(clearStoredCreds(vault, 'a b')).rejects.toThrow();
+  });
+});
+
+describe('clearStoredCreds — counts only the keys actually removed', () => {
+  it('removes every persisted key and reports the count', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      'p',
+      { accessToken: 'a', refreshToken: 'r', expiresAt: Date.now(), scope: 's', tokenType: 'Bearer' },
+      { ...META, extras: { account_id: 'x' } },
+    );
+    const removed = await clearStoredCreds(vault, 'p');
+    expect(removed).toBeGreaterThan(0);
+    expect(await readStoredCreds(vault, 'p')).toBeNull();
+    // Nothing left under the namespace.
+    expect([...vault.store.keys()].filter((k) => k.startsWith('oauth/p/'))).toEqual([]);
+  });
+});

package/src/storage.ts

@@ -0,0 +1,208 @@
+import type { TokenSet } from './flow.js';
+
+/**
+ * Vault key convention:
+ *   oauth/<provider>/access_token
+ *   oauth/<provider>/refresh_token
+ *   oauth/<provider>/expires_at      (epoch ms, string)
+ *   oauth/<provider>/scope
+ *   oauth/<provider>/token_type
+ *   oauth/<provider>/id_token        (OIDC providers only)
+ *   oauth/<provider>/client_id       (so refresh doesn't need the model to re-pass it)
+ *   oauth/<provider>/client_secret   (confidential clients only)
+ *   oauth/<provider>/token_url       (so refresh works without re-supplying)
+ *   oauth/<provider>/extras          (JSON map of provider-specific fields, e.g. account_id)
+ *
+ * Provider names are namespaced with a `/` so the vault's `list-by-tag`
+ * UI groups them. Provider names MUST be `[a-z0-9._-]+`; the schema in
+ * the tool layer enforces this.
+ */
+const PROVIDER_RE = /^[a-z0-9._-]+$/;
+
+/**
+ * Minimal vault shape this module uses. Both `@moxxy/plugin-vault`'s
+ * `VaultStore` and the SDK's `ProviderVault` structurally satisfy it, so
+ * callers can pass whichever they hold.
+ */
+export interface OAuthVault {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, tags?: ReadonlyArray<string>): Promise<void>;
+  delete?(key: string): Promise<boolean>;
+}
+
+export function validateProvider(name: string): void {
+  if (!PROVIDER_RE.test(name)) {
+    throw new Error(
+      `oauth provider name "${name}" must match ${PROVIDER_RE.source} (lowercase, digits, ._-)`,
+    );
+  }
+}
+
+export interface StoreTokenSetMeta {
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly tokenUrl: string;
+  /**
+   * Provider-specific extras the framework persists alongside the token
+   * set. Used for fields like `account_id`, `org_id`, `team_slug` that
+   * don't fit `TokenSet` but the caller wants to recover later.
+   */
+  readonly extras?: Readonly<Record<string, string>>;
+}
+
+export interface StoredCreds {
+  readonly tokenSet: TokenSet;
+  readonly clientId: string;
+  readonly clientSecret: string | null;
+  readonly tokenUrl: string;
+  readonly extras: Readonly<Record<string, string>>;
+}
+
+export async function storeTokenSet(
+  vault: OAuthVault,
+  provider: string,
+  tokens: TokenSet,
+  meta: StoreTokenSetMeta,
+): Promise<void> {
+  validateProvider(provider);
+  const tag = `oauth:${provider}`;
+  const base = `oauth/${provider}`;
+  // Write each optional field when present, but DELETE the stored key when the
+  // new TokenSet omits it, so the persisted bundle exactly mirrors the live
+  // TokenSet. A refresh response that omits expires_in/scope/id_token (RFC 6749
+  // §5.1 permits this) must not leave a stale expires_at (which would make
+  // isExpired() loop forever or trust a token off dead data) or a stale OIDC
+  // id_token (which extractAccountId/extractExtras might re-derive identity
+  // from). Callers preserve a rotated-or-prior refresh_token BEFORE calling us
+  // (RFC 6749 §6: a refresh MAY omit refresh_token), so an undefined
+  // refreshToken here genuinely means "no refresh token" — mirror that too.
+  const upsert = async (key: string, value: string | undefined): Promise<void> => {
+    if (value !== undefined) {
+      await vault.set(`${base}/${key}`, value, [tag]);
+    } else {
+      await vault.delete?.(`${base}/${key}`);
+    }
+  };
+  await vault.set(`${base}/access_token`, tokens.accessToken, [tag]);
+  await upsert('refresh_token', tokens.refreshToken);
+  await upsert('expires_at', tokens.expiresAt !== undefined ? String(tokens.expiresAt) : undefined);
+  await upsert('scope', tokens.scope);
+  await vault.set(`${base}/token_type`, tokens.tokenType, [tag]);
+  await upsert('id_token', tokens.idToken);
+  await vault.set(`${base}/client_id`, meta.clientId, [tag]);
+  if (meta.clientSecret) {
+    await vault.set(`${base}/client_secret`, meta.clientSecret, [tag]);
+  }
+  await vault.set(`${base}/token_url`, meta.tokenUrl, [tag]);
+  if (meta.extras && Object.keys(meta.extras).length > 0) {
+    await vault.set(`${base}/extras`, JSON.stringify(meta.extras), [tag]);
+  }
+}
+
+export async function readStoredCreds(
+  vault: OAuthVault,
+  provider: string,
+): Promise<StoredCreds | null> {
+  validateProvider(provider);
+  const base = `oauth/${provider}`;
+  const access = await vault.get(`${base}/access_token`);
+  if (!access) return null;
+  // The remaining nine keys are independent reads with no ordering dependency;
+  // ensureFreshTokens runs this before every upstream LLM call, so fetch them
+  // concurrently instead of serializing ~9 vault round-trips on the hot path.
+  const [refresh, expiresStr, scope, tokenTypeRaw, idToken, clientId, clientSecret, tokenUrl, extrasRaw] =
+    await Promise.all([
+      vault.get(`${base}/refresh_token`),
+      vault.get(`${base}/expires_at`),
+      vault.get(`${base}/scope`),
+      vault.get(`${base}/token_type`),
+      vault.get(`${base}/id_token`),
+      vault.get(`${base}/client_id`),
+      vault.get(`${base}/client_secret`),
+      vault.get(`${base}/token_url`),
+      vault.get(`${base}/extras`),
+    ]);
+  const tokenType = tokenTypeRaw ?? 'Bearer';
+  if (!clientId || !tokenUrl) {
+    // Missing setup-meta means a partial store — refresh impossible. Treat as absent.
+    return null;
+  }
+  // A stored `expires_at` that doesn't parse to a finite number (corrupt vault
+  // write, a hand-edited value, a partial flush) is poison: carried through as
+  // NaN it makes `isExpired` return false (NaN comparisons are always false),
+  // so the token would read as ETERNALLY fresh and never refresh — the user
+  // silently keeps presenting a possibly-dead token. Drop the unparseable value
+  // and let `expiresAt` go undefined; `isExpired` then defends the
+  // no-known-expiry case explicitly (see below).
+  const expiresAtParsed = expiresStr !== null ? Number.parseInt(expiresStr, 10) : null;
+  const expiresAt =
+    expiresAtParsed !== null && Number.isFinite(expiresAtParsed) ? expiresAtParsed : undefined;
+  return {
+    tokenSet: {
+      accessToken: access,
+      ...(refresh !== null ? { refreshToken: refresh } : {}),
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+      ...(scope !== null ? { scope } : {}),
+      tokenType,
+      ...(idToken !== null ? { idToken } : {}),
+    },
+    clientId,
+    clientSecret,
+    tokenUrl,
+    extras: parseExtras(extrasRaw),
+  };
+}
+
+export async function clearStoredCreds(vault: OAuthVault, provider: string): Promise<number> {
+  validateProvider(provider);
+  const base = `oauth/${provider}`;
+  const keys = [
+    `${base}/access_token`,
+    `${base}/refresh_token`,
+    `${base}/expires_at`,
+    `${base}/scope`,
+    `${base}/token_type`,
+    `${base}/id_token`,
+    `${base}/client_id`,
+    `${base}/client_secret`,
+    `${base}/token_url`,
+    `${base}/extras`,
+  ];
+  let removed = 0;
+  for (const k of keys) {
+    if (await vault.delete?.(k)) removed += 1;
+  }
+  return removed;
+}
+
+/**
+ * True when the access token has expired (or is within `skewMs` of doing so).
+ *
+ * A token with no `expiresAt` is treated as non-expiring (some providers issue
+ * tokens without `expires_in`). A non-FINITE `expiresAt` (NaN/Infinity — corrupt
+ * data, an out-of-range parse) is treated as EXPIRED, never as fresh: a bare
+ * `>=` against NaN is always false, which would otherwise mark a token eternally
+ * valid and suppress every refresh. Forcing the expired branch degrades to a
+ * refresh (or a clear AUTH_EXPIRED if no refresh_token) instead of silently
+ * serving a token whose real expiry is unknown.
+ */
+export function isExpired(tokens: TokenSet, skewMs = 60_000): boolean {
+  if (tokens.expiresAt === undefined) return false;
+  if (!Number.isFinite(tokens.expiresAt)) return true;
+  return Date.now() + skewMs >= tokens.expiresAt;
+}
+
+function parseExtras(raw: string | null): Readonly<Record<string, string>> {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (typeof v === 'string') out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}

package/src/tools.test.ts

@@ -0,0 +1,239 @@
+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 { MoxxyError } from '@moxxy/sdk';
+import { buildOauthGetTokenTool } from './tools.js';
+import { storeTokenSet, readStoredCreds, type OAuthVault } from './storage.js';
+
+// oauth_get_token's refresh path takes the same cross-process lockfile under
+// `<moxxy home>/locks` that ensure-fresh.ts uses; 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-oauth-tools-'));
+  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 PROVIDER = 'test-rotating';
+const META = { clientId: 'client-1', tokenUrl: 'https://idp.example/token' };
+
+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;
+}
+
+const noopLogger = { debug() {}, info() {}, warn() {}, error() {} };
+const fakeCtx = { signal: new AbortController().signal, logger: noopLogger } as never;
+
+async function seedExpired(vault: OAuthVault, refreshToken: string): Promise<void> {
+  await storeTokenSet(
+    vault,
+    PROVIDER,
+    { accessToken: 'old', refreshToken, expiresAt: Date.now() - 1000, tokenType: 'Bearer' },
+    META,
+  );
+}
+
+describe('oauth_get_token — per-credential refresh serialization (u91-1)', () => {
+  it('coalesces concurrent refreshes into one IdP call; all callers end with the SAME rotated token', async () => {
+    const vault = makeVault();
+    await seedExpired(vault, 'r-old');
+    let refreshCalls = 0;
+    // Token endpoint that ROTATES the refresh_token every call AND rejects a
+    // stale (already-spent) one with invalid_grant — i.e. exactly the
+    // single-use-rotating refresh_token the lock exists to protect.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (_url: unknown, init?: RequestInit) => {
+        const rt = new URLSearchParams(String(init?.body ?? '')).get('refresh_token') ?? '';
+        if (rt !== 'r-old') {
+          return tokenResponse({ error: 'invalid_grant' }, 400);
+        }
+        refreshCalls++;
+        return tokenResponse({ access_token: 'new', refresh_token: 'r-new', expires_in: 3600 });
+      }),
+    );
+
+    const tool = buildOauthGetTokenTool({ vault: vault as never });
+    const [a, b] = await Promise.all([
+      tool.handler({ provider: PROVIDER }, fakeCtx),
+      tool.handler({ provider: PROVIDER }, fakeCtx),
+    ]);
+
+    // Exactly one network refresh; the loser re-read the winner's rotated token
+    // under the lock instead of burning the now-dead one.
+    expect(refreshCalls).toBe(1);
+    expect((a as Record<string, unknown>).accessToken).toBe('new');
+    expect((b as Record<string, unknown>).accessToken).toBe('new');
+    expect(vault.store.get(`oauth/${PROVIDER}/refresh_token`)).toBe('r-new');
+  });
+
+  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') {
+          // Another moxxy rotated the stored bundle after we read it.
+          vault.store.set(`oauth/${PROVIDER}/refresh_token`, 'r-fresh');
+          return tokenResponse({ error: 'invalid_grant' }, 400);
+        }
+        return tokenResponse({ access_token: 'new-2', refresh_token: 'r-next', expires_in: 3600 });
+      }),
+    );
+
+    const tool = buildOauthGetTokenTool({ vault: vault as never });
+    const res = await tool.handler({ provider: PROVIDER }, fakeCtx);
+
+    expect(attempted).toEqual(['r-dead', 'r-fresh']);
+    expect((res as Record<string, unknown>).accessToken).toBe('new-2');
+    expect(vault.store.get(`oauth/${PROVIDER}/refresh_token`)).toBe('r-next');
+  });
+
+  it('still returns a fresh cached token without any network call (valid existing flow)', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      PROVIDER,
+      { accessToken: 'still-good', refreshToken: 'r1', expiresAt: Date.now() + 3_600_000, tokenType: 'Bearer' },
+      META,
+    );
+    const fetchSpy = vi.fn(async () => tokenResponse({ access_token: 'should-not-happen' }));
+    vi.stubGlobal('fetch', fetchSpy);
+
+    const tool = buildOauthGetTokenTool({ vault: vault as never });
+    const res = await tool.handler({ provider: PROVIDER }, fakeCtx);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect((res as Record<string, unknown>).accessToken).toBe('still-good');
+  });
+
+  it('throws AUTH_NO_CREDENTIALS when nothing is stored', async () => {
+    const vault = makeVault();
+    const tool = buildOauthGetTokenTool({ vault: vault as never });
+    const err = await tool.handler({ provider: PROVIDER }, fakeCtx).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('AUTH_NO_CREDENTIALS');
+  });
+
+  it('preserves stored extras (account_id) across a tool-driven refresh', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      PROVIDER,
+      { accessToken: 'old', refreshToken: 'r-old', expiresAt: Date.now() - 1000, tokenType: 'Bearer' },
+      { ...META, extras: { account_id: 'acct-123' } },
+    );
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => tokenResponse({ access_token: 'new', refresh_token: 'r-new', expires_in: 3600 })),
+    );
+
+    const tool = buildOauthGetTokenTool({ vault: vault as never });
+    await tool.handler({ provider: PROVIDER }, fakeCtx);
+
+    const reread = await readStoredCreds(vault, PROVIDER);
+    expect(reread?.extras.account_id).toBe('acct-123');
+  });
+});
+
+describe('storeTokenSet — clears stale optional fields on partial refresh (u91-2)', () => {
+  it('drops a stale expires_at / id_token / scope when the refreshed set omits them', async () => {
+    const vault = makeVault();
+    // First store: a full token set with expiry, id_token and scope.
+    await storeTokenSet(
+      vault,
+      PROVIDER,
+      {
+        accessToken: 'a1',
+        refreshToken: 'r1',
+        expiresAt: Date.now() + 3_600_000,
+        scope: 'openid email',
+        tokenType: 'Bearer',
+        idToken: 'old.id.token',
+      },
+      META,
+    );
+    expect(vault.store.has(`oauth/${PROVIDER}/expires_at`)).toBe(true);
+    expect(vault.store.has(`oauth/${PROVIDER}/id_token`)).toBe(true);
+    expect(vault.store.has(`oauth/${PROVIDER}/scope`)).toBe(true);
+
+    // Refresh response omits expires_in, id_token and scope (common: many IdPs
+    // don't re-issue an id_token on refresh). The caller preserves the prior
+    // refresh_token per RFC 6749 §6.
+    await storeTokenSet(
+      vault,
+      PROVIDER,
+      { accessToken: 'a2', refreshToken: 'r1', tokenType: 'Bearer' },
+      META,
+    );
+
+    // Stale keys must be gone — not left pointing at dead data.
+    expect(vault.store.has(`oauth/${PROVIDER}/expires_at`)).toBe(false);
+    expect(vault.store.has(`oauth/${PROVIDER}/id_token`)).toBe(false);
+    expect(vault.store.has(`oauth/${PROVIDER}/scope`)).toBe(false);
+
+    const reread = await readStoredCreds(vault, PROVIDER);
+    expect(reread?.tokenSet.accessToken).toBe('a2');
+    expect(reread?.tokenSet.expiresAt).toBeUndefined();
+    expect(reread?.tokenSet.idToken).toBeUndefined();
+    expect(reread?.tokenSet.scope).toBeUndefined();
+    // refresh_token preserved (the caller merged the prior one before storing).
+    expect(reread?.tokenSet.refreshToken).toBe('r1');
+  });
+
+  it('still writes optional fields when the new set provides them (valid full refresh)', async () => {
+    const vault = makeVault();
+    await storeTokenSet(
+      vault,
+      PROVIDER,
+      { accessToken: 'a1', refreshToken: 'r1', expiresAt: 111, scope: 'a', tokenType: 'Bearer', idToken: 'id1' },
+      META,
+    );
+    await storeTokenSet(
+      vault,
+      PROVIDER,
+      { accessToken: 'a2', refreshToken: 'r2', expiresAt: 222, scope: 'a b', tokenType: 'Bearer', idToken: 'id2' },
+      META,
+    );
+    const reread = await readStoredCreds(vault, PROVIDER);
+    expect(reread?.tokenSet.expiresAt).toBe(222);
+    expect(reread?.tokenSet.scope).toBe('a b');
+    expect(reread?.tokenSet.idToken).toBe('id2');
+    expect(reread?.tokenSet.refreshToken).toBe('r2');
+  });
+});