@modelprofile.com/authswitch 8.1.0 → 9.0.0

package/ts/classes.authoritybroker.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
-  IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
+  IAuthSwitchOperation, IAuthSwitchSnapshot, TAuthSwitchLoginOwnerTool } from './authority-contract.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
 import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
   IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
@@ -50,14 +51,57 @@ 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 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,
@@ -340,7 +384,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();
@@ -406,7 +450,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()]);
@@ -513,7 +557,7 @@ export class AuthSwitchAuthorityBroker {
   public async getOperation(operationId: string): 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.');
+    if (!operation || operation.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
     return publicOperation(operation);
   }
 
@@ -537,7 +581,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();
@@ -554,7 +598,7 @@ export class AuthSwitchAuthorityBroker {
     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.');
+      if (!account || account.removed || account.revision !== expectedRevision) throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
       return { ...account, label, revision: account.revision + 1, updateId,
         statusObservedAt: new Date(this.now()).toISOString() };
     });
@@ -585,7 +629,7 @@ export class AuthSwitchAuthorityBroker {
         || grant.owner !== 'daemon'
         || grant.purpose !== input.purpose || account.providerId !== 'openai'
         || input.runtime === 'claude') {
-        throw new Error('Account is not available for this runtime.');
+        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,
@@ -623,21 +667,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);
@@ -659,6 +709,15 @@ export class AuthSwitchAuthorityBroker {
     }, minValidityMs, rejectedGrantGeneration);
   }
 
+  /**
+   * The shared managed-access loop, whose refusals are deliberately still unmarked faults.
+   *
+   * Its two callers repair differently: a runtime holding a binding binds again, while the usage reader has
+   * no binding at all and collapses everything into one usage problem. Naming a code here would either say
+   * "binding" to a caller that has none, or invent a second meaning for one that does, so the decision waits
+   * for the slice that gives the usage answer its own vocabulary. What a bound runtime can act on is decided
+   * before this point, in the view `resolveAccess` supplies.
+   */
   private async resolveManagedAccess(readView: () => Promise<{
     account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
   }>, minValidityMs: number, rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {

package/ts/classes.authorityclient.ts

@@ -68,7 +68,13 @@ export interface IAuthSwitchSubscriptionOptions {
   heartbeatMs?: number;
 }
 
-/** Node-only client for the per-user daemon. Each request has its own bounded Unix connection. */
+/**
+ * Node-only client for the per-user daemon. Each request has its own bounded Unix connection.
+ *
+ * Every method takes an optional `AbortSignal`. A referenced socket with a 35 second timeout outlives a
+ * consumer's own stop unless that consumer can cancel the read, so the signal is what releases it; it
+ * detaches this request only and never cancels work the daemon already owns.
+ */
 export class AuthSwitchClient {
   private readonly target: plugins.typedrequest.TypedTarget;
   private readonly runtimeTarget: plugins.typedrequest.TypedTarget;
@@ -119,9 +125,10 @@ export class AuthSwitchClient {
       { submission, callerQuiescent: true, acknowledgeRunOrder: true }, 120_000, true, signal)).result;
   }
 
-  public async getUsage(accountId: string, loginId: string, force = false): Promise<IReq_AuthSwitchUsage['response']['usage']> {
+  public async getUsage(accountId: string, loginId: string, force = false,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchUsage['response']['usage']> {
     return (await this.request<IReq_AuthSwitchUsage>('authswitch.authority.usage',
-      { accountId, loginId, force })).usage;
+      { accountId, loginId, force }, 35_000, false, signal)).usage;
   }
 
   /** Assemble a consistent view from bounded database pages; restart if a writer changes the revision. */
@@ -167,8 +174,24 @@ export class AuthSwitchClient {
     if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 50 || heartbeatMs > 30_000) {
       throw new Error('Authswitch subscription heartbeat must be 50–30000 ms.');
     }
+    /**
+     * 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 = () => new Promise<void>(resolve => {
+      if (signal.aborted) { resolve(); return; }
       const timer = setTimeout(() => { signal.removeEventListener('abort', aborted); resolve(); }, 250);
+      timer.unref();
       const aborted = () => { clearTimeout(timer); resolve(); };
       signal.addEventListener('abort', aborted, { once: true });
     });
@@ -258,8 +281,10 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchBeginReauth>('authswitch.authority.reauth',
       { operationId, accountId, loginId, purpose, flow: 'device' }, 35_000, false, signal)).operation;
   }
-  public listOperations(after?: string, limit?: number): Promise<IReq_AuthSwitchListOperations['response']> {
-    return this.request<IReq_AuthSwitchListOperations>('authswitch.authority.operations', { after, limit });
+  public listOperations(after?: string, limit?: number,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchListOperations['response']> {
+    return this.request<IReq_AuthSwitchListOperations>('authswitch.authority.operations',
+      { after, limit }, 35_000, false, signal);
   }
   public async getOperation(operationId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchGetOperation['response']['operation']> {
     return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation',
@@ -284,27 +309,39 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchCancelPreuse>(
       'authswitch.authority.preuse.cancel', { operationId }, 35_000, false, signal)).operation;
   }
-  public async renameAccount(accountId: string, expectedRevision: number, label: string): Promise<IReq_AuthSwitchRenameAccount['response']['account']> {
-    return (await this.request<IReq_AuthSwitchRenameAccount>('authswitch.authority.rename', { accountId, expectedRevision, label })).account;
+  public async renameAccount(accountId: string, expectedRevision: number, label: string,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchRenameAccount['response']['account']> {
+    return (await this.request<IReq_AuthSwitchRenameAccount>('authswitch.authority.rename',
+      { accountId, expectedRevision, label }, 35_000, false, signal)).account;
   }
-  public async removeAccount(accountId: string, expectedRevision: number): Promise<IReq_AuthSwitchRemoveAccount['response']['account']> {
-    return (await this.request<IReq_AuthSwitchRemoveAccount>('authswitch.authority.remove', { accountId, expectedRevision })).account;
+  public async removeAccount(accountId: string, expectedRevision: number,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchRemoveAccount['response']['account']> {
+    return (await this.request<IReq_AuthSwitchRemoveAccount>('authswitch.authority.remove',
+      { accountId, expectedRevision }, 35_000, false, signal)).account;
   }
-  public async switchClaudeNative(accountId: string, loginId: string): Promise<IReq_AuthSwitchSwitchClaudeNative['response']['handoff']> {
+  public async switchClaudeNative(accountId: string, loginId: string,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchSwitchClaudeNative['response']['handoff']> {
     return (await this.request<IReq_AuthSwitchSwitchClaudeNative>('authswitch.authority.claude.switch',
-      { accountId, loginId, purpose: 'claude_host_native' })).handoff;
+      { accountId, loginId, purpose: 'claude_host_native' }, 35_000, false, signal)).handoff;
   }
-  public async getClaudeNativeHandoff(operationId: string): Promise<IReq_AuthSwitchClaudeNativeHandoff['response']['handoff']> {
-    return (await this.request<IReq_AuthSwitchClaudeNativeHandoff>('authswitch.authority.claude.handoff', { operationId })).handoff;
+  public async getClaudeNativeHandoff(operationId: string,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchClaudeNativeHandoff['response']['handoff']> {
+    return (await this.request<IReq_AuthSwitchClaudeNativeHandoff>('authswitch.authority.claude.handoff',
+      { operationId }, 35_000, false, signal)).handoff;
   }
-  public listClaudeNativeHandoffs(after?: string, limit?: number): Promise<IReq_AuthSwitchClaudeNativeHandoffs['response']> {
-    return this.request<IReq_AuthSwitchClaudeNativeHandoffs>('authswitch.authority.claude.handoffs', { after, limit });
+  public listClaudeNativeHandoffs(after?: string, limit?: number,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchClaudeNativeHandoffs['response']> {
+    return this.request<IReq_AuthSwitchClaudeNativeHandoffs>('authswitch.authority.claude.handoffs',
+      { after, limit }, 35_000, false, signal);
   }
-  public bindAccount(input: IReq_AuthSwitchBindAccount['request']): Promise<IReq_AuthSwitchBindAccount['response']> {
-    return this.request<IReq_AuthSwitchBindAccount>('authswitch.authority.bind', input);
+  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);
   }
-  public resolveAccess(input: IReq_AuthSwitchResolveAccess['request']): Promise<IReq_AuthSwitchResolveAccess['response']> {
-    return this.request<IReq_AuthSwitchResolveAccess>('authswitch.authority.resolveAccess', input, 35_000, true);
+  public resolveAccess(input: IReq_AuthSwitchResolveAccess['request'],
+    signal?: AbortSignal): Promise<IReq_AuthSwitchResolveAccess['response']> {
+    return this.request<IReq_AuthSwitchResolveAccess>('authswitch.authority.resolveAccess',
+      input, 35_000, true, signal);
   }
   public releaseBinding(input: IReq_AuthSwitchReleaseBinding['request'], signal?: AbortSignal): Promise<IReq_AuthSwitchReleaseBinding['response']> {
     return this.request<IReq_AuthSwitchReleaseBinding>('authswitch.authority.release', input, 35_000, true, signal);
@@ -320,9 +357,10 @@ export class AuthSwitchRuntimeClient {
       postMethod: (payload, options) => post(runtimeSocketPath, payload, options?.signal),
     });
   }
-  public resolveAccess(input: IReq_AuthSwitchResolveAccess['request']): Promise<IReq_AuthSwitchResolveAccess['response']> {
+  public resolveAccess(input: IReq_AuthSwitchResolveAccess['request'],
+    signal?: AbortSignal): Promise<IReq_AuthSwitchResolveAccess['response']> {
     return new plugins.typedrequest.TypedRequest<IReq_AuthSwitchResolveAccess>(this.target,
-      'authswitch.authority.resolveAccess').fire(input, { timeoutMs: 35_000, maxRetries: 0 });
+      'authswitch.authority.resolveAccess').fire(input, { timeoutMs: 35_000, maxRetries: 0, abortSignal: signal });
   }
   public releaseBinding(input: IReq_AuthSwitchReleaseBinding['request'], signal?: AbortSignal): Promise<IReq_AuthSwitchReleaseBinding['response']> {
     return new plugins.typedrequest.TypedRequest<IReq_AuthSwitchReleaseBinding>(this.target,