@modelprofile.com/authswitch 8.2.0 → 9.1.0

package/ts/classes.authoritybroker.ts

@@ -1,9 +1,10 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
-  IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
-import { AuthSwitchRefusal } from './authority-contract.js';
+  IAuthSwitchNativeAssignment, IAuthSwitchOperation, IAuthSwitchSnapshot, IReq_AuthSwitchSnapshot,
+  TAuthSwitchLoginOwnerTool } from './authority-contract.js';
+import { AuthSwitchRefusal, isAuthSwitchAccountLabel } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
-import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
+import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityClaudeHome, IStoredAuthorityGrant,
   IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
 import type { IAuthSwitchUsageContext } from './classes.authorityusage.js';
 import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
@@ -41,8 +42,6 @@ const sameUsageAuthority = (left: IAuthSwitchUsageContext, right: IAuthSwitchUsa
 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'
   && value.length > 0 && value.length <= maximum && !/[\u0000-\u001f\u007f]/.test(value);
 const validRevision = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
@@ -51,14 +50,61 @@ const tokenExpiry = (credential: TOpenAiCredential): string | null => {
   catch { return null; }
 };
 const openAiGrantId = (accountId: string): string => idHash('authswitch-grant-v1', accountId, 'openai_managed', 'chatgpt');
+
+/**
+ * What a caller is told when the answer is decided. Each states the repair and names no id, path or host.
+ *
+ * They are written once because several sites answer the same question: an operation id this authority does
+ * not hold is the same answer whether a read, a cancel or a start met it, and a client that branches on the
+ * code must not have to tell those apart.
+ */
+const unknownOperation = 'This authority knows no device sign-in by that operation ID. '
+  + 'Start a new sign-in and follow that one.';
+const loginNotBindable = 'This login cannot back a runtime binding. The authority must hold the login '
+  + 'itself, it must be the account\'s selected OpenAI login, and it must be ready. Reauthenticate the '
+  + 'account or choose another one.';
+const bindingUnauthorized = 'This runtime binding is not authorized. Bind the account again to obtain a '
+  + 'capability for it.';
+const bindingMoved = 'This runtime binding changed while its credential was being resolved. Bind the '
+  + 'account again.';
+const bindingNeedsReauth = 'The account no longer holds the login this binding was authorized for. '
+  + 'Reauthenticate the account, then bind it again.';
+const loginNeedsReauth = 'This account\'s sign-in has ended. Reauthenticate the account with a new device '
+  + 'sign-in; a runtime bound to it binds again afterwards.';
+const accessNotFresh = 'The provider could not renew this account\'s access yet. Try the request again '
+  + 'shortly; the authority keeps retrying the renewal.';
 const publicAccount = (account: IStoredAuthorityAccount): IAuthSwitchAccount => ({
   id: account.id, providerId: account.providerId, label: account.label, email: account.email,
   plan: account.plan, removed: account.removed, revision: account.revision,
   statusObservedAt: account.statusObservedAt,
 });
+
+/**
+ * Which native tool refreshes a grant, decided here because this is the one place that publishes a login.
+ *
+ * `owner` and `purpose` are what the authority stores; the tool is their meaning, and naming it here keeps
+ * every consumer from re-deriving it -- the derivation that is wrong as soon as two purposes share a tool,
+ * or one tool gains a second purpose. `daemon` and `none` have no native refresher at all, which is a value
+ * of its own rather than a missing one.
+ */
+const loginOwnerTool = (grant: IStoredAuthorityGrant): TAuthSwitchLoginOwnerTool | null => {
+  if (grant.owner === 'claude_native') return 'claude_code';
+  if (grant.owner !== 'legacy_native') return null;
+  switch (grant.purpose) {
+    case 'opencode_native': return 'opencode';
+    case 'openai_managed': return 'codex';
+    case 'claude_host_native': return 'claude_code';
+    // A container setup token is held for a container, not refreshed by a tool on this host.
+    case 'claude_container_setup': return null;
+    // A purpose added without deciding its tool fails the type check here rather than publishing `null`,
+    // which would claim the authority refreshes a login some tool actually holds.
+    default: { const unhandledPurpose: never = grant.purpose; return unhandledPurpose; }
+  }
+};
+
 const publicLogin = (grant: IStoredAuthorityGrant): IAuthSwitchLogin => ({
   id: grant.id, accountId: grant.accountId, providerId: grant.providerId, purpose: grant.purpose,
-  owner: grant.owner,
+  owner: grant.owner, ownerTool: loginOwnerTool(grant),
   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,
@@ -90,6 +136,12 @@ const publicBinding = (binding: IStoredAuthorityBinding): IAuthSwitchBinding =>
   scopeId: binding.scopeId, incarnationId: binding.incarnationId, revision: binding.revision,
 });
 
+const publicClaudeAssignment = (home: IStoredAuthorityClaudeHome): IAuthSwitchNativeAssignment => ({
+  id: home.id, tool: 'claude_code', accountId: home.activeAccountId, loginId: home.activeGrantId,
+  state: home.status === 'quarantined' ? 'quarantined' : home.pendingOperationId !== null ? 'switching' : 'ready',
+  revision: home.revision,
+});
+
 interface IManagedOperation {
   id: string;
   handle: plugins.flexAccounts.ISmartAiProviderLoginHandle;
@@ -111,6 +163,8 @@ export class AuthSwitchAuthorityBroker {
   private readonly operations = new Map<string, IManagedOperation>();
   private readonly refreshes = new Map<string, Promise<void>>();
   private readonly listeners = new Set<() => void>();
+  /** Operation long polls; woken by their operation's own changes, and all of them on close. */
+  private readonly operationWaiters = new Set<() => void>();
   private claudeRefresh?: (grantId: string) => Promise<void>;
   private maintenance?: Promise<void>;
   private timer?: NodeJS.Timeout;
@@ -224,19 +278,23 @@ export class AuthSwitchAuthorityBroker {
     for (const listener of this.listeners) listener();
   }
 
-  public async snapshot(options: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; limit?: number } = {}): Promise<IAuthSwitchSnapshot> {
+  public async snapshot(options: IReq_AuthSwitchSnapshot['request'] = {}): 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.');
+      || (options.bindingAfter !== undefined && !isId(options.bindingAfter))
+      || (options.nativeAssignmentAfter !== undefined && !isId(options.nativeAssignmentAfter))) {
+      throw new Error('Invalid account snapshot cursor.');
+    }
     const page = await this.database.page(options.accountAfter ?? null, options.loginAfter ?? null,
-      options.bindingAfter ?? null, options.limit ?? 128);
+      options.bindingAfter ?? null, options.nativeAssignmentAfter ?? 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(account => !account.removed).map(publicAccount),
-      logins: page.grants.filter(grant => grant.state !== 'removed').map(publicLogin),
+      accounts: page.accounts.filter(account => options.includeRemoved || !account.removed).map(publicAccount),
+      logins: page.grants.filter(grant => options.includeRemoved || grant.state !== 'removed').map(publicLogin),
       bindings: page.bindings.map(publicBinding),
+      nativeAssignments: page.claudeHomes.map(publicClaudeAssignment),
       nextAccountCursor: page.nextAccountCursor, nextLoginCursor: page.nextGrantCursor,
-      nextBindingCursor: page.nextBindingCursor };
+      nextBindingCursor: page.nextBindingCursor, nextNativeAssignmentCursor: page.nextClaudeHomeCursor };
   }
 
   public async events(epoch: string, afterRevision: number, waitMs: number, signal?: AbortSignal): Promise<{
@@ -341,7 +399,7 @@ export class AuthSwitchAuthorityBroker {
   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 (!current || current.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
     if (deviceOperationTerminal(current)) return current;
     if (current.state !== 'starting') throw new Error('Account operation already started its provider login.');
     const updateId = plugins.crypto.randomUUID();
@@ -407,7 +465,7 @@ export class AuthSwitchAuthorityBroker {
     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.');
+      if (!stored || stored.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
       current = stored;
     } catch (error) {
       await Promise.allSettled([handle.cancel(), handle.close()]);
@@ -511,11 +569,46 @@ export class AuthSwitchAuthorityBroker {
     return publicOperation(pending);
   }
 
-  public async getOperation(operationId: string): Promise<IAuthSwitchOperation> {
+  /**
+   * One device sign-in. With `wait`, the read is a long poll, the way `events` waits: it answers at once when
+   * the operation's revision is past `afterRevision` or the sign-in has finished, and otherwise when the
+   * operation next changes or `waitMs` runs out, whichever is first -- so a caller follows the prompt and
+   * the outcome without polling. A timed-out wait answers with the unchanged operation.
+   */
+  public async getOperation(operationId: string, wait?: { afterRevision: number; waitMs: number },
+    signal?: AbortSignal): Promise<IAuthSwitchOperation> {
     if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
-    const operation = await this.database.readOperation(operationId);
-    if (!operation || operation.kind === 'preuse_openai') throw new Error('Account operation was not found.');
-    return publicOperation(operation);
+    if (wait !== undefined && (!validRevision(wait.afterRevision) || !Number.isSafeInteger(wait.waitMs)
+      || wait.waitMs < 0 || wait.waitMs > 30_000)) throw new Error('Invalid operation wait.');
+    const read = async (): Promise<IStoredAuthorityDeviceOperation> => {
+      const operation = await this.database.readOperation(operationId);
+      if (!operation || operation.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
+      return operation;
+    };
+    const answers = (operation: IStoredAuthorityDeviceOperation): boolean => wait === undefined
+      || operation.revision > wait.afterRevision || deviceOperationTerminal(operation);
+    const immediate = await read();
+    if (answers(immediate) || wait!.waitMs === 0 || this.closed || signal?.aborted) return publicOperation(immediate);
+    return new Promise((resolve, reject) => {
+      let finished = false;
+      const settle = (outcome: () => void) => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        unobserve();
+        this.operationWaiters.delete(wake);
+        signal?.removeEventListener('abort', wake);
+        outcome();
+      };
+      const wake = () => settle(() => { void read().then(operation => resolve(publicOperation(operation)), reject); });
+      const timer = setTimeout(wake, wait!.waitMs);
+      const unobserve = this.database.observeDeviceOperations(changed => { if (changed === operationId) wake(); });
+      this.operationWaiters.add(wake);
+      signal?.addEventListener('abort', wake, { once: true });
+      // Close the read/register race without holding a database session for the wait.
+      void read().then(operation => { if (answers(operation)) wake(); },
+        error => settle(() => reject(error)));
+    });
   }
 
   public async listOperations(after: string | null, limit = 128): Promise<{ operations: IAuthSwitchOperation[]; nextCursor: string | null }> {
@@ -538,7 +631,7 @@ export class AuthSwitchAuthorityBroker {
   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 || current.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
     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();
@@ -552,7 +645,11 @@ export class AuthSwitchAuthorityBroker {
   }
 
   public async renameAccount(accountId: string, expectedRevision: number, label: string): Promise<IAuthSwitchAccount> {
-    if (!isId(accountId) || !validRevision(expectedRevision) || !safeLabel(label)) throw new Error('Invalid account change.');
+    if (!isId(accountId) || !validRevision(expectedRevision)) throw new Error('Invalid account change.');
+    if (!isAuthSwitchAccountLabel(label)) {
+      throw new AuthSwitchRefusal('invalid_input', 'An account label has between one and one hundred and twenty-eight '
+        + 'characters, with no space at either end and no control character. Choose another label.');
+    }
     const updateId = plugins.crypto.randomUUID();
     const updated = await this.database.changeAccount(updateId, accountId, account => {
       if (!account || account.removed || account.revision !== expectedRevision) throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
@@ -582,11 +679,12 @@ export class AuthSwitchAuthorityBroker {
     const capabilityHash = idHash(capability);
     const updateId = plugins.crypto.randomUUID();
     const updated = await this.database.changeBinding(updateId, id, input.accountId, input.loginId, (existing, account, grant) => {
+      // A ChatGPT login backs every runtime, Claude Code included; a Claude account reaches Claude Code
+      // through its native switch instead, so it never binds (its provider is not OpenAI).
       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.');
+        || grant.purpose !== input.purpose || account.providerId !== 'openai') {
+        throw new AuthSwitchRefusal('login_unavailable', loginNotBindable);
       }
       return { id, accountId: input.accountId, grantId: grant.id, runtime: input.runtime, scopeId: input.scopeId,
         incarnationId: input.incarnationId, revision: (existing?.revision ?? 0) + 1,
@@ -596,6 +694,12 @@ export class AuthSwitchAuthorityBroker {
     return { binding: publicBinding(updated.binding), capability };
   }
 
+  public async getBinding(bindingId: string): Promise<IAuthSwitchBinding | null> {
+    if (!isId(bindingId)) throw new Error('Invalid runtime binding.');
+    const binding = await this.database.readBinding(bindingId);
+    return binding ? publicBinding(binding) : null;
+  }
+
   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,
@@ -624,21 +728,27 @@ export class AuthSwitchAuthorityBroker {
       const current = await this.database.readBindingContext(bindingId);
       const binding = current.binding;
       const expected = Buffer.from(binding?.capabilityHash ?? '0'.repeat(64), 'hex');
+      // A missing binding and a wrong capability are compared against the same zero hash on purpose, so
+      // nothing here tells a caller which it was. One code preserves exactly that, and it is truthful for
+      // both: this capability does not authorize anything, and binding again is the only repair.
       if (!binding || !plugins.crypto.timingSafeEqual(supplied, expected)) {
-        throw new Error('Runtime binding is not authorized.');
+        throw new AuthSwitchRefusal('binding_unauthorized', bindingUnauthorized);
       }
       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.');
+        // The capability still matched, so what moved is the binding itself: another incarnation took the
+        // scope, or the account was reauthorized under it. The caller's repair is the one above -- bind
+        // again -- so it is the same code; a second one would name a difference no runtime can act on.
+        throw new AuthSwitchRefusal('binding_unauthorized', bindingMoved);
       }
       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.');
+        throw new AuthSwitchRefusal('login_unavailable', bindingNeedsReauth);
       }
       return { account: current.account, grant: current.grant };
     }, minValidityMs, rejectedGrantGeneration);
@@ -660,6 +770,14 @@ export class AuthSwitchAuthorityBroker {
     }, minValidityMs, rejectedGrantGeneration);
   }
 
+  /**
+   * The shared managed-access loop. What it decides about the login itself is a marked refusal both callers
+   * read the same way: `login_needs_reauth` when only a new sign-in brings the login back, `access_not_fresh`
+   * when the login is intact and the provider could not renew it yet. The usage reader still folds either
+   * into its own problem; a bound runtime shows the instruction. What only concerns a binding is decided
+   * before this point, in the view `resolveAccess` supplies, and a changed identity or a view that keeps
+   * moving stays an unmarked fault, because nobody decided it.
+   */
   private async resolveManagedAccess(readView: () => Promise<{
     account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
   }>, minValidityMs: number, rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {
@@ -667,20 +785,20 @@ export class AuthSwitchAuthorityBroker {
       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.');
+        throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
       }
       if (rejectedGrantGeneration !== undefined && rejectedGrantGeneration > grant.grantGeneration) {
         throw new Error('Provider rejected a future account grant generation.');
       }
       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.');
+        if (!inFlight) throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
         await inFlight;
         continue;
       }
       if (grant.owner !== 'daemon' || grant.purpose !== 'openai_managed'
         || !['ready', 'retry_wait'].includes(grant.state)) {
-        throw new Error('Account needs reauthentication.');
+        throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
       }
       const rejectedCurrent = rejectedGrantGeneration === grant.grantGeneration;
       if (this.isDue(grant, minValidityMs) || rejectedCurrent) {
@@ -689,9 +807,9 @@ export class AuthSwitchAuthorityBroker {
             rejectedCurrent ? rejectedGrantGeneration : undefined);
           continue;
         }
-        throw new Error('Account access credential is not fresh enough.');
+        throw new AuthSwitchRefusal('access_not_fresh', accessNotFresh);
       }
-      if (!grant.accessExpiresAt) throw new Error('Account access credential is not fresh enough.');
+      if (!grant.accessExpiresAt) throw new AuthSwitchRefusal('access_not_fresh', accessNotFresh);
       const credential = await this.unsealCredential(account, grant);
       const info = plugins.flexAuth.parseOpenAiChatGptTokenInfo(credential.accessToken);
       if (info.chatgptAccountId !== account.workspaceId || info.chatgptUserId !== account.subject) {
@@ -709,7 +827,7 @@ export class AuthSwitchAuthorityBroker {
         || 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)) {
-        throw new Error('Account access credential is not fresh enough.');
+        throw new AuthSwitchRefusal('access_not_fresh', accessNotFresh);
       }
       return { accessToken: credential.accessToken, accountId: account.workspaceId,
         isFedrampAccount: info.chatgptAccountIsFedramp, expiresAt: grant.accessExpiresAt,
@@ -794,7 +912,8 @@ export class AuthSwitchAuthorityBroker {
         });
         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.');
+      // The grant is now `needs_reauth`: an uncertain rotation is never replayed, so only a sign-in repairs it.
+      throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
     }
   }
 
@@ -803,6 +922,7 @@ export class AuthSwitchAuthorityBroker {
     this.closed = true;
     if (this.timer) clearTimeout(this.timer);
     for (const wake of this.listeners) wake();
+    for (const wake of this.operationWaiters) wake();
     this.closing = (async () => {
       if (this.maintenance) await this.maintenance;
       await Promise.allSettled([...this.operations.values()].map(item => item.handle.cancel()));

package/ts/classes.authorityclient.ts

@@ -5,7 +5,8 @@ import type {
   IReq_AuthSwitchBeginReauth, IReq_AuthSwitchCancelOperation,
   IReq_AuthSwitchClaudeNativeHandoff, IReq_AuthSwitchClaudeNativeHandoffs,
   IReq_AuthSwitchSwitchClaudeNative, IReq_AuthSwitchEvents,
-  IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations, IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount,
+  IReq_AuthSwitchGetBinding, IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations,
+  IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount,
   IReq_AuthSwitchCancelPreuse, IReq_AuthSwitchGetPreuse, IReq_AuthSwitchSnapshot,
   IReq_AuthSwitchStartPreuse, IReq_AuthSwitchUsage,
 } from './authority-contract.js';
@@ -53,10 +54,36 @@ const post = (path: string, payload: ITypedRequest, signal?: AbortSignal): Promi
     });
 };
 
+/**
+ * The daemon answered with an older contract than this client reads: it runs an authswitch release from before
+ * this one and was not restarted after the upgrade. Restarting it onto the installed release is the repair.
+ */
+export class AuthSwitchDaemonOutdatedError extends Error {
+  constructor() {
+    super('The authswitch authority daemon runs an older release than this client. Restart it onto the '
+      + 'installed authswitch: authswitch authority service stop, then authswitch authority service start.');
+    this.name = 'AuthSwitchDaemonOutdatedError';
+  }
+}
+
+/**
+ * A snapshot page carries every member of this release's contract. `schemaVersion` is not bumped for an
+ * additive member, so an older daemon is told apart by the members its answer lacks.
+ */
+const assertCurrentSnapshot = (snapshot: IAuthSwitchSnapshot): IAuthSwitchSnapshot => {
+  const page: Partial<IAuthSwitchSnapshot> = snapshot;
+  if (!Array.isArray(page.nativeAssignments) || page.nextNativeAssignmentCursor === undefined) {
+    throw new AuthSwitchDaemonOutdatedError();
+  }
+  return snapshot;
+};
+
 /** A snapshot is usable only while state is current; lastVerifiedAt is the last successful daemon proof. */
 export interface IAuthSwitchSubscriptionStatus {
   state: 'current' | 'unavailable' | 'closed';
-  reason: 'initial' | 'snapshot' | 'event' | 'heartbeat' | 'disconnect' | 'resync' | 'abort' | 'consumer_error';
+  /** `daemon_outdated`: the daemon runs an older release; see `AuthSwitchDaemonOutdatedError`. */
+  reason: 'initial' | 'snapshot' | 'event' | 'heartbeat' | 'disconnect' | 'resync' | 'abort' | 'consumer_error'
+    | 'daemon_outdated';
   epoch: string | null;
   revision: number | null;
   lastVerifiedAt: string | null;
@@ -66,6 +93,8 @@ export interface IAuthSwitchSubscriptionOptions {
   onStatus?: (status: IAuthSwitchSubscriptionStatus) => void | Promise<void>;
   /** Bounded long-poll interval; defaults to 30 seconds. */
   heartbeatMs?: number;
+  /** Deliver snapshots that also carry removed accounts and logins; see `IReq_AuthSwitchSnapshot`. */
+  includeRemoved?: boolean;
 }
 
 /**
@@ -96,8 +125,10 @@ export class AuthSwitchClient {
       .fire(request, { timeoutMs, maxRetries: 0, abortSignal: signal });
   }
 
+  /** One snapshot page; an older daemon's answer fails with `AuthSwitchDaemonOutdatedError`. */
   public async snapshot(options: IReq_AuthSwitchSnapshot['request'] = {}, signal?: AbortSignal): Promise<IAuthSwitchSnapshot> {
-    return (await this.request<IReq_AuthSwitchSnapshot>('authswitch.authority.snapshot', options, 35_000, false, signal)).snapshot;
+    return assertCurrentSnapshot((await this.request<IReq_AuthSwitchSnapshot>('authswitch.authority.snapshot',
+      options, 35_000, false, signal)).snapshot);
   }
 
   /** One independently stamped diagnostic page; callers may continue with its independent cursors. */
@@ -132,30 +163,39 @@ export class AuthSwitchClient {
   }
 
   /** Assemble a consistent view from bounded database pages; restart if a writer changes the revision. */
-  public async snapshotAll(options: { limit?: number; signal?: AbortSignal } = {}): Promise<IAuthSwitchSnapshot> {
+  public async snapshotAll(options: { limit?: number; includeRemoved?: boolean; signal?: AbortSignal } = {}): Promise<IAuthSwitchSnapshot> {
     while (true) {
       if (options.signal?.aborted) throw options.signal.reason ?? new Error('Account snapshot cancelled.');
       let accountAfter: string | undefined;
       let loginAfter: string | undefined;
       let bindingAfter: string | undefined;
+      let nativeAssignmentAfter: string | undefined;
       let aggregate: IAuthSwitchSnapshot | undefined;
       let changed = false;
       while (true) {
-        const page = await this.snapshot({ accountAfter, loginAfter, bindingAfter, limit: options.limit }, options.signal);
-        if (!aggregate) aggregate = { ...page, accounts: [...page.accounts], logins: [...page.logins], bindings: [...page.bindings] };
-        else if (aggregate.epoch !== page.epoch || aggregate.revision !== page.revision) {
+        const page = await this.snapshot({ accountAfter, loginAfter, bindingAfter, nativeAssignmentAfter,
+          limit: options.limit, ...(options.includeRemoved ? { includeRemoved: true } : {}) }, options.signal);
+        if (!aggregate) {
+          aggregate = { ...page, accounts: [...page.accounts], logins: [...page.logins], bindings: [...page.bindings],
+            nativeAssignments: [...page.nativeAssignments] };
+        } else if (aggregate.epoch !== page.epoch || aggregate.revision !== page.revision) {
           changed = true;
           break;
         } else {
           aggregate.accounts.push(...page.accounts);
           aggregate.logins.push(...page.logins);
           aggregate.bindings.push(...page.bindings);
+          aggregate.nativeAssignments.push(...page.nativeAssignments);
         }
         accountAfter = page.nextAccountCursor ?? accountAfter ?? page.accounts.at(-1)?.id;
         loginAfter = page.nextLoginCursor ?? loginAfter ?? page.logins.at(-1)?.id;
         bindingAfter = page.nextBindingCursor ?? bindingAfter ?? page.bindings.at(-1)?.id;
-        if (!page.nextAccountCursor && !page.nextLoginCursor && !page.nextBindingCursor) {
-          return { ...aggregate, nextAccountCursor: null, nextLoginCursor: null, nextBindingCursor: null };
+        nativeAssignmentAfter = page.nextNativeAssignmentCursor ?? nativeAssignmentAfter
+          ?? page.nativeAssignments.at(-1)?.id;
+        if (!page.nextAccountCursor && !page.nextLoginCursor && !page.nextBindingCursor
+          && !page.nextNativeAssignmentCursor) {
+          return { ...aggregate, nextAccountCursor: null, nextLoginCursor: null, nextBindingCursor: null,
+            nextNativeAssignmentCursor: null };
         }
       }
       if (!changed) throw new Error('Authority snapshot could not complete.');
@@ -174,8 +214,24 @@ export class AuthSwitchClient {
     if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 50 || heartbeatMs > 30_000) {
       throw new Error('Authswitch subscription heartbeat must be 50–30000 ms.');
     }
-    const retry = () => new Promise<void>(resolve => {
-      const timer = setTimeout(() => { signal.removeEventListener('abort', aborted); resolve(); }, 250);
+    /**
+     * The pause between reconnection attempts, which never keeps its consumer's process alive.
+     *
+     * A subscription that cannot reach the daemon re-arms this timer for as long as that lasts, and during
+     * each pause it is the only handle this client holds -- the failed request already destroyed its socket.
+     * Referenced, that chain of 250 ms waits would hold an otherwise finished process open indefinitely,
+     * and it has nothing to finish: the wait itself does no work, and an abort clears it.
+     *
+     * An abort that already happened is checked before the timer is armed, because a signal fires once: a
+     * consumer that stops from inside its own disconnect callback aborts between this loop's last check and
+     * this call, and a listener added afterwards would never run. The pause would then be waited out in
+     * full, and since it holds nothing, a process whose only remaining handle it is can exit inside it --
+     * dropping the closing status this loop owes its consumer.
+     */
+    const retry = (delayMs = 250) => new Promise<void>(resolve => {
+      if (signal.aborted) { resolve(); return; }
+      const timer = setTimeout(() => { signal.removeEventListener('abort', aborted); resolve(); }, delayMs);
+      timer.unref();
       const aborted = () => { clearTimeout(timer); resolve(); };
       signal.addEventListener('abort', aborted, { once: true });
     });
@@ -192,19 +248,34 @@ export class AuthSwitchClient {
       snapshot = undefined;
       if (available) { available = false; await status('unavailable', reason); }
     };
+    /**
+     * An older daemon answers every attempt the same way until it is restarted, so the consumer is told why once
+     * per outage, and the loop keeps trying at a slower pace: the restart that repairs it needs nothing else.
+     */
+    let outdatedReported = false;
+    const unreadable = async (error: unknown): Promise<boolean> => {
+      if (!(error instanceof AuthSwitchDaemonOutdatedError)) return false;
+      snapshot = undefined;
+      available = false;
+      if (!outdatedReported) { outdatedReported = true; await status('unavailable', 'daemon_outdated'); }
+      await retry(5_000);
+      return true;
+    };
     try {
       if (!signal.aborted) await status('unavailable', 'initial');
       while (!signal.aborted) {
         if (!snapshot) {
           let fresh: IAuthSwitchSnapshot;
-          try { fresh = await this.snapshotAll({ signal }); }
-          catch {
+          try { fresh = await this.snapshotAll({ signal, includeRemoved: options.includeRemoved }); }
+          catch (error) {
             if (signal.aborted) break;
+            if (await unreadable(error)) continue;
             await invalidate('disconnect');
             await retry();
             continue;
           }
           snapshot = fresh;
+          outdatedReported = false;
           await onSnapshot(fresh);
           available = true;
           lastEpoch = fresh.epoch;
@@ -227,9 +298,10 @@ export class AuthSwitchClient {
         }
         if (result.events.length) {
           let fresh: IAuthSwitchSnapshot;
-          try { fresh = await this.snapshotAll({ signal }); }
-          catch {
+          try { fresh = await this.snapshotAll({ signal, includeRemoved: options.includeRemoved }); }
+          catch (error) {
             if (signal.aborted) break;
+            if (await unreadable(error)) continue;
             await invalidate('disconnect');
             await retry();
             continue;
@@ -274,6 +346,16 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation',
       { operationId }, 35_000, false, signal)).operation;
   }
+  /**
+   * Waits up to `waitMs` for the sign-in to change past `afterRevision` and answers with it; a finished
+   * sign-in answers at once, and a timed-out wait with the unchanged operation. Follow a sign-in by passing
+   * each answer's `revision` back until its state is final.
+   */
+  public async watchOperation(operationId: string, afterRevision: number, waitMs = 30_000,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchGetOperation['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation',
+      { operationId, afterRevision, waitMs }, waitMs + 5_000, false, signal)).operation;
+  }
   public async cancelOperation(operationId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchCancelOperation['response']['operation']> {
     return (await this.request<IReq_AuthSwitchCancelOperation>('authswitch.authority.cancel',
       { operationId }, 35_000, false, signal)).operation;
@@ -318,6 +400,11 @@ export class AuthSwitchClient {
     return this.request<IReq_AuthSwitchClaudeNativeHandoffs>('authswitch.authority.claude.handoffs',
       { after, limit }, 35_000, false, signal);
   }
+  /** The binding `bind` returned, credential-free, or null once this authority holds none by that id. */
+  public async getBinding(bindingId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchGetBinding['response']['binding']> {
+    return (await this.request<IReq_AuthSwitchGetBinding>('authswitch.authority.binding',
+      { bindingId }, 35_000, false, signal)).binding;
+  }
   public bindAccount(input: IReq_AuthSwitchBindAccount['request'],
     signal?: AbortSignal): Promise<IReq_AuthSwitchBindAccount['response']> {
     return this.request<IReq_AuthSwitchBindAccount>('authswitch.authority.bind', input, 35_000, false, signal);