@modelprofile.com/authswitch 6.2.0 → 6.4.0

package/ts/classes.authorityclient.ts

@@ -0,0 +1,183 @@
+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,
+} from './authority-contract.js';
+import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+import { AuthSwitchAuthorityFrameReader, authSwitchAuthorityFrameBytes,
+  maxAuthSwitchAuthorityFrameBytes } from './classes.authorityframing.js';
+
+const post = (path: string, payload: ITypedRequest, signal?: AbortSignal): Promise<ITypedRequest> => {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) { reject(signal.reason); return; }
+      const socket = plugins.net.createConnection(path);
+      let settled = false;
+      const frame = new AuthSwitchAuthorityFrameReader();
+      const finish = (error?: unknown, response?: ITypedRequest): void => {
+        if (settled) return;
+        settled = true;
+        signal?.removeEventListener('abort', abort);
+        socket.destroy();
+        if (error) reject(error);
+        else if (response) resolve(response);
+        else reject(new Error('Authswitch daemon returned no response.'));
+      };
+      const abort = () => finish(signal?.reason ?? new Error('Account request was cancelled.'));
+      signal?.addEventListener('abort', abort, { once: true });
+      socket.setTimeout(35_000, () => finish(new Error('Authswitch daemon request timed out.')));
+      socket.on('connect', () => {
+        const raw = JSON.stringify(payload);
+        if (authSwitchAuthorityFrameBytes(raw) > maxAuthSwitchAuthorityFrameBytes) { finish(new Error('Account request is too large.')); return; }
+        socket.write(raw + '\n');
+      });
+      socket.on('data', chunk => {
+        if (!Buffer.isBuffer(chunk)) { finish(new Error('Account response must be a byte frame.')); return; }
+        let input: string | null;
+        try { input = frame.add(chunk); }
+        catch (error) { finish(error); return; }
+        if (input === null) return;
+        try { finish(undefined, JSON.parse(input) as ITypedRequest); }
+        catch { finish(new Error('Account response could not be decoded.')); }
+      });
+      socket.on('error', () => finish(new Error('Authswitch daemon is unavailable.')));
+      socket.on('close', () => finish(new Error('Authswitch daemon connection closed before its response.')));
+    });
+};
+
+/** 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;
+  private readonly runtimeTarget: plugins.typedrequest.TypedTarget;
+
+  constructor(public readonly socketPath: string, public readonly runtimeSocketPath: string) {
+    this.target = new plugins.typedrequest.TypedTarget({
+      supportsAbortSignal: true,
+      postMethod: (payload, options) => post(this.socketPath, payload, options?.signal),
+    });
+    this.runtimeTarget = new plugins.typedrequest.TypedTarget({
+      supportsAbortSignal: true,
+      postMethod: (payload, options) => post(this.runtimeSocketPath, payload, options?.signal),
+    });
+  }
+
+  private request<T extends ITypedRequest>(method: T['method'], request: T['request'], timeoutMs = 35_000,
+    runtime = false, signal?: AbortSignal): Promise<T['response']> {
+    return new plugins.typedrequest.TypedRequest<T>(runtime ? this.runtimeTarget : this.target, method)
+      .fire(request, { timeoutMs, maxRetries: 0, abortSignal: signal });
+  }
+
+  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;
+  }
+
+  /** 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 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] };
+        else if (aggregate.epoch !== page.epoch || aggregate.revision !== page.revision) {
+          changed = true;
+          break;
+        } else {
+          aggregate.accounts.push(...page.accounts);
+          aggregate.bindings.push(...page.bindings);
+        }
+        accountAfter = page.nextAccountCursor ?? accountAfter ?? page.accounts.at(-1)?.id;
+        bindingAfter = page.nextBindingCursor ?? bindingAfter ?? page.bindings.at(-1)?.id;
+        if (!page.nextAccountCursor && !page.nextBindingCursor) {
+          return { ...aggregate, nextAccountCursor: null, nextBindingCursor: null };
+        }
+      }
+      if (!changed) throw new Error('Authority snapshot could not complete.');
+    }
+  }
+
+  public events(epoch: string, afterRevision: number, waitMs = 30_000, signal?: AbortSignal): Promise<IReq_AuthSwitchEvents['response']> {
+    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. */
+  public async subscribe(onSnapshot: (snapshot: IAuthSwitchSnapshot) => void | Promise<void>,
+    onEvent: (event: IAuthSwitchAccountEvent) => void | Promise<void>, signal: AbortSignal): Promise<void> {
+    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 }); }
+        catch {
+          if (signal.aborted) break;
+          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;
+      }
+      for (const event of result.events) await onEvent(event);
+      snapshot = { ...snapshot, revision: result.revision };
+    }
+  }
+
+  public async beginAddOpenAi(): Promise<IReq_AuthSwitchBeginAdd['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchBeginAdd>('authswitch.authority.add', { providerId: 'openai', flow: 'device' })).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 getOperation(operationId: string): Promise<IReq_AuthSwitchGetOperation['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation', { operationId })).operation;
+  }
+  public async cancelOperation(operationId: string): Promise<IReq_AuthSwitchCancelOperation['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchCancelOperation>('authswitch.authority.cancel', { operationId })).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 removeAccount(accountId: string, expectedRevision: number): Promise<IReq_AuthSwitchRemoveAccount['response']['account']> {
+    return (await this.request<IReq_AuthSwitchRemoveAccount>('authswitch.authority.remove', { accountId, expectedRevision })).account;
+  }
+  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);
+  }
+}
+
+/** Container-facing client. It can only resolve a previously issued binding capability. */
+export class AuthSwitchRuntimeClient {
+  private readonly target: plugins.typedrequest.TypedTarget;
+  constructor(runtimeSocketPath: string) {
+    this.target = new plugins.typedrequest.TypedTarget({
+      supportsAbortSignal: true,
+      postMethod: (payload, options) => post(runtimeSocketPath, payload, options?.signal),
+    });
+  }
+  public resolveAccess(input: IReq_AuthSwitchResolveAccess['request']): Promise<IReq_AuthSwitchResolveAccess['response']> {
+    return new plugins.typedrequest.TypedRequest<IReq_AuthSwitchResolveAccess>(this.target,
+      'authswitch.authority.resolveAccess').fire(input, { timeoutMs: 35_000, maxRetries: 0 });
+  }
+}

package/ts/classes.authoritydaemon.ts

@@ -0,0 +1,219 @@
+import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
+import * as plugins from './plugins.js';
+import type {
+  IReq_AuthSwitchBeginAdd, IReq_AuthSwitchBeginReauth, IReq_AuthSwitchCancelOperation,
+  IReq_AuthSwitchEvents, IReq_AuthSwitchGetOperation, IReq_AuthSwitchRemoveAccount,
+  IReq_AuthSwitchRenameAccount, IReq_AuthSwitchSnapshot,
+} from './authority-contract.js';
+import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+import { AuthSwitchAuthorityBroker, type IAuthSwitchAuthorityBrokerOptions } from './classes.authoritybroker.js';
+import { AuthSwitchAuthorityDatabase, type IAuthSwitchAuthorityDatabaseOptions } from './classes.authoritydatabase.js';
+import { AuthSwitchAuthorityFrameReader, authSwitchAuthorityFrameBytes,
+  maxAuthSwitchAuthorityFrameBytes } from './classes.authorityframing.js';
+
+export interface IAuthSwitchAuthorityDaemonOptions extends IAuthSwitchAuthorityDatabaseOptions {
+  authoritySocketPath: string;
+  runtimeSocketPath: string;
+  broker?: IAuthSwitchAuthorityBrokerOptions;
+}
+
+const hasKeys = (value: unknown, keys: readonly string[]): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const invalid = (): never => { throw new plugins.typedrequest.TypedResponseError('Invalid authswitch authority request.'); };
+
+/** TypedRequest handlers over a private one-request-per-connection Unix socket. */
+export class AuthSwitchAuthorityDaemon {
+  public readonly database: AuthSwitchAuthorityDatabase;
+  public readonly broker: AuthSwitchAuthorityBroker;
+  private readonly managementRouter = new plugins.typedrequest.TypedRouter();
+  private readonly runtimeRouter = new plugins.typedrequest.TypedRouter();
+  private managementServer?: plugins.net.Server;
+  private runtimeServer?: plugins.net.Server;
+  private readonly sockets = new Set<plugins.net.Socket>();
+
+  constructor(private readonly options: IAuthSwitchAuthorityDaemonOptions) {
+    this.database = new AuthSwitchAuthorityDatabase(options);
+    this.broker = new AuthSwitchAuthorityBroker(this.database, options.broker);
+    this.register();
+  }
+
+  private register(): void {
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchSnapshot>(
+      'authswitch.authority.snapshot', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)) invalid();
+        const keys = Object.keys(request);
+        if (keys.some(key => !['accountAfter', 'bindingAfter', 'limit'].includes(key))) invalid();
+        return { snapshot: await this.broker.snapshot(request) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchEvents>(
+      'authswitch.authority.events', async (request, tools) => {
+        if (!hasKeys(request, ['epoch', 'afterRevision', 'waitMs'])) invalid();
+        return this.broker.events(request.epoch, request.afterRevision, request.waitMs, tools?.abortSignal);
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBeginAdd>(
+      'authswitch.authority.add', async request => {
+        if (!hasKeys(request, ['providerId', 'flow']) || request.providerId !== 'openai' || request.flow !== 'device') invalid();
+        return { operation: await this.broker.beginAddOpenAi() };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBeginReauth>(
+      'authswitch.authority.reauth', async request => {
+        if (!hasKeys(request, ['accountId', 'flow']) || request.flow !== 'device' || typeof request.accountId !== 'string') invalid();
+        return { operation: await this.broker.beginReauthOpenAi(request.accountId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchGetOperation>(
+      'authswitch.authority.operation', async request => {
+        if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
+        return { operation: this.broker.getOperation(request.operationId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchCancelOperation>(
+      'authswitch.authority.cancel', async request => {
+        if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
+        return { operation: await this.broker.cancelOperation(request.operationId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchRenameAccount>(
+      'authswitch.authority.rename', async request => {
+        if (!hasKeys(request, ['accountId', 'expectedRevision', 'label']) || typeof request.accountId !== 'string'
+          || typeof request.expectedRevision !== 'number' || typeof request.label !== 'string') invalid();
+        return { account: await this.broker.renameAccount(request.accountId, request.expectedRevision, request.label) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchRemoveAccount>(
+      'authswitch.authority.remove', async request => {
+        if (!hasKeys(request, ['accountId', 'expectedRevision']) || typeof request.accountId !== 'string'
+          || typeof request.expectedRevision !== 'number') invalid();
+        return { account: await this.broker.removeAccount(request.accountId, request.expectedRevision) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBindAccount>(
+      'authswitch.authority.bind', async request => {
+        if (!hasKeys(request, ['accountId', 'runtime', 'scopeId', 'incarnationId'])
+          || typeof request.accountId !== 'string' || typeof request.scopeId !== 'string'
+          || typeof request.incarnationId !== 'string') invalid();
+        return this.broker.bindAccount(request);
+      }));
+    this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchResolveAccess>(
+      'authswitch.authority.resolveAccess', async request => {
+        if (!hasKeys(request, ['bindingId', 'capability', 'minValidityMs'])
+          || typeof request.bindingId !== 'string' || typeof request.capability !== 'string'
+          || typeof request.minValidityMs !== 'number') invalid();
+        return this.broker.resolveAccess(request.bindingId, request.capability, request.minValidityMs);
+      }));
+  }
+
+  public async start(): Promise<void> {
+    if (this.managementServer || this.runtimeServer) throw new Error('Authswitch authority daemon is already started.');
+    await this.database.start();
+    try {
+      await this.broker.start();
+      const managementDirectory = plugins.path.dirname(this.options.authoritySocketPath);
+      const runtimeDirectory = plugins.path.dirname(this.options.runtimeSocketPath);
+      const databaseDirectory = plugins.path.dirname(this.options.socketPath);
+      if (managementDirectory === runtimeDirectory || databaseDirectory === runtimeDirectory
+        || managementDirectory.startsWith(runtimeDirectory + plugins.path.sep)
+        || databaseDirectory.startsWith(runtimeDirectory + plugins.path.sep)
+        || runtimeDirectory.startsWith(managementDirectory + plugins.path.sep)
+        || runtimeDirectory.startsWith(databaseDirectory + plugins.path.sep)) {
+        throw new Error('Runtime socket directory must contain no management or database endpoint.');
+      }
+      this.managementServer = await this.listen(this.options.authoritySocketPath, this.managementRouter);
+      this.runtimeServer = await this.listen(this.options.runtimeSocketPath, this.runtimeRouter);
+    } catch (error) {
+      try { await this.close(); } catch { /* Preserve startup failure. */ }
+      throw error;
+    }
+  }
+
+  private async listen(path: string, router: plugins.typedrequest.TypedRouter): Promise<plugins.net.Server> {
+    const directory = plugins.path.dirname(path);
+    await plugins.fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await plugins.fs.promises.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()) {
+      throw new Error('Authswitch authority socket directory is not private.');
+    }
+    await plugins.fs.promises.chmod(directory, 0o700);
+    await this.clearStaleSocket(path);
+    const server = plugins.net.createServer(socket => this.accept(socket, router));
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, () => { server.off('error', reject); resolve(); });
+      });
+      await plugins.fs.promises.chmod(path, 0o600);
+      return server;
+    } catch (error) {
+      if (server.listening) await new Promise<void>(resolve => server.close(() => resolve()));
+      throw error;
+    }
+  }
+
+  /** A killed daemon leaves a pathname behind; only remove an unchanged, owned, refused Unix socket. */
+  private async clearStaleSocket(path: string): Promise<void> {
+    let before: plugins.fs.Stats;
+    try { before = await plugins.fs.promises.lstat(path); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+      throw error;
+    }
+    if (!before.isSocket() || before.uid !== process.getuid?.()) throw new Error('Authswitch socket path is unsafe.');
+    const refused = await new Promise<boolean>((resolve, reject) => {
+      const probe = plugins.net.createConnection(path);
+      probe.setTimeout(1_000, () => { probe.destroy(); reject(new Error('Authswitch socket probe timed out.')); });
+      probe.once('connect', () => { probe.destroy(); resolve(false); });
+      probe.once('error', error => {
+        probe.destroy();
+        if ((error as NodeJS.ErrnoException).code === 'ECONNREFUSED') resolve(true);
+        else reject(error);
+      });
+    });
+    if (!refused) throw new Error('Authswitch authority socket is already active.');
+    const after = await plugins.fs.promises.lstat(path);
+    if (!after.isSocket() || after.uid !== before.uid || after.dev !== before.dev || after.ino !== before.ino) {
+      throw new Error('Authswitch socket path changed during startup.');
+    }
+    await plugins.fs.promises.unlink(path);
+  }
+
+  private accept(socket: plugins.net.Socket, router: plugins.typedrequest.TypedRouter): void {
+    this.sockets.add(socket);
+    const abort = new AbortController();
+    socket.on('close', () => { this.sockets.delete(socket); abort.abort(); });
+    const frame = new AuthSwitchAuthorityFrameReader();
+    let handled = false;
+    socket.setTimeout(35_000, () => socket.destroy());
+    socket.on('data', chunk => {
+      if (handled) { socket.destroy(); return; }
+      if (!Buffer.isBuffer(chunk)) { socket.destroy(); return; }
+      let input: string | null;
+      try { input = frame.add(chunk); }
+      catch { socket.destroy(); return; }
+      if (input === null) return;
+      handled = true;
+      let request: ITypedRequest;
+      try { request = JSON.parse(input) as ITypedRequest; }
+      catch { socket.destroy(); return; }
+      void router.routeAndAddResponse(request, { trustedLocalData: { authoritySocket: socket },
+        trustedAbortSignal: abort.signal })
+        .then(response => {
+          const raw = JSON.stringify(response);
+          if (authSwitchAuthorityFrameBytes(raw) > maxAuthSwitchAuthorityFrameBytes) { socket.destroy(); return; }
+          socket.end(raw + '\n');
+        }).catch(() => socket.destroy());
+    });
+  }
+
+  public async close(): Promise<void> {
+    const errors: unknown[] = [];
+    try { await this.broker.close(); } catch (error) { errors.push(error); }
+    const management = this.managementServer;
+    const runtime = this.runtimeServer;
+    this.managementServer = undefined;
+    this.runtimeServer = undefined;
+    for (const socket of this.sockets) socket.destroy();
+    for (const server of [management, runtime]) {
+      if (server) try {
+        await new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+      } catch (error) { errors.push(error); }
+    }
+    try { await this.database.stop(); } catch (error) { errors.push(error); }
+    if (errors.length) throw new AggregateError(errors, 'Authswitch authority shutdown was incomplete.');
+  }
+}