@modelprofile.com/authswitch 6.3.0 → 6.5.0

package/ts/classes.authorityclient.ts

@@ -0,0 +1,252 @@
+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.')));
+    });
+};
+
+/** 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;
+  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);
+  }
+
+  /** 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,
+    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;
+    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;
+        }
+        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');
+        }
+      }
+    } 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 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,403 @@
+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';
+import { AuthSwitchManagedCodex, findManagedCodexProcess, type IAuthSwitchManagedCodexOptions } from './classes.codexmanaged.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>();
+  private readonly managedCodex = new Map<string, Promise<{ runtime: AuthSwitchManagedCodex; bindingId: string;
+    capability: string; homeId: string; runId: string }>>();
+  private readonly managedCodexHomes = new Set<string>();
+  private readonly managedCodexAccountIds = new Map<string, string>();
+  private readonly drainingAccounts = new Set<string>();
+  private readonly managedCodexStops = new Map<string, Promise<void>>();
+  private readonly managedCodexFailures: unknown[] = [];
+  private closing = false;
+
+  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();
+        if (this.drainingAccounts.has(request.accountId)) throw new Error('Account runtime drain is already in progress.');
+        this.drainingAccounts.add(request.accountId);
+        try {
+          await this.drainManagedCodexAccount(request.accountId);
+          const operation = await this.broker.beginReauthOpenAi(request.accountId);
+          void this.broker.waitOperation(operation.id).finally(() => this.drainingAccounts.delete(request.accountId)).catch(() => {});
+          return { operation };
+        } catch (error) { this.drainingAccounts.delete(request.accountId); throw error; }
+      }));
+    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();
+        if (this.drainingAccounts.has(request.accountId)) throw new Error('Account runtime drain is already in progress.');
+        this.drainingAccounts.add(request.accountId);
+        try {
+          await this.drainManagedCodexAccount(request.accountId);
+          return { account: await this.broker.removeAccount(request.accountId, request.expectedRevision) };
+        } finally { this.drainingAccounts.delete(request.accountId); }
+      }));
+    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 ((typeof request !== 'object' || request === null || Array.isArray(request))
+          || !['bindingId', 'capability', 'minValidityMs'].every(key => Object.hasOwn(request, key))
+          || Object.keys(request).some(key => !['bindingId', 'capability', 'minValidityMs',
+            'rejectedGrantGeneration'].includes(key))
+          || typeof request.bindingId !== 'string' || typeof request.capability !== 'string'
+          || typeof request.minValidityMs !== 'number'
+          || (request.rejectedGrantGeneration !== undefined && typeof request.rejectedGrantGeneration !== 'number')) invalid();
+        return this.broker.resolveAccess(request.bindingId, request.capability, request.minValidityMs,
+          request.rejectedGrantGeneration);
+      }));
+  }
+
+  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;
+    }
+  }
+
+  /** Trusted in-process SDK admission; management RPC exposure belongs to the later CLI cutover. */
+  private async drainManagedCodexAccount(accountId: string): Promise<void> {
+    const scopes = [...this.managedCodexAccountIds]
+      .filter(([, assignedAccountId]) => assignedAccountId === accountId).map(([scopeId]) => scopeId);
+    const results = await Promise.allSettled(scopes.map(scopeId => this.stopManagedCodex(scopeId)));
+    const failed = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+    if (failed.length) throw new AggregateError(failed.map(result => result.reason), 'Managed Codex account drain failed.');
+  }
+
+  public async startManagedCodex(input: { accountId: string; scopeId: string; workspaceDirectory: string;
+    codexHomeDirectory: string;
+    executable?: string; onNotification?: IAuthSwitchManagedCodexOptions['onNotification'];
+    onServerRequest?: IAuthSwitchManagedCodexOptions['onServerRequest'] }): Promise<AuthSwitchManagedCodex> {
+    if (!plugins.path.isAbsolute(input.codexHomeDirectory)
+      || plugins.path.normalize(input.codexHomeDirectory) !== input.codexHomeDirectory) {
+      throw new Error('Managed Codex requires a normalized absolute state home.');
+    }
+    const homeId = plugins.crypto.createHash('sha256').update(JSON.stringify(['authswitch-codex-home-v1', input.codexHomeDirectory])).digest('hex');
+    if (this.closing || !this.managementServer || !this.runtimeServer
+      || this.managedCodex.has(input.scopeId) || this.managedCodexStops.has(input.scopeId)
+      || this.managedCodexHomes.has(homeId) || this.drainingAccounts.has(input.accountId)) {
+      throw new Error('Managed Codex scope is unavailable.');
+    }
+    this.managedCodexHomes.add(homeId);
+    this.managedCodexAccountIds.set(input.scopeId, input.accountId);
+    const runId = plugins.crypto.randomUUID();
+    const task = (async () => {
+      let bound: Awaited<ReturnType<typeof this.broker.bindAccount>> | undefined;
+      let runtime: AuthSwitchManagedCodex | undefined;
+      let claimed = false;
+      try {
+        const home = input.codexHomeDirectory;
+        const parent = plugins.path.dirname(home);
+        const parentStat = await plugins.fs.promises.lstat(parent);
+        if (!parentStat.isDirectory() || parentStat.isSymbolicLink() || parentStat.uid !== process.getuid?.()
+          || (parentStat.mode & 0o077) !== 0 || await plugins.fs.promises.realpath(parent) !== parent) {
+          throw new Error('Managed Codex home parent must be private and owned by this user.');
+        }
+        const nativeHomes = [plugins.path.join(plugins.os.homedir(), '.codex'), process.env.CODEX_HOME]
+          .filter((value): value is string => typeof value === 'string' && plugins.path.isAbsolute(value));
+        if (nativeHomes.some(native => home === native || home.startsWith(native + plugins.path.sep)
+          || native.startsWith(home + plugins.path.sep))) {
+          throw new Error('Managed Codex cannot adopt an active native Codex home.');
+        }
+        const existing = await this.database.readCodexHome(homeId);
+        if (existing && (existing.accountId !== input.accountId || existing.scopeId !== input.scopeId)) {
+          throw new Error('Managed Codex home already belongs to another account or scope.');
+        }
+        let homeExists = false;
+        try {
+          const stat = await plugins.fs.promises.lstat(home);
+          if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()
+            || (stat.mode & 0o077) !== 0 || await plugins.fs.promises.realpath(home) !== home) {
+            throw new Error('Managed Codex home is not a private owned directory.');
+          }
+          homeExists = true;
+        } catch (error) {
+          if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')) throw error;
+        }
+        if (!existing && homeExists && (await plugins.fs.promises.readdir(home)).length) {
+          throw new Error('An existing Codex home needs explicit native-owner handoff before enrollment.');
+        }
+        await this.database.reserveCodexHome(input.accountId, input.scopeId, homeId, plugins.crypto.randomUUID());
+        if (!homeExists) await plugins.fs.promises.mkdir(home, { mode: 0o700 });
+        bound = await this.broker.bindAccount({ accountId: input.accountId, runtime: 'codex',
+          scopeId: input.scopeId, incarnationId: plugins.crypto.randomUUID() });
+        runtime = new AuthSwitchManagedCodex({
+          runtimeDirectory: plugins.path.join(plugins.path.dirname(plugins.path.dirname(this.options.authoritySocketPath)), 'managed-codex'),
+          codexHomeDirectory: home, workspaceDirectory: input.workspaceDirectory, executable: input.executable,
+          onNotification: input.onNotification, onServerRequest: input.onServerRequest,
+          broker: this.broker, bindingId: bound.binding.id, capability: bound.capability,
+          onPreparedRun: async socketPath => {
+            const assigned = await this.database.readCodexHome(homeId);
+            if (!assigned || assigned.accountId !== input.accountId || assigned.scopeId !== input.scopeId) {
+              throw new Error('Managed Codex home assignment changed.');
+            }
+            if (assigned.activeRun) {
+              const survivor = await findManagedCodexProcess(assigned.activeRun.socketPath);
+              if (survivor) throw new Error('Managed Codex home still has a live app-server owner.');
+              await this.database.changeCodexRun(homeId, assigned.activeRun.id, null, plugins.crypto.randomUUID());
+            }
+            await this.database.changeCodexRun(homeId, null,
+              { id: runId, socketPath, pid: null, startedAt: null }, plugins.crypto.randomUUID());
+            claimed = true;
+          },
+          onChildSpawned: async (pid, startedAt) => {
+            const assigned = await this.database.readCodexHome(homeId);
+            if (assigned?.activeRun?.id !== runId || assigned.activeRun.pid !== null) {
+              throw new Error('Managed Codex run registration changed before process verification.');
+            }
+            await this.database.changeCodexRun(homeId, runId,
+              { ...assigned.activeRun, pid, startedAt }, plugins.crypto.randomUUID());
+          },
+          onUnavailable: () => {
+            void this.stopManagedCodex(input.scopeId).catch(error => {
+              this.managedCodexFailures.push(error);
+              process.stderr.write('Managed Codex cleanup failed after its control connection closed.\n');
+            });
+          },
+        });
+        await runtime.start();
+        if (this.closing) throw new Error('Managed Codex admission closed during startup.');
+        return { runtime, bindingId: bound.binding.id, capability: bound.capability, homeId, runId };
+      } catch (error) {
+        const cleanupErrors: unknown[] = [];
+        if (runtime) try { await runtime.close(); } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        if (claimed && cleanupErrors.length === 0) try {
+          await this.database.changeCodexRun(homeId, runId, null, plugins.crypto.randomUUID());
+        } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        if (bound) try { await this.broker.revokeBinding(bound.binding.id, bound.capability); }
+        catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        if (cleanupErrors.length === 0) {
+          this.managedCodexHomes.delete(homeId);
+          this.managedCodexAccountIds.delete(input.scopeId);
+        }
+        if (cleanupErrors.length) throw new AggregateError([error, ...cleanupErrors], 'Managed Codex admission cleanup failed.');
+        throw error;
+      }
+    })();
+    this.managedCodex.set(input.scopeId, task);
+    try { return (await task).runtime; }
+    catch (error) { this.managedCodex.delete(input.scopeId); throw error; }
+  }
+
+  public stopManagedCodex(scopeId: string): Promise<void> {
+    const existing = this.managedCodexStops.get(scopeId);
+    if (existing) return existing;
+    const task = this.managedCodex.get(scopeId);
+    if (!task) return Promise.resolve();
+    this.managedCodex.delete(scopeId);
+    const stopping = (async () => {
+      let entry: Awaited<typeof task>;
+      try { entry = await task; }
+      catch { /* Failed admission already closed its process and revoked its binding. */ return; }
+      const { runtime, bindingId, capability, homeId, runId } = entry;
+      const errors: unknown[] = [];
+      try { await runtime.close(); } catch (error) { errors.push(error); }
+      if (errors.length === 0) try {
+        await this.database.changeCodexRun(homeId, runId, null, plugins.crypto.randomUUID());
+        this.managedCodexHomes.delete(homeId);
+        this.managedCodexAccountIds.delete(scopeId);
+      } catch (error) { errors.push(error); }
+      try { await this.broker.revokeBinding(bindingId, capability); } catch (error) { errors.push(error); }
+      if (errors.length) throw new AggregateError(errors, 'Managed Codex shutdown was incomplete.');
+    })();
+    this.managedCodexStops.set(scopeId, stopping);
+    void stopping.finally(() => { if (this.managedCodexStops.get(scopeId) === stopping) this.managedCodexStops.delete(scopeId); }).catch(() => {});
+    return stopping;
+  }
+
+  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> {
+    this.closing = true;
+    const errors: unknown[] = [];
+    for (const scopeId of [...this.managedCodex.keys()]) {
+      try { await this.stopManagedCodex(scopeId); } catch (error) { errors.push(error); }
+    }
+    for (const stopping of [...this.managedCodexStops.values()]) {
+      try { await stopping; } catch (error) { errors.push(error); }
+    }
+    errors.push(...this.managedCodexFailures);
+    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.');
+  }
+}