@modelprofile.com/authswitch 8.0.0 → 8.1.0

package/ts/authority-import-contract.ts

@@ -0,0 +1,216 @@
+import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
+
+/**
+ * The one-time account import: reading the legacy stores that existed before the authority, and the
+ * credential-free report an owner reads before anything is imported.
+ *
+ * Importing a refresh token is a transfer of ownership, not a copy. The provider rotates a refresh token on
+ * use, so the moment one holder refreshes, every other copy of that token is dead. This contract therefore
+ * separates the classes of legacy source by who refreshes them after the import, and names the proof each
+ * class can offer without rotating anything.
+ */
+
+/** Mirrors the migration ledger's source kinds, which are the only sources a ledger row can describe. */
+export type TAuthSwitchImportSourceKind = 'authswitch_stash' | 'authswitch_backup' | 'agl_flex'
+  | 'codex_native' | 'opencode_native' | 'claude_native';
+
+/**
+ * The ledger statuses a source can already hold when an inventory runs.
+ *
+ * - `prepared`: the source is named in the authority and nothing has been sent for it yet.
+ * - `pending_native_owner`: the account is registered and its native tool keeps the refresher, but the
+ *   store could not be proven live. Nothing rotating was ever sent, so it is proven by submitting the
+ *   source again once that tool has refreshed its own store.
+ * - `verified` and `complete`: the import settled; `complete` is the tombstone for that source.
+ * - `quarantined`: a rotating refresh may already have been consumed for this source, so it is never
+ *   submitted again and its account is repaired by a device sign-in.
+ */
+export type TAuthSwitchImportLedgerStatus = 'pending_native_owner' | 'prepared' | 'verified' | 'complete'
+  | 'quarantined';
+
+/**
+ * What the ownership rule allows for a source.
+ *
+ * - `import`: the authority becomes the single refresher. Nothing else owns this copy, so taking it over
+ *   strands no other holder.
+ * - `project`: a native tool keeps refreshing its own store; the authority registers the account and holds
+ *   the grant as a projection it must never refresh. Two refreshers on one refresh token is the failure this
+ *   avoids.
+ * - `refuse`: the source cannot become an authority grant at all, and the owner signs in again instead.
+ */
+export type TAuthSwitchImportTreatment = 'import' | 'project' | 'refuse';
+
+/**
+ * What can make this source's ledger row `verified`.
+ *
+ * - `rotating_refresh`: one real refresh through the authority. It proves the refresh token was live and
+ *   makes the authority its holder in the same step -- and it is the point of no return, because the legacy
+ *   copy is stale from that moment.
+ * - `access_token_read`: a provider read with the stored access token alone, matched against the identity
+ *   derived locally from the same source bytes. It rotates nothing, so a native refresher keeps its grant.
+ *   It is available only while that access token is still valid.
+ * - `none`: no proof exists for this source; it cannot be verified and cannot be imported.
+ */
+export type TAuthSwitchImportProof = 'rotating_refresh' | 'access_token_read' | 'none';
+
+/**
+ * One legacy source as the inventory found it. Credential-free by construction: identity claims and a digest
+ * of the source bytes, never a token, a token digest, or the source path.
+ */
+export interface IAuthSwitchImportSource {
+  /** The migration ledger row this source would use. Derived from its kind and path, so it is stable. */
+  id: string;
+  sourceKind: TAuthSwitchImportSourceKind;
+  /** The source location as a hash. The ledger never stores a path and this DTO never exposes one. */
+  sourcePathHash: string;
+  /** Binds a later import to exactly these bytes. Changes whenever the source changes. */
+  sourceDigest: string;
+  treatment: TAuthSwitchImportTreatment;
+  proof: TAuthSwitchImportProof;
+  /** The authority account this source resolves to, derived locally from its identity claims. */
+  accountId: string | null;
+  providerId: string | null;
+  email: string | null;
+  plan: string | null;
+  label: string | null;
+  /** Expiry claim of the stored access token. It decides whether a non-rotating proof is available now. */
+  accessExpiresAt: string | null;
+  /** Remote-control enrollments carried by this source; `null` when they could not be counted. */
+  enrollmentCount: number | null;
+  /** The ledger row for this source, when one already exists. */
+  ledgerStatus: TAuthSwitchImportLedgerStatus | null;
+  /** Why this source cannot be submitted as it stands. An empty list means it can. */
+  problems: string[];
+}
+
+/** The complete credential-free report. `notice` is what the owner must know before importing anything. */
+export interface IAuthSwitchImportInventory {
+  generatedAt: string;
+  /** Identifies the credential locations this inventory read, as `authSwitchEnvironmentId` computes them. */
+  environmentId: string;
+  notice: string[];
+  sources: IAuthSwitchImportSource[];
+  /** Locations that could not be read at all, so an empty result never looks like an empty store. */
+  problems: string[];
+}
+
+/** Management-only. Reads legacy stores and the ledger; changes nothing, and carries no credential. */
+export interface IReq_AuthSwitchImportInventory extends ITypedRequest {
+  method: 'authswitch.authority.import.inventory';
+  request: Record<string, never>;
+  response: { inventory: IAuthSwitchImportInventory };
+}
+
+/** A ChatGPT login held by a store outside this package, submitted by the backend that owns its format. */
+export interface IAuthSwitchImportOpenAiCredential {
+  providerId: 'openai';
+  accessToken: string;
+  refreshToken: string;
+  idToken: string;
+}
+
+/**
+ * What is being imported.
+ *
+ * A source this daemon can read itself is named only by its id: the daemon re-runs its readers, resolves the
+ * location from the hash and re-checks the digest, so no credential crosses the socket and no caller can
+ * substitute bytes the owner never approved. Only a store this package cannot read -- AGL's sealed Flex
+ * records -- submits material, and that is the whole reason submit lives on the backend-only runtime socket.
+ */
+export type TAuthSwitchImportSubmission =
+  | { kind: 'local'; sourceId: string; sourceDigest: string }
+  | { kind: 'external'; sourceKind: 'agl_flex'; sourcePathHash: string; sourceDigest: string;
+      credential: IAuthSwitchImportOpenAiCredential };
+
+/** The outcome of one source. `quarantined` always names what to do instead, never a silent failure. */
+export interface IAuthSwitchImportResult {
+  sourceId: string;
+  sourceKind: TAuthSwitchImportSourceKind;
+  treatment: TAuthSwitchImportTreatment;
+  status: TAuthSwitchImportLedgerStatus;
+  accountId: string | null;
+  loginId: string | null;
+  problems: string[];
+}
+
+/**
+ * What the owner does next with one source.
+ *
+ * - `none`: the import settled; nothing is outstanding.
+ * - `resume`: submit the same source again. Nothing rotating has been sent for this source, so a second
+ *   attempt is safe: an interrupted adopt continues from its durable record, and a native store that could
+ *   not be proven live is proven the moment its own tool has refreshed it.
+ * - `device_login`: this source is finished as a source. Its account needs a fresh device sign-in, because a
+ *   rotating refresh token whose outcome is unknown is never sent a second time.
+ */
+export type TAuthSwitchImportAction = 'none' | 'resume' | 'device_login';
+
+/**
+ * Marks an error answer whose text is an instruction for the owner, not a report of a fault.
+ *
+ * The daemon sets it on the refusals the importer authors and on nothing else. Every other failure answers
+ * with the transport's own sanitised text, which a caller must never present as if it said what to do next --
+ * for a submit in particular, an unmarked failure means the outcome is unknown and the source must be read
+ * with `authswitch.authority.import.status` rather than submitted again.
+ */
+export const authSwitchImportRefusalReason = 'authswitch_import_refusal';
+
+/** True when the daemon answered with an importer refusal, so `error.message` is the instruction to show. */
+export const isAuthSwitchImportRefusal = (error: unknown): boolean => {
+  if (typeof error !== 'object' || error === null || !('errorData' in error)) return false;
+  const data = error.errorData;
+  return typeof data === 'object' && data !== null && 'reason' in data
+    && data.reason === authSwitchImportRefusalReason;
+};
+
+/**
+ * Where one source stands, read from the migration ledger, the grant it produced and its handoff.
+ *
+ * Only sources the authority has been told about appear here. A source that was never submitted has no
+ * ledger row; `authority import inventory` is the read that looks at the host and lists those.
+ */
+export interface IAuthSwitchImportStatusEntry {
+  sourceId: string;
+  sourceKind: TAuthSwitchImportSourceKind;
+  status: TAuthSwitchImportLedgerStatus;
+  accountId: string | null;
+  loginId: string | null;
+  /**
+   * Who refreshes that login now, or `null` when the ledger row names no grant yet. `none` is the absence of
+   * a refresher: the grant needs a device sign-in before anything can use it again.
+   */
+  owner: 'daemon' | 'claude_native' | 'legacy_native' | 'none' | null;
+  action: TAuthSwitchImportAction;
+  statusObservedAt: string;
+}
+
+export interface IAuthSwitchImportStatus {
+  generatedAt: string;
+  entries: IAuthSwitchImportStatusEntry[];
+  nextCursor: string | null;
+}
+
+/** Management-only. Reads durable records only; it opens no legacy store and carries no credential. */
+export interface IReq_AuthSwitchImportStatus extends ITypedRequest {
+  method: 'authswitch.authority.import.status';
+  request: { after?: string; limit?: number };
+  response: { status: IAuthSwitchImportStatus };
+}
+
+/**
+ * Backend-only. One source, one ownership decision.
+ *
+ * Both flags are required and both must be `true`. `callerQuiescent` is the caller's own assertion, because
+ * this daemon can observe a watch, a native process and Codex's app-server but cannot observe a host that
+ * uses the legacy library in its own process. `acknowledgeRunOrder` is the owner's acknowledgement that an
+ * imported source's legacy copy is dead and that the everyday commands must already run on the authority.
+ */
+export interface IReq_AuthSwitchImportSubmit extends ITypedRequest {
+  method: 'authswitch.authority.import.submit';
+  request: {
+    submission: TAuthSwitchImportSubmission;
+    callerQuiescent: true;
+    acknowledgeRunOrder: true;
+  };
+  response: { result: IAuthSwitchImportResult };
+}

package/ts/classes.authoritycli.ts

@@ -1,5 +1,8 @@
 import type { IAuthSwitchDoctorPage, IAuthSwitchOperation, IAuthSwitchPreuseOperation,
   IAuthSwitchSnapshot, IReq_AuthSwitchDoctor, IReq_AuthSwitchStartPreuse } from './authority-contract.js';
+import { isAuthSwitchImportRefusal } from './authority-import-contract.js';
+import type { IAuthSwitchImportInventory, IAuthSwitchImportResult, IAuthSwitchImportStatus,
+  IReq_AuthSwitchImportStatus, TAuthSwitchImportAction } from './authority-import-contract.js';
 import { AuthSwitchClient } from './classes.authorityclient.js';
 import { resolveAuthSwitchAuthorityPaths } from './classes.authorityservice.js';
 import { defaultPreusePrompt, validatePreuseOptions } from './preuse.js';
@@ -9,6 +12,9 @@ import * as plugins from './plugins.js';
 export interface IAuthSwitchAuthorityCliClient {
   snapshotAll(): Promise<IAuthSwitchSnapshot>;
   doctorPage(request: IReq_AuthSwitchDoctor['request']): Promise<IAuthSwitchDoctorPage>;
+  importInventory(): Promise<IAuthSwitchImportInventory>;
+  importStatus(request: IReq_AuthSwitchImportStatus['request']): Promise<IAuthSwitchImportStatus>;
+  submitImport(sourceId: string, sourceDigest: string): Promise<IAuthSwitchImportResult>;
   beginAddOpenAi(operationId: string): Promise<IAuthSwitchOperation>;
   beginReauthOpenAi(operationId: string, accountId: string, loginId: string,
     purpose: 'openai_managed'): Promise<IAuthSwitchOperation>;
@@ -33,6 +39,9 @@ export interface IAuthSwitchAuthorityCliOptions {
 type TAuthorityCliCommand =
   | { kind: 'list'; json: boolean }
   | { kind: 'doctor'; json: boolean }
+  | { kind: 'importInventory'; json: boolean }
+  | { kind: 'importStatus'; json: boolean }
+  | { kind: 'importSubmit'; sourceId: string; sourceDigest: string; json: boolean }
   | { kind: 'add'; json: boolean }
   | { kind: 'reauth'; accountId: string; loginId: string; json: boolean }
   | { kind: 'get'; operationId: string; json: boolean }
@@ -51,9 +60,11 @@ class AuthorityCliFailure extends Error {
   }
 }
 
-const usage = 'Usage: authswitch account list [--json] | authswitch account add openai [--json] | authswitch account reauth <account-id> <login-id> [--json] | authswitch account operation get|cancel|resume <operation-id> [--json] | authswitch account preuse <account-id> <login-id>|--all [--prompt <text>] [--model <id>] [--json] | authswitch account preuse operation get|cancel|resume <operation-id> [--json] | authswitch authority doctor [--json]';
+const usage = 'Usage: authswitch account list [--json] | authswitch account add openai [--json] | authswitch account reauth <account-id> <login-id> [--json] | authswitch account operation get|cancel|resume <operation-id> [--json] | authswitch account preuse <account-id> <login-id>|--all [--prompt <text>] [--model <id>] [--json] | authswitch account preuse operation get|cancel|resume <operation-id> [--json] | authswitch authority doctor [--json] | authswitch authority import inventory [--json] | authswitch authority import status [--json] | authswitch authority import submit <source-id> --digest <source-digest> [--json]';
 const safe = (value: string | number | null): string => plainText(value === null ? 'none' : String(value));
 const isId = (value: string | undefined): value is string => Boolean(value && !value.startsWith('-'));
+const isHash = (value: string | undefined): value is string =>
+  typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
 
 const parsePreuse = (argv: readonly string[]): TAuthorityCliCommand | null => {
   if (argv[2] === 'operation') {
@@ -109,6 +120,21 @@ const parse = (argv: readonly string[]): TAuthorityCliCommand | null => {
     && (argv.length === 2 || (argv.length === 3 && argv[2] === '--json'))) {
     return { kind: 'doctor', json: argv[2] === '--json' };
   }
+  if (argv[0] === 'authority' && argv[1] === 'import' && argv[2] === 'inventory'
+    && (argv.length === 3 || (argv.length === 4 && argv[3] === '--json'))) {
+    return { kind: 'importInventory', json: argv[3] === '--json' };
+  }
+  if (argv[0] === 'authority' && argv[1] === 'import' && argv[2] === 'status'
+    && (argv.length === 3 || (argv.length === 4 && argv[3] === '--json'))) {
+    return { kind: 'importStatus', json: argv[3] === '--json' };
+  }
+  if (argv[0] === 'authority' && argv[1] === 'import' && argv[2] === 'submit') {
+    // The digest the owner read in the inventory is part of the command: the daemon refuses a source whose
+    // bytes have changed since, so approving one source can never import a different one.
+    if (!isHash(argv[3]) || argv[4] !== '--digest' || !isHash(argv[5])
+      || (argv.length !== 6 && (argv.length !== 7 || argv[6] !== '--json'))) return null;
+    return { kind: 'importSubmit', sourceId: argv[3], sourceDigest: argv[5], json: argv[6] === '--json' };
+  }
   if (argv[0] === 'account' && argv[1] === 'add' && argv[2] === 'openai'
     && (argv.length === 3 || (argv.length === 4 && argv[3] === '--json'))) {
     return { kind: 'add', json: argv[3] === '--json' };
@@ -143,6 +169,18 @@ class ScopedAuthorityCliClient implements IAuthSwitchAuthorityCliClient {
     return this.client.doctorPage(request, this.controller.signal);
   }
 
+  public importInventory(): Promise<IAuthSwitchImportInventory> {
+    return this.client.importInventory(this.controller.signal);
+  }
+
+  public importStatus(request: IReq_AuthSwitchImportStatus['request']): Promise<IAuthSwitchImportStatus> {
+    return this.client.importStatus(request, this.controller.signal);
+  }
+
+  public submitImport(sourceId: string, sourceDigest: string): Promise<IAuthSwitchImportResult> {
+    return this.client.submitImport({ kind: 'local', sourceId, sourceDigest }, this.controller.signal);
+  }
+
   public beginAddOpenAi(operationId: string): Promise<IAuthSwitchOperation> {
     return this.client.beginAddOpenAi(operationId, this.controller.signal);
   }
@@ -201,6 +239,91 @@ const renderList = (snapshot: IAuthSwitchSnapshot): string => {
   return lines.join('\n') + '\n';
 };
 
+/**
+ * The legacy-source report.
+ *
+ * The notice comes first and is never abbreviated: an import is a one-way transfer of ownership, and this is
+ * the only place an owner reads what that costs before approving it.
+ */
+const renderInventory = (inventory: IAuthSwitchImportInventory): string => {
+  const lines = [`Legacy account sources — generated ${safe(inventory.generatedAt)}, environment ${safe(inventory.environmentId)}`,
+    'Before you import:'];
+  for (const notice of inventory.notice) lines.push(`  - ${safe(notice)}`);
+  lines.push('');
+  if (inventory.sources.length === 0) lines.push('No legacy credential source was found.');
+  for (const source of inventory.sources) {
+    lines.push(`${safe(source.label ?? source.email ?? source.sourceKind)} [${safe(source.providerId)}]`,
+      `  source ${safe(source.id)}; kind ${safe(source.sourceKind)}; treatment ${safe(source.treatment)}; proof ${safe(source.proof)}`,
+      `  account ${safe(source.accountId)}; plan ${safe(source.plan)}; access token expires ${safe(source.accessExpiresAt)}`,
+      `  enrollments ${source.enrollmentCount === null ? 'unknown' : source.enrollmentCount}; ledger ${safe(source.ledgerStatus)}; digest ${safe(source.sourceDigest)}`);
+    for (const problem of source.problems) lines.push(`  problem: ${safe(problem)}`);
+  }
+  if (inventory.problems.length) {
+    lines.push('', 'Locations that could not be read:');
+    for (const problem of inventory.problems) lines.push(`  - ${safe(problem)}`);
+  }
+  return lines.join('\n') + '\n';
+};
+
+/**
+ * What the owner does next with a source, in words rather than a contract value. An action this version does
+ * not recognise is read as the careful one: never invite a second submission on a guess.
+ */
+const actionText = (action: TAuthSwitchImportAction): string =>
+  action === 'none' ? 'nothing to do'
+    : action === 'resume' ? 'submit this source again to continue where it stopped'
+      : 'sign in to this account again; this source cannot be imported a second time';
+
+/**
+ * Every page of the ledger, as one report.
+ *
+ * The owner acts on this read, so it must not stop at a page boundary and leave a quarantined source
+ * unmentioned. A cursor that does not advance is a broken answer rather than a reason to keep asking.
+ */
+const collectImportStatus = async (client: IAuthSwitchAuthorityCliClient): Promise<IAuthSwitchImportStatus> => {
+  const first = await client.importStatus({ limit: 128 });
+  const entries = [...first.entries];
+  let cursor = first.nextCursor;
+  while (cursor !== null) {
+    const page = await client.importStatus({ after: cursor, limit: 128 });
+    if (page.entries.length === 0 || page.nextCursor === cursor) throw new AuthorityCliFailure('response');
+    entries.push(...page.entries);
+    cursor = page.nextCursor;
+  }
+  return { ...first, entries, nextCursor: null };
+};
+
+const renderImportStatus = (status: IAuthSwitchImportStatus): string => {
+  const lines = [`Import status — generated ${safe(status.generatedAt)}`];
+  if (status.entries.length === 0) {
+    lines.push('No source has been submitted yet. Run `authswitch authority import inventory` to see what this host holds.');
+  }
+  for (const entry of status.entries) {
+    lines.push(`${safe(entry.sourceKind)} ${safe(entry.sourceId)}`,
+      `  state ${safe(entry.status)}; refresher ${safe(entry.owner)}; recorded ${safe(entry.statusObservedAt)}`,
+      `  account ${safe(entry.accountId)}; login ${safe(entry.loginId)}`,
+      `  next: ${actionText(entry.action)}`);
+  }
+  // A source that was never submitted has no ledger row, so it is the inventory's subject, not this read's.
+  lines.push('Sources that were never submitted are listed by `authswitch authority import inventory`.');
+  return lines.join('\n') + '\n';
+};
+
+const renderImportResult = (result: IAuthSwitchImportResult): string => {
+  const settled = result.status === 'complete';
+  const lines = [`${settled ? 'Imported' : 'Import did not settle'}: ${safe(result.sourceKind)} ${safe(result.sourceId)}`,
+    `  treatment ${safe(result.treatment)}; state ${safe(result.status)}`,
+    `  account ${safe(result.accountId)}; login ${safe(result.loginId)}`];
+  for (const problem of result.problems) lines.push(`  problem: ${safe(problem)}`);
+  if (settled && result.treatment === 'import') {
+    lines.push('  The authority now refreshes this login. Its legacy copy holds a token the provider has rotated away.');
+  }
+  if (settled && result.treatment === 'project') {
+    lines.push('  The native tool still refreshes this login. The authority holds no copy of it.');
+  }
+  return lines.join('\n') + '\n';
+};
+
 const terminalOperation = (operation: IAuthSwitchOperation): boolean =>
   operation.state === 'complete' || operation.state === 'failed' || operation.state === 'cancelled'
   || operation.state === 'interrupted' || operation.state === 'outcome_unknown';
@@ -443,6 +566,7 @@ export const runAuthSwitchAuthorityCli = async (argv: readonly string[],
   let preuseHint = false;
   let beginAttempted = false;
   let beginResponded = false;
+  let submitAttempted = false;
   const operationController = new AbortController();
   const closeClient = (reason?: Error): void => {
     if (clientClosed || !client) return;
@@ -579,6 +703,24 @@ export const runAuthSwitchAuthorityCli = async (argv: readonly string[],
       await runDoctor(activeClient, command.json, writeOutput);
       return 0;
     }
+    if (command.kind === 'importInventory') {
+      const inventory = await activeClient.importInventory();
+      await writeOutput(command.json ? JSON.stringify(inventory) + '\n' : renderInventory(inventory));
+      return 0;
+    }
+    if (command.kind === 'importStatus') {
+      const status = await collectImportStatus(activeClient);
+      await writeOutput(command.json ? JSON.stringify(status) + '\n' : renderImportStatus(status));
+      return 0;
+    }
+    if (command.kind === 'importSubmit') {
+      // A lost response leaves the outcome unknown to this process but never to the authority, so the
+      // failure path below points at the status read rather than inviting a second submission.
+      submitAttempted = true;
+      const result = await activeClient.submitImport(command.sourceId, command.sourceDigest);
+      await writeOutput(command.json ? JSON.stringify(result) + '\n' : renderImportResult(result));
+      return result.status === 'complete' ? 0 : 1;
+    }
     if (command.kind === 'preuseGet' || command.kind === 'preuseCancel') {
       const operation = validatePreuseOperation(command.kind === 'preuseGet'
         ? await activeClient.getPreuse(command.operationId)
@@ -692,15 +834,27 @@ export const runAuthSwitchAuthorityCli = async (argv: readonly string[],
     }
     return 0;
   } catch (error) {
-    let message = cancelled ? 'Authswitch authority request was cancelled.\n'
-      : timedOut ? 'Authswitch authority operation timed out.\n'
-        : beginAttempted && !beginResponded
-          ? 'Authswitch authority operation start response was lost.\n'
-          : error instanceof AuthorityCliFailure && error.kind === 'output'
-            ? 'Authswitch authority output failed.\n'
-            : error instanceof AuthorityCliFailure && error.kind === 'response'
-              ? 'Authswitch authority daemon returned an invalid response.\n'
-              : 'Authswitch authority daemon is unavailable.\n';
+    // A marked refusal is the daemon's answer to the command, not a fault: it names what the owner does
+    // instead and nothing was left half-done, so it is shown as written rather than replaced by a generic
+    // line. Any other failure -- including the transport's own sanitised text -- stays a diagnostic.
+    const refusal = error instanceof Error && isAuthSwitchImportRefusal(error) && !cancelled && !timedOut
+      ? safe(error.message) : null;
+    let message = refusal !== null ? `${refusal}\n`
+      : cancelled ? 'Authswitch authority request was cancelled.\n'
+        : timedOut ? 'Authswitch authority operation timed out.\n'
+          : beginAttempted && !beginResponded
+            ? 'Authswitch authority operation start response was lost.\n'
+            : error instanceof AuthorityCliFailure && error.kind === 'output'
+              ? 'Authswitch authority output failed.\n'
+              : error instanceof AuthorityCliFailure && error.kind === 'response'
+                ? 'Authswitch authority daemon returned an invalid response.\n'
+                : 'Authswitch authority daemon is unavailable.\n';
+    if (submitAttempted && refusal === null) {
+      // The authority may have settled this source even though this process never learned the answer; never
+      // submit it again blindly, because a rotating refresh token is sent at most once.
+      message += 'The outcome of this import is unknown to this command. Run `authswitch authority import '
+        + 'status` before doing anything else with this source.\n';
+    }
     if (operationIdForHint !== null) {
       const resume = preuseHint ? preuseResumeCommand(operationIdForHint, command.json)
         : resumeCommand(operationIdForHint, command.json);

package/ts/classes.authorityclient.ts

@@ -11,6 +11,8 @@ import type {
 } from './authority-contract.js';
 import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchReleaseBinding,
   IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+import type { IReq_AuthSwitchImportInventory, IReq_AuthSwitchImportStatus,
+  IReq_AuthSwitchImportSubmit } from './authority-import-contract.js';
 import { AuthSwitchAuthorityFrameReader, authSwitchAuthorityFrameBytes,
   maxAuthSwitchAuthorityFrameBytes } from './classes.authorityframing.js';
 
@@ -97,6 +99,26 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchDoctor>('authswitch.authority.doctor', options, 35_000, false, signal)).page;
   }
 
+  /** The credential-free legacy-source report of the one-time import. It changes nothing. */
+  public async importInventory(signal?: AbortSignal): Promise<IReq_AuthSwitchImportInventory['response']['inventory']> {
+    return (await this.request<IReq_AuthSwitchImportInventory>('authswitch.authority.import.inventory',
+      {}, 35_000, false, signal)).inventory;
+  }
+
+  /** Where every source the authority knows about stands. Durable records only; no store is opened. */
+  public async importStatus(request: IReq_AuthSwitchImportStatus['request'] = {},
+    signal?: AbortSignal): Promise<IReq_AuthSwitchImportStatus['response']['status']> {
+    return (await this.request<IReq_AuthSwitchImportStatus>('authswitch.authority.import.status',
+      request, 35_000, false, signal)).status;
+  }
+
+  /** Backend-only. One source, one ownership decision; both acknowledgements are required. */
+  public async submitImport(submission: IReq_AuthSwitchImportSubmit['request']['submission'],
+    signal?: AbortSignal): Promise<IReq_AuthSwitchImportSubmit['response']['result']> {
+    return (await this.request<IReq_AuthSwitchImportSubmit>('authswitch.authority.import.submit',
+      { submission, callerQuiescent: true, acknowledgeRunOrder: true }, 120_000, true, signal)).result;
+  }
+
   public async getUsage(accountId: string, loginId: string, force = false): Promise<IReq_AuthSwitchUsage['response']['usage']> {
     return (await this.request<IReq_AuthSwitchUsage>('authswitch.authority.usage',
       { accountId, loginId, force })).usage;

package/ts/classes.authoritydaemon.ts

@@ -10,6 +10,11 @@ import type {
 } from './authority-contract.js';
 import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchReleaseBinding,
   IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+import { authSwitchImportRefusalReason } from './authority-import-contract.js';
+import type { IReq_AuthSwitchImportInventory, IReq_AuthSwitchImportStatus, IReq_AuthSwitchImportSubmit,
+  TAuthSwitchImportSubmission } from './authority-import-contract.js';
+import { AuthSwitchAuthorityImport, AuthSwitchImportRefusal,
+  type IAuthSwitchAuthorityImportOptions } from './classes.authorityimport.js';
 import { authSwitchBindingCapabilityHash, AuthSwitchAuthorityBroker,
   type IAuthSwitchAuthorityBrokerOptions } from './classes.authoritybroker.js';
 import { AuthSwitchAuthorityDatabase, type IAuthSwitchAuthorityDatabaseOptions } from './classes.authoritydatabase.js';
@@ -32,6 +37,8 @@ export interface IAuthSwitchAuthorityDaemonOptions extends IAuthSwitchAuthorityD
   claudeStatus?: ClaudeAccountStatus;
   /** Activated only after a verified backend source receipt has registered the native home. */
   claudeNative?: IClaudeNativeAuthorityOptions;
+  /** Where the one-time import reads the legacy stores. Defaults to this user's own locations. */
+  legacyImport?: IAuthSwitchAuthorityImportOptions;
 }
 
 const hasKeys = (value: unknown, keys: readonly string[]): value is Record<string, unknown> =>
@@ -41,6 +48,28 @@ const invalid = (): never => { throw new plugins.typedrequest.TypedResponseError
 const validBindingId = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
 const validBindingCapability = (value: unknown): value is string => typeof value === 'string'
   && /^[A-Za-z0-9_-]{43}$/.test(value);
+const validHash = (value: unknown): value is string => typeof value === 'string'
+  && /^[a-f0-9]{64}$/.test(value);
+const boundedToken = (value: unknown): value is string => typeof value === 'string'
+  && value.length > 0 && value.length <= 8192;
+
+/** A submission names a local source by id and digest, or carries one external store's own login. */
+const validImportSubmission = (value: unknown): value is TAuthSwitchImportSubmission => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const submission = value as Record<string, unknown>;
+  if (submission.kind === 'local') {
+    return hasKeys(submission, ['kind', 'sourceId', 'sourceDigest'])
+      && validHash(submission.sourceId) && validHash(submission.sourceDigest);
+  }
+  if (submission.kind !== 'external'
+    || !hasKeys(submission, ['kind', 'sourceKind', 'sourcePathHash', 'sourceDigest', 'credential'])
+    || submission.sourceKind !== 'agl_flex' || !validHash(submission.sourcePathHash)
+    || !validHash(submission.sourceDigest)) return false;
+  const credential = submission.credential;
+  return hasKeys(credential, ['providerId', 'accessToken', 'refreshToken', 'idToken'])
+    && credential.providerId === 'openai' && boundedToken(credential.accessToken)
+    && boundedToken(credential.refreshToken) && boundedToken(credential.idToken);
+};
 
 interface IPreuseAccountReservation {
   operationId: string;
@@ -52,6 +81,7 @@ export class AuthSwitchAuthorityDaemon {
   public readonly broker: AuthSwitchAuthorityBroker;
   public readonly usage: AuthSwitchAuthorityUsage;
   public readonly preuse: AuthSwitchAuthorityPreuse;
+  public readonly legacyImport: AuthSwitchAuthorityImport;
   public readonly claudeNative?: ClaudeNativeAuthority;
   private readonly managementRouter = new plugins.typedrequest.TypedRouter();
   private readonly runtimeRouter = new plugins.typedrequest.TypedRouter();
@@ -102,6 +132,7 @@ export class AuthSwitchAuthorityDaemon {
       provider,
     });
     this.preuse = new AuthSwitchAuthorityPreuse(this.database, this.broker, options.preuse);
+    this.legacyImport = new AuthSwitchAuthorityImport(this.database, options.legacyImport);
     if (options.claudeNative) {
       this.claudeNative = new ClaudeNativeAuthority(this.database, {
         ...options.claudeNative, onChanged: () => this.broker.notifyChanged(),
@@ -248,6 +279,25 @@ export class AuthSwitchAuthorityDaemon {
             || request.limit < 1 || request.limit > 128))) invalid();
         return { page: await this.doctorPage(request) };
       }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchImportInventory>(
+      'authswitch.authority.import.inventory', async request => {
+        // A read with no parameters: the inventory is the whole host, and a caller cannot narrow it into
+        // believing a source does not exist.
+        if (request === null || typeof request !== 'object' || Array.isArray(request)
+          || Object.keys(request).length !== 0) invalid();
+        if (this.closing) throw new Error('Authswitch authority is shutting down.');
+        return { inventory: await this.legacyImport.inventory() };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchImportStatus>(
+      'authswitch.authority.import.status', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)
+          || Object.keys(request).some(key => !['after', 'limit'].includes(key))
+          || (request.after !== undefined && !validHash(request.after))
+          || (request.limit !== undefined && (!Number.isSafeInteger(request.limit)
+            || request.limit < 1 || request.limit > 128))) invalid();
+        if (this.closing) throw new Error('Authswitch authority is shutting down.');
+        return { status: await this.legacyImport.status(request) };
+      }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchEvents>(
       'authswitch.authority.events', async (request, tools) => {
         if (!hasKeys(request, ['epoch', 'afterRevision', 'waitMs'])) invalid();
@@ -381,6 +431,28 @@ export class AuthSwitchAuthorityDaemon {
         if (this.closing) throw new Error('Authswitch authority is closing.');
         return this.releaseRuntimeBinding(request.bindingId, request.capability);
       }));
+    this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchImportSubmit>(
+      'authswitch.authority.import.submit', async request => {
+        // Backend-only: an external submission carries the material of a store this package cannot read.
+        if (!hasKeys(request, ['submission', 'callerQuiescent', 'acknowledgeRunOrder'])
+          || request.callerQuiescent !== true || request.acknowledgeRunOrder !== true
+          || !validImportSubmission(request.submission)) invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        try {
+          return { result: await this.legacyImport.submit({ submission: request.submission,
+            callerQuiescent: true, acknowledgeRunOrder: true }) };
+        } catch (error) {
+          // A refusal is an answer, not a fault: it names what the owner does instead, and only a
+          // TypedResponseError survives the wire with its text. The marker is what lets the caller tell
+          // that instruction apart from the transport's sanitised text for an unexpected failure, whose
+          // import outcome is unknown. Everything else stays sanitised and unmarked.
+          if (error instanceof AuthSwitchImportRefusal) {
+            throw new plugins.typedrequest.TypedResponseError(error.message,
+              { reason: authSwitchImportRefusalReason });
+          }
+          throw error;
+        }
+      }));
   }
 
   private async doctorPage(request: IReq_AuthSwitchDoctor['request']): Promise<IAuthSwitchDoctorPage> {