@modelprofile.com/authswitch 2.1.2

package/ts/classes.credentialstore.ts

@@ -0,0 +1,101 @@
+import * as plugins from './plugins.js';
+import { writeSecretFileAtomically } from './helpers.js';
+
+export const credentialRecord = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Unsupported credential document.');
+  return value as Record<string, unknown>;
+};
+export const credentialText = (value: unknown): string | undefined => typeof value === 'string' && value.length > 0 ? value : undefined;
+export const credentialHash = (value: string): string => plugins.crypto.createHash('sha256').update(value).digest('hex');
+
+/** A bounded file read; malformed secrets never become parser diagnostics in the CLI. */
+export const readCredentialDocument = (file: string): { raw: string | null; data: Record<string, unknown> } => {
+  let fd: number | undefined;
+  try {
+    fd = plugins.fs.openSync(file, plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NONBLOCK);
+    const stat = plugins.fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 4 * 1024 * 1024) throw new Error();
+    const buffer = Buffer.alloc(4 * 1024 * 1024 + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const count = plugins.fs.readSync(fd, buffer, size, buffer.length - size, null);
+      if (!count) break;
+      size += count;
+    }
+    if (size === buffer.length) throw new Error();
+    const raw = buffer.subarray(0, size).toString('utf8');
+    return { raw, data: credentialRecord(JSON.parse(raw)) };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { raw: null, data: {} };
+    throw new Error('Credential file is unreadable, malformed, or too large; no changes were made.');
+  } finally { if (fd !== undefined) plugins.fs.closeSync(fd); }
+};
+
+export interface IStoredCredential {
+  schemaVersion: 1;
+  id: string;
+  slotId: string;
+  identity: string;
+  label: string;
+  savedAt: string;
+  /** Harness-owned payload. This object must never cross the public account interface. */
+  credential: Record<string, unknown>;
+}
+
+/** A single atomic, owner-only record keeps the saved credential and its identity together. */
+export class CredentialStore {
+  public readonly dir: string;
+  constructor(harness: string, root = process.env.AUTHSWITCH_HOME || plugins.path.join(plugins.os.homedir(), '.authswitch')) {
+    this.dir = plugins.path.join(root, harness);
+  }
+  public id(slot: string, identity: string): string { return credentialHash(JSON.stringify([slot, identity])); }
+  private file(id: string): string {
+    if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('Invalid saved account ID.');
+    return plugins.path.join(this.dir, `${id}.json`);
+  }
+  public read(id: string): IStoredCredential {
+    const value = readCredentialDocument(this.file(id)).data;
+    if (value.schemaVersion !== 1 || value.id !== id || !credentialText(value.slotId) || !credentialText(value.identity)
+      || !credentialText(value.label) || typeof value.savedAt !== 'string' || !Number.isFinite(Date.parse(value.savedAt))
+      || this.id(value.slotId as string, value.identity as string) !== id) throw new Error('Saved account metadata is invalid; restore it from a verified backup.');
+    credentialRecord(value.credential);
+    return value as unknown as IStoredCredential;
+  }
+  public list(): IStoredCredential[] {
+    if (!plugins.fs.existsSync(this.dir)) return [];
+    return plugins.fs.readdirSync(this.dir).filter(name => /^[a-f0-9]{64}\.json$/.test(name))
+      .map(name => this.read(name.slice(0, -5))).sort((a, b) => b.savedAt.localeCompare(a.savedAt));
+  }
+  public save(entry: Omit<IStoredCredential, 'schemaVersion' | 'id' | 'savedAt'>): IStoredCredential {
+    const record: IStoredCredential = { ...entry, schemaVersion: 1, id: this.id(entry.slotId, entry.identity), savedAt: new Date().toISOString() };
+    plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    plugins.fs.chmodSync(this.dir, 0o700);
+    const raw = JSON.stringify(record, null, 2) + '\n';
+    writeSecretFileAtomically(this.file(record.id), raw);
+    if (readCredentialDocument(this.file(record.id)).raw !== raw) throw new Error('Saved credential verification failed; the active login was preserved.');
+    return this.read(record.id);
+  }
+  public remove(id: string): void { this.read(id); plugins.fs.unlinkSync(this.file(id)); }
+  public locked<T>(action: () => T): T {
+    plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    const file = plugins.path.join(this.dir, '.lock');
+    let fd: number;
+    try { fd = plugins.fs.openSync(file, 'wx', 0o600); }
+    catch { throw new Error(`Account storage is locked. Close other authswitch operations; if none remain, remove ${file}.`); }
+    try { return action(); }
+    finally { plugins.fs.closeSync(fd); plugins.fs.unlinkSync(file); }
+  }
+}
+
+/** Native harnesses retain credentials and may refresh them. Refuse writes while one is running. */
+export const requireHarnessStopped = (binary: 'opencode' | 'claude'): void => {
+  let names: string[];
+  try {
+    if (process.platform === 'win32') {
+      names = plugins.childProcess.execFileSync('tasklist', ['/FO', 'CSV', '/NH'], { encoding: 'utf8', timeout: 5000 }).split('\n').map(line => line.split('",')[0].replace(/^"/, ''));
+    } else {
+      names = plugins.childProcess.execFileSync('ps', ['-u', String(process.getuid!()), '-o', 'comm='], { encoding: 'utf8', timeout: 5000 }).split('\n').map(line => plugins.path.basename(line.trim()));
+    }
+  } catch { throw new Error(`Could not verify that ${binary} is stopped. No login was changed.`); }
+  if (names.some(name => name === binary || name === `${binary}.exe`)) throw new Error(`Exit running ${binary} processes before saving or switching credentials, then start ${binary} again.`);
+};

package/ts/classes.fileharness.ts

@@ -0,0 +1,120 @@
+import type { IAuthHarness, IHarnessAccountStatus, IHarnessOutcome, IHarnessState } from './interfaces.harness.js';
+import { CredentialStore, type IStoredCredential } from './classes.credentialstore.js';
+import { plainText } from './formatting.js';
+
+export interface IFileAccount {
+  slotId: string;
+  identity: string;
+  label: string;
+  credential: Record<string, unknown>;
+}
+export interface IFileHarnessSnapshot {
+  accounts: IFileAccount[];
+  unavailable: string | null;
+}
+
+/** Shared verified preservation for harnesses with independently replaceable credential slots. */
+export abstract class FileHarness implements IAuthHarness {
+  public abstract readonly id: string;
+  public abstract readonly label: string;
+  public abstract readonly loginHint: string;
+  public readonly diagnosticsLabel = 'Check credential storage and account availability';
+  protected abstract readonly store: CredentialStore;
+  protected abstract snapshot(): IFileHarnessSnapshot;
+  protected abstract apply(slotId: string, previous: IFileAccount | undefined, target: IFileAccount | undefined): void;
+  protected abstract beforeMutation(): void;
+  protected abstract inspect(credential: Record<string, unknown>, slotId: string): IFileAccount;
+  public abstract readAccountStatus(id: string): Promise<IHarnessAccountStatus>;
+
+  private saved(entry: IStoredCredential): IFileAccount {
+    const account = this.inspect(entry.credential, entry.slotId);
+    if (account.identity !== entry.identity) throw new Error('Saved credential does not match its account identity.');
+    return account;
+  }
+  public readState(): IHarnessState {
+    const snapshot = this.snapshot();
+    const saved = this.store.list();
+    const accounts: IHarnessState['accounts'] = saved.map(entry => {
+      this.saved(entry);
+      return { id: entry.id, slotId: entry.slotId, label: entry.label, isActive: false, isStashed: true, savedAt: entry.savedAt, details: [`Provider: ${entry.slotId}`] };
+    });
+    for (const active of snapshot.accounts) {
+      const id = this.store.id(active.slotId, active.identity);
+      const existing = accounts.find(account => account.id === id);
+      if (existing) { existing.isActive = true; existing.label = active.label; }
+      else accounts.unshift({ id, slotId: active.slotId, label: active.label, isActive: true, isStashed: false, savedAt: null, details: [`Provider: ${active.slotId}`] });
+    }
+    for (const account of accounts) {
+      if (accounts.some(other => other.id !== account.id && other.label === account.label)) account.details.push(`Account ID: ${account.id}`);
+    }
+    return { accounts, saveUnavailableReason: snapshot.unavailable };
+  }
+  protected readCredential(id: string): IFileAccount {
+    const active = this.snapshot().accounts.find(account => this.store.id(account.slotId, account.identity) === id);
+    return active ?? this.saved(this.store.read(id));
+  }
+  /** Save a newly authenticated credential without changing a native harness's login. */
+  public importCredential(slotId: string, credential: Record<string, unknown>): { accountId: string } {
+    return this.store.locked(() => ({ accountId: this.store.save(this.inspect(credential, slotId)).id }));
+  }
+  /** Backend-only login handoff. Preserve the outgoing credential before replacing its slot. */
+  public activateCredential(slotId: string, credential: Record<string, unknown>): IHarnessOutcome {
+    return this.outcome(() => {
+      this.beforeMutation();
+      const target = this.inspect(credential, slotId);
+      const snapshot = this.snapshot();
+      if (snapshot.unavailable) throw new Error(snapshot.unavailable);
+      const previous = snapshot.accounts.find(account => account.slotId === slotId);
+      if (previous) this.store.save(previous);
+      this.apply(slotId, previous, target);
+      return `Activated ${plainText(target.label)} (${plainText(slotId)}).`;
+    });
+  }
+  public resolveAccount(reference: string): { id: string } | { candidates: string[] } {
+    const accounts = this.store.list();
+    const exact = accounts.filter(account => account.id === reference || account.label.toLowerCase() === reference.toLowerCase()
+      || `${account.slotId}:${account.label}`.toLowerCase() === reference.toLowerCase());
+    const matches = exact.length ? exact : accounts.filter(account => account.label.toLowerCase().startsWith(reference.toLowerCase()));
+    return matches.length === 1 ? { id: matches[0].id } : { candidates: matches.map(account => `${account.slotId}:${account.label} (${account.id})`) };
+  }
+  private outcome(action: () => string): IHarnessOutcome {
+    try { return this.store.locked(() => ({ lines: [action()], problems: [] })); }
+    catch (error) { return { lines: [], problems: [error instanceof Error ? error.message : 'Credential operation failed.'] }; }
+  }
+  public saveCurrent(options: { keepActive: boolean; accountId?: string }): IHarnessOutcome {
+    return this.outcome(() => {
+      this.beforeMutation();
+      const snapshot = this.snapshot();
+      if (snapshot.unavailable) throw new Error(snapshot.unavailable);
+      const matches = snapshot.accounts.filter(account => !options.accountId || this.store.id(account.slotId, account.identity) === options.accountId || account.slotId === options.accountId || account.label === options.accountId);
+      if (matches.length !== 1) throw new Error(matches.length ? 'Several logins are active. Select the account or provider to save.' : 'No matching active login to save.');
+      const active = matches[0];
+      this.store.save(active);
+      if (!options.keepActive) this.apply(active.slotId, active, undefined);
+      return `Saved ${plainText(active.label)} (${plainText(active.slotId)})${options.keepActive ? '; login remains in place.' : `. Start ${this.label} to log in again.`}`;
+    });
+  }
+  public switchAccount(id: string): IHarnessOutcome {
+    return this.outcome(() => {
+      this.beforeMutation();
+      const target = this.saved(this.store.read(id));
+      const snapshot = this.snapshot();
+      if (snapshot.unavailable) throw new Error(snapshot.unavailable);
+      const previous = snapshot.accounts.find(account => account.slotId === target.slotId);
+      // Refresh the outgoing stash even when this account was already saved.
+      if (previous) this.store.save(previous);
+      if (previous?.identity === target.identity) return `${plainText(target.label)} is already active; its latest credential is saved.`;
+      this.apply(target.slotId, previous, target);
+      return `Activated ${plainText(target.label)} (${plainText(target.slotId)}). Start ${this.label} to use it.`;
+    });
+  }
+  public removeAccount(id: string): IHarnessOutcome {
+    return this.outcome(() => { const account = this.store.read(id); this.store.remove(id); return `Removed saved login for ${plainText(account.label)}; the active login is preserved.`; });
+  }
+  public diagnose(): IHarnessOutcome {
+    try {
+      const state = this.readState();
+      return { lines: [`${this.label}: ${state.accounts.filter(account => account.isActive).length} active login(s), ${state.accounts.filter(account => account.isStashed).length} saved account(s).`, this.loginHint], problems: state.saveUnavailableReason ? [state.saveUnavailableReason] : [] };
+    } catch { return { lines: [], problems: ['Credential storage could not be verified. Check file permissions and saved credential records.'] }; }
+  }
+}

package/ts/classes.login.ts

@@ -0,0 +1,103 @@
+import * as plugins from './plugins.js';
+import type { IHarnessLoginHandle, IHarnessLoginOptions, IHarnessLoginResult } from './interfaces.harness.js';
+
+export type TAuthLoginFlow = plugins.flexAccounts.TSmartAiProviderLoginFlow;
+export type TAuthLoginCredential = plugins.flexAccounts.TSmartAiProviderCredential;
+export type TAuthLoginPrompt = plugins.flexAccounts.TSmartAiProviderLoginPrompt;
+export interface IAuthLoginResult extends plugins.flexAccounts.ISmartAiProviderLoginResult {}
+export interface IAuthLoginHandle extends plugins.flexAccounts.ISmartAiProviderLoginHandle {}
+export interface IAuthLoginProvider extends Pick<plugins.flexAccounts.ISmartAiProviderAdapter, 'descriptor' | 'beginLogin' | 'dispose'> {}
+export interface IAuthLoginOptions extends plugins.flexAccounts.ISmartAiProviderLoginOptions {
+  providerId: string;
+}
+export interface IAuthSwitchLoginOptions {
+  /** False when an enclosing provider registry owns disposal of injected adapters. */
+  disposeProviders?: boolean;
+}
+
+/** Shared login owner for terminal and hosted UIs. Credential results stay on the backend. */
+export class AuthSwitchLogin {
+  private readonly providers = new Map<string, IAuthLoginProvider>();
+  private pending = 0;
+  private closed = false;
+  private closing?: Promise<void>;
+  private readonly handles = new Set<IAuthLoginHandle>();
+
+  constructor(providers: IAuthLoginProvider[] = [new plugins.flexAccounts.OpenAiProviderAdapter()], private readonly options: IAuthSwitchLoginOptions = {}) {
+    for (const provider of providers) {
+      if (this.providers.has(provider.descriptor.providerId)) throw new Error('Duplicate login provider.');
+      this.providers.set(provider.descriptor.providerId, provider);
+    }
+  }
+  public listProviders(): plugins.flexAccounts.ISmartAiProviderDescriptor[] {
+    return [...this.providers.values()].map(provider => ({ ...provider.descriptor, loginFlows: [...provider.descriptor.loginFlows] }));
+  }
+  public async beginLogin(options: IAuthLoginOptions): Promise<IAuthLoginHandle> {
+    if (this.closed) throw new Error('Login service is closed.');
+    const provider = this.providers.get(options.providerId);
+    if (!provider?.descriptor.loginFlows.includes(options.flow)) throw new Error('This provider does not support the requested login flow.');
+    if (this.pending + this.handles.size >= 8) throw new Error('Too many pending logins. Complete or cancel an existing login first.');
+    this.pending++;
+    try {
+      const handle = await provider.beginLogin(options);
+      if (this.closed) { await handle.close(); throw new Error('Login service is closed.'); }
+      this.handles.add(handle);
+      // Keep cancellation/close ownership until the consumer has persisted the secret result.
+      return {
+        prompt: handle.prompt,
+        completion: handle.completion,
+        cancel: () => handle.cancel(),
+        close: async () => { await handle.close(); this.handles.delete(handle); },
+      };
+    } catch {
+      throw new Error('Provider login could not be started.');
+    } finally { this.pending--; }
+  }
+  public close(): Promise<void> { return this.closing ??= this.closeOwnedResources(); }
+  private async closeOwnedResources(): Promise<void> {
+    this.closed = true;
+    const results = await Promise.allSettled([...this.handles].map(handle => handle.close()));
+    const disposed = this.options.disposeProviders === false ? [] : await Promise.allSettled([...this.providers.values()].map(provider => provider.dispose()));
+    if ([...results, ...disposed].some(result => result.status === 'rejected')) throw new Error('Provider login cleanup failed.');
+    this.handles.clear();
+  }
+}
+
+/** A hosted or terminal UI sees only the prompt and saved-account outcome. */
+export const beginSavedOpenAiLogin = async (
+  save: (result: IAuthLoginResult) => IHarnessLoginResult,
+  options: IHarnessLoginOptions,
+  fetcher?: typeof fetch,
+): Promise<IHarnessLoginHandle> => {
+  if (options.providerId !== 'openai' || options.flow !== 'device') throw new Error('This harness supports OpenAI device login.');
+  const service = new AuthSwitchLogin([new plugins.flexAccounts.OpenAiProviderAdapter({ fetch: fetcher })]);
+  try {
+    const handle = await service.beginLogin({ providerId: 'openai', flow: 'device' });
+    const completion = handle.completion.then(save).catch((): IHarnessLoginResult => ({
+      outcome: { lines: [], problems: ['Login did not complete or its saved credential could not be verified. The active login was preserved.'] },
+    })).finally(() => service.close());
+    return { prompt: handle.prompt, completion, cancel: async () => { await handle.cancel(); }, close: () => service.close() };
+  } catch { await service.close(); throw new Error('Provider login could not be started.'); }
+};
+
+/** Convert a verified OpenAI login for native OpenCode without exposing it in public account DTOs. */
+export const openCodeCredentialFromLogin = (credential: plugins.flexAccounts.IOpenAiChatGptOAuthCredential): {
+  type: 'oauth'; access: string; refresh: string; expires: number; accountId?: string;
+} => {
+  try {
+    const auth = plugins.flexAccounts.toOpenAiChatGptAuthCredentials(credential);
+    const payload = credential.accessToken.split('.')[1];
+    let expires = 0;
+    if (payload && payload.length <= 48 * 1024) {
+      try {
+        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: unknown };
+        expires = typeof claims?.exp === 'number' ? claims.exp * 1000 : 0;
+      } catch { /* Opaque access tokens are valid; native OpenCode refreshes an unknown expiry. */ }
+    }
+    return {
+      type: 'oauth', access: credential.accessToken, refresh: credential.refreshToken,
+      expires: Number.isSafeInteger(expires) && expires >= 0 ? expires : 0,
+      ...(auth.accountId ? { accountId: auth.accountId } : {}),
+    };
+  } catch { throw new Error('OpenAI login credential is invalid.'); }
+};

package/ts/classes.opencodeharness.ts

@@ -0,0 +1,114 @@
+import * as plugins from './plugins.js';
+import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
+import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, requireHarnessStopped } from './classes.credentialstore.js';
+import { CodexAccountStatus } from './classes.codexstatus.js';
+import { writeSecretFileAtomically } from './helpers.js';
+import type { IHarnessAccountStatus, IHarnessLoginOptions, IHarnessLoginProvider } from './interfaces.harness.js';
+import { beginSavedOpenAiLogin, openCodeCredentialFromLogin } from './classes.login.js';
+import { plainText } from './formatting.js';
+
+export interface IOpenCodeHarnessOptions {
+  dataHome?: string;
+  stashRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  fetch?: typeof fetch;
+  /** Process inspection dependency, injectable for isolated installations and tests. */
+  checkStopped?: () => void;
+}
+
+/** OpenCode owns one login per provider. Replacing a slot never replaces the whole provider set. */
+export class OpenCodeHarness extends FileHarness {
+  public readonly id = 'opencode';
+  public readonly label = 'OpenCode';
+  public readonly loginHint = 'Use authswitch opencode login for OpenAI; use opencode auth login for other providers.';
+  public readonly loginProviders: IHarnessLoginProvider[] = [{ providerId: 'openai', label: 'OpenAI', flows: ['device'] }];
+  protected readonly store: CredentialStore;
+  private readonly file: string;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly status: CodexAccountStatus;
+  private readonly checkStopped: () => void;
+  private readonly fetcher?: typeof fetch;
+
+  constructor(options: IOpenCodeHarnessOptions = {}) {
+    super();
+    this.env = options.env ?? process.env;
+    this.file = plugins.path.join(options.dataHome ?? (this.env.XDG_DATA_HOME || plugins.path.join(plugins.os.homedir(), '.local', 'share')), 'opencode', 'auth.json');
+    this.store = new CredentialStore(this.id, options.stashRoot);
+    this.status = new CodexAccountStatus(options.fetch);
+    this.fetcher = options.fetch;
+    this.checkStopped = options.checkStopped ?? (() => requireHarnessStopped('opencode'));
+  }
+  protected beforeMutation(): void { this.checkStopped(); }
+  /** Public identity only, for reconciling a host's OpenAI association after native refresh/restart. */
+  public activeOpenAiAccountId(): string | undefined {
+    const account = this.snapshot().accounts.find(item => item.slotId === 'openai');
+    return account ? this.openAiInfo(account.credential).accountId : undefined;
+  }
+  public beginLogin(options: IHarnessLoginOptions = { providerId: 'openai', flow: 'device' }) {
+    return beginSavedOpenAiLogin(result => {
+      const saved = this.importCredential('openai', openCodeCredentialFromLogin(result.credential));
+      const account = this.readState().accounts.find(account => account.id === saved.accountId)!;
+      return { outcome: { lines: [`Saved OpenAI login for ${plainText(account.label)}. Select it to switch OpenCode.`], problems: [] }, account: { id: account.id, label: account.label, slotId: account.slotId } };
+    }, options, this.fetcher);
+  }
+  private openAiInfo(entry: Record<string, unknown>): { accountId?: string; email?: string; plan?: string } {
+    if (entry.type !== 'oauth') return {};
+    let claims: plugins.flexAuth.IOpenAiChatGptTokenInfo | undefined;
+    try { claims = plugins.flexAuth.parseOpenAiChatGptTokenInfo(credentialText(entry.access)!); } catch { /* Opaque tokens can still be preserved. */ }
+    const accountId = credentialText(entry.accountId) ?? claims?.chatgptAccountId;
+    if (entry.accountId && claims?.chatgptAccountId && entry.accountId !== claims.chatgptAccountId) throw new Error('OpenCode OpenAI account ID does not match the credential.');
+    return { accountId, email: claims?.email?.toLowerCase(), plan: claims?.chatgptPlanType };
+  }
+  protected inspect(credential: Record<string, unknown>, slotId: string): IFileAccount {
+    if (!slotId || slotId.length > 256) throw new Error('Unsupported OpenCode provider ID.');
+    const type = credential.type;
+    let secret: string | undefined;
+    if (type === 'oauth') {
+      if (!credentialText(credential.access) || !credentialText(credential.refresh) || typeof credential.expires !== 'number' || !Number.isFinite(credential.expires)) throw new Error('Unsupported OpenCode OAuth credential.');
+      secret = credentialText(credential.refresh);
+    } else if (type === 'api') secret = credentialText(credential.key);
+    else if (type === 'wellknown' && credentialText(credential.key)) secret = credentialText(credential.token);
+    if (!secret) throw new Error('Unsupported OpenCode credential; the provider entry was preserved.');
+    const info = slotId === 'openai' ? this.openAiInfo(credential) : {};
+    const fingerprint = credentialHash(secret);
+    const identity = info.accountId ? `oauth:${info.accountId}` : `${type}:${fingerprint}`;
+    const label = info.email ?? (info.accountId ? `openai:${info.accountId}` : `${slotId} ${type === 'api' ? 'API key' : type} ${fingerprint.slice(0, 12)}`);
+    return { slotId, identity, label, credential };
+  }
+  protected snapshot(): IFileHarnessSnapshot {
+    if (this.env.OPENCODE_AUTH_CONTENT !== undefined) return { accounts: [], unavailable: 'OPENCODE_AUTH_CONTENT overrides the credential file. Unset it before managing file logins.' };
+    const data = readCredentialDocument(this.file).data;
+    const accounts: IFileAccount[] = [];
+    const unsupported: string[] = [];
+    for (const [provider, value] of Object.entries(data)) {
+      try { accounts.push(this.inspect(credentialRecord(value), provider)); }
+      catch { unsupported.push(provider); }
+    }
+    return { accounts, unavailable: unsupported.length ? 'OpenCode contains unsupported credential entries. Resolve them with opencode auth before modifying logins.' : null };
+  }
+  protected apply(slotId: string, previous: IFileAccount | undefined, target: IFileAccount | undefined): void {
+    const snapshot = readCredentialDocument(this.file);
+    if (JSON.stringify(snapshot.data[slotId]) !== JSON.stringify(previous?.credential)) throw new Error('OpenCode login changed during the operation; no credential was replaced.');
+    const next = { ...snapshot.data };
+    if (target) Object.defineProperty(next, slotId, { value: target.credential, enumerable: true, configurable: true, writable: true });
+    else delete next[slotId];
+    const raw = JSON.stringify(next, null, 2) + '\n';
+    if (readCredentialDocument(this.file).raw !== snapshot.raw) throw new Error('OpenCode credential file changed during the operation. Try again after OpenCode exits.');
+    plugins.fs.mkdirSync(plugins.path.dirname(this.file), { recursive: true, mode: 0o700 });
+    writeSecretFileAtomically(this.file, raw);
+    if (readCredentialDocument(this.file).raw !== raw) throw new Error('Active login verification failed. The outgoing login remains saved.');
+  }
+  public async readAccountStatus(id: string): Promise<IHarnessAccountStatus> {
+    const account = this.readCredential(id);
+    if (account.slotId === 'openai' && account.credential.type === 'oauth') {
+      const info = this.openAiInfo(account.credential);
+      if (!info.accountId) return { facts: [], problems: ['The OpenAI login has no account ID for a status lookup.'] };
+      return this.status.readCredential(credentialText(account.credential.access)!, info.accountId, info.plan);
+    }
+    return { facts: [
+      { section: 'Authentication', label: 'Provider', value: account.slotId },
+      { section: 'Authentication', label: 'Login type', value: String(account.credential.type) },
+      { section: 'Availability', label: 'Account usage and billing', value: 'This provider login does not expose a supported subscription or quota API.' },
+    ], problems: [] };
+  }
+}

package/ts/classes.operations.ts

@@ -0,0 +1,101 @@
+import * as plugins from './plugins.js';
+import type { IAuthHarness, IHarnessOutcome } from './interfaces.harness.js';
+
+export type TAuthSwitchMutation = { harnessId: string } & (
+  | { action: 'save'; accountId?: string; keepActive: boolean }
+  | { action: 'switch' | 'remove'; accountId: string }
+);
+export interface IAuthSwitchCoordinationRequest {
+  protocolVersion: 1;
+  /** Identifies credential locations; a host must refuse a different environment. */
+  contextId: string;
+  mutation: TAuthSwitchMutation;
+  /** Consent to wait for current work to finish; never permission to kill an active session. */
+  waitForIdle: boolean;
+}
+export type TAuthSwitchCoordinationResult =
+  | { status: 'unavailable' }
+  | { status: 'busy'; message: string }
+  | { status: 'complete'; outcome: IHarnessOutcome };
+export type TAuthSwitchCoordinator = (request: IAuthSwitchCoordinationRequest) => Promise<TAuthSwitchCoordinationResult>;
+export type TAuthSwitchConfirmation = (message: string) => Promise<boolean>;
+
+export const authSwitchEnvironmentId = (env: NodeJS.ProcessEnv = process.env): string => plugins.crypto.createHash('sha256').update(JSON.stringify({
+  home: plugins.os.homedir(),
+  stash: plugins.path.resolve(env.AUTHSWITCH_HOME || plugins.path.join(plugins.os.homedir(), '.authswitch')),
+  codex: plugins.path.resolve(env.CODEX_HOME || plugins.path.join(plugins.os.homedir(), '.codex')),
+  data: plugins.path.resolve(env.XDG_DATA_HOME || plugins.path.join(plugins.os.homedir(), '.local/share')),
+  claude: plugins.path.resolve(env.CLAUDE_CONFIG_DIR || plugins.path.join(plugins.os.homedir(), '.claude')),
+  openCodeOverride: env.OPENCODE_AUTH_CONTENT !== undefined,
+})).digest('hex');
+
+/** Validate the secret-free command boundary, including callers that do not use TypeScript. */
+export const assertAuthSwitchMutation: (value: unknown) => asserts value is TAuthSwitchMutation = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid account operation.');
+  const item = value as Record<string, unknown>;
+  const keys = item.action === 'save' ? ['harnessId', 'action', 'accountId', 'keepActive'] : ['harnessId', 'action', 'accountId'];
+  if (Object.keys(item).some(key => !keys.includes(key))
+    || typeof item.harnessId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.harnessId)
+    || !['save', 'switch', 'remove'].includes(String(item.action))
+    || (item.accountId !== undefined && (typeof item.accountId !== 'string' || !item.accountId.length || item.accountId.length > 512))
+    || (item.action === 'save' ? typeof item.keepActive !== 'boolean' : typeof item.accountId !== 'string')) {
+    throw new Error('Invalid account operation.');
+  }
+};
+
+export const runAuthSwitchMutation = async (harness: IAuthHarness, mutation: TAuthSwitchMutation): Promise<IHarnessOutcome> => {
+  assertAuthSwitchMutation(mutation);
+  if (harness.id !== mutation.harnessId) throw new Error('Account operation targets a different harness.');
+  switch (mutation.action) {
+    case 'save': return harness.saveCurrent({ keepActive: mutation.keepActive, accountId: mutation.accountId });
+    case 'switch': return harness.switchAccount(mutation.accountId);
+    case 'remove': return harness.removeAccount(mutation.accountId);
+  }
+};
+
+/** One mutation path for command, guide and TUI. Supervisors own their complete restart transaction. */
+export class AuthSwitchOperations {
+  constructor(private readonly coordinator?: TAuthSwitchCoordinator) {}
+  public async run(harness: IAuthHarness, mutation: TAuthSwitchMutation, confirm?: TAuthSwitchConfirmation): Promise<IHarnessOutcome> {
+    assertAuthSwitchMutation(mutation);
+    if (harness.id !== mutation.harnessId) throw new Error('Account operation targets a different harness.');
+    if (this.coordinator && mutation.action !== 'remove') {
+      const request: IAuthSwitchCoordinationRequest = { protocolVersion: 1, contextId: authSwitchEnvironmentId(), mutation, waitForIdle: false };
+      let result = await this.coordinator(request);
+      if (result.status === 'busy') {
+        if (!confirm || !await confirm(result.message)) return { lines: [], problems: [result.message] };
+        result = await this.coordinator({ ...request, waitForIdle: true });
+      }
+      if (result.status === 'complete') return result.outcome;
+      if (result.status === 'busy') return { lines: [], problems: [result.message] };
+    }
+    return runAuthSwitchMutation(harness, mutation);
+  }
+}
+
+/** AGL owns authenticated controller discovery. No AGL dependency, tokens or credential payloads cross this bridge. */
+export class AglAuthSwitchCoordinator {
+  public async coordinate(request: IAuthSwitchCoordinationRequest): Promise<TAuthSwitchCoordinationResult> {
+    assertAuthSwitchMutation(request.mutation);
+    const output = await new Promise<string | undefined>((resolve, reject) => {
+      plugins.childProcess.execFile('agl', ['authswitch', '--request', JSON.stringify(request)], {
+        encoding: 'utf8', timeout: 360_000, maxBuffer: 1024 * 1024, windowsHide: true,
+      }, (error, stdout) => {
+        if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') { resolve(undefined); return; }
+        if (error) { reject(new Error('AGL coordination did not complete. Check AGL and account status before retrying; no local credential operation was attempted. Install an AGL version with authswitch support.')); return; }
+        resolve(stdout);
+      });
+    });
+    if (output === undefined) return { status: 'unavailable' };
+    try {
+      const result = JSON.parse(output) as TAuthSwitchCoordinationResult;
+      if (result.status === 'unavailable') return { status: 'unavailable' };
+      if (result.status === 'busy' && typeof result.message === 'string' && result.message.length <= 4096) return { status: 'busy', message: result.message };
+      if (result.status === 'complete' && result.outcome && ['lines', 'problems'].every(key => {
+        const items = result.outcome[key as keyof IHarnessOutcome];
+        return Array.isArray(items) && items.length <= 100 && items.every(item => typeof item === 'string' && item.length <= 4096);
+      })) return { status: 'complete', outcome: { lines: result.outcome.lines, problems: result.outcome.problems } };
+    } catch { /* Never print raw transport output, which may contain native diagnostics. */ }
+    throw new Error('AGL returned an unsupported coordination response. Check account status before retrying.');
+  }
+}