@modelprofile.com/authswitch 6.2.0 → 6.4.0

package/ts/classes.authoritybroker.ts

@@ -0,0 +1,530 @@
+import * as plugins from './plugins.js';
+import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
+import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
+import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant } from './classes.authoritymodels.js';
+import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
+
+type TOpenAiCredential = plugins.flexAccounts.IOpenAiChatGptOAuthCredential;
+type TOpenAiProvider = Pick<plugins.flexAccounts.ISmartAiProviderAdapter, 'beginLogin' | 'refreshCredential' | 'inspectCredential' | 'dispose'>;
+
+export interface IAuthSwitchAuthorityBrokerOptions {
+  provider?: TOpenAiProvider;
+  secrets?: IAuthSwitchSecretCodec;
+  now?: () => number;
+  proactive?: boolean;
+}
+
+export interface IAuthSwitchResolvedAccess {
+  accessToken: string;
+  accountId: string;
+  isFedrampAccount: boolean;
+  expiresAt: string;
+  grantGeneration: number;
+}
+
+const idHash = (...values: string[]): string => plugins.crypto.createHash('sha256').update(JSON.stringify(values)).digest('hex');
+const isId = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const isUuid = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value);
+const safeLabel = (value: unknown): value is string => typeof value === 'string' && value.trim() === value
+  && value.length > 0 && value.length <= 128 && !/[\u0000-\u001f\u007f]/.test(value);
+const safeScope = (value: unknown, maximum: number): value is string => typeof value === 'string'
+  && value.length > 0 && value.length <= maximum && !/[\u0000-\u001f\u007f]/.test(value);
+const validRevision = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
+const tokenExpiry = (credential: TOpenAiCredential): string | null => {
+  try { return plugins.flexAuth.parseOpenAiChatGptTokenInfo(credential.accessToken).expiresAt ?? null; }
+  catch { return null; }
+};
+const openAiGrantId = (accountId: string): string => idHash('authswitch-grant-v1', accountId, 'openai_managed', 'chatgpt');
+const publicAccount = (account: IStoredAuthorityAccount, grant: IStoredAuthorityGrant | null): IAuthSwitchAccount => ({
+  id: account.id, providerId: account.providerId, label: account.label, email: account.email,
+  plan: account.plan, health: account.removed ? 'removed'
+    : grant?.state === 'exchange_may_have_been_sent' ? 'refreshing' : grant?.state ?? 'needs_reauth',
+  owner: grant?.owner ?? 'none', grantGeneration: grant?.grantGeneration ?? 0, revision: account.revision,
+  accessExpiresAt: grant?.accessExpiresAt ?? null, retryAt: grant?.retryAt ?? null, problem: grant?.problem ?? 'none',
+  statusObservedAt: account.statusObservedAt,
+});
+const publicBinding = (binding: IStoredAuthorityBinding): IAuthSwitchBinding => ({
+  id: binding.id, accountId: binding.accountId, runtime: binding.runtime,
+  scopeId: binding.scopeId, incarnationId: binding.incarnationId, revision: binding.revision,
+});
+
+interface IManagedOperation {
+  public: IAuthSwitchOperation;
+  handle: plugins.flexAccounts.ISmartAiProviderLoginHandle;
+  task: Promise<void>;
+  cancelled: boolean;
+  committing: boolean;
+  finishedAt: number | null;
+}
+
+/** One daemon-owned authority. No management DTO contains a refresh grant. */
+export class AuthSwitchAuthorityBroker {
+  private readonly provider: TOpenAiProvider;
+  private readonly secrets: IAuthSwitchSecretCodec;
+  private readonly now: () => number;
+  private readonly proactive: boolean;
+  private readonly operations = new Map<string, IManagedOperation>();
+  private readonly refreshes = new Map<string, Promise<void>>();
+  private readonly listeners = new Set<() => void>();
+  private timer?: NodeJS.Timeout;
+  private closed = false;
+
+  constructor(private readonly database: AuthSwitchAuthorityDatabase, options: IAuthSwitchAuthorityBrokerOptions = {}) {
+    this.provider = options.provider ?? new plugins.flexAccounts.OpenAiProviderAdapter();
+    this.secrets = options.secrets ?? new AuthSwitchTpmSecretCodec();
+    this.now = options.now ?? Date.now;
+    this.proactive = options.proactive ?? true;
+  }
+
+  public async start(): Promise<void> {
+    const probe = plugins.crypto.randomBytes(32);
+    const probeId = idHash('authswitch-custody-probe-v1');
+    try {
+      const sealed = await this.secrets.seal(probeId, probe);
+      const opened = await this.secrets.unseal(probeId, sealed);
+      try {
+        if (opened.length !== probe.length || !plugins.crypto.timingSafeEqual(opened, probe)) {
+          throw new Error('Authswitch secret custody self-check failed.');
+        }
+      } finally { opened.fill(0); }
+    } finally { probe.fill(0); }
+    let after: string | null = null;
+    while (true) {
+      const page = await this.database.grantsByState('exchange_may_have_been_sent', after);
+      if (!page.length) break;
+      for (const grant of page) {
+        const updateId = plugins.crypto.randomUUID();
+        await this.database.changeGrant(updateId, grant.id, current => {
+          if (!current || current.state !== 'exchange_may_have_been_sent') throw new Error('Refresh recovery changed concurrently.');
+          return { ...current, state: 'needs_reauth', attemptId: null, problem: 'exchange_uncertain',
+            revision: current.revision + 1, statusObservedAt: new Date(this.now()).toISOString(), updateId };
+        });
+        this.publish();
+      }
+      after = page.at(-1)!.id;
+    }
+    if (this.proactive) this.schedule();
+  }
+
+  private schedule(): void {
+    if (this.closed) return;
+    this.timer = setTimeout(() => {
+      void this.refreshDueAccounts().catch(() => {
+        process.stderr.write('Authswitch proactive refresh scan failed; account status may be stale.\n');
+      }).finally(() => this.schedule());
+    }, 30_000);
+    this.timer.unref();
+  }
+
+  public async refreshDueAccounts(): Promise<void> {
+    if (this.closed) return;
+    for (const state of ['ready', 'retry_wait'] as const) {
+      let after: string | null = null;
+      while (true) {
+      const page = await this.database.grantsByState(state, after);
+        if (!page.length) break;
+        await Promise.allSettled(page.filter(grant => grant.purpose === 'openai_managed'
+          && grant.owner === 'daemon' && this.isDue(grant, 0)
+          && (grant.state !== 'retry_wait' || (grant.retryAt !== null && Date.parse(grant.retryAt) <= this.now())))
+          .map(grant => this.refreshAccount(grant.accountId)));
+        after = page.at(-1)!.id;
+      }
+    }
+  }
+
+  private isDue(grant: IStoredAuthorityGrant, minValidityMs: number): boolean {
+    const expires = grant.accessExpiresAt === null ? NaN : Date.parse(grant.accessExpiresAt);
+    return !Number.isFinite(expires) || expires <= this.now() + Math.max(minValidityMs, 0) + 300_000;
+  }
+
+  private publish(): void {
+    for (const listener of this.listeners) listener();
+  }
+
+  public async snapshot(options: { accountAfter?: string; bindingAfter?: string; limit?: number } = {}): Promise<IAuthSwitchSnapshot> {
+    if ((options.accountAfter !== undefined && !isId(options.accountAfter))
+      || (options.bindingAfter !== undefined && !isId(options.bindingAfter))) throw new Error('Invalid account snapshot cursor.');
+    const page = await this.database.page(options.accountAfter ?? null, options.bindingAfter ?? null, options.limit ?? 128);
+    return { schemaVersion: 1, epoch: page.meta.epoch, revision: page.meta.revision,
+      generatedAt: new Date(this.now()).toISOString(),
+      accounts: page.accounts.filter(item => !item.account.removed)
+        .map(item => publicAccount(item.account, item.grant)),
+      bindings: page.bindings.map(publicBinding),
+      nextAccountCursor: page.nextAccountCursor, nextBindingCursor: page.nextBindingCursor };
+  }
+
+  public async events(epoch: string, afterRevision: number, waitMs: number, signal?: AbortSignal): Promise<{
+    epoch: string; revision: number; resyncRequired: boolean; events: IAuthSwitchAccountEvent[];
+  }> {
+    if (!isUuid(epoch) || !validRevision(afterRevision) || !Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 30_000) {
+      throw new Error('Invalid account event cursor.');
+    }
+    const inspect = async () => {
+      const meta = await this.database.readMeta();
+      const resyncRequired = epoch !== meta.epoch || afterRevision > meta.revision;
+      const persisted = resyncRequired ? [] : await this.database.eventsAfter(afterRevision);
+      if (!resyncRequired && afterRevision < meta.revision
+        && (persisted.length === 0 || persisted.some((item, index) => item.revision !== afterRevision + index + 1))) {
+        return { epoch: meta.epoch, revision: meta.revision, resyncRequired: true, events: [] };
+      }
+      const events = persisted.map(item => ({ epoch: item.epoch, revision: item.revision, kind: item.kind, accountId: item.accountId }));
+      const revision = events.at(-1)?.revision ?? meta.revision;
+      return { epoch: meta.epoch, revision, resyncRequired, events };
+    };
+    const immediate = await inspect();
+    if (immediate.resyncRequired || immediate.events.length || waitMs === 0 || this.closed || signal?.aborted) return immediate;
+    return new Promise((resolve, reject) => {
+      let finished = false;
+      const fail = (error: unknown) => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        this.listeners.delete(wake);
+        signal?.removeEventListener('abort', wake);
+        reject(error);
+      };
+      const wake = () => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        this.listeners.delete(wake);
+        signal?.removeEventListener('abort', wake);
+        void inspect().then(resolve, reject);
+      };
+      const timer = setTimeout(wake, waitMs);
+      this.listeners.add(wake);
+      signal?.addEventListener('abort', wake, { once: true });
+      // Close the read/register race without holding a database session for the wait.
+      void inspect().then(result => { if (result.resyncRequired || result.events.length) wake(); }, fail);
+    });
+  }
+
+  private identity(credential: TOpenAiCredential): { id: string; subject: string; workspaceId: string; email: string | null; plan: string | null } {
+    const token = plugins.flexAuth.parseOpenAiChatGptTokenInfo(credential.idToken);
+    const subject = token.chatgptUserId;
+    const workspaceId = token.chatgptAccountId;
+    if (!subject || !workspaceId) throw new Error('OpenAI login omitted a stable user or account identity.');
+    return { id: idHash('authswitch-account-v1', 'openai', subject, workspaceId), subject, workspaceId,
+      email: token.email?.toLowerCase() ?? null, plan: token.chatgptPlanType ?? null };
+  }
+
+  private async sealCredential(grantId: string, credential: TOpenAiCredential): Promise<string> {
+    const bytes = Buffer.from(JSON.stringify(credential), 'utf8');
+    try { return await this.secrets.seal(grantId, bytes); }
+    finally { bytes.fill(0); }
+  }
+
+  private async unsealCredential(account: IStoredAuthorityAccount, grant: IStoredAuthorityGrant): Promise<TOpenAiCredential> {
+    if (!grant.ciphertext || grant.owner !== 'daemon' || grant.purpose !== 'openai_managed'
+      || grant.accountId !== account.id) throw new Error('Account has no daemon-owned credential.');
+    const bytes = await this.secrets.unseal(grant.id, grant.ciphertext);
+    try {
+      const value: unknown = JSON.parse(Buffer.from(bytes).toString('utf8'));
+      if (!value || typeof value !== 'object') throw new Error();
+      const record = value as Record<string, unknown>;
+      if (record.kind !== 'chatgptOAuth' || record.providerId !== 'openai'
+        || typeof record.accessToken !== 'string' || typeof record.refreshToken !== 'string'
+        || typeof record.idToken !== 'string') throw new Error();
+      const credential = value as TOpenAiCredential;
+      if (this.identity(credential).id !== account.id) throw new Error();
+      this.provider.inspectCredential(credential);
+      return credential;
+    } catch { throw new Error('Stored account credential is invalid or belongs to another account.'); }
+    finally { bytes.fill(0); }
+  }
+
+  public async beginAddOpenAi(): Promise<IAuthSwitchOperation> { return this.beginLogin(null); }
+  public async beginReauthOpenAi(accountId: string): Promise<IAuthSwitchOperation> {
+    if (!isId(accountId)) throw new Error('Invalid account ID.');
+    const { account, grant } = await this.database.readAccountAndPrimaryGrant(accountId);
+    if (!account || account.removed || account.providerId !== 'openai') throw new Error('OpenAI account was not found.');
+    if (grant?.owner === 'legacy_native') throw new Error('Stop the legacy native owner before reauthenticating this account.');
+    return this.beginLogin(accountId);
+  }
+
+  private async beginLogin(targetId: string | null): Promise<IAuthSwitchOperation> {
+    if (this.closed) throw new Error('Authswitch authority is closing.');
+    this.pruneOperations();
+    if ([...this.operations.values()].filter(item => item.public.state === 'pending').length >= 32) {
+      throw new Error('Too many pending device logins.');
+    }
+    const handle = await this.provider.beginLogin({ flow: 'device' });
+    if (handle.prompt.flow !== 'device') {
+      await handle.close();
+      throw new Error('Provider did not start a device login.');
+    }
+    const publicOperation: IAuthSwitchOperation = { id: plugins.crypto.randomUUID(), state: 'pending',
+      prompt: { flow: 'device', verificationUrl: handle.prompt.verificationUrl, userCode: handle.prompt.userCode },
+      account: null, error: null };
+    const operation: IManagedOperation = { public: publicOperation, handle, task: Promise.resolve(),
+      cancelled: false, committing: false, finishedAt: null };
+    this.operations.set(publicOperation.id, operation);
+    operation.task = handle.completion.then(async result => {
+      if (operation.cancelled || this.closed) return;
+      operation.committing = true;
+      const identity = this.identity(result.credential);
+      if (targetId !== null && identity.id !== targetId) throw new Error('The device login selected a different OpenAI account.');
+      const grantId = openAiGrantId(identity.id);
+      const ciphertext = await this.sealCredential(grantId, result.credential);
+      if (operation.cancelled || this.closed) return;
+      const updateId = plugins.crypto.randomUUID();
+      const updated = await this.database.changeAccountAndGrant(updateId, identity.id, grantId, (existing, oldGrant) => {
+        if (targetId === null && existing && !existing.removed) throw new Error('Account already exists; reauthenticate that account instead.');
+        if (targetId !== null && (!existing || existing.removed)) throw new Error('Target account was removed during login.');
+        if (oldGrant?.owner === 'legacy_native') throw new Error('The legacy native owner still holds this grant.');
+        const now = new Date(this.now()).toISOString();
+        const account: IStoredAuthorityAccount = existing
+          ? { ...existing, label: existing.label || identity.email || `OpenAI ${identity.workspaceId}`,
+            email: identity.email, plan: identity.plan, primaryGrantId: grantId, removed: false,
+            revision: existing.revision + 1, statusObservedAt: now, updateId }
+          : { id: identity.id, providerId: 'openai', issuer: 'openai', subject: identity.subject,
+            workspaceId: identity.workspaceId, label: identity.email ?? `OpenAI ${identity.workspaceId}`,
+            email: identity.email, plan: identity.plan, primaryGrantId: grantId, removed: false,
+            revision: 1, statusObservedAt: now, updateId };
+        const grant: IStoredAuthorityGrant = oldGrant
+          ? { ...oldGrant, state: 'ready', owner: 'daemon', ciphertext,
+            grantGeneration: oldGrant.grantGeneration + 1,
+            authorizationGeneration: oldGrant.authorizationGeneration + 1,
+            revision: oldGrant.revision + 1, accessExpiresAt: tokenExpiry(result.credential),
+            attemptId: null, retryAt: null, retryCount: 0, problem: 'none', statusObservedAt: now, updateId }
+          : { id: grantId, accountId: identity.id, providerId: 'openai', purpose: 'openai_managed',
+            audience: 'chatgpt', state: 'ready', owner: 'daemon', grantGeneration: 1,
+            authorizationGeneration: 1, revision: 1, ciphertext,
+            accessExpiresAt: tokenExpiry(result.credential), attemptId: null,
+            retryAt: null, retryCount: 0, problem: 'none', statusObservedAt: now, updateId };
+        return { account, grant };
+      });
+      this.publish();
+      operation.public.account = publicAccount(updated.account, updated.grant);
+      operation.public.state = 'complete';
+    }).catch(() => {
+      operation.public.state = operation.cancelled ? 'cancelled' : 'failed';
+      operation.public.error = operation.cancelled ? null : targetId === null
+        ? 'OpenAI login failed or the account could not be saved. No active account was changed.'
+        : 'OpenAI reauthentication failed or selected a different account. The existing account was preserved.';
+    }).finally(async () => {
+      operation.finishedAt = this.now();
+      try { await handle.close(); } catch { /* A completed operation remains inspectable. */ }
+    });
+    return structuredClone(publicOperation);
+  }
+
+  public getOperation(operationId: string): IAuthSwitchOperation {
+    if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
+    this.pruneOperations();
+    const operation = this.operations.get(operationId);
+    if (!operation) throw new Error('Account operation expired or was not found.');
+    return structuredClone(operation.public);
+  }
+
+  private pruneOperations(): void {
+    for (const [id, operation] of this.operations) {
+      if (operation.finishedAt !== null && this.now() - operation.finishedAt > 600_000) this.operations.delete(id);
+    }
+  }
+
+  public async cancelOperation(operationId: string): Promise<IAuthSwitchOperation> {
+    const operation = this.operations.get(operationId);
+    if (!isUuid(operationId) || !operation) throw new Error('Account operation expired or was not found.');
+    if (operation.public.state !== 'pending') return structuredClone(operation.public);
+    if (operation.committing) throw new Error('Login is completing; check its operation status.');
+    operation.cancelled = true;
+    await operation.handle.cancel();
+    operation.public.state = 'cancelled';
+    operation.public.error = null;
+    return structuredClone(operation.public);
+  }
+
+  public async renameAccount(accountId: string, expectedRevision: number, label: string): Promise<IAuthSwitchAccount> {
+    if (!isId(accountId) || !validRevision(expectedRevision) || !safeLabel(label)) throw new Error('Invalid account change.');
+    const updateId = plugins.crypto.randomUUID();
+    const updated = await this.database.changeAccount(updateId, accountId, account => {
+      if (!account || account.removed || account.revision !== expectedRevision) throw new Error('Account changed; refresh before editing.');
+      return { ...account, label, revision: account.revision + 1, updateId,
+        statusObservedAt: new Date(this.now()).toISOString() };
+    });
+    this.publish();
+    const grant = updated.account.primaryGrantId ? await this.database.readGrant(updated.account.primaryGrantId) : null;
+    return publicAccount(updated.account, grant);
+  }
+
+  public async removeAccount(accountId: string, expectedRevision: number): Promise<IAuthSwitchAccount> {
+    if (!isId(accountId) || !validRevision(expectedRevision)) throw new Error('Invalid account change.');
+    const updateId = plugins.crypto.randomUUID();
+    const account = await this.database.removeAccountAndGrants(updateId, accountId,
+      expectedRevision, new Date(this.now()).toISOString());
+    this.publish();
+    const grant = account.primaryGrantId ? await this.database.readGrant(account.primaryGrantId) : null;
+    return publicAccount(account, grant);
+  }
+
+  public async bindAccount(input: { accountId: string; runtime: IAuthSwitchBinding['runtime']; scopeId: string; incarnationId: string }): Promise<{ binding: IAuthSwitchBinding; capability: string }> {
+    if (!isId(input.accountId) || !['flex', 'codex', 'opencode', 'claude'].includes(input.runtime)
+      || !safeScope(input.scopeId, 512) || !safeScope(input.incarnationId, 256)) throw new Error('Invalid account binding.');
+    const id = idHash('authswitch-binding-v1', input.runtime, input.scopeId);
+    const capability = plugins.crypto.randomBytes(32).toString('base64url');
+    const capabilityHash = idHash(capability);
+    const updateId = plugins.crypto.randomUUID();
+    const updated = await this.database.changeBinding(updateId, id, input.accountId, (existing, account, grant) => {
+      if (account.removed || grant?.state !== 'ready' || grant.owner !== 'daemon'
+        || grant.purpose !== 'openai_managed' || account.providerId !== 'openai'
+        || input.runtime === 'claude') {
+        throw new Error('Account is not available for this runtime.');
+      }
+      return { id, accountId: input.accountId, grantId: grant.id, runtime: input.runtime, scopeId: input.scopeId,
+        incarnationId: input.incarnationId, revision: (existing?.revision ?? 0) + 1,
+        grantAuthorizationGeneration: grant.authorizationGeneration, capabilityHash, updateId };
+    });
+    this.publish();
+    return { binding: publicBinding(updated.binding), capability };
+  }
+
+  public async resolveAccess(bindingId: string, capability: string, minValidityMs: number): Promise<IAuthSwitchResolvedAccess> {
+    if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)
+      || !Number.isSafeInteger(minValidityMs) || minValidityMs < 0 || minValidityMs > 3_600_000) throw new Error('Invalid runtime credential request.');
+    const supplied = Buffer.from(idHash(capability), 'hex');
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const initial = await this.database.readBindingContext(bindingId);
+      const binding = initial.binding;
+      const expected = Buffer.from(binding?.capabilityHash ?? '0'.repeat(64), 'hex');
+      if (!binding || !plugins.crypto.timingSafeEqual(supplied, expected)) {
+        throw new Error('Runtime binding is not authorized.');
+      }
+      const { account, grant } = initial;
+      if (!account || account.removed || !grant || grant.id !== binding.grantId
+        || binding.grantAuthorizationGeneration !== grant.authorizationGeneration) {
+        throw new Error('Account needs reauthentication.');
+      }
+      if (grant.state === 'exchange_may_have_been_sent') {
+        const inFlight = this.refreshes.get(account.id);
+        if (!inFlight) throw new Error('Account refresh is unresolved; reauthentication is required.');
+        await inFlight;
+        continue;
+      }
+      if (grant.owner !== 'daemon' || grant.purpose !== 'openai_managed'
+        || !['ready', 'retry_wait'].includes(grant.state)) {
+        throw new Error('Account needs reauthentication.');
+      }
+      if (this.isDue(grant, minValidityMs)) {
+        if (grant.state === 'ready' || (grant.retryAt !== null && Date.parse(grant.retryAt) <= this.now())) {
+          await this.refreshAccount(account.id);
+          continue;
+        }
+        throw new Error('Account access credential is not fresh enough.');
+      }
+      if (!grant.accessExpiresAt) throw new Error('Account access credential is not fresh enough.');
+      const credential = await this.unsealCredential(account, grant);
+      const info = plugins.flexAuth.parseOpenAiChatGptTokenInfo(credential.accessToken);
+      if (info.chatgptAccountId !== account.workspaceId || info.chatgptUserId !== account.subject) {
+        throw new Error('Account access identity changed.');
+      }
+      const latest = await this.database.readBindingContext(bindingId);
+      if (!latest.binding || latest.binding.capabilityHash !== binding.capabilityHash
+        || latest.binding.accountId !== binding.accountId
+        || latest.binding.grantId !== binding.grantId
+        || latest.binding.incarnationId !== binding.incarnationId
+        || latest.binding.grantAuthorizationGeneration !== binding.grantAuthorizationGeneration
+        || latest.account?.removed || !latest.grant
+        || latest.grant.authorizationGeneration !== grant.authorizationGeneration
+        || latest.grant.owner !== 'daemon') {
+        throw new Error('Account binding changed during credential resolution.');
+      }
+      if (latest.grant.grantGeneration !== grant.grantGeneration
+        || latest.grant.state === 'exchange_may_have_been_sent') continue;
+      if (!['ready', 'retry_wait'].includes(latest.grant.state) || this.isDue(latest.grant, minValidityMs)) {
+        throw new Error('Account access credential is not fresh enough.');
+      }
+      return { accessToken: credential.accessToken, accountId: account.workspaceId,
+        isFedrampAccount: info.chatgptAccountIsFedramp, expiresAt: grant.accessExpiresAt,
+        grantGeneration: grant.grantGeneration };
+    }
+    throw new Error('Account credential rotated repeatedly during resolution; retry the request.');
+  }
+
+  private async refreshAccount(accountId: string): Promise<void> {
+    const prior = this.refreshes.get(accountId);
+    if (prior) return prior;
+    const task = this.performRefresh(accountId).finally(() => { if (this.refreshes.get(accountId) === task) this.refreshes.delete(accountId); });
+    this.refreshes.set(accountId, task);
+    return task;
+  }
+
+  private async performRefresh(accountId: string): Promise<void> {
+    const initial = await this.database.readAccountAndPrimaryGrant(accountId);
+    const initialGrant = initial.grant;
+    if (!initial.account || initial.account.removed || !initialGrant || initialGrant.purpose !== 'openai_managed'
+      || !['ready', 'retry_wait'].includes(initialGrant.state) || initialGrant.owner !== 'daemon'
+      || !this.isDue(initialGrant, 0)
+      || (initialGrant.state === 'retry_wait'
+        && (initialGrant.retryAt === null || Date.parse(initialGrant.retryAt) > this.now()))) return;
+    const credential = await this.unsealCredential(initial.account, initialGrant);
+    const attemptId = plugins.crypto.randomUUID();
+    await this.database.changeGrant(attemptId, initialGrant.id, (grant, account) => {
+      if (account.removed || grant.state !== initialGrant.state || grant.revision !== initialGrant.revision
+        || grant.grantGeneration !== initialGrant.grantGeneration) throw new Error('Account changed before refresh began.');
+      return { ...grant, state: 'exchange_may_have_been_sent', attemptId, retryAt: null,
+        revision: grant.revision + 1, statusObservedAt: new Date(this.now()).toISOString(), updateId: attemptId };
+    });
+    this.publish();
+    try {
+      const refreshed = await this.provider.refreshCredential(credential);
+      if (!refreshed.success) {
+        if (refreshed.requestOutcome === 'notSent') {
+          const retryId = plugins.crypto.randomUUID();
+          await this.database.changeGrant(retryId, initialGrant.id, grant => {
+            if (grant.state !== 'exchange_may_have_been_sent' || grant.attemptId !== attemptId) {
+              throw new Error('Account ownership changed during refresh.');
+            }
+            const backoffMs = Math.min(30_000 * 2 ** Math.min(grant.retryCount, 10), 1_800_000);
+            const retryMs = Math.max(backoffMs, Math.min(refreshed.retryAfterMs ?? 0, 3_600_000));
+            return { ...grant, state: 'retry_wait', attemptId: null,
+              retryAt: new Date(this.now() + retryMs).toISOString(), retryCount: grant.retryCount + 1,
+              problem: 'provider_unavailable',
+              revision: grant.revision + 1, statusObservedAt: new Date(this.now()).toISOString(), updateId: retryId };
+          });
+          this.publish();
+          return;
+        }
+        throw new Error('Provider refresh outcome is unknown.');
+      }
+      const identity = this.identity(refreshed.credential);
+      if (identity.id !== accountId) throw new Error('Provider returned a different account.');
+      const ciphertext = await this.sealCredential(initialGrant.id, refreshed.credential);
+      const commitId = plugins.crypto.randomUUID();
+      await this.database.changeGrant(commitId, initialGrant.id, grant => {
+        if (grant.state !== 'exchange_may_have_been_sent' || grant.attemptId !== attemptId) {
+          throw new Error('Account ownership changed during refresh.');
+        }
+        return { ...grant, state: 'ready', attemptId: null, retryAt: null, retryCount: 0, problem: 'none',
+          ciphertext, accessExpiresAt: tokenExpiry(refreshed.credential),
+          grantGeneration: grant.grantGeneration + 1, revision: grant.revision + 1,
+          statusObservedAt: new Date(this.now()).toISOString(), updateId: commitId };
+      });
+      this.publish();
+    } catch {
+      const uncertainId = plugins.crypto.randomUUID();
+      try {
+        await this.database.changeGrant(uncertainId, initialGrant.id, grant => {
+          if (grant.state !== 'exchange_may_have_been_sent' || grant.attemptId !== attemptId) {
+            throw new Error('Account was changed after its refresh attempt.');
+          }
+          return { ...grant, state: 'needs_reauth', attemptId: null, retryAt: null,
+            problem: 'exchange_uncertain', revision: grant.revision + 1,
+            statusObservedAt: new Date(this.now()).toISOString(), updateId: uncertainId };
+        });
+        this.publish();
+      } catch { /* A persisted attempt marker forces needs_reauth on daemon restart. */ }
+      throw new Error('Refresh result is uncertain. Reauthenticate this account; its old grant will not be replayed.');
+    }
+  }
+
+  public async close(): Promise<void> {
+    this.closed = true;
+    if (this.timer) clearTimeout(this.timer);
+    for (const wake of this.listeners) wake();
+    await Promise.allSettled([...this.operations.values()].map(item => item.handle.cancel()));
+    await Promise.allSettled([...this.operations.values()].map(item => item.task));
+    await Promise.allSettled([...this.refreshes.values()]);
+    await this.provider.dispose();
+  }
+}