@modelprofile.com/authswitch 2.1.2

package/ts/classes.remotecontrol.ts

@@ -0,0 +1,208 @@
+import * as plugins from './plugins.js';
+import type { IRemoteControlEnrollment } from './interfaces.js';
+import { CodexHome } from './classes.codexhome.js';
+
+const TABLE_NAME = 'remote_control_enrollments';
+
+/** The columns authswitch knows how to carry across a switch. */
+const COLUMNS = [
+  'websocket_url',
+  'account_id',
+  'app_server_client_name',
+  'server_id',
+  'environment_id',
+  'server_name',
+  'updated_at',
+  'remote_control_enabled',
+] as const;
+
+/** The columns that make up the table's primary key. */
+const KEY_COLUMNS = ['websocket_url', 'account_id', 'app_server_client_name'] as const;
+
+/**
+ * Reads and restores Codex' remote-control enrollments.
+ *
+ * An enrollment is the record that binds this machine's Codex app-server to a
+ * paired ChatGPT client. Its primary key includes the account id, so enrollments
+ * for several accounts can coexist -- but a credential swap can still leave an
+ * account without its row, which is exactly what breaks remote control after a
+ * naive auth switch. authswitch captures the rows next to the credential and
+ * puts them back when the credential is restored.
+ */
+export class RemoteControlStore {
+  public readonly codexHome: CodexHome;
+
+  constructor(codexHomeArg: CodexHome) {
+    this.codexHome = codexHomeArg;
+  }
+
+  /** True when a Codex state database exists and carries the enrollment table. */
+  public isAvailable(): boolean {
+    const statePath = this.codexHome.statePath;
+    if (!statePath) {
+      return false;
+    }
+    try {
+      return this.withDatabase(statePath, true, (databaseArg) => this.hasTable(databaseArg));
+    } catch {
+      // A read-only connection cannot create the -shm file a WAL database needs,
+      // so an unclean shutdown can make even the probe fail. Report "not
+      // available" here; the restore path probes over its writable connection.
+      return false;
+    }
+  }
+
+  /**
+   * Returns the enrollments for one account, or every enrollment when no
+   * account id is given.
+   */
+  public read(accountIdArg?: string | null): IRemoteControlEnrollment[] {
+    const statePath = this.codexHome.statePath;
+    if (!statePath) {
+      return [];
+    }
+    try {
+      return this.withDatabase(statePath, true, (databaseArg) => {
+        if (!this.hasTable(databaseArg)) {
+          return [];
+        }
+        const selection = COLUMNS.join(', ');
+        const statement = accountIdArg
+          ? databaseArg.prepare(`select ${selection} from ${TABLE_NAME} where account_id = ?`)
+          : databaseArg.prepare(`select ${selection} from ${TABLE_NAME}`);
+        const rows = accountIdArg ? statement.all(accountIdArg) : statement.all();
+        return rows.map((rowArg) => this.toEnrollment(rowArg as Record<string, unknown>));
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Puts enrollments back, updating any row with the same primary key.
+   *
+   * Throws rather than reporting zero when the database or the table is not
+   * there: restoring remote control is the reason this tool exists, so failing
+   * to do it must surface instead of looking like "there was nothing to do".
+   */
+  public restore(enrollmentsArg: IRemoteControlEnrollment[]): number {
+    if (enrollmentsArg.length === 0) {
+      return 0;
+    }
+    const statePath = this.codexHome.statePath;
+    if (!statePath) {
+      throw new Error(
+        `no Codex state database found in ${this.codexHome.dir}; cannot restore remote-control enrollments`,
+      );
+    }
+    // Opened read-write: the read-only probe cannot create the -shm file a WAL
+    // database needs, and failing there would leave the switch half-applied.
+    return this.withDatabase(statePath, false, (databaseArg) => {
+      if (!this.hasTable(databaseArg)) {
+        throw new Error(
+          `${statePath} has no ${TABLE_NAME} table; this Codex version stores remote-control enrollments elsewhere`,
+        );
+      }
+      this.assertKnownColumns(databaseArg, statePath);
+
+      const placeholders = COLUMNS.map(() => '?').join(', ');
+      const updates = COLUMNS.filter(
+        (columnArg) => !(KEY_COLUMNS as readonly string[]).includes(columnArg),
+      )
+        .map((columnArg) => `${columnArg} = excluded.${columnArg}`)
+        .join(', ');
+      const statement = databaseArg.prepare(
+        `insert into ${TABLE_NAME} (${COLUMNS.join(', ')}) values (${placeholders})
+         on conflict(${KEY_COLUMNS.join(', ')}) do update set ${updates}`,
+      );
+
+      databaseArg.exec('begin immediate');
+      try {
+        for (const enrollmentArg of enrollmentsArg) {
+          statement.run(
+            enrollmentArg.websocketUrl,
+            enrollmentArg.accountId,
+            enrollmentArg.appServerClientName,
+            enrollmentArg.serverId,
+            enrollmentArg.environmentId,
+            enrollmentArg.serverName,
+            enrollmentArg.updatedAt,
+            enrollmentArg.remoteControlEnabled,
+          );
+        }
+        databaseArg.exec('commit');
+      } catch (errorArg) {
+        databaseArg.exec('rollback');
+        throw errorArg;
+      }
+      return enrollmentsArg.length;
+    });
+  }
+
+  private hasTable(databaseArg: InstanceType<typeof plugins.DatabaseSync>): boolean {
+    const row = databaseArg
+      .prepare(`select name from sqlite_master where type = 'table' and name = ?`)
+      .get(TABLE_NAME);
+    return row !== undefined;
+  }
+
+  /**
+   * Refuses to write when Codex has added columns this version does not know
+   * about. `CodexHome` deliberately follows the newest state generation, so a
+   * Codex upgrade can widen this table -- and writing only the columns we know
+   * would quietly reset the rest to their defaults.
+   */
+  private assertKnownColumns(
+    databaseArg: InstanceType<typeof plugins.DatabaseSync>,
+    statePathArg: string,
+  ): void {
+    const rows = databaseArg.prepare(`pragma table_info(${TABLE_NAME})`).all() as Array<
+      Record<string, unknown>
+    >;
+    const actual = rows.map((rowArg) => String(rowArg.name));
+    const unexpected = actual.filter((nameArg) => !(COLUMNS as readonly string[]).includes(nameArg));
+    const missing = COLUMNS.filter((nameArg) => !actual.includes(nameArg));
+    if (unexpected.length > 0 || missing.length > 0) {
+      throw new Error(
+        `${statePathArg} has an unexpected ${TABLE_NAME} schema ` +
+          `(unexpected: ${unexpected.join(', ') || 'none'}; missing: ${missing.join(', ') || 'none'}). ` +
+          'Refusing to restore rather than write a partial row - authswitch needs an update for this Codex version.',
+      );
+    }
+  }
+
+  private toEnrollment(rowArg: Record<string, unknown>): IRemoteControlEnrollment {
+    return {
+      websocketUrl: String(rowArg.websocket_url ?? ''),
+      accountId: String(rowArg.account_id ?? ''),
+      appServerClientName: String(rowArg.app_server_client_name ?? ''),
+      serverId: String(rowArg.server_id ?? ''),
+      environmentId: String(rowArg.environment_id ?? ''),
+      serverName: String(rowArg.server_name ?? ''),
+      updatedAt: Number(rowArg.updated_at ?? 0),
+      remoteControlEnabled:
+        rowArg.remote_control_enabled === null || rowArg.remote_control_enabled === undefined
+          ? null
+          : Number(rowArg.remote_control_enabled),
+    };
+  }
+
+  /**
+   * Codex keeps the state database in WAL mode and holds it open from the
+   * app-server, so every access takes a busy timeout rather than failing on the
+   * first lock contention.
+   */
+  private withDatabase<T>(
+    pathArg: string,
+    readOnlyArg: boolean,
+    handlerArg: (databaseArg: InstanceType<typeof plugins.DatabaseSync>) => T,
+  ): T {
+    const database = new plugins.DatabaseSync(pathArg, { readOnly: readOnlyArg });
+    try {
+      database.exec('pragma busy_timeout = 5000');
+      return handlerArg(database);
+    } finally {
+      database.close();
+    }
+  }
+}

package/ts/classes.service.ts

@@ -0,0 +1,152 @@
+import * as plugins from './plugins.js';
+import { CodexHarness } from './classes.codexharness.js';
+import { OpenCodeHarness } from './classes.opencodeharness.js';
+import { ClaudeCodeHarness } from './classes.claudecodeharness.js';
+import { readAccountList } from './classes.accountlist.js';
+import { assertAuthSwitchMutation, authSwitchEnvironmentId, runAuthSwitchMutation, type IAuthSwitchCoordinationRequest, type TAuthSwitchCoordinationResult, type TAuthSwitchCoordinator } from './classes.operations.js';
+import type { IAuthHarness, IHarnessLoginHandle, IHarnessLoginOptions, IHarnessLoginProvider, IHarnessLoginResult, IHarnessOutcome } from './interfaces.harness.js';
+import type { IAccountList } from './interfaces.list.js';
+import type { TAuthLoginPrompt } from './classes.login.js';
+
+export type TAuthSwitchServiceRequest = { protocolVersion: 1 } & (
+  | { action: 'list'; harnessId?: string }
+  | { action: 'mutate'; coordination: IAuthSwitchCoordinationRequest }
+  | ({ action: 'login'; harnessId: string } & IHarnessLoginOptions)
+  | { action: 'get' | 'cancel'; operationId: string }
+);
+/** Disposable operation status. Hosts authenticate callers; neither prompts nor results contain credentials. */
+export interface IAuthSwitchServiceOperation {
+  id: string;
+  contextId: string;
+  state: 'pending' | 'complete' | 'failed';
+  prompt?: TAuthLoginPrompt;
+  accounts?: IAccountList;
+  loginCapabilities?: { harnessId: string; providers: IHarnessLoginProvider[] }[];
+  account?: IHarnessLoginResult['account'];
+  result?: TAuthSwitchCoordinationResult;
+  error?: string;
+}
+interface IOperation {
+  status: IAuthSwitchServiceOperation;
+  task: Promise<void>;
+  finishedAt?: number;
+  login?: IHarnessLoginHandle;
+  cancelled: boolean;
+}
+
+const publicOutcome = (outcome: IHarnessOutcome): IHarnessOutcome => ({ lines: [...outcome.lines], problems: [...outcome.problems] });
+const publicResult = (result: TAuthSwitchCoordinationResult): TAuthSwitchCoordinationResult => result.status === 'complete'
+  ? { status: 'complete', outcome: publicOutcome(result.outcome) }
+  : result.status === 'busy' ? { status: 'busy', message: result.message } : { status: 'unavailable' };
+const publicPrompt = (prompt: TAuthLoginPrompt): TAuthLoginPrompt => prompt.flow === 'device'
+  ? { flow: 'device', verificationUrl: prompt.verificationUrl, userCode: prompt.userCode }
+  : { flow: 'browser', authUrl: prompt.authUrl };
+
+export const assertAuthSwitchServiceRequest: (value: unknown) => asserts value is TAuthSwitchServiceRequest = value => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid authswitch request.');
+  const request = value as Record<string, unknown>;
+  const keys = request.action === 'login' ? ['harnessId', 'providerId', 'flow'] : request.action === 'list' ? ['harnessId']
+    : request.action === 'mutate' ? ['coordination'] : ['operationId'];
+  if (request.protocolVersion !== 1 || !['list', 'login', 'mutate', 'get', 'cancel'].includes(String(request.action))
+    || Object.keys(request).some(key => !['protocolVersion', 'action', ...keys].includes(key))) throw new Error('Unsupported authswitch request.');
+  if (request.action === 'mutate') {
+    const coordination = request.coordination as IAuthSwitchCoordinationRequest | undefined;
+    if (!coordination || coordination.protocolVersion !== 1 || typeof coordination.waitForIdle !== 'boolean'
+      || typeof coordination.contextId !== 'string' || !/^[a-f0-9]{64}$/.test(coordination.contextId)
+      || Object.keys(coordination).some(key => !['protocolVersion', 'contextId', 'mutation', 'waitForIdle'].includes(key))) throw new Error('Invalid coordination request.');
+    assertAuthSwitchMutation(coordination.mutation);
+  } else if (request.action === 'get' || request.action === 'cancel') {
+    if (typeof request.operationId !== 'string' || !/^[a-f0-9-]{36}$/.test(request.operationId)) throw new Error('Invalid operation ID.');
+  } else if ((request.harnessId !== undefined || request.action === 'login')
+    && (typeof request.harnessId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(request.harnessId))) throw new Error('Invalid harness ID.');
+  if (request.action === 'login' && (typeof request.providerId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(request.providerId)
+    || !['device', 'browser'].includes(String(request.flow)))) throw new Error('Invalid login provider or flow.');
+};
+
+/** Hosted account manager. Operations outlive HTTP connections and are retained briefly for polling. */
+export class AuthSwitchService {
+  private readonly operations = new Map<string, IOperation>();
+  private closed = false;
+  constructor(
+    private readonly harnesses: IAuthHarness[] = [new CodexHarness(), new OpenCodeHarness(), new ClaudeCodeHarness()],
+    private readonly coordinator?: TAuthSwitchCoordinator,
+  ) {}
+  private harness(id: string): IAuthHarness {
+    const harness = this.harnesses.find(item => item.id === id);
+    if (!harness) throw new Error('Unknown harness.');
+    return harness;
+  }
+  private snapshot(operation: IOperation): IAuthSwitchServiceOperation { return structuredClone(operation.status); }
+  public async request(request: TAuthSwitchServiceRequest): Promise<IAuthSwitchServiceOperation> {
+    assertAuthSwitchServiceRequest(request);
+    if (this.closed) throw new Error('Account manager is closed.');
+    for (const [id, operation] of this.operations) {
+      if (operation.finishedAt !== undefined && Date.now() - operation.finishedAt > 10 * 60_000) this.operations.delete(id);
+    }
+    if (request.action === 'get' || request.action === 'cancel') {
+      const operation = this.operations.get(request.operationId);
+      if (!operation) throw new Error('Operation expired or belongs to another controller. Check account status before retrying.');
+      if (request.action === 'cancel') {
+        if (operation.status.state === 'pending' && !operation.status.prompt) throw new Error('Only a pending login can be cancelled.');
+        operation.cancelled = true;
+        await operation.login?.cancel();
+      }
+      return this.snapshot(operation);
+    }
+    if (this.operations.size >= 64 || [...this.operations.values()].filter(item => item.status.state === 'pending').length >= 8) {
+      throw new Error('Account manager operation limit reached. Finish pending operations before starting another.');
+    }
+    const operation: IOperation = { status: { id: plugins.crypto.randomUUID(), contextId: authSwitchEnvironmentId(), state: 'pending' }, task: Promise.resolve(), cancelled: false };
+    this.operations.set(operation.status.id, operation);
+    operation.task = Promise.resolve().then(async () => {
+      switch (request.action) {
+        case 'list': {
+          operation.status.accounts = await readAccountList(request.harnessId ? [this.harness(request.harnessId)] : this.harnesses);
+          operation.status.loginCapabilities = this.harnesses.filter(item => item.beginLogin).map(item => ({ harnessId: item.id,
+            providers: (item.loginProviders ?? []).map(provider => ({ providerId: provider.providerId, label: provider.label, flows: [...provider.flows] })) }));
+          break;
+        }
+        case 'mutate': {
+          if (request.coordination.contextId !== authSwitchEnvironmentId()) {
+            operation.status.result = { status: 'complete', outcome: { lines: [], problems: ['AGL and authswitch use different credential locations. Use matching credential environment settings before switching.'] } };
+            break;
+          }
+          const harness = this.harness(request.coordination.mutation.harnessId);
+          const coordinated = this.coordinator ? await this.coordinator(request.coordination) : { status: 'unavailable' } as const;
+          operation.status.result = publicResult(coordinated.status === 'unavailable'
+            ? { status: 'complete', outcome: await runAuthSwitchMutation(harness, request.coordination.mutation) } : coordinated);
+          break;
+        }
+        case 'login': {
+          const harness = this.harness(request.harnessId);
+          if (!harness.beginLogin) throw new Error('This harness does not support hosted login.');
+          if (!harness.loginProviders?.some(provider => provider.providerId === request.providerId && provider.flows.includes(request.flow))) throw new Error('This harness does not support that login flow.');
+          const login = await harness.beginLogin({ providerId: request.providerId, flow: request.flow });
+          operation.login = login;
+          operation.status.prompt = publicPrompt(login.prompt);
+          if (operation.cancelled || this.closed) await login.cancel();
+          try {
+            const result = await login.completion;
+            operation.status.result = { status: 'complete', outcome: publicOutcome(result.outcome) };
+            operation.status.account = result.account ? { id: result.account.id, label: result.account.label, slotId: result.account.slotId } : undefined;
+          }
+          finally { await login.close(); operation.login = undefined; }
+          break;
+        }
+      }
+      operation.status.state = 'complete';
+    }).catch(() => {
+      operation.status.state = 'failed';
+      operation.status.error = 'Account operation failed. Check account and runtime status before retrying.';
+    }).finally(() => { operation.finishedAt = Date.now(); });
+    return this.snapshot(operation);
+  }
+  public async close(): Promise<void> {
+    this.closed = true;
+    await Promise.allSettled([...this.operations.values()].map(async operation => {
+      operation.cancelled = true;
+      await operation.login?.cancel();
+    }));
+    await Promise.all([...this.operations.values()].map(operation => operation.task));
+  }
+}

package/ts/classes.stashstore.ts

@@ -0,0 +1,223 @@
+import * as plugins from './plugins.js';
+import type {
+  ICodexIdentity,
+  IRemoteControlEnrollment,
+  IStashEntry,
+  THarnessName,
+} from './interfaces.js';
+import { writeSecretFileAtomically } from './helpers.js';
+
+const AUTH_FILE_NAME = 'auth.json';
+const META_FILE_NAME = 'stash.json';
+
+/**
+ * Filesystem-backed store for Codex credentials and enrollment metadata.
+ * Other harness adapters own their storage format; this is not a universal auth schema.
+ *
+ * A stash is deliberately a directory of files rather than a database: the thing
+ * being stored *is* a credential file, the store must survive with no services
+ * running, and it must be greppable and removable by hand when something goes
+ * wrong. Everything is written owner-only.
+ */
+export class StashStore {
+  public readonly rootDir: string;
+  public readonly harness: THarnessName;
+
+  constructor(harnessArg: THarnessName, rootDirArg?: string) {
+    if (!/^[a-z][a-z0-9-]*$/.test(harnessArg)) {
+      throw new Error('invalid harness namespace');
+    }
+    this.harness = harnessArg;
+    const base =
+      rootDirArg ??
+      process.env.AUTHSWITCH_HOME ??
+      plugins.path.join(plugins.os.homedir(), '.authswitch');
+    this.rootDir = plugins.path.join(base, harnessArg);
+  }
+
+  /**
+   * Turns an account email into a directory name that is safe on every
+   * filesystem while staying readable, so `ls ~/.authswitch/codex` is useful.
+   */
+  public slugFor(emailArg: string): string {
+    const slug = emailArg
+      .toLowerCase()
+      .replace(/[^a-z0-9._@+-]+/g, '_')
+      .replace(/^[._]+|[._]+$/g, '');
+    if (slug.length === 0) {
+      throw new Error(`cannot derive a stash name from "${emailArg}"`);
+    }
+    return slug;
+  }
+
+  public entryDir(emailArg: string): string {
+    return plugins.path.join(this.rootDir, this.slugFor(emailArg));
+  }
+
+  public has(emailArg: string): boolean {
+    return plugins.fs.existsSync(plugins.path.join(this.entryDir(emailArg), META_FILE_NAME));
+  }
+
+  /**
+   * Writes a credential and its remote-control enrollments under the account email,
+   * replacing any existing stash for the same account.
+   *
+   * Both files go through an atomic temp-and-rename, and the metadata is written
+   * last: a crash mid-write therefore leaves either the previous complete stash
+   * or a credential whose metadata is still the old one, never a directory that
+   * `list()` skips because its metadata never arrived. The caller is expected to
+   * verify with `readBack()` before destroying the original.
+   */
+  public write(
+    identityArg: ICodexIdentity,
+    rawAuthArg: string,
+    enrollmentsArg: IRemoteControlEnrollment[],
+    codexHomeArg: string,
+  ): IStashEntry {
+    const previous = this.readMeta(identityArg.email);
+    if (previous && (previous.email !== identityArg.email || previous.accountId !== identityArg.accountId || previous.kind !== identityArg.kind)) {
+      throw new Error('a different Codex account already occupies this email-based stash; refusing to replace its credential');
+    }
+    const dir = this.entryDir(identityArg.email);
+    plugins.fs.mkdirSync(this.rootDir, { recursive: true, mode: 0o700 });
+    plugins.fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // mkdirSync's mode is subject to the umask and is ignored for a directory
+    // that already exists, so tighten both levels explicitly.
+    plugins.fs.chmodSync(this.rootDir, 0o700);
+    plugins.fs.chmodSync(dir, 0o700);
+
+    const entry: IStashEntry = {
+      email: identityArg.email,
+      kind: identityArg.kind,
+      accountId: identityArg.accountId,
+      planType: identityArg.planType,
+      userId: identityArg.userId,
+      stashedAt: new Date().toISOString(),
+      codexHome: codexHomeArg,
+      enrollments: enrollmentsArg,
+    };
+
+    writeSecretFileAtomically(plugins.path.join(dir, AUTH_FILE_NAME), rawAuthArg);
+    writeSecretFileAtomically(
+      plugins.path.join(dir, META_FILE_NAME),
+      `${JSON.stringify(entry, null, 2)}\n`,
+    );
+    return entry;
+  }
+
+  /**
+   * Reads a stash back and confirms it matches what was meant to be written.
+   * Callers use this before clearing the active credential, so a stash is only
+   * ever trusted once it has been proven readable.
+   */
+  public readBack(emailArg: string, expectedAuthArg: string): boolean {
+    const meta = this.readMeta(emailArg);
+    const auth = this.readAuth(emailArg);
+    return meta !== null && auth === expectedAuthArg;
+  }
+
+  public readMeta(emailArg: string): IStashEntry | null {
+    const metaPath = plugins.path.join(this.entryDir(emailArg), META_FILE_NAME);
+    if (!plugins.fs.existsSync(metaPath)) {
+      return null;
+    }
+    try {
+      return JSON.parse(plugins.fs.readFileSync(metaPath, 'utf8')) as IStashEntry;
+    } catch {
+      return null;
+    }
+  }
+
+  public readAuth(emailArg: string): string | null {
+    const authPath = plugins.path.join(this.entryDir(emailArg), AUTH_FILE_NAME);
+    if (!plugins.fs.existsSync(authPath)) {
+      return null;
+    }
+    return plugins.fs.readFileSync(authPath, 'utf8');
+  }
+
+  /** Every stash, newest first. Unreadable directories are skipped, not fatal. */
+  public list(): IStashEntry[] {
+    if (!plugins.fs.existsSync(this.rootDir)) {
+      return [];
+    }
+    const entries: IStashEntry[] = [];
+    for (const nameArg of plugins.fs.readdirSync(this.rootDir)) {
+      const metaPath = plugins.path.join(this.rootDir, nameArg, META_FILE_NAME);
+      if (!plugins.fs.existsSync(metaPath)) {
+        continue;
+      }
+      try {
+        entries.push(JSON.parse(plugins.fs.readFileSync(metaPath, 'utf8')) as IStashEntry);
+      } catch {
+        continue;
+      }
+    }
+    return entries.sort((leftArg, rightArg) => rightArg.stashedAt.localeCompare(leftArg.stashedAt));
+  }
+
+  /**
+   * Directories under the stash root that hold a credential but no readable
+   * metadata -- the shape an interrupted write would leave behind. Reported by
+   * `doctor` so they are visible rather than silently skipped by `list()`.
+   */
+  public incomplete(): string[] {
+    if (!plugins.fs.existsSync(this.rootDir)) {
+      return [];
+    }
+    return plugins.fs.readdirSync(this.rootDir).filter((nameArg) => {
+      const dir = plugins.path.join(this.rootDir, nameArg);
+      if (!plugins.fs.statSync(dir).isDirectory()) {
+        return false;
+      }
+      const hasAuth = plugins.fs.existsSync(plugins.path.join(dir, AUTH_FILE_NAME));
+      const hasMeta = plugins.fs.existsSync(plugins.path.join(dir, META_FILE_NAME));
+      return hasAuth && !hasMeta;
+    });
+  }
+
+  /**
+   * Resolves a user-supplied account reference to a stashed email.
+   *
+   * Accepts the exact email, the directory slug, the local part, or a prefix.
+   * Deliberately not a substring match: this reference selects which credential
+   * becomes active, so an incidental substring hit would activate an account the
+   * user never named.
+   */
+  public resolve(referenceArg: string): { email: string } | { candidates: string[] } {
+    const needle = referenceArg.toLowerCase();
+    const all = this.list();
+
+    const exact = all.find((entryArg) => entryArg.email.toLowerCase() === needle);
+    if (exact) {
+      return { email: exact.email };
+    }
+    const bySlug = all.find((entryArg) => this.slugFor(entryArg.email) === needle);
+    if (bySlug) {
+      return { email: bySlug.email };
+    }
+    const byLocalPart = all.filter(
+      (entryArg) => entryArg.email.toLowerCase().split('@')[0] === needle,
+    );
+    if (byLocalPart.length === 1) {
+      return { email: byLocalPart[0].email };
+    }
+    if (byLocalPart.length > 1) {
+      return { candidates: byLocalPart.map((entryArg) => entryArg.email) };
+    }
+    const byPrefix = all.filter((entryArg) => entryArg.email.toLowerCase().startsWith(needle));
+    if (byPrefix.length === 1) {
+      return { email: byPrefix[0].email };
+    }
+    return { candidates: byPrefix.map((entryArg) => entryArg.email) };
+  }
+
+  public remove(emailArg: string): boolean {
+    const dir = this.entryDir(emailArg);
+    if (!plugins.fs.existsSync(dir)) {
+      return false;
+    }
+    plugins.fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+}