@modelprofile.com/authswitch 6.5.0 → 8.0.0

package/ts/classes.authoritybroker.ts

@@ -1,11 +1,15 @@
 import * as plugins from './plugins.js';
-import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
+import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
+  IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
-import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant } from './classes.authoritymodels.js';
+import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
+  IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
+import type { IAuthSwitchUsageContext } from './classes.authorityusage.js';
 import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
 
 type TOpenAiCredential = plugins.flexAccounts.IOpenAiChatGptOAuthCredential;
-type TOpenAiProvider = Pick<plugins.flexAccounts.ISmartAiProviderAdapter, 'beginLogin' | 'refreshCredential' | 'inspectCredential' | 'dispose'>;
+type TOpenAiProvider = Pick<plugins.flexAccounts.ISmartAiProviderAdapter,
+  'beginLogin' | 'refreshCredential' | 'inspectCredential' | 'getAccountRateLimits' | 'dispose'>;
 
 export interface IAuthSwitchAuthorityBrokerOptions {
   provider?: TOpenAiProvider;
@@ -23,8 +27,19 @@ export interface IAuthSwitchResolvedAccess {
 }
 
 const idHash = (...values: string[]): string => plugins.crypto.createHash('sha256').update(JSON.stringify(values)).digest('hex');
+export const authSwitchBindingCapabilityHash = (capability: string): string => idHash(capability);
 const isId = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const sameUsageAuthority = (left: IAuthSwitchUsageContext, right: IAuthSwitchUsageContext): boolean =>
+  left.epoch === right.epoch && left.accountId === right.accountId && left.loginId === right.loginId
+  && left.subjectId === right.subjectId && left.workspaceId === right.workspaceId
+  && left.providerId === right.providerId
+  && left.providerId === 'openai' && left.purpose === 'openai_managed'
+  && left.owner === 'daemon' && left.purpose === right.purpose && left.owner === right.owner
+  && !left.removed && !right.removed
+  && left.authorizationGeneration === right.authorizationGeneration;
 const isUuid = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value);
+const deviceOperationTerminal = (operation: IStoredAuthorityDeviceOperation): boolean =>
+  !['starting', 'pending', 'committing'].includes(operation.state);
 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'
@@ -35,26 +50,54 @@ const tokenExpiry = (credential: TOpenAiCredential): string | 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 => ({
+const publicAccount = (account: IStoredAuthorityAccount): 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',
+  plan: account.plan, removed: account.removed, revision: account.revision,
   statusObservedAt: account.statusObservedAt,
 });
+const publicLogin = (grant: IStoredAuthorityGrant): IAuthSwitchLogin => ({
+  id: grant.id, accountId: grant.accountId, providerId: grant.providerId, purpose: grant.purpose,
+  owner: grant.owner,
+  health: grant.state === 'exchange_may_have_been_sent' ? 'refreshing'
+    : grant.state === 'native' ? 'unverified'
+      : grant.state === 'legacy_native_pending' || grant.state === 'handoff_pending' ? 'pending_handoff' : grant.state,
+  problem: grant.problem, grantGeneration: grant.grantGeneration, revision: grant.revision,
+  accessExpiresAt: grant.accessExpiresAt, retryAt: grant.retryAt,
+  statusObservedAt: grant.statusObservedAt,
+  capabilities: {
+    canReauthenticate: grant.purpose === 'openai_managed' && grant.owner === 'daemon'
+      && grant.id === openAiGrantId(grant.accountId)
+      && !['removed', 'exchange_may_have_been_sent'].includes(grant.state),
+    canBind: grant.purpose === 'openai_managed' && grant.owner === 'daemon'
+      && grant.id === openAiGrantId(grant.accountId) && grant.state === 'ready',
+    canPreuse: grant.providerId === 'openai' && grant.purpose === 'openai_managed' && grant.owner === 'daemon'
+      && grant.id === openAiGrantId(grant.accountId) && ['ready', 'retry_wait'].includes(grant.state),
+  },
+});
+const publicOperation = (stored: IStoredAuthorityDeviceOperation): IAuthSwitchOperation => ({
+  id: stored.id, kind: stored.kind, purpose: stored.purpose,
+  targetAccountId: stored.accountId, targetLoginId: stored.grantId, state: stored.state,
+  prompt: stored.prompt, result: stored.result ? {
+    accountId: stored.result.accountId, loginId: stored.result.grantId,
+    accountRevision: stored.result.accountRevision, loginGeneration: stored.result.grantGeneration,
+  } : null,
+  error: stored.error, createdAt: stored.createdAt, updatedAt: stored.updatedAt,
+  finishedAt: stored.finishedAt, revision: stored.revision,
+});
 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;
+  id: string;
   handle: plugins.flexAccounts.ISmartAiProviderLoginHandle;
   task: Promise<void>;
-  cancelled: boolean;
-  committing: boolean;
-  finishedAt: number | null;
+}
+
+interface IStartingOperation {
+  requestKey: string;
+  promise: Promise<IAuthSwitchOperation>;
 }
 
 /** One daemon-owned authority. No management DTO contains a refresh grant. */
@@ -63,11 +106,15 @@ export class AuthSwitchAuthorityBroker {
   private readonly secrets: IAuthSwitchSecretCodec;
   private readonly now: () => number;
   private readonly proactive: boolean;
+  private readonly starts = new Map<string, IStartingOperation>();
   private readonly operations = new Map<string, IManagedOperation>();
   private readonly refreshes = new Map<string, Promise<void>>();
   private readonly listeners = new Set<() => void>();
+  private claudeRefresh?: (grantId: string) => Promise<void>;
+  private maintenance?: Promise<void>;
   private timer?: NodeJS.Timeout;
   private closed = false;
+  private closing?: Promise<void>;
 
   constructor(private readonly database: AuthSwitchAuthorityDatabase, options: IAuthSwitchAuthorityBrokerOptions = {}) {
     this.provider = options.provider ?? new plugins.flexAccounts.OpenAiProviderAdapter();
@@ -76,6 +123,13 @@ export class AuthSwitchAuthorityBroker {
     this.proactive = options.proactive ?? true;
   }
 
+  public setClaudeRefresher(refresh: (grantId: string) => Promise<void>): void {
+    if (this.claudeRefresh) throw new Error('Claude refresh owner is already configured.');
+    this.claudeRefresh = refresh;
+  }
+
+  public notifyChanged(): void { this.publish(); }
+
   public async start(): Promise<void> {
     const probe = plugins.crypto.randomBytes(32);
     const probeId = idHash('authswitch-custody-probe-v1');
@@ -88,6 +142,28 @@ export class AuthSwitchAuthorityBroker {
         }
       } finally { opened.fill(0); }
     } finally { probe.fill(0); }
+    for (const state of ['starting', 'pending', 'committing'] as const) {
+      let after: string | null = null;
+      while (true) {
+        const page = await this.database.operationsByState(state, after);
+        if (!page.length) break;
+        for (const operation of page) {
+          const now = new Date(this.now()).toISOString();
+          const updateId = plugins.crypto.randomUUID();
+          await this.database.changeOperation(updateId, operation.id, current => {
+            if (current.state !== state) throw new Error('Device operation recovery changed concurrently.');
+            return { ...current, state: state === 'committing' ? 'outcome_unknown' : 'interrupted',
+              prompt: null, result: null,
+              error: state === 'committing'
+                ? 'Sign-in completed but its account result could not be confirmed. Check the login before retrying.'
+                : 'Sign-in was interrupted by authority restart; no account change was committed.',
+              updatedAt: now, finishedAt: now, revision: current.revision + 1,
+              updateId };
+          });
+        }
+        after = page.at(-1)!.id;
+      }
+    }
     let after: string | null = null;
     while (true) {
       const page = await this.database.grantsByState('exchange_may_have_been_sent', after);
@@ -109,9 +185,13 @@ export class AuthSwitchAuthorityBroker {
   private schedule(): void {
     if (this.closed) return;
     this.timer = setTimeout(() => {
-      void this.refreshDueAccounts().catch(() => {
+      const task = this.refreshDueAccounts().catch(() => {
         process.stderr.write('Authswitch proactive refresh scan failed; account status may be stale.\n');
-      }).finally(() => this.schedule());
+      }).finally(() => {
+        if (this.maintenance === task) this.maintenance = undefined;
+        this.schedule();
+      });
+      this.maintenance = task;
     }, 30_000);
     this.timer.unref();
   }
@@ -121,12 +201,14 @@ export class AuthSwitchAuthorityBroker {
     for (const state of ['ready', 'retry_wait'] as const) {
       let after: string | null = null;
       while (true) {
-      const page = await this.database.grantsByState(state, after);
+        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)
+        await Promise.allSettled(page.filter(grant => 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)));
+          .flatMap(grant => grant.purpose === 'openai_managed'
+            ? [this.refreshAccount(grant.accountId, 0)]
+            : grant.purpose === 'claude_host_native' && this.claudeRefresh
+              ? [this.claudeRefresh(grant.id)] : []));
         after = page.at(-1)!.id;
       }
     }
@@ -141,16 +223,19 @@ export class AuthSwitchAuthorityBroker {
     for (const listener of this.listeners) listener();
   }
 
-  public async snapshot(options: { accountAfter?: string; bindingAfter?: string; limit?: number } = {}): Promise<IAuthSwitchSnapshot> {
+  public async snapshot(options: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; limit?: number } = {}): Promise<IAuthSwitchSnapshot> {
     if ((options.accountAfter !== undefined && !isId(options.accountAfter))
+      || (options.loginAfter !== undefined && !isId(options.loginAfter))
       || (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,
+    const page = await this.database.page(options.accountAfter ?? null, options.loginAfter ?? null,
+      options.bindingAfter ?? null, options.limit ?? 128);
+    return { schemaVersion: 2, 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)),
+      accounts: page.accounts.filter(account => !account.removed).map(publicAccount),
+      logins: page.grants.filter(grant => grant.state !== 'removed').map(publicLogin),
       bindings: page.bindings.map(publicBinding),
-      nextAccountCursor: page.nextAccountCursor, nextBindingCursor: page.nextBindingCursor };
+      nextAccountCursor: page.nextAccountCursor, nextLoginCursor: page.nextGrantCursor,
+      nextBindingCursor: page.nextBindingCursor };
   }
 
   public async events(epoch: string, afterRevision: number, waitMs: number, signal?: AbortSignal): Promise<{
@@ -233,113 +318,236 @@ export class AuthSwitchAuthorityBroker {
     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 startDeviceOperation(operationId: string, requestKey: string,
+    start: () => Promise<IAuthSwitchOperation>): Promise<IAuthSwitchOperation> {
+    if (!isUuid(operationId)) return Promise.reject(new Error('Invalid operation ID.'));
+    if (this.closed) return Promise.reject(new Error('Authswitch authority is closing.'));
+    const existing = this.starts.get(operationId);
+    if (existing) {
+      if (existing.requestKey !== requestKey) {
+        return Promise.reject(new Error('Account operation ID belongs to a different request.'));
+      }
+      return existing.promise;
+    }
+    const promise = start();
+    this.starts.set(operationId, { requestKey, promise });
+    void promise.finally(() => {
+      if (this.starts.get(operationId)?.promise === promise) this.starts.delete(operationId);
+    }).catch(() => {});
+    return promise;
+  }
+
+  private async finishStartingOperation(operationId: string, state: 'failed' | 'interrupted',
+    error: string): Promise<IStoredAuthorityDeviceOperation> {
+    const current = await this.database.readOperation(operationId);
+    if (!current || current.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+    if (deviceOperationTerminal(current)) return current;
+    if (current.state !== 'starting') throw new Error('Account operation already started its provider login.');
+    const updateId = plugins.crypto.randomUUID();
+    const now = new Date(this.now()).toISOString();
+    try {
+      return await this.database.changeOperation(updateId, operationId, operation => ({ ...operation,
+        state, error, updatedAt: now, finishedAt: now, revision: operation.revision + 1, updateId }));
+    } catch (changeError) {
+      const changed = await this.database.readOperation(operationId);
+      if (changed && changed.kind !== 'preuse_openai' && deviceOperationTerminal(changed)) return changed;
+      throw changeError;
+    }
+  }
+
+  public beginAddOpenAi(operationId: string): Promise<IAuthSwitchOperation> {
+    return this.startDeviceOperation(operationId, 'add_openai', () => this.beginLogin(operationId, null));
   }
 
-  private async beginLogin(targetId: string | null): Promise<IAuthSwitchOperation> {
+  public beginReauthOpenAi(operationId: string, accountId: string, loginId: string,
+    purpose: 'openai_managed', beforeNew?: () => Promise<void>): Promise<IAuthSwitchOperation> {
+    if (!isId(accountId) || !isId(loginId) || purpose !== 'openai_managed') {
+      return Promise.reject(new Error('Invalid login target.'));
+    }
+    const requestKey = JSON.stringify(['reauth_openai', accountId, loginId, purpose]);
+    return this.startDeviceOperation(operationId, requestKey,
+      () => this.beginLogin(operationId, { accountId, grantId: loginId }, beforeNew));
+  }
+
+  private async beginLogin(operationId: string, target: { accountId: string; grantId: string } | null,
+    beforeNew?: () => Promise<void>): 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 now = new Date(this.now()).toISOString();
+    const admitted = await this.database.createOperation({ id: operationId, kind: target ? 'reauth_openai' : 'add_openai',
+      purpose: 'openai_managed', accountId: target?.accountId ?? null, grantId: target?.grantId ?? null,
+      state: 'starting', prompt: null, result: null, error: null, commitId: null,
+      createdAt: now, updatedAt: now, finishedAt: null,
+      revision: 1, updateId: plugins.crypto.randomUUID() });
+    if (!admitted.created) return publicOperation(admitted.operation);
+    const id = operationId;
+    try {
+      if (this.closed) throw new Error('Authswitch authority is closing.');
+      if (this.operations.size >= 32) throw new Error('Too many pending device logins.');
+      await beforeNew?.();
+      if (this.closed) throw new Error('Authswitch authority is closing.');
+      await this.database.confirmOperationMayStart(id);
+      if (this.closed) throw new Error('Authswitch authority is closing.');
+    } catch (error) {
+      const terminal = await this.finishStartingOperation(id, this.closed ? 'interrupted' : 'failed',
+        this.closed ? 'Sign-in was interrupted; no account change was committed.'
+          : 'Device sign-in preparation failed; no provider login was started.');
+      if (terminal.state === 'cancelled') return publicOperation(terminal);
+      throw error;
+    }
+    let handle: plugins.flexAccounts.ISmartAiProviderLoginHandle;
+    try {
+      handle = await this.provider.beginLogin({ flow: 'device' });
+    } catch {
+      return publicOperation(await this.finishStartingOperation(id, this.closed ? 'interrupted' : 'failed',
+        this.closed ? 'Sign-in was interrupted; no account change was committed.'
+          : 'Device sign-in could not start.'));
+    }
+    void handle.completion.catch(() => {});
+    let current: IStoredAuthorityDeviceOperation;
+    try {
+      const stored = await this.database.readOperation(id);
+      if (!stored || stored.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+      current = stored;
+    } catch (error) {
+      await Promise.allSettled([handle.cancel(), handle.close()]);
+      throw error;
     }
-    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.');
+    if (this.closed || current.state !== 'starting') {
+      await Promise.allSettled([handle.cancel(), handle.close()]);
+      const terminal = this.closed && current.state === 'starting'
+        ? await this.finishStartingOperation(id, 'interrupted',
+          'Sign-in was interrupted; no account change was committed.') : current;
+      return publicOperation(terminal);
+    }
+    const prompt = handle.prompt;
+    if (prompt.flow !== 'device') {
+      await Promise.allSettled([handle.cancel(), handle.close()]);
+      return publicOperation(await this.finishStartingOperation(id, 'failed', 'Device sign-in could not start.'));
+    }
+    const operation: IManagedOperation = { id, handle, task: Promise.resolve() };
+    this.operations.set(id, operation);
+    let pending: IStoredAuthorityDeviceOperation;
+    try {
+      const updateId = plugins.crypto.randomUUID();
+      pending = await this.database.changeOperation(updateId, id, current => ({ ...current,
+        state: 'pending', prompt: { flow: 'device', verificationUrl: prompt.verificationUrl,
+          userCode: prompt.userCode }, updatedAt: new Date(this.now()).toISOString(),
+        revision: current.revision + 1, updateId }));
+    } catch (error) {
+      await Promise.allSettled([handle.cancel(), handle.close()]);
+      if (this.operations.get(id) === operation) this.operations.delete(id);
+      const current = await this.database.readOperation(id);
+      if (current && current.kind !== 'preuse_openai' && deviceOperationTerminal(current)) return publicOperation(current);
+      throw error;
     }
-    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;
+      if (this.closed) throw new Error('Authority closed during sign-in.');
       const identity = this.identity(result.credential);
-      if (targetId !== null && identity.id !== targetId) throw new Error('The device login selected a different OpenAI account.');
+      if (target && identity.id !== target.accountId) throw new Error('The device login selected a different OpenAI account.');
       const grantId = openAiGrantId(identity.id);
+      if (target && grantId !== target.grantId) throw new Error('The device login selected a different OpenAI login.');
+      const commitId = plugins.crypto.randomUUID();
+      try {
+        const markerUpdateId = plugins.crypto.randomUUID();
+        await this.database.changeOperation(markerUpdateId, id, current => {
+          if (current.state !== 'pending') throw new Error('Device operation is no longer pending.');
+          return { ...current, state: 'committing', prompt: null, commitId,
+            updatedAt: new Date(this.now()).toISOString(), revision: current.revision + 1,
+            updateId: markerUpdateId };
+        });
+      } catch (error) {
+        const current = await this.database.readOperation(id);
+        if (current?.state === 'cancelled' || current?.state === 'interrupted') return;
+        throw error;
+      }
       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 (this.closed) throw new Error('Authority closed before device sign-in commit.');
+      await this.database.commitLoginOperation(commitId, id, identity.id, grantId, (existing, oldGrant) => {
+        if (!target && existing && !existing.removed) throw new Error('Account already exists; reauthenticate that account instead.');
+        if (target && (!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 }
+            revision: existing.revision + 1, statusObservedAt: now, updateId: commitId }
           : { 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 };
+            revision: 1, statusObservedAt: now, updateId: commitId };
         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 }
+            attemptId: null, retryAt: null, retryCount: 0, problem: 'none', statusObservedAt: now, updateId: commitId }
           : { 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 };
+            retryAt: null, retryCount: 0, problem: 'none', statusObservedAt: now, updateId: commitId };
         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.';
+    }).catch(async () => {
+      const current = await this.database.readOperation(id);
+      if (!current || ['complete', 'failed', 'cancelled', 'interrupted', 'outcome_unknown'].includes(current.state)) return;
+      const state = current.state === 'committing' ? 'outcome_unknown' : this.closed ? 'interrupted' : 'failed';
+      const updateId = plugins.crypto.randomUUID();
+      await this.database.changeOperation(updateId, id, prior => ({ ...prior, state,
+        prompt: null, result: null, error: state === 'outcome_unknown'
+          ? 'Sign-in completed but its account result could not be confirmed. Check the login before retrying.'
+          : state === 'interrupted' ? 'Sign-in was interrupted; no account change was committed.'
+            : target ? 'Reauthentication failed or selected a different identity. The existing login was preserved.'
+              : 'Device sign-in failed. No account was added.',
+        updatedAt: new Date(this.now()).toISOString(), finishedAt: new Date(this.now()).toISOString(),
+        revision: prior.revision + 1, updateId }));
     }).finally(async () => {
-      operation.finishedAt = this.now();
       try { await handle.close(); } catch { /* A completed operation remains inspectable. */ }
+      if (this.operations.get(id) === operation) this.operations.delete(id);
     });
-    return structuredClone(publicOperation);
+    void operation.task.catch(() => {});
+    return publicOperation(pending);
   }
 
-  public getOperation(operationId: string): IAuthSwitchOperation {
+  public async getOperation(operationId: string): Promise<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);
+    const operation = await this.database.readOperation(operationId);
+    if (!operation || operation.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+    return publicOperation(operation);
+  }
+
+  public async listOperations(after: string | null, limit = 128): Promise<{ operations: IAuthSwitchOperation[]; nextCursor: string | null }> {
+    if (after !== null && !isUuid(after)) throw new Error('Invalid operation cursor.');
+    const page = await this.database.operationsPage(after, limit);
+    return { operations: page.operations.map(publicOperation), nextCursor: page.nextCursor };
   }
 
   /** Trusted daemon lifecycle hook: hold new managed runtimes out until targeted reauth settles. */
   public async waitOperation(operationId: string): Promise<void> {
     const operation = this.operations.get(operationId);
-    if (!isUuid(operationId) || !operation) throw new Error('Account operation expired or was not found.');
-    await operation.task;
-  }
-
-  private pruneOperations(): void {
-    for (const [id, operation] of this.operations) {
-      if (operation.finishedAt !== null && this.now() - operation.finishedAt > 600_000) this.operations.delete(id);
+    if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
+    if (operation) await operation.task;
+    else if (['starting', 'pending', 'committing'].includes(
+      (await this.database.readOperation(operationId))?.state ?? '')) {
+      throw new Error('Unfinished device operation has no active provider owner.');
     }
   }
 
   public async cancelOperation(operationId: string): Promise<IAuthSwitchOperation> {
+    if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
+    const current = await this.database.readOperation(operationId);
+    if (!current || current.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+    if (current.state === 'committing') throw new Error('Login is completing; check its operation status.');
+    if (current.state !== 'starting' && current.state !== 'pending') return publicOperation(current);
+    const updateId = plugins.crypto.randomUUID();
+    const cancelled = await this.database.changeOperation(updateId, operationId, prior => ({ ...prior,
+      state: 'cancelled', prompt: null, result: null, error: 'Device sign-in was cancelled.',
+      updatedAt: new Date(this.now()).toISOString(), finishedAt: new Date(this.now()).toISOString(),
+      revision: prior.revision + 1, updateId }));
     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);
+    if (operation) await operation.handle.cancel();
+    return publicOperation(cancelled);
   }
 
   public async renameAccount(accountId: string, expectedRevision: number, label: string): Promise<IAuthSwitchAccount> {
@@ -351,8 +559,7 @@ export class AuthSwitchAuthorityBroker {
         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);
+    return publicAccount(updated.account);
   }
 
   public async removeAccount(accountId: string, expectedRevision: number): Promise<IAuthSwitchAccount> {
@@ -361,20 +568,22 @@ export class AuthSwitchAuthorityBroker {
     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);
+    return publicAccount(account);
   }
 
-  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)
+  public async bindAccount(input: { accountId: string; loginId: string; purpose: 'openai_managed';
+    runtime: IAuthSwitchBinding['runtime']; scopeId: string; incarnationId: string }): Promise<{ binding: IAuthSwitchBinding; capability: string }> {
+    if (!isId(input.accountId) || !isId(input.loginId) || input.purpose !== 'openai_managed'
+      || !['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'
+    const updated = await this.database.changeBinding(updateId, id, input.accountId, input.loginId, (existing, account, grant) => {
+      if (account.removed || grant?.state !== 'ready' || grant.id !== account.primaryGrantId
+        || grant.owner !== 'daemon'
+        || grant.purpose !== input.purpose || account.providerId !== 'openai'
         || input.runtime === 'claude') {
         throw new Error('Account is not available for this runtime.');
       }
@@ -388,11 +597,20 @@ export class AuthSwitchAuthorityBroker {
 
   public async revokeBinding(bindingId: string, capability: string): Promise<boolean> {
     if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)) throw new Error('Invalid runtime binding revocation.');
-    const revoked = await this.database.revokeBinding(plugins.crypto.randomUUID(), bindingId, idHash(capability));
+    const revoked = await this.database.revokeBinding(plugins.crypto.randomUUID(), bindingId,
+      authSwitchBindingCapabilityHash(capability));
     if (revoked) this.publish();
     return revoked;
   }
 
+  public async releaseExternalBinding(bindingId: string, capability: string): Promise<'released' | 'inactive'> {
+    if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)) throw new Error('Invalid runtime binding release.');
+    const released = await this.database.releaseExternalBinding(plugins.crypto.randomUUID(), bindingId,
+      authSwitchBindingCapabilityHash(capability));
+    if (released) this.publish();
+    return released ? 'released' : 'inactive';
+  }
+
   public async resolveAccess(bindingId: string, capability: string, minValidityMs: number,
     rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {
     if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)
@@ -400,16 +618,54 @@ export class AuthSwitchAuthorityBroker {
       || (rejectedGrantGeneration !== undefined && (!Number.isSafeInteger(rejectedGrantGeneration)
         || rejectedGrantGeneration < 1))) 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;
+    let originalBinding: IStoredAuthorityBinding | null = null;
+    return this.resolveManagedAccess(async () => {
+      const current = await this.database.readBindingContext(bindingId);
+      const binding = current.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) {
+      if (originalBinding && (binding.id !== originalBinding.id
+        || binding.capabilityHash !== originalBinding.capabilityHash
+        || binding.accountId !== originalBinding.accountId || binding.grantId !== originalBinding.grantId
+        || binding.incarnationId !== originalBinding.incarnationId
+        || binding.grantAuthorizationGeneration !== originalBinding.grantAuthorizationGeneration)) {
+        throw new Error('Account binding changed during credential resolution.');
+      }
+      originalBinding ??= binding;
+      if (!current.account || current.account.removed || !current.grant
+        || current.grant.id !== binding.grantId
+        || current.grant.authorizationGeneration !== binding.grantAuthorizationGeneration) {
+        throw new Error('Account needs reauthentication.');
+      }
+      return { account: current.account, grant: current.grant };
+    }, minValidityMs, rejectedGrantGeneration);
+  }
+
+  /** Backend-only access for usage; it never creates or bypasses a runtime binding. */
+  public async resolveUsageAccess(context: IAuthSwitchUsageContext,
+    rejectedGrantGeneration: number | undefined, minValidityMs: number): Promise<IAuthSwitchResolvedAccess> {
+    if (!isId(context.accountId) || !isId(context.loginId)
+      || !Number.isSafeInteger(minValidityMs) || minValidityMs < 0 || minValidityMs > 3_600_000
+      || (rejectedGrantGeneration !== undefined && (!Number.isSafeInteger(rejectedGrantGeneration)
+        || rejectedGrantGeneration < 1))) throw new Error('Invalid authority usage access request.');
+    return this.resolveManagedAccess(async () => {
+      const current = await this.database.readUsageAccessView(context.accountId, context.loginId);
+      if (!current || !sameUsageAuthority(context, current.context)) {
+        throw new Error('Account usage authority changed.');
+      }
+      return { account: current.account, grant: current.grant };
+    }, minValidityMs, rejectedGrantGeneration);
+  }
+
+  private async resolveManagedAccess(readView: () => Promise<{
+    account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
+  }>, minValidityMs: number, rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const { account, grant } = await readView();
+      if (account.removed || grant.accountId !== account.id || grant.id !== account.primaryGrantId
+        || account.providerId !== 'openai' || grant.providerId !== 'openai') {
         throw new Error('Account needs reauthentication.');
       }
       if (rejectedGrantGeneration !== undefined && rejectedGrantGeneration > grant.grantGeneration) {
@@ -428,7 +684,8 @@ export class AuthSwitchAuthorityBroker {
       const rejectedCurrent = rejectedGrantGeneration === grant.grantGeneration;
       if (this.isDue(grant, minValidityMs) || rejectedCurrent) {
         if (grant.state === 'ready' || (grant.retryAt !== null && Date.parse(grant.retryAt) <= this.now())) {
-          await this.refreshAccount(account.id, rejectedCurrent ? rejectedGrantGeneration : undefined);
+          await this.refreshAccount(account.id, minValidityMs,
+            rejectedCurrent ? rejectedGrantGeneration : undefined);
           continue;
         }
         throw new Error('Account access credential is not fresh enough.');
@@ -439,18 +696,15 @@ export class AuthSwitchAuthorityBroker {
       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
+      const latest = await readView();
+      if (latest.account.removed || latest.account.id !== account.id
+        || latest.account.primaryGrantId !== latest.grant.id
+        || latest.account.workspaceId !== account.workspaceId || latest.account.subject !== account.subject
+        || latest.grant.id !== grant.id || latest.grant.authorizationGeneration !== grant.authorizationGeneration
         || latest.grant.owner !== 'daemon') {
         throw new Error('Account binding changed during credential resolution.');
       }
-      if (latest.grant.grantGeneration !== grant.grantGeneration
+      if (latest.grant.grantGeneration !== grant.grantGeneration || latest.grant.revision !== grant.revision
         || latest.grant.state === 'exchange_may_have_been_sent') continue;
       if (!['ready', 'retry_wait'].includes(latest.grant.state) || this.isDue(latest.grant, minValidityMs)
         || (rejectedGrantGeneration !== undefined && latest.grant.grantGeneration === rejectedGrantGeneration)) {
@@ -463,20 +717,23 @@ export class AuthSwitchAuthorityBroker {
     throw new Error('Account credential rotated repeatedly during resolution; retry the request.');
   }
 
-  private async refreshAccount(accountId: string, rejectedGrantGeneration?: number): Promise<void> {
+  private async refreshAccount(accountId: string, minValidityMs: number,
+    rejectedGrantGeneration?: number): Promise<void> {
     const prior = this.refreshes.get(accountId);
     if (prior) return prior;
-    const task = this.performRefresh(accountId, rejectedGrantGeneration).finally(() => { if (this.refreshes.get(accountId) === task) this.refreshes.delete(accountId); });
+    const task = this.performRefresh(accountId, minValidityMs, rejectedGrantGeneration)
+      .finally(() => { if (this.refreshes.get(accountId) === task) this.refreshes.delete(accountId); });
     this.refreshes.set(accountId, task);
     return task;
   }
 
-  private async performRefresh(accountId: string, rejectedGrantGeneration?: number): Promise<void> {
+  private async performRefresh(accountId: string, minValidityMs: number,
+    rejectedGrantGeneration?: number): 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.grantGeneration !== rejectedGrantGeneration)
+      || (!this.isDue(initialGrant, minValidityMs) && initialGrant.grantGeneration !== rejectedGrantGeneration)
       || (initialGrant.state === 'retry_wait'
         && (initialGrant.retryAt === null || Date.parse(initialGrant.retryAt) > this.now()))) return;
     const credential = await this.unsealCredential(initial.account, initialGrant);
@@ -540,13 +797,20 @@ export class AuthSwitchAuthorityBroker {
     }
   }
 
-  public async close(): Promise<void> {
+  public close(): Promise<void> {
+    if (this.closing) return this.closing;
     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();
+    this.closing = (async () => {
+      if (this.maintenance) await this.maintenance;
+      await Promise.allSettled([...this.operations.values()].map(item => item.handle.cancel()));
+      await Promise.allSettled([...this.starts.values()].map(item => item.promise));
+      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();
+    })();
+    return this.closing;
   }
 }