@modelprofile.com/authswitch 8.0.0 → 8.2.0

package/readme.md

@@ -49,8 +49,11 @@ const receipt = await client.getOperation(operation.id);
 ```
 
 Browser code can import the credential-free DTOs from
-`@modelprofile.com/authswitch/authority-contract`. A backend binds an account to a
-runtime incarnation by exact account ID, login ID and purpose, and keeps the returned
+`@modelprofile.com/authswitch/authority-contract`. The backend-only binding, access and release
+requests are named by `@modelprofile.com/authswitch/authority-runtime-contract`, and the one-time
+import's own DTOs by `@modelprofile.com/authswitch/authority-import-contract`; the runtime contract
+belongs to the runtime socket and its capability must never reach a browser. A backend binds an
+account to a runtime incarnation by exact account ID, login ID and purpose, and keeps the returned
 capability private. Targeted reauthentication likewise requires the exact login; an
 account's presentation default never selects a grant for either action. Completed and
 interrupted operations remain discoverable through `getOperation()` and paged
@@ -76,6 +79,31 @@ the runtime and clears its durable run before internal revocation. Binding relea
 or changes ownership of the account grant. External-binding recovery after an owner crash remains
 a prerequisite for the full account-mutation cutover.
 
+Every route on either socket answers in one of three ways: a result, a **refusal**, or a fault. A refusal
+is an answer -- the daemon completed its check, nothing was left half-done, and its message says what the
+owner does instead -- so it crosses the wire marked, with the message verbatim beside
+`{ reason, code }`. A fault is anything the daemon did not decide: the transport replaces its text with
+`Internal server error`, and a caller must never present that as if it said what to do next. A malformed
+request is neither; it keeps its own text and carries no marker, because a caller's own bug is not an
+instruction for an owner.
+
+`asAuthSwitchRefusal(error)` from `@modelprofile.com/authswitch/authority-contract` is the one reader of
+that marker: it answers `{ code, instruction }` for a refusal and `null` for a fault. The code is the
+closed `TAuthSwitchRefusalCode` set, which is what a client branches on without reading the text:
+`authority_closing`, `not_found`, `account_changed`, `account_busy`, `login_unavailable`,
+`native_owner_holds_login`, `claude_home_unregistered`, `claude_handoff_pending`,
+`claude_receipt_missing` and `import_refusal`. The instruction is authored for the owner and contains no
+path, credential or digest; only an importer refusal may name the process the owner has to stop.
+
+The import routes keep the marker they published in 8.1.0, `authswitch_import_refusal`, and
+`isAuthSwitchImportRefusal` from `@modelprofile.com/authswitch/authority-import-contract` is the same
+reader asking for the `import_refusal` code, so a consumer written against 8.1.0 keeps working and a
+client of this release still reads the payload a daemon of that release answers with. The distinction
+matters most for `import.submit`: a refusal there is a submit that decided -- it left nothing half-done,
+and the ledger row it wrote says where that source stands -- while an unmarked failure leaves the outcome
+unknown, and that source must then be read with `authswitch.authority.import.status` rather than
+submitted again.
+
 `AuthSwitchClient.subscribe(onSnapshot, onEvent, signal, { onStatus })` reports `current`
 after a fresh snapshot or verified heartbeat, `unavailable` on disconnect or resync, and
 `closed` on abort. Keep cached account actions disabled while status is not `current`.
@@ -110,6 +138,9 @@ authswitch account preuse operation get <operation-id> [--json]
 authswitch account preuse operation cancel <operation-id> [--json]
 authswitch account preuse operation 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]
 ```
 
 `account list --json` prints the complete, consistent credential-free authority snapshot.
@@ -164,6 +195,84 @@ If the daemon is unavailable before the first response, it fails with a fixed di
 stderr and leaves stdout empty. The older native-store commands documented below still coexist until the coordinated
 major-version migration and removal; these authority routes never use them.
 
+### The Claude native home
+
+The daemon serves Claude Code's own credential store, which stays the native store that Claude Code
+reads. `authswitch.authority.claude.switch`, `.handoff` and `.handoffs` on the management socket move
+that one home between two authority logins and report the journal of those moves, and
+`authswitch.authority.usage` answers for an Anthropic account from it. The home is
+`CLAUDE_CONFIG_DIR` or `~/.claude`, and the authority identifies it by the hash of the credential file
+Claude Code owns -- the same value the import publishes as that source's path hash, which is what lets a
+verified receipt adopt it.
+
+The daemon is wired for that home whether or not Claude Code is installed, so `doctor` reports
+`claudeNativeAuthority: configured` on any host; the `claudeHomes` page is what says whether a home has
+been adopted. Until a verified `claude_native` import has adopted one, every Claude route refuses. A
+`CLAUDE_CONFIG_DIR` that is not an absolute path is refused when the daemon starts, because the same
+variable also decides which file the import would read; it is never resolved against a working directory.
+
+A switch is only attempted when the host can prove Claude Code uses that native login: exactly the
+verified Claude Code release, a subscriber login in the store, no credential override in the
+environment, no managed or local settings selecting another auth source, and no scoped Claude session
+running. Anything else refuses and leaves both logins where they were. A move that reaches the home and
+then cannot complete that proof is quarantined with `problem: unsupported_effective_auth`, and the
+handoff's optional `proofFailure` names which condition failed -- `unsupported_release`, `subscription`,
+`override`, `settings`, `profile`, `profile_unreadable` or `running_session` -- so an owner is told what
+to change. It is absent whenever `problem` is anything else. The settings that proof reads are the ones
+the daemon may speak for: the user settings file of the resolved home and the managed settings directory.
+A project's `.claude/settings.json` is read from the working directory of each running Claude session,
+never from the daemon's own, which is its service unit's and selects nothing. While a login is in the
+native home, Claude Code is its only refresher; the authority takes it back by the same journaled handoff.
+
+## The one-time account import
+
+The three `authority import` commands move the accounts that existed before the authority into it.
+
+`import inventory` reads this host and changes nothing: no authority record, no legacy file, no
+credential. It lists every Codex stash directory, saved credential record and native Codex, Claude and
+OpenCode store with the authority account it resolves to, derived from the claims the stored token already
+carries -- no provider is contacted. A malformed or unrecognised entry is reported rather than skipped, so
+an empty result is never mistaken for an empty store. The report carries no token, no token digest and no
+source path; a source is named by a hash of its location and a digest of its bytes.
+
+Each source is classified by who refreshes its login **after** the import.
+
+- **adopt** -- a copy authswitch made for itself, and AGL's own records. Nothing else refreshes such a
+  copy, so the authority takes it over outright. It is verified by one real refresh, which rotates the
+  token: from that moment the legacy copy is dead. That is the point of no return for that account, and the
+  only fallback is one device sign-in.
+- **project** -- a native Codex, Claude or OpenCode store. The vendor tool keeps refreshing its own store,
+  so the authority registers the account, leaves the grant with its native owner and holds no copy of the
+  credential. It is verified by a provider read with the access token already in the store, which rotates
+  nothing. Two refreshers on one rotating refresh token is the failure this avoids.
+
+A verified Claude projection also adopts the native home it came from, so the daemon may serve Claude
+switches for it. The receipt is what adopts it, and a home belongs to one login at a time: a second home
+for a login another one already holds -- a `.credentials.json` copied to another `CLAUDE_CONFIG_DIR` --
+and a home whose active login has since moved are both refused with the importer's own code, so the
+submit is known to have decided, the ledger row stays `verified` and no home changed.
+
+`import submit` takes the source id and the digest the owner read in the inventory. The daemon re-reads the
+source itself and refuses if the digest changed, so approving one source can never import a different one;
+no credential crosses the socket for a source this package can read. It refuses while an authswitch watch, a
+native harness process or Codex's app-server is running, and an app-server it cannot ask counts as running.
+An adopt whose refresh fails, or whose answer is lost, is never retried: the source is quarantined, its grant
+is left needing re-authentication, and the command says so. A projection fails differently, because nothing
+rotating was ever sent for it: a native store that could not be proven live stays a pending native owner and
+is imported by submitting the same source again once its own tool has refreshed it.
+
+`import status` reads the migration ledger, the grants and the handoffs -- never the host -- and reports, per
+source, where it stands, which owner refreshes its login now, and what to do next: nothing, submit the same
+source again, or sign in to that account again. Submitting a source again is how an interrupted run resumes,
+and the answer comes from the same durable record the daemon decides on: a source whose sign-in was in
+flight when the run died is reported as needing a device sign-in, not as resumable, because a rotating
+refresh token is never sent a second time. Sources that were never submitted have no ledger row and appear
+only in the inventory.
+
+An import deletes nothing: retiring the legacy files is a separate, later step. The authority store is
+deliberately not backed up, so losing it costs one device sign-in per account -- and the remote-control
+enrollments and runtime bindings with it.
+
 `AuthSwitchClient.getUsage(accountId, loginId)` reads OpenAI managed limits or a Claude
 host login's profile and usage through the management socket. The tagged, credential-free
 reading preserves Claude's labelled five-hour, weekly and model windows, plan provenance,

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/authswitch',
-  version: '8.0.0',
+  version: '8.2.0',
   description: 'Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status'
 }

package/ts/authority-contract.ts

@@ -2,6 +2,99 @@ import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
 import type { IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
 export type { IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
 
+/**
+ * Why the authority declined, as a closed set a client branches on without reading the text.
+ *
+ * A refusal is an answer: the daemon did the check, nothing was left half-done, and the message says what
+ * the owner does instead. Everything else stays a fault whose text the transport replaces, and a caller
+ * must never present a fault as if it said what to do next.
+ */
+export type TAuthSwitchRefusalCode =
+  | 'authority_closing'
+  | 'not_found'
+  | 'account_changed'
+  | 'account_busy'
+  | 'login_unavailable'
+  | 'native_owner_holds_login'
+  | 'claude_home_unregistered'
+  | 'claude_handoff_pending'
+  | 'claude_receipt_missing'
+  | 'import_refusal';
+
+/** The marker the importer has published since 8.1.0; it keeps its own value on the wire. */
+export const authSwitchImportRefusalMarker = 'authswitch_import_refusal';
+export const authSwitchRefusalReason = 'authswitch_refusal';
+
+export type TAuthSwitchRefusalReason = typeof authSwitchRefusalReason | typeof authSwitchImportRefusalMarker;
+
+/** Everything a refusal puts on the wire beside its message: two literals, never a value of its own. */
+export interface IAuthSwitchRefusalData {
+  reason: TAuthSwitchRefusalReason;
+  code: TAuthSwitchRefusalCode;
+}
+
+/** What the owner is told when the answer is an instruction rather than a fault. */
+export interface IAuthSwitchRefusal {
+  code: TAuthSwitchRefusalCode;
+  /** The instruction, authored by the handler that declined. */
+  instruction: string;
+}
+
+const refusalCodes: ReadonlySet<string> = new Set<TAuthSwitchRefusalCode>([
+  'authority_closing', 'not_found', 'account_changed', 'account_busy',
+  'login_unavailable', 'native_owner_holds_login', 'claude_home_unregistered',
+  'claude_handoff_pending', 'claude_receipt_missing', 'import_refusal',
+]);
+
+const isRefusalCode = (value: unknown): value is TAuthSwitchRefusalCode =>
+  typeof value === 'string' && refusalCodes.has(value);
+
+/** The importer keeps the marker it published; every other code shares the authority's own. */
+const reasonOf = (code: TAuthSwitchRefusalCode): TAuthSwitchRefusalReason =>
+  code === 'import_refusal' ? authSwitchImportRefusalMarker : authSwitchRefusalReason;
+
+/**
+ * One refusal, thrown by a handler and turned into a marked answer by the router that owns the wire.
+ *
+ * It accepts nothing but a code of the closed set and the text the owner is to read, and builds the marker
+ * from the code alone, so no handler can attach a value of its own to what a client branches on.
+ */
+export class AuthSwitchRefusal extends Error {
+  public readonly code: TAuthSwitchRefusalCode;
+
+  constructor(code: TAuthSwitchRefusalCode, instruction: string) {
+    super(instruction);
+    this.code = code;
+  }
+
+  /** Everything this refusal puts on the wire beside its message. */
+  public get data(): IAuthSwitchRefusalData { return { reason: reasonOf(this.code), code: this.code }; }
+}
+
+/**
+ * The refusal an error answer carries, or null when it is a fault whose text says nothing.
+ *
+ * This is the only reader of `errorData` in the package: the importer's published predicate is expressed
+ * through it, so a caller never has to know which of the two markers a route uses.
+ *
+ * 8.1.0 marked the importer's refusal with the reason alone. A per-user daemon keeps running across an
+ * upgrade until its owner restarts it, so a newer client still meets that payload, and it names the one
+ * refusal that release could answer with -- which is why it is read rather than treated as a fault.
+ */
+export const asAuthSwitchRefusal = (error: unknown): IAuthSwitchRefusal | null => {
+  if (error instanceof AuthSwitchRefusal) return { code: error.code, instruction: error.message };
+  if (typeof error !== 'object' || error === null || !('errorData' in error)) return null;
+  const data: unknown = error.errorData;
+  if (typeof data !== 'object' || data === null || !('reason' in data)) return null;
+  const code: unknown = 'code' in data ? data.code : undefined;
+  const instruction = 'message' in error && typeof error.message === 'string' ? error.message : '';
+  if (data.reason === authSwitchImportRefusalMarker) {
+    return code === undefined || code === 'import_refusal' ? { code: 'import_refusal', instruction } : null;
+  }
+  if (data.reason !== authSwitchRefusalReason || !isRefusalCode(code)) return null;
+  return { code, instruction };
+};
+
 /** Credential-free account management contract. Safe to import in browser code. */
 export type TAuthSwitchLoginPurpose = 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native';
 export type TAuthSwitchLoginHealth = 'ready' | 'refreshing' | 'retry_wait' | 'needs_reauth' | 'unverified' | 'pending_handoff' | 'handoff_quarantined' | 'removed';
@@ -234,6 +327,17 @@ export interface IAuthSwitchPreuseOperation {
   revision: number;
 }
 
+/**
+ * Why the host could not prove that Claude Code uses its own native login.
+ *
+ * Each value names one condition of that proof, so an owner is told what to change: install the supported
+ * release, sign in to a subscriber plan, remove a credential override or a settings source, let the
+ * profile read succeed, or close the running session.
+ */
+export type TAuthSwitchClaudeProofFailure =
+  | 'unsupported_release' | 'override' | 'profile' | 'profile_unreadable'
+  | 'settings' | 'subscription' | 'running_session';
+
 /** Credential-free native file ownership result. It makes no claim about a running session's active request. */
 export interface IAuthSwitchClaudeNativeHandoff {
   id: string;
@@ -243,6 +347,8 @@ export interface IAuthSwitchClaudeNativeHandoff {
   phase: 'reserved' | 'prepared' | 'committed' | 'aborted' | 'quarantined';
   problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
   runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
+  /** Which condition of the native-login proof failed, when `problem` is `unsupported_effective_auth`. */
+  proofFailure?: TAuthSwitchClaudeProofFailure;
   updatedAt: string;
 }
 

package/ts/authority-import-contract.ts

@@ -0,0 +1,217 @@
+import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
+import { asAuthSwitchRefusal, authSwitchImportRefusalMarker } from './authority-contract.js';
+
+/**
+ * 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: a refusal any other route
+ * authors carries the authority's own marker, and a failure neither of them decided answers with the
+ * transport's 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.
+ *
+ * It is one code of the authority's refusal contract (`./authority-contract`), which every route now uses;
+ * this marker keeps its own value on the wire so a consumer written against 8.1.0 keeps working.
+ */
+export const authSwitchImportRefusalReason = authSwitchImportRefusalMarker;
+
+/** True when the daemon answered with an importer refusal, so `error.message` is the instruction to show. */
+export const isAuthSwitchImportRefusal = (error: unknown): boolean =>
+  asAuthSwitchRefusal(error)?.code === 'import_refusal';
+
+/**
+ * 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.authoritybroker.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
   IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
 import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
   IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
@@ -554,7 +555,7 @@ export class AuthSwitchAuthorityBroker {
     if (!isId(accountId) || !validRevision(expectedRevision) || !safeLabel(label)) throw new Error('Invalid account change.');
     const updateId = plugins.crypto.randomUUID();
     const updated = await this.database.changeAccount(updateId, accountId, account => {
-      if (!account || account.removed || account.revision !== expectedRevision) throw new Error('Account changed; refresh before editing.');
+      if (!account || account.removed || account.revision !== expectedRevision) throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
       return { ...account, label, revision: account.revision + 1, updateId,
         statusObservedAt: new Date(this.now()).toISOString() };
     });