@modelprofile.com/authswitch 6.4.0 → 7.0.0

package/ts/classes.authorityclient.ts

@@ -1,12 +1,16 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
 import * as plugins from './plugins.js';
 import type {
-  IAuthSwitchAccountEvent, IAuthSwitchSnapshot, IReq_AuthSwitchBeginAdd,
-  IReq_AuthSwitchBeginReauth, IReq_AuthSwitchCancelOperation, IReq_AuthSwitchEvents,
-  IReq_AuthSwitchGetOperation, IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount,
-  IReq_AuthSwitchSnapshot,
+  IAuthSwitchAccountEvent, IAuthSwitchSnapshot, IReq_AuthSwitchBeginAdd, IReq_AuthSwitchDoctor,
+  IReq_AuthSwitchBeginReauth, IReq_AuthSwitchCancelOperation,
+  IReq_AuthSwitchClaudeNativeHandoff, IReq_AuthSwitchClaudeNativeHandoffs,
+  IReq_AuthSwitchSwitchClaudeNative, IReq_AuthSwitchEvents,
+  IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations, IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount,
+  IReq_AuthSwitchCancelPreuse, IReq_AuthSwitchGetPreuse, IReq_AuthSwitchSnapshot,
+  IReq_AuthSwitchStartPreuse, IReq_AuthSwitchUsage,
 } from './authority-contract.js';
-import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchReleaseBinding,
+  IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
 import { AuthSwitchAuthorityFrameReader, authSwitchAuthorityFrameBytes,
   maxAuthSwitchAuthorityFrameBytes } from './classes.authorityframing.js';
 
@@ -47,6 +51,21 @@ const post = (path: string, payload: ITypedRequest, signal?: AbortSignal): Promi
     });
 };
 
+/** 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';
+  epoch: string | null;
+  revision: number | null;
+  lastVerifiedAt: string | null;
+}
+
+export interface IAuthSwitchSubscriptionOptions {
+  onStatus?: (status: IAuthSwitchSubscriptionStatus) => void | Promise<void>;
+  /** Bounded long-poll interval; defaults to 30 seconds. */
+  heartbeatMs?: number;
+}
+
 /** Node-only client for the per-user daemon. Each request has its own bounded Unix connection. */
 export class AuthSwitchClient {
   private readonly target: plugins.typedrequest.TypedTarget;
@@ -73,28 +92,41 @@ export class AuthSwitchClient {
     return (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. */
+  public async doctorPage(options: IReq_AuthSwitchDoctor['request'] = {}, signal?: AbortSignal): Promise<IReq_AuthSwitchDoctor['response']['page']> {
+    return (await this.request<IReq_AuthSwitchDoctor>('authswitch.authority.doctor', options, 35_000, false, signal)).page;
+  }
+
+  public async getUsage(accountId: string, loginId: string, force = false): Promise<IReq_AuthSwitchUsage['response']['usage']> {
+    return (await this.request<IReq_AuthSwitchUsage>('authswitch.authority.usage',
+      { accountId, loginId, force })).usage;
+  }
+
   /** 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> {
     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 aggregate: IAuthSwitchSnapshot | undefined;
       let changed = false;
       while (true) {
-        const page = await this.snapshot({ accountAfter, bindingAfter, limit: options.limit }, options.signal);
-        if (!aggregate) aggregate = { ...page, accounts: [...page.accounts], bindings: [...page.bindings] };
+        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) {
           changed = true;
           break;
         } else {
           aggregate.accounts.push(...page.accounts);
+          aggregate.logins.push(...page.logins);
           aggregate.bindings.push(...page.bindings);
         }
         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.nextBindingCursor) {
-          return { ...aggregate, nextAccountCursor: null, nextBindingCursor: null };
+        if (!page.nextAccountCursor && !page.nextLoginCursor && !page.nextBindingCursor) {
+          return { ...aggregate, nextAccountCursor: null, nextLoginCursor: null, nextBindingCursor: null };
         }
       }
       if (!changed) throw new Error('Authority snapshot could not complete.');
@@ -105,53 +137,130 @@ export class AuthSwitchClient {
     return this.request<IReq_AuthSwitchEvents>('authswitch.authority.events', { epoch, afterRevision, waitMs }, waitMs + 5_000, false, signal);
   }
 
-  /** Always obtains a fresh snapshot after reconnect or an event-log gap. */
+  /** Snapshot callback runs after every known change; onStatus invalidates it on disconnect, resync or abort. */
   public async subscribe(onSnapshot: (snapshot: IAuthSwitchSnapshot) => void | Promise<void>,
-    onEvent: (event: IAuthSwitchAccountEvent) => void | Promise<void>, signal: AbortSignal): Promise<void> {
+    onEvent: (event: IAuthSwitchAccountEvent) => void | Promise<void>, signal: AbortSignal,
+    options: IAuthSwitchSubscriptionOptions = {}): Promise<void> {
+    const heartbeatMs = options.heartbeatMs ?? 30_000;
+    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);
       const aborted = () => { clearTimeout(timer); resolve(); };
       signal.addEventListener('abort', aborted, { once: true });
     });
     let snapshot: IAuthSwitchSnapshot | undefined;
-    while (!signal.aborted) {
-      if (!snapshot) {
-        try { snapshot = await this.snapshotAll({ signal }); }
+    let available = false;
+    let lastVerifiedAt: string | null = null;
+    let lastEpoch: string | null = null;
+    let lastRevision: number | null = null;
+    const status = async (state: IAuthSwitchSubscriptionStatus['state'],
+      reason: IAuthSwitchSubscriptionStatus['reason']): Promise<void> => {
+      await options.onStatus?.({ state, reason, epoch: lastEpoch, revision: lastRevision, lastVerifiedAt });
+    };
+    const invalidate = async (reason: 'disconnect' | 'resync'): Promise<void> => {
+      snapshot = undefined;
+      if (available) { available = false; await status('unavailable', reason); }
+    };
+    try {
+      if (!signal.aborted) await status('unavailable', 'initial');
+      while (!signal.aborted) {
+        if (!snapshot) {
+          let fresh: IAuthSwitchSnapshot;
+          try { fresh = await this.snapshotAll({ signal }); }
+          catch {
+            if (signal.aborted) break;
+            await invalidate('disconnect');
+            await retry();
+            continue;
+          }
+          snapshot = fresh;
+          await onSnapshot(fresh);
+          available = true;
+          lastEpoch = fresh.epoch;
+          lastRevision = fresh.revision;
+          lastVerifiedAt = new Date().toISOString();
+          await status('current', 'snapshot');
+        }
+        let result: IReq_AuthSwitchEvents['response'];
+        try { result = await this.events(snapshot.epoch, snapshot.revision, heartbeatMs, signal); }
         catch {
           if (signal.aborted) break;
+          await invalidate('disconnect');
           await retry();
           continue;
         }
-        await onSnapshot(snapshot);
-      }
-      let result: IReq_AuthSwitchEvents['response'];
-      try { result = await this.events(snapshot.epoch, snapshot.revision, 30_000, signal); }
-      catch {
-        if (signal.aborted) break;
-        snapshot = undefined;
-        await retry();
-        continue;
-      }
-      if (result.resyncRequired || result.epoch !== snapshot.epoch) {
-        snapshot = undefined;
-        continue;
+        if (result.resyncRequired || result.epoch !== snapshot.epoch
+          || (result.events.length === 0 && result.revision !== snapshot.revision)) {
+          await invalidate('resync');
+          continue;
+        }
+        if (result.events.length) {
+          let fresh: IAuthSwitchSnapshot;
+          try { fresh = await this.snapshotAll({ signal }); }
+          catch {
+            if (signal.aborted) break;
+            await invalidate('disconnect');
+            await retry();
+            continue;
+          }
+          if (fresh.epoch !== result.epoch || fresh.revision < result.revision) {
+            await invalidate('resync');
+            continue;
+          }
+          snapshot = fresh;
+          await onSnapshot(fresh);
+          for (const event of result.events) await onEvent(event);
+          lastEpoch = fresh.epoch;
+          lastRevision = fresh.revision;
+          lastVerifiedAt = new Date().toISOString();
+          await status('current', 'event');
+        } else {
+          lastVerifiedAt = new Date().toISOString();
+          await status('current', 'heartbeat');
+        }
       }
-      for (const event of result.events) await onEvent(event);
-      snapshot = { ...snapshot, revision: result.revision };
+    } finally {
+      available = false;
+      await status('closed', signal.aborted ? 'abort' : 'consumer_error');
     }
   }
 
-  public async beginAddOpenAi(): Promise<IReq_AuthSwitchBeginAdd['response']['operation']> {
-    return (await this.request<IReq_AuthSwitchBeginAdd>('authswitch.authority.add', { providerId: 'openai', flow: 'device' })).operation;
+  public async beginAddOpenAi(operationId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchBeginAdd['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchBeginAdd>('authswitch.authority.add',
+      { operationId, providerId: 'openai', flow: 'device' }, 35_000, false, signal)).operation;
+  }
+  public async beginReauthOpenAi(operationId: string, accountId: string, loginId: string,
+    purpose: 'openai_managed', signal?: AbortSignal): Promise<IReq_AuthSwitchBeginReauth['response']['operation']> {
+    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 async getOperation(operationId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchGetOperation['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation',
+      { operationId }, 35_000, false, signal)).operation;
   }
-  public async beginReauthOpenAi(accountId: string): Promise<IReq_AuthSwitchBeginReauth['response']['operation']> {
-    return (await this.request<IReq_AuthSwitchBeginReauth>('authswitch.authority.reauth', { accountId, flow: 'device' })).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;
   }
-  public async getOperation(operationId: string): Promise<IReq_AuthSwitchGetOperation['response']['operation']> {
-    return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation', { operationId })).operation;
+  public async startPreuse(input: IReq_AuthSwitchStartPreuse['request'],
+    signal?: AbortSignal): Promise<IReq_AuthSwitchStartPreuse['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchStartPreuse>(
+      'authswitch.authority.preuse.start', input, 35_000, false, signal)).operation;
   }
-  public async cancelOperation(operationId: string): Promise<IReq_AuthSwitchCancelOperation['response']['operation']> {
-    return (await this.request<IReq_AuthSwitchCancelOperation>('authswitch.authority.cancel', { operationId })).operation;
+  public async getPreuse(operationId: string,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchGetPreuse['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchGetPreuse>(
+      'authswitch.authority.preuse.operation', { operationId }, 35_000, false, signal)).operation;
+  }
+  public async cancelPreuse(operationId: string,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchCancelPreuse['response']['operation']> {
+    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;
@@ -159,15 +268,28 @@ export class AuthSwitchClient {
   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 switchClaudeNative(accountId: string, loginId: string): Promise<IReq_AuthSwitchSwitchClaudeNative['response']['handoff']> {
+    return (await this.request<IReq_AuthSwitchSwitchClaudeNative>('authswitch.authority.claude.switch',
+      { accountId, loginId, purpose: 'claude_host_native' })).handoff;
+  }
+  public async getClaudeNativeHandoff(operationId: string): Promise<IReq_AuthSwitchClaudeNativeHandoff['response']['handoff']> {
+    return (await this.request<IReq_AuthSwitchClaudeNativeHandoff>('authswitch.authority.claude.handoff', { operationId })).handoff;
+  }
+  public listClaudeNativeHandoffs(after?: string, limit?: number): Promise<IReq_AuthSwitchClaudeNativeHandoffs['response']> {
+    return this.request<IReq_AuthSwitchClaudeNativeHandoffs>('authswitch.authority.claude.handoffs', { after, limit });
+  }
   public bindAccount(input: IReq_AuthSwitchBindAccount['request']): Promise<IReq_AuthSwitchBindAccount['response']> {
     return this.request<IReq_AuthSwitchBindAccount>('authswitch.authority.bind', input);
   }
   public resolveAccess(input: IReq_AuthSwitchResolveAccess['request']): Promise<IReq_AuthSwitchResolveAccess['response']> {
     return this.request<IReq_AuthSwitchResolveAccess>('authswitch.authority.resolveAccess', input, 35_000, true);
   }
+  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);
+  }
 }
 
-/** Container-facing client. It can only resolve a previously issued binding capability. */
+/** Container-facing client. It can only resolve or release a previously issued binding capability. */
 export class AuthSwitchRuntimeClient {
   private readonly target: plugins.typedrequest.TypedTarget;
   constructor(runtimeSocketPath: string) {
@@ -180,4 +302,8 @@ export class AuthSwitchRuntimeClient {
     return new plugins.typedrequest.TypedRequest<IReq_AuthSwitchResolveAccess>(this.target,
       'authswitch.authority.resolveAccess').fire(input, { timeoutMs: 35_000, maxRetries: 0 });
   }
+  public releaseBinding(input: IReq_AuthSwitchReleaseBinding['request'], signal?: AbortSignal): Promise<IReq_AuthSwitchReleaseBinding['response']> {
+    return new plugins.typedrequest.TypedRequest<IReq_AuthSwitchReleaseBinding>(this.target,
+      'authswitch.authority.release').fire(input, { timeoutMs: 35_000, maxRetries: 0, abortSignal: signal });
+  }
 }