@modelprofile.com/authswitch 8.0.0 → 8.2.0

package/ts/classes.authorityimport.ts

@@ -0,0 +1,746 @@
+import * as plugins from './plugins.js';
+import type { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
+import { authSwitchEnvironmentId } from './classes.operations.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
+import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
+import { ClaudeAccountStatus, type IClaudeLogin, type IClaudeStatusRead } from './classes.claudestatus.js';
+import { ClaudeTokenRefresh, type TClaudeAuthorityRefreshResult } from './classes.claudetokenrefresh.js';
+import { CodexDaemon } from './classes.codexdaemon.js';
+import { CodexHome } from './classes.codexhome.js';
+import { HarnessProcesses, type THarnessBinary } from './classes.harnessprocesses.js';
+import { LegacySourceChangedError, readLegacySourceEnrollments, readLegacySourceMaterial,
+  readLegacySources, resolveLegacySourceLocations } from './ts_migration/legacysources/index.js';
+import type { ILegacySourceRecord, TLegacySourceMaterial } from './ts_migration/legacysources/index.js';
+import type { IStoredAuthorityAccount, IStoredAuthorityGrant, IStoredAuthorityHandoff,
+  IStoredAuthorityMigrationLedger, TStoredGrantPurpose } from './classes.authoritymodels.js';
+import type { IAuthSwitchImportInventory, IAuthSwitchImportResult, IAuthSwitchImportSource,
+  IAuthSwitchImportStatus, IAuthSwitchImportStatusEntry, TAuthSwitchImportAction,
+  TAuthSwitchImportLedgerStatus, TAuthSwitchImportSubmission } from './authority-import-contract.js';
+
+/**
+ * What the owner must know before importing anything.
+ *
+ * The run-order line is not advice: after an account is imported, its legacy record holds a refresh token
+ * the provider has already rotated away, and the everyday legacy commands would restore or exercise exactly
+ * that record. The import is therefore only safe once those commands run on the authority.
+ */
+const INVENTORY_NOTICE: readonly string[] = [
+  'This inventory only reads. It changes no authority record, no legacy store and no credential.',
+  'Importing transfers ownership; it does not copy. Verifying a saved authswitch record refreshes its token, '
+  + 'and the legacy copy is unusable from that moment. The fallback is one device sign-in for that account.',
+  'A native Codex, Claude or OpenCode store is projected, not imported: the native tool stays the only '
+  + 'refresher, and its record is verified by a provider read that rotates nothing.',
+  'Do not import until the everyday commands run on the authority and the native projections exist. Until '
+  + 'then a legacy command could restore or exercise a record whose token an import has already replaced.',
+  'No file under the legacy stores is deleted by an import. Retiring those files is a separate later step.',
+  'The authority store is deliberately not backed up. Losing it later loses the remote-control enrollments '
+  + 'and every runtime binding as well as the logins: each account then needs a device sign-in, and each '
+  + 'enrollment has to be paired again.',
+];
+
+/**
+ * What this daemon can observe about writers of the legacy stores.
+ *
+ * It cannot observe every writer: a host that uses the legacy library inside its own process is invisible
+ * here, which is why a submission also carries the caller's own assertion. Unknown is never idle.
+ */
+export interface IAuthSwitchImportQuiescence {
+  /** The live pid of the authswitch watch that owns the legacy stores, or null when none runs. */
+  watchHolderPid(): number | null;
+  runningHarnessPids(binary: THarnessBinary): readonly number[];
+  /** Codex's own answer about its app-server. `null` means unknown, which counts as running. */
+  codexAppServerRunning(): boolean | null;
+}
+
+/**
+ * Exactly the two provider operations an import needs, so nothing here can reach for a third.
+ *
+ * `OpenAiProviderAdapter` satisfies this; naming only what is used keeps the rotating call countable and
+ * makes it visible that a projection never touches `refreshCredential`.
+ */
+export interface IAuthSwitchImportOpenAiOperations {
+  refreshCredential(credential: plugins.flexAccounts.IOpenAiChatGptOAuthCredential):
+  Promise<plugins.flexAccounts.TSmartAiProviderRefreshResult>;
+  getAccountRateLimits(credential: plugins.flexAccounts.TOpenAiChatGptReadCredential):
+  Promise<plugins.flexAccounts.TSmartAiProviderAccountRateLimitsResult>;
+}
+
+/** The non-rotating Claude proof: one profile read that must name the expected immutable identity. */
+export interface IAuthSwitchImportClaudeStatus {
+  readDetailed(login: IClaudeLogin): Promise<IClaudeStatusRead>;
+}
+
+/** The rotating Claude refresh, with its own explicit uncertain outcome. */
+export interface IAuthSwitchImportClaudeTokens {
+  refreshForAuthority(oauth: Record<string, unknown>): Promise<TClaudeAuthorityRefreshResult>;
+}
+
+export interface IAuthSwitchAuthorityImportOptions {
+  /** Locates the legacy stores, exactly as each owning class locates its own. */
+  env?: NodeJS.ProcessEnv;
+  homeDirectory?: string;
+  now?: () => number;
+  /** The one rotating refresh of an imported ChatGPT login, and the non-rotating read that proves one. */
+  openAi?: IAuthSwitchImportOpenAiOperations;
+  claudeStatus?: IAuthSwitchImportClaudeStatus;
+  claudeTokens?: IAuthSwitchImportClaudeTokens;
+  secrets?: IAuthSwitchSecretCodec;
+  quiescence?: IAuthSwitchImportQuiescence;
+}
+
+/** Reads the host: the watch lock file, the process table and Codex's own daemon status. */
+export class AuthSwitchImportHostQuiescence implements IAuthSwitchImportQuiescence {
+  constructor(private readonly authSwitchHome: string, private readonly codexHome: string) {}
+
+  public watchHolderPid(): number | null {
+    // The lock is read, never acquired: an inventory or an import must not become the watch.
+    let raw: string;
+    try { raw = plugins.fs.readFileSync(plugins.path.join(this.authSwitchHome, 'watch.lock'), 'utf8'); }
+    catch { return null; }
+    let pid: unknown;
+    try { pid = (JSON.parse(raw) as Record<string, unknown>).pid; } catch { return null; }
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0) return null;
+    try { process.kill(pid, 0); return pid; }
+    catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM' ? pid : null; }
+  }
+
+  public runningHarnessPids(binary: THarnessBinary): readonly number[] {
+    return new HarnessProcesses(binary).list().map(item => item.pid);
+  }
+
+  public codexAppServerRunning(): boolean | null {
+    const status = new CodexDaemon(new CodexHome(this.codexHome)).status();
+    return status === null ? null : status.running;
+  }
+}
+
+/** The grant one source becomes: its purpose, its audience and who refreshes it once the import settles. */
+interface IImportGrantPlan {
+  providerId: 'openai' | 'anthropic';
+  purpose: TStoredGrantPurpose;
+  audience: string;
+  /** The owner a settled import leaves behind. A projection never becomes `daemon`. */
+  settledOwner: IStoredAuthorityGrant['owner'];
+}
+
+const idHash = (...values: string[]): string =>
+  plugins.crypto.createHash('sha256').update(JSON.stringify(values)).digest('hex');
+
+const grantPlan = (record: Pick<ILegacySourceRecord, 'sourceKind' | 'providerId'>): IImportGrantPlan => {
+  if (record.sourceKind === 'claude_native') {
+    return { providerId: 'anthropic', purpose: 'claude_host_native', audience: 'claude-code-host',
+      settledOwner: 'claude_native' };
+  }
+  if (record.sourceKind === 'opencode_native') {
+    return { providerId: 'openai', purpose: 'opencode_native', audience: 'chatgpt',
+      settledOwner: 'legacy_native' };
+  }
+  if (record.sourceKind === 'codex_native') {
+    return { providerId: 'openai', purpose: 'openai_managed', audience: 'chatgpt',
+      settledOwner: 'legacy_native' };
+  }
+  return record.providerId === 'anthropic'
+    ? { providerId: 'anthropic', purpose: 'claude_host_native', audience: 'claude-code-host',
+      settledOwner: 'daemon' }
+    : { providerId: 'openai', purpose: 'openai_managed', audience: 'chatgpt', settledOwner: 'daemon' };
+};
+
+/** One grant per account, purpose and audience -- the same rule the device login uses. */
+const importGrantId = (accountId: string, plan: IImportGrantPlan): string =>
+  idHash('authswitch-grant-v1', accountId, plan.purpose, plan.audience);
+const importHandoffId = (sourceId: string): string => idHash('authswitch-import-handoff-v1', sourceId);
+
+/** The handoff phases past the pre-send marker: the exchange may already have consumed the refresh token. */
+const spentHandoffPhases: readonly IStoredAuthorityHandoff['phase'][] =
+  ['source_stopped', 'needs_reauth', 'aborted'];
+
+/**
+ * What a ledger status asks of the owner.
+ *
+ * An unsettled row is resumed by submitting the same source again -- unless its handoff got past the marker
+ * that says the sign-in exchange may have been sent, because a rotating refresh token is never sent twice.
+ * Reading the handoff here is what keeps this answer truthful: without it a source whose only remaining
+ * repair is a device sign-in would invite a submission that can only end in a quarantine.
+ */
+const importAction = (status: TAuthSwitchImportLedgerStatus,
+  handoff: IStoredAuthorityHandoff | null): TAuthSwitchImportAction => {
+  if (status === 'complete') return 'none';
+  if (status === 'quarantined') return 'device_login';
+  return handoff !== null && spentHandoffPhases.includes(handoff.phase) ? 'device_login' : 'resume';
+};
+
+/**
+ * A refusal the owner can act on. It never leaves a half-written import behind.
+ *
+ * One class hierarchy for the whole authority: this is the authority's refusal with the importer's code,
+ * which is what keeps the marker this route has published since 8.1.0 on the wire.
+ */
+export class AuthSwitchImportRefusal extends AuthSwitchRefusal {
+  constructor(instruction: string) {
+    super('import_refusal', instruction);
+  }
+}
+
+// The annotation on the binding, not only on the arrow, is what lets a refusal narrow the code after it.
+const refuse: (reason: string) => never = reason => { throw new AuthSwitchImportRefusal(reason); };
+
+const RUN_ORDER_REFUSAL = 'Importing needs the run-order acknowledgement: an imported source\'s legacy copy '
+  + 'holds a refresh token the provider has rotated away, and the everyday legacy commands would restore or '
+  + 'exercise exactly that copy. Import only once those commands run on the authority and the native '
+  + 'projections exist.';
+
+/** Strips the source location: a ledger row stores its hash, and no response may carry the path. */
+const publicSource = (record: ILegacySourceRecord,
+  ledgerStatus: IAuthSwitchImportSource['ledgerStatus']): IAuthSwitchImportSource => ({
+  id: record.id,
+  sourceKind: record.sourceKind,
+  sourcePathHash: record.sourcePathHash,
+  sourceDigest: record.sourceDigest,
+  treatment: record.treatment,
+  proof: record.proof,
+  accountId: record.accountId,
+  providerId: record.providerId,
+  email: record.email,
+  plan: record.plan,
+  label: record.label,
+  accessExpiresAt: record.accessExpiresAt,
+  enrollmentCount: record.enrollmentCount,
+  ledgerStatus,
+  problems: [...record.problems],
+});
+
+/**
+ * The one-time account import.
+ *
+ * It reads the legacy stores through the isolated migration readers and reports them against the authority's
+ * migration ledger. Nothing here is a runtime fallback: no ordinary authority operation reaches this class,
+ * and it never writes to a legacy store.
+ */
+export class AuthSwitchAuthorityImport {
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly homeDirectory: string;
+  private readonly now: () => number;
+  private readonly openAi: IAuthSwitchImportOpenAiOperations;
+  private readonly claudeStatus: IAuthSwitchImportClaudeStatus;
+  private readonly claudeTokens: IAuthSwitchImportClaudeTokens;
+  private readonly secrets: IAuthSwitchSecretCodec;
+  private readonly quiescence: IAuthSwitchImportQuiescence;
+
+  constructor(private readonly database: AuthSwitchAuthorityDatabase,
+    options: IAuthSwitchAuthorityImportOptions = {}) {
+    this.env = options.env ?? process.env;
+    this.homeDirectory = options.homeDirectory ?? plugins.os.homedir();
+    this.now = options.now ?? Date.now;
+    this.openAi = options.openAi ?? new plugins.flexAccounts.OpenAiProviderAdapter();
+    this.claudeStatus = options.claudeStatus ?? new ClaudeAccountStatus();
+    this.claudeTokens = options.claudeTokens ?? new ClaudeTokenRefresh();
+    this.secrets = options.secrets ?? new AuthSwitchTpmSecretCodec();
+    const locations = resolveLegacySourceLocations(this.env, this.homeDirectory);
+    this.quiescence = options.quiescence
+      ?? new AuthSwitchImportHostQuiescence(locations.authSwitchHome, locations.codexHome);
+  }
+
+  /** The credential-free report. Reads the legacy stores and the ledger; writes nothing. */
+  public async inventory(): Promise<IAuthSwitchImportInventory> {
+    const now = this.now();
+    const report = readLegacySources({ env: this.env, homeDirectory: this.homeDirectory, now });
+    const sources: IAuthSwitchImportSource[] = [];
+    for (const record of report.sources) {
+      const ledger = await this.database.readMigrationLedger(record.id);
+      const source = publicSource(record, ledger?.status ?? null);
+      if (ledger !== null && ledger.sourceDigest !== record.sourceDigest) {
+        // The source changed after its row was written. A later import must not treat the approved bytes and
+        // the current bytes as the same source; the ledger deliberately refuses to move that row.
+        source.problems.push('the source changed after its migration ledger row was written');
+      }
+      if (ledger?.status === 'complete') {
+        source.problems.push('this source is already imported; its legacy copy is retired');
+      }
+      sources.push(source);
+    }
+    return {
+      generatedAt: new Date(now).toISOString(),
+      environmentId: authSwitchEnvironmentId(this.env),
+      notice: [...INVENTORY_NOTICE],
+      sources,
+      problems: [...report.problems],
+    };
+  }
+
+  /**
+   * Where every source the authority knows about stands.
+   *
+   * Read from the migration ledger, the grants and the handoffs only: it opens no legacy store, so it stays
+   * truthful about what the authority decided even if a source has since been moved or deleted on the host.
+   * A source that was never submitted has no ledger row and belongs to the inventory, not here.
+   */
+  public async status(request: { after?: string; limit?: number } = {}): Promise<IAuthSwitchImportStatus> {
+    const page = await this.database.migrationLedgerPage(request.after ?? null, request.limit ?? 128);
+    const entries: IAuthSwitchImportStatusEntry[] = [];
+    for (const row of page.rows) {
+      const grant = row.grantId === null ? null : await this.database.readGrant(row.grantId);
+      const handoff = await this.database.readHandoff(importHandoffId(row.id));
+      entries.push({
+        sourceId: row.id, sourceKind: row.sourceKind, status: row.status,
+        accountId: row.accountId, loginId: row.grantId, owner: grant?.owner ?? null,
+        action: importAction(row.status, handoff), statusObservedAt: row.statusObservedAt,
+      });
+    }
+    return { generatedAt: this.stamp(), entries, nextCursor: page.nextCursor };
+  }
+
+  /**
+   * Imports one source.
+   *
+   * A source whose grant the authority takes over is verified by one real refresh, which rotates its token
+   * and is the point of no return; a source a native tool keeps refreshing is verified by a provider read
+   * that rotates nothing. Every step before the refresh is durable, and the marker that says "the exchange
+   * may have been sent" is the handoff's own `source_stopped` phase: a restart that finds it never replays
+   * the grant, it asks for a device sign-in instead.
+   */
+  public async submit(request: { submission: TAuthSwitchImportSubmission; callerQuiescent: true;
+    acknowledgeRunOrder: true }): Promise<IAuthSwitchImportResult> {
+    if (request.acknowledgeRunOrder !== true) refuse(RUN_ORDER_REFUSAL);
+    if (request.callerQuiescent !== true) {
+      refuse('Importing needs the caller\'s assertion that nothing it owns will use this source meanwhile: '
+        + 'a host that drives the legacy library inside its own process cannot be observed from here.');
+    }
+    const record = this.resolveSource(request.submission);
+    const plan = grantPlan(record);
+    this.assertQuiescent(record);
+    const ledger = await this.database.readMigrationLedger(record.id);
+    if (ledger !== null) {
+      if (ledger.sourceDigest !== record.sourceDigest) {
+        refuse('The source changed after its migration ledger row was written; it is a different source now.');
+      }
+      if (ledger.status === 'complete') refuse('This source is already imported.');
+      if (ledger.status === 'quarantined') {
+        refuse('This source is quarantined: its outcome could not be established, so it needs a device '
+          + 'sign-in for that account rather than another import.');
+      }
+    }
+    const accountId = record.accountId;
+    const subject = record.subject;
+    const workspaceId = record.workspaceId;
+    if (accountId === null || subject === null || workspaceId === null) {
+      refuse('The source carries no provider identity the authority can bind an account to.');
+    }
+    const grantId = importGrantId(accountId, plan);
+    if (ledger === null) await this.beginLedger(record);
+    const material = this.material(record, request.submission);
+    return record.treatment === 'project'
+      ? this.project(record, plan, { accountId, subject, workspaceId, grantId }, material)
+      : this.adopt(record, plan, { accountId, subject, workspaceId, grantId }, material);
+  }
+
+  /** The source a submission names, proven to be the one that was inventoried. */
+  private resolveSource(submission: TAuthSwitchImportSubmission): ILegacySourceRecord {
+    if (submission.kind === 'external') {
+      const identity = this.externalIdentity(submission.credential.idToken);
+      return {
+        id: idHash('authswitch-migration-v1', 'agl_flex', submission.sourcePathHash),
+        sourceKind: 'agl_flex', path: '', sourcePathHash: submission.sourcePathHash,
+        sourceDigest: submission.sourceDigest, treatment: 'import', proof: 'rotating_refresh',
+        accountId: identity.accountId, subject: identity.subject, workspaceId: identity.workspaceId,
+        providerId: 'openai', email: identity.email, plan: identity.plan, label: identity.email,
+        accessExpiresAt: null, enrollmentCount: null, problems: [],
+      };
+    }
+    const report = readLegacySources({ env: this.env, homeDirectory: this.homeDirectory, now: this.now() });
+    const record = report.sources.find(source => source.id === submission.sourceId);
+    if (!record) refuse('That source no longer exists on this host.');
+    if (record.sourceDigest !== submission.sourceDigest) {
+      refuse('The source changed after it was inventoried; review the inventory again before importing.');
+    }
+    if (record.problems.length) refuse(`The source cannot be imported: ${record.problems.join('; ')}.`);
+    if (record.treatment === 'refuse') refuse('This source is not a login the authority can hold.');
+    return record;
+  }
+
+  private externalIdentity(idToken: string): { accountId: string; subject: string; workspaceId: string;
+    email: string | null; plan: string | null } {
+    let info: ReturnType<typeof plugins.flexAuth.parseOpenAiChatGptTokenInfo>;
+    try { info = plugins.flexAuth.parseOpenAiChatGptTokenInfo(idToken); }
+    catch { return refuse('The submitted login carries no readable ChatGPT identity.'); }
+    if (!info.chatgptUserId || !info.chatgptAccountId) {
+      refuse('The submitted login omits a stable ChatGPT user or account identity.');
+    }
+    return {
+      accountId: idHash('authswitch-account-v1', 'openai', info.chatgptUserId, info.chatgptAccountId),
+      subject: info.chatgptUserId, workspaceId: info.chatgptAccountId,
+      email: info.email?.toLowerCase() ?? null, plan: info.chatgptPlanType ?? null,
+    };
+  }
+
+  /** Reads the credential the daemon will seal. Only an external submission brings its own. */
+  private material(record: ILegacySourceRecord,
+    submission: TAuthSwitchImportSubmission): TLegacySourceMaterial {
+    if (submission.kind === 'external') {
+      return { providerId: 'openai', credential: { kind: 'chatgptOAuth', providerId: 'openai',
+        accessToken: submission.credential.accessToken, refreshToken: submission.credential.refreshToken,
+        idToken: submission.credential.idToken } };
+    }
+    try { return readLegacySourceMaterial(record); }
+    catch (error) {
+      if (error instanceof LegacySourceChangedError) refuse(error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Refuses while anything that could refresh this source is running.
+   *
+   * Unknown counts as running: an import that guessed idle could rotate a token another owner is using.
+   */
+  private assertQuiescent(record: ILegacySourceRecord): void {
+    const watch = this.quiescence.watchHolderPid();
+    if (watch !== null) {
+      refuse(`An authswitch watch is running (pid ${watch}); it switches logins. Stop it and import again.`);
+    }
+    const binary: THarnessBinary | null = record.providerId === 'anthropic' ? 'claude'
+      : record.sourceKind === 'opencode_native' ? 'opencode' : null;
+    if (binary !== null) {
+      const pids = this.quiescence.runningHarnessPids(binary);
+      if (pids.length) {
+        refuse(`${binary} is running (pid ${pids.join(', ')}) and owns this login. Close it and import again.`);
+      }
+    }
+    if (record.sourceKind === 'codex_native'
+      || (record.sourceKind === 'authswitch_stash' && record.providerId === 'openai')) {
+      const running = this.quiescence.codexAppServerRunning();
+      if (running !== false) {
+        refuse(running === null
+          ? 'Codex could not be asked whether its app-server is running, and an unknown app-server counts '
+            + 'as running. Make Codex answerable and import again.'
+          : 'The Codex app-server is running and refreshes this login on its own schedule. '
+            + 'Stop it with `codex app-server daemon stop` and import again.');
+      }
+    }
+  }
+
+  private async beginLedger(record: ILegacySourceRecord): Promise<void> {
+    const updateId = plugins.crypto.randomUUID();
+    // Written before any provider call, so a crash always leaves the source named in the authority.
+    await this.database.changeMigrationLedger(updateId, record.id, () => ({
+      id: record.id, version: 1, sourceKind: record.sourceKind, sourcePathHash: record.sourcePathHash,
+      sourceDigest: record.sourceDigest, status: 'prepared', accountId: null, grantId: null,
+      revision: 1, statusObservedAt: this.stamp(), updateId,
+    }));
+  }
+
+  private async moveLedger(ledgerId: string, status: IStoredAuthorityMigrationLedger['status'],
+    accountId: string | null, grantId: string | null): Promise<IStoredAuthorityMigrationLedger> {
+    const updateId = plugins.crypto.randomUUID();
+    return this.database.changeMigrationLedger(updateId, ledgerId, current => {
+      if (!current) throw new Error('The migration ledger row disappeared during the import.');
+      return { ...current, status, accountId, grantId, revision: current.revision + 1,
+        statusObservedAt: this.stamp(), updateId };
+    });
+  }
+
+  private stamp(): string { return new Date(this.now()).toISOString(); }
+
+  private account(record: ILegacySourceRecord, identity: { accountId: string; subject: string;
+    workspaceId: string }, plan: IImportGrantPlan, existing: IStoredAuthorityAccount | null,
+  grantId: string, updateId: string): IStoredAuthorityAccount {
+    const label = record.label ?? record.email ?? `${plan.providerId} ${identity.workspaceId}`;
+    return existing
+      ? { ...existing, label: existing.label || label, email: record.email, plan: record.plan,
+        removed: false, revision: existing.revision + 1, statusObservedAt: this.stamp(), updateId }
+      : { id: identity.accountId, providerId: plan.providerId, issuer: plan.providerId,
+        subject: identity.subject, workspaceId: identity.workspaceId, label, email: record.email,
+        plan: record.plan, primaryGrantId: grantId, removed: false, revision: 1,
+        statusObservedAt: this.stamp(), updateId };
+  }
+
+  /** Writes the account and its grant, choosing the primary or the secondary transaction by identity. */
+  private async putGrant(identity: { accountId: string; subject: string; workspaceId: string },
+    record: ILegacySourceRecord, plan: IImportGrantPlan, grantId: string,
+    make: (existing: IStoredAuthorityGrant | null, updateId: string) => IStoredAuthorityGrant): Promise<void> {
+    const existingAccount = await this.database.readAccount(identity.accountId);
+    const updateId = plugins.crypto.randomUUID();
+    if (existingAccount && existingAccount.primaryGrantId !== grantId) {
+      await this.database.changeSecondaryGrant(updateId, identity.accountId, grantId,
+        grant => make(grant, updateId));
+      return;
+    }
+    await this.database.changeAccountAndGrant(updateId, identity.accountId, grantId, (account, grant) => ({
+      account: this.account(record, identity, plan, account, grantId, updateId),
+      grant: make(grant, updateId),
+    }));
+  }
+
+  private baseGrant(identity: { accountId: string }, plan: IImportGrantPlan, grantId: string,
+    existing: IStoredAuthorityGrant | null, updateId: string,
+    overrides: Partial<IStoredAuthorityGrant>): IStoredAuthorityGrant {
+    return {
+      id: grantId, accountId: identity.accountId, providerId: plan.providerId, purpose: plan.purpose,
+      audience: plan.audience, state: 'legacy_native_pending', owner: 'legacy_native',
+      grantGeneration: existing ? existing.grantGeneration : 1,
+      authorizationGeneration: existing ? existing.authorizationGeneration : 1,
+      revision: existing ? existing.revision + 1 : 1, ciphertext: null, accessExpiresAt: null,
+      attemptId: null, retryAt: null, retryCount: 0, problem: 'native_owner',
+      statusObservedAt: this.stamp(), updateId, ...overrides,
+    };
+  }
+
+  /** Refuses a source whose grant another owner already holds, in either direction. */
+  private assertOwnable(existing: IStoredAuthorityGrant | null, plan: IImportGrantPlan): void {
+    if (!existing) return;
+    if (existing.owner === plan.settledOwner || existing.owner === 'none') return;
+    refuse(existing.owner === 'daemon'
+      ? 'The authority already owns this login; a native store cannot take it over without a handoff.'
+      : 'A native store already owns this login. Its account is registered from that source; select it '
+        + 'there rather than importing a second copy.');
+  }
+
+  /**
+   * A projected source: the account is registered, the grant stays with its native owner, and the proof is a
+   * provider read that rotates nothing. No refresh is ever sent here.
+   */
+  private async project(record: ILegacySourceRecord, plan: IImportGrantPlan,
+    identity: { accountId: string; subject: string; workspaceId: string; grantId: string },
+    material: TLegacySourceMaterial): Promise<IAuthSwitchImportResult> {
+    this.assertOwnable(await this.database.readGrant(identity.grantId), plan);
+    await this.putGrant(identity, record, plan, identity.grantId, (existing, updateId) =>
+      this.baseGrant(identity, plan, identity.grantId, existing, updateId,
+        { state: 'native', owner: plan.settledOwner }));
+    try { await this.proveWithoutRotation(record, identity, material); }
+    catch (error) {
+      // Not a quarantine: no rotating token was sent here, so nothing was consumed and nothing is lost. The
+      // account stays registered with its native owner, unproven, and the same source is submitted again
+      // once that native tool has refreshed its own store -- which is exactly what the refusal asks for.
+      await this.moveLedger(record.id, 'pending_native_owner', identity.accountId, identity.grantId);
+      throw error;
+    }
+    await this.moveLedger(record.id, 'verified', identity.accountId, identity.grantId);
+    if (record.sourceKind === 'claude_native') await this.adoptClaudeHome(record, identity);
+    await this.moveLedger(record.id, 'complete', identity.accountId, identity.grantId);
+    return this.result(record, 'complete', identity, []);
+  }
+
+  /**
+   * Adopts the native Claude home this source is, so the daemon may serve `claude.*` for it.
+   *
+   * The verified receipt is the only thing that may adopt a home, and the source id it was earned with is
+   * the home id, so nothing else has to be trusted here. Re-submitting the same source returns the same
+   * home record rather than writing a second one.
+   */
+  private async adoptClaudeHome(record: ILegacySourceRecord,
+    identity: { accountId: string; subject: string; workspaceId: string; grantId: string }): Promise<void> {
+    await this.database.registerClaudeHomeFromReceipt({
+      homeId: record.sourcePathHash, accountId: identity.accountId, grantId: identity.grantId,
+      receiptId: record.id, sourceDigest: record.sourceDigest,
+      accountUuid: identity.subject, organizationUuid: identity.workspaceId,
+      updateId: plugins.crypto.randomUUID(), now: this.stamp(),
+    });
+  }
+
+  /** The non-rotating proof: the stored access token is asked about itself and must name this account. */
+  private async proveWithoutRotation(record: ILegacySourceRecord,
+    identity: { accountId: string; subject: string; workspaceId: string },
+    material: TLegacySourceMaterial): Promise<void> {
+    if (material.providerId === 'openai') {
+      const result = await this.openAi.getAccountRateLimits({ kind: 'chatgptAccess',
+        providerId: 'openai', accessToken: material.credential.accessToken,
+        accountId: identity.workspaceId, isFedrampAccount: false });
+      if (!result.success) {
+        refuse(`The stored access token could not be proven live (${result.errorCode}); let the native tool `
+          + 'refresh its own store, then import again.');
+      }
+      // The claims of the very token that answered must still name this account.
+      const claims = plugins.flexAuth.parseOpenAiChatGptTokenInfo(material.credential.accessToken);
+      if (claims.chatgptAccountId !== identity.workspaceId) {
+        refuse('The stored access token belongs to another ChatGPT account.');
+      }
+      return;
+    }
+    const oauth = material.login.claudeAiOauth;
+    const accessToken = typeof oauth.accessToken === 'string' ? oauth.accessToken : '';
+    const scopes = Array.isArray(oauth.scopes)
+      ? oauth.scopes.filter((scope): scope is string => typeof scope === 'string') : [];
+    const read = await this.claudeStatus.readDetailed({ accessToken, scopes,
+      identity: { accountUuid: identity.subject, organizationUuid: identity.workspaceId },
+      ...(record.plan === null ? {} : { plan: record.plan }) });
+    if (read.profile === 'mismatch') refuse('The native Claude login belongs to another account.');
+    if (read.profile !== 'verified') {
+      refuse(`The native Claude login could not be proven live (profile ${read.profile}); let Claude Code `
+        + 'refresh its own store, then import again.');
+    }
+  }
+
+  /**
+   * A source the authority takes over.
+   *
+   * The handoff row is the durable record of how far this went. `source_stopped` is written before the
+   * refresh is sent, so a lost answer is always visible afterwards and is never retried.
+   */
+  private async adopt(record: ILegacySourceRecord, plan: IImportGrantPlan,
+    identity: { accountId: string; subject: string; workspaceId: string; grantId: string },
+    material: TLegacySourceMaterial): Promise<IAuthSwitchImportResult> {
+    const handoffId = importHandoffId(record.id);
+    let handoff = await this.database.readHandoff(handoffId);
+    if (handoff === null) {
+      this.assertOwnable(await this.database.readGrant(identity.grantId), plan);
+      const ciphertext = await this.seal(identity.grantId, material);
+      await this.putGrant(identity, record, plan, identity.grantId, (existing, updateId) =>
+        this.baseGrant(identity, plan, identity.grantId, existing, updateId, { ciphertext }));
+      handoff = await this.moveHandoff(handoffId, record, identity, 'prepared',
+        grant => ({ ...grant, state: 'legacy_native_pending' }));
+    }
+    if (handoff.phase === 'needs_reauth' || handoff.phase === 'aborted') {
+      await this.quarantine(record, identity);
+      refuse('A previous import of this source did not settle; sign in to that account again instead.');
+    }
+    if (handoff.phase === 'prepared') {
+      // The durable marker. Everything after it may have reached the provider.
+      handoff = await this.moveHandoff(handoffId, record, identity, 'source_stopped',
+        grant => ({ ...grant, state: 'legacy_native_pending' }));
+      const rotated = await this.rotate(material);
+      if (rotated === null) {
+        await this.failHandoff(handoffId, record, identity);
+        await this.quarantine(record, identity);
+        refuse('The sign-in service did not give a usable answer, and a rotating refresh token is never '
+          + 'sent twice. Sign in to that account again to finish this import.');
+      }
+      const ciphertext = await this.seal(identity.grantId, rotated.material);
+      handoff = await this.moveHandoff(handoffId, record, identity, 'target_written', grant => ({
+        ...grant, ciphertext, accessExpiresAt: rotated.accessExpiresAt,
+        grantGeneration: grant.grantGeneration + 1, state: 'legacy_native_pending',
+      }));
+    }
+    if (handoff.phase === 'source_stopped') {
+      // Reached only by a restart: the exchange may have been sent, so the grant is never replayed.
+      await this.failHandoff(handoffId, record, identity);
+      await this.quarantine(record, identity);
+      refuse('This import was interrupted while its sign-in was in flight. A rotating refresh token is '
+        + 'never sent twice; sign in to that account again.');
+    }
+    if (handoff.phase === 'target_written') {
+      handoff = await this.moveHandoff(handoffId, record, identity, 'verified',
+        grant => ({ ...grant, state: 'legacy_native_pending' }));
+    }
+    if (handoff.phase === 'verified') {
+      await this.moveHandoff(handoffId, record, identity, 'committed', grant => ({
+        ...grant, state: 'ready', owner: 'daemon', problem: 'none',
+        authorizationGeneration: grant.authorizationGeneration + 1,
+      }));
+    }
+    const ledger = await this.database.readMigrationLedger(record.id);
+    if (ledger?.status !== 'verified' && ledger?.status !== 'complete') {
+      await this.moveLedger(record.id, 'verified', identity.accountId, identity.grantId);
+    }
+    await this.storeEnrollments(record, identity);
+    if ((await this.database.readMigrationLedger(record.id))?.status !== 'complete') {
+      await this.moveLedger(record.id, 'complete', identity.accountId, identity.grantId);
+    }
+    return this.result(record, 'complete', identity, []);
+  }
+
+  private async moveHandoff(handoffId: string, record: ILegacySourceRecord,
+    identity: { accountId: string; grantId: string }, phase: IStoredAuthorityHandoff['phase'],
+    grantChange: (grant: IStoredAuthorityGrant) => IStoredAuthorityGrant): Promise<IStoredAuthorityHandoff> {
+    const updateId = plugins.crypto.randomUUID();
+    const result = await this.database.changeHandoffAndGrant(updateId, handoffId, identity.grantId,
+      (current, grant) => ({
+        handoff: {
+          id: handoffId, accountId: identity.accountId, grantId: identity.grantId,
+          nativeHomeId: record.sourcePathHash, direction: 'to_daemon', phase,
+          operationId: current?.operationId ?? plugins.crypto.randomUUID(),
+          sourceDigest: record.sourceDigest,
+          verifiedSourceDigest: ['verified', 'committed'].includes(phase) ? record.sourceDigest
+            : current?.verifiedSourceDigest ?? null,
+          revision: current ? current.revision + 1 : 1, statusObservedAt: this.stamp(), updateId,
+        },
+        grant: { ...grantChange(grant), revision: grant.revision + 1,
+          statusObservedAt: this.stamp(), updateId },
+      }));
+    return result.handoff;
+  }
+
+  private async failHandoff(handoffId: string, record: ILegacySourceRecord,
+    identity: { accountId: string; grantId: string }): Promise<void> {
+    await this.moveHandoff(handoffId, record, identity, 'needs_reauth', grant => ({
+      ...grant, state: 'needs_reauth', owner: 'none', ciphertext: null, accessExpiresAt: null,
+      problem: 'exchange_uncertain',
+    }));
+  }
+
+  /**
+   * Marks a source whose sign-in exchange may already have been consumed. That is its only meaning, so the
+   * refusal a later submission gets needs no further reason: the repair is always a device sign-in.
+   */
+  private async quarantine(record: ILegacySourceRecord,
+    identity: { accountId: string; grantId: string }): Promise<void> {
+    const ledger = await this.database.readMigrationLedger(record.id);
+    if (!ledger || ledger.status === 'complete' || ledger.status === 'quarantined') return;
+    // A quarantined row keeps the account and grant it names, so the owner knows which account to sign in to.
+    await this.moveLedger(record.id, 'quarantined', identity.accountId, identity.grantId);
+  }
+
+  /**
+   * The one rotating refresh. `null` means the outcome is unknown and the grant must never be replayed.
+   *
+   * A thrown error is the same answer as a failed one: once the request left this process, whether the
+   * provider consumed the token is unknowable, so both end in a device sign-in rather than a retry.
+   */
+  private async rotate(material: TLegacySourceMaterial):
+  Promise<{ material: TLegacySourceMaterial; accessExpiresAt: string | null } | null> {
+    try { return await this.rotateOnce(material); }
+    catch { return null; }
+  }
+
+  private async rotateOnce(material: TLegacySourceMaterial):
+  Promise<{ material: TLegacySourceMaterial; accessExpiresAt: string | null } | null> {
+    if (material.providerId === 'openai') {
+      const result = await this.openAi.refreshCredential(material.credential);
+      if (!result.success) return null;
+      let accessExpiresAt: string | null = null;
+      try { accessExpiresAt = plugins.flexAuth.parseOpenAiChatGptTokenInfo(result.credential.accessToken).expiresAt ?? null; }
+      catch { accessExpiresAt = null; }
+      return { material: { providerId: 'openai', credential: { kind: 'chatgptOAuth', providerId: 'openai',
+        accessToken: result.credential.accessToken, refreshToken: result.credential.refreshToken,
+        idToken: result.credential.idToken } }, accessExpiresAt };
+    }
+    const outcome = await this.claudeTokens.refreshForAuthority(material.login.claudeAiOauth);
+    if (!outcome.success) return null;
+    return {
+      material: { providerId: 'anthropic', login: { ...material.login,
+        claudeAiOauth: { ...material.login.claudeAiOauth, accessToken: outcome.tokens.accessToken,
+          refreshToken: outcome.tokens.refreshToken, expiresAt: outcome.tokens.expiresAt,
+          scopes: outcome.tokens.scopes } } },
+      accessExpiresAt: new Date(outcome.tokens.expiresAt).toISOString(),
+    };
+  }
+
+  private async seal(grantId: string, material: TLegacySourceMaterial): Promise<string> {
+    const payload = material.providerId === 'openai' ? material.credential : material.login;
+    const bytes = Buffer.from(JSON.stringify(payload), 'utf8');
+    try { return await this.secrets.seal(grantId, bytes); }
+    finally { bytes.fill(0); }
+  }
+
+  /** Codex remote-control enrollments travel with the credential; losing them is losing a pairing. */
+  private async storeEnrollments(record: ILegacySourceRecord,
+    identity: { accountId: string }): Promise<void> {
+    if (record.sourceKind !== 'authswitch_stash' || !record.enrollmentCount) return;
+    const rows = readLegacySourceEnrollments(record);
+    if (!rows.length) return;
+    const enrollmentId = idHash('authswitch-enrollment-v1', identity.accountId);
+    const updateId = plugins.crypto.randomUUID();
+    const bytes = Buffer.from(JSON.stringify(rows), 'utf8');
+    let ciphertext: string;
+    try { ciphertext = await this.secrets.seal(identity.accountId, bytes); }
+    finally { bytes.fill(0); }
+    await this.database.changeEnrollment(updateId, enrollmentId, identity.accountId, current => ({
+      id: enrollmentId, accountId: identity.accountId, ciphertext,
+      revision: current ? current.revision + 1 : 1, updateId,
+    }));
+  }
+
+  private result(record: ILegacySourceRecord, status: IAuthSwitchImportResult['status'],
+    identity: { accountId: string; grantId: string }, problems: string[]): IAuthSwitchImportResult {
+    return { sourceId: record.id, sourceKind: record.sourceKind, treatment: record.treatment, status,
+      accountId: identity.accountId, loginId: identity.grantId, problems };
+  }
+}