@modelprofile.com/authswitch 8.1.0 → 9.0.0

package/ts/classes.authorityimport.ts

@@ -1,6 +1,7 @@
 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';
@@ -75,9 +76,15 @@ export interface IAuthSwitchImportClaudeTokens {
 }
 
 export interface IAuthSwitchAuthorityImportOptions {
-  /** Locates the legacy stores, exactly as each owning class locates its own. */
-  env?: NodeJS.ProcessEnv;
-  homeDirectory?: string;
+  /**
+   * Locates the legacy stores, exactly as each owning class locates its own -- and always stated.
+   *
+   * These are the two inputs that decide whose real credentials an import reads, so the importer never
+   * reaches for the host's own environment: a caller that could not name them has no business importing.
+   * `AuthSwitchAuthorityService`'s entry point is the one place that takes them from this host.
+   */
+  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;
@@ -168,8 +175,17 @@ const importAction = (status: TAuthSwitchImportLedgerStatus,
   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. */
-export class AuthSwitchImportRefusal extends Error {}
+/**
+ * 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); };
@@ -179,6 +195,58 @@ const RUN_ORDER_REFUSAL = 'Importing needs the run-order acknowledgement: an imp
   + 'exercise exactly that copy. Import only once those commands run on the authority and the native '
   + 'projections exist.';
 
+/**
+ * A row keeps the login it named, permanently: no route forgets a row or re-points it at another account,
+ * and one would be a way to import a login the owner never approved under an approval given for a different
+ * one. The same is true of a settled row, which answers that it is already imported.
+ */
+const FOREIGN_SOURCE_REFUSAL = 'This source now holds a different account\'s login than the one this import '
+  + 'registered for it. Restore the login this source was registered with, then import it again.';
+const CHANGED_SOURCE_REFUSAL =
+  'The source changed after its migration ledger row was written; it is a different source now.';
+
+/**
+ * Whether a row may take the bytes its source holds now.
+ *
+ * A projection that could not be proven waits for its own tool, and that tool proves itself by refreshing
+ * its store -- which rewrites the file. The row has to be able to follow those bytes, or the retry its own
+ * refusal asks for could never be made at all. It follows them only this far: the row is unsettled, nothing
+ * rotating was ever sent for it, and the authority holds no copy of its credential. That the bytes are still
+ * the same login is a separate question, and `ledgerObjection` answers it first.
+ */
+const followsRefreshedSource = (ledger: IStoredAuthorityMigrationLedger,
+  record: Pick<ILegacySourceRecord, 'treatment'>): boolean =>
+  ledger.status === 'pending_native_owner' && record.treatment === 'project' && ledger.grantId !== null;
+
+/**
+ * What this source's own row objects to, asked once and answered for both the report and the submit.
+ *
+ * The runbook tells the owner not to submit a source the inventory lists a problem for, which is only true
+ * while the two agree, so they are the same four questions in one place. The identity question is the one
+ * the provider cannot answer: a row is found by the hash of its location, so the same row answers for
+ * whatever login that location holds later -- `codex login` under the same path, a replaced saved record --
+ * and the non-rotating proof asks the provider about the identity the newly read bytes themselves claim. It
+ * therefore proves those bytes are self-consistent and live, never that they are the login this row was
+ * approved for. A source with no derivable identity is left to its reader's own problem.
+ */
+type TLedgerObjection = 'imported' | 'quarantined' | 'foreign' | 'changed';
+
+const ledgerObjection = (ledger: IStoredAuthorityMigrationLedger,
+  record: Pick<ILegacySourceRecord, 'treatment' | 'accountId' | 'sourceDigest'>,
+  grantId: string | null): TLedgerObjection | null => {
+  // A quarantined row is terminal whatever its location holds now, and its answer -- sign in to that
+  // account again -- is the next step either way. Everything after it is about the login that is there.
+  if (ledger.status === 'quarantined') return 'quarantined';
+  // Before "already imported": a settled row whose location now holds another account would otherwise
+  // answer that a login it never touched is imported.
+  if (record.accountId !== null && grantId !== null
+    && ((ledger.accountId !== null && ledger.accountId !== record.accountId)
+      || (ledger.grantId !== null && ledger.grantId !== grantId))) return 'foreign';
+  if (ledger.status === 'complete') return 'imported';
+  if (ledger.sourceDigest !== record.sourceDigest && !followsRefreshedSource(ledger, record)) return 'changed';
+  return null;
+};
+
 /** 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 => ({
@@ -217,9 +285,9 @@ export class AuthSwitchAuthorityImport {
   private readonly quiescence: IAuthSwitchImportQuiescence;
 
   constructor(private readonly database: AuthSwitchAuthorityDatabase,
-    options: IAuthSwitchAuthorityImportOptions = {}) {
-    this.env = options.env ?? process.env;
-    this.homeDirectory = options.homeDirectory ?? plugins.os.homedir();
+    options: IAuthSwitchAuthorityImportOptions) {
+    this.env = options.env;
+    this.homeDirectory = options.homeDirectory;
     this.now = options.now ?? Date.now;
     this.openAi = options.openAi ?? new plugins.flexAccounts.OpenAiProviderAdapter();
     this.claudeStatus = options.claudeStatus ?? new ClaudeAccountStatus();
@@ -238,12 +306,20 @@ export class AuthSwitchAuthorityImport {
     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.
+      // The same four questions the submit decides on, so a source the report invites is one the submit
+      // takes. New bytes of the same login under a row that is still waiting for them are not an objection:
+      // they are the retry that row asks for, and no problem line tells the owner to stop.
+      const objection = ledger === null ? null : ledgerObjection(ledger, record,
+        record.accountId === null ? null : importGrantId(record.accountId, grantPlan(record)));
+      if (objection === 'foreign') {
+        source.problems.push('this source now holds a different account\'s login than the one it was registered with');
+      }
+      if (objection === 'changed') {
+        // 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') {
+      if (objection === 'imported') {
         source.problems.push('this source is already imported; its legacy copy is retired');
       }
       sources.push(source);
@@ -298,17 +374,6 @@ export class AuthSwitchAuthorityImport {
     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;
@@ -316,6 +381,18 @@ export class AuthSwitchAuthorityImport {
       refuse('The source carries no provider identity the authority can bind an account to.');
     }
     const grantId = importGrantId(accountId, plan);
+    const ledger = await this.database.readMigrationLedger(record.id);
+    // Every one of these is decided from the durable row alone, before a single write: a projection
+    // registers its account and grant before the provider is asked anything, so an objection that arrived
+    // later would arrive after the record it objects to had been written.
+    switch (ledger === null ? null : ledgerObjection(ledger, record, grantId)) {
+      case 'imported': refuse('This source is already imported.');
+      case '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.');
+      case 'foreign': refuse(FOREIGN_SOURCE_REFUSAL);
+      case 'changed': refuse(CHANGED_SOURCE_REFUSAL);
+    }
     if (ledger === null) await this.beginLedger(record);
     const material = this.material(record, request.submission);
     return record.treatment === 'project'
@@ -418,12 +495,20 @@ export class AuthSwitchAuthorityImport {
     }));
   }
 
+  /**
+   * Moves the row, and -- only where a caller states it -- the bytes that move with the status.
+   *
+   * The digest is part of the same write as the status it was proven under, so no row can record a proof of
+   * bytes it does not name. The database holds the rule about which row may carry a new digest at all.
+   */
   private async moveLedger(ledgerId: string, status: IStoredAuthorityMigrationLedger['status'],
-    accountId: string | null, grantId: string | null): Promise<IStoredAuthorityMigrationLedger> {
+    accountId: string | null, grantId: string | null,
+    sourceDigest?: string): 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,
+      return { ...current, status, accountId, grantId,
+        sourceDigest: sourceDigest ?? current.sourceDigest, revision: current.revision + 1,
         statusObservedAt: this.stamp(), updateId };
     });
   }
@@ -503,11 +588,31 @@ export class AuthSwitchAuthorityImport {
       await this.moveLedger(record.id, 'pending_native_owner', identity.accountId, identity.grantId);
       throw error;
     }
-    await this.moveLedger(record.id, 'verified', identity.accountId, identity.grantId);
+    // The bytes that were just proven are the bytes this row records, written with the proof itself: a row
+    // that followed its tool's refresh names the store the provider answered for, never the one before it.
+    await this.moveLedger(record.id, 'verified', identity.accountId, identity.grantId, record.sourceDigest);
+    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 },

package/ts/classes.authoritymodels.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import type { TAuthSwitchLoginPrompt } from './authority-contract.js';
+import type { TAuthSwitchClaudeProofFailure, TAuthSwitchLoginPrompt } from './authority-contract.js';
 import type { IAuthSwitchStoredUsage } from './classes.authorityusage.js';
 
 export interface IStoredAuthorityMeta {
@@ -155,6 +155,8 @@ export interface IStoredAuthorityClaudeHandoff {
   sealedOutgoing: string | null;
   runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
   problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
+  /** Which condition of the native-login proof failed; stored, so a lost answer stays diagnosable. */
+  proofFailure: TAuthSwitchClaudeProofFailure | null;
   startedAt: string;
   updatedAt: string;
   revision: number;
@@ -502,7 +504,7 @@ export const assertStoredAuthorityClaudeHandoff: (value: unknown) => asserts val
   if (!object(value) || !exactKeys(value, ['id', 'homeId', 'outgoingAccountId', 'outgoingGrantId',
     'incomingAccountId', 'incomingGrantId', 'phase', 'before', 'after', 'sourceIdentity',
     'targetIdentity', 'sourceAccessDigest', 'targetAccessDigest', 'sealedOutgoing',
-    'runningEffectiveAuth', 'problem', 'startedAt', 'updatedAt', 'revision', 'updateId'])
+    'runningEffectiveAuth', 'problem', 'proofFailure', 'startedAt', 'updatedAt', 'revision', 'updateId'])
     || !uuid(value.id) || !hash(value.homeId) || !hash(value.outgoingAccountId)
     || !hash(value.outgoingGrantId) || !hash(value.incomingAccountId) || !hash(value.incomingGrantId)
     || value.outgoingAccountId === value.incomingAccountId || value.outgoingGrantId === value.incomingGrantId
@@ -514,8 +516,14 @@ export const assertStoredAuthorityClaudeHandoff: (value: unknown) => asserts val
     || !ciphertext(value.sealedOutgoing)
     || ![null, 'no_scoped_sessions', 'unsupported_effective_auth'].includes(value.runningEffectiveAuth as null)
     || !['none', 'native_uncertain', 'foreign_or_torn', 'unsupported_effective_auth', 'database_uncertain'].includes(String(value.problem))
+    || ![null, 'unsupported_release', 'override', 'profile', 'profile_unreadable', 'settings',
+      'subscription', 'running_session'].includes(value.proofFailure as null)
     || !iso(value.startedAt) || !iso(value.updatedAt) || !revision(value.revision)
     || value.revision === 0 || !uuid(value.updateId)) throw new Error('Invalid Claude native handoff.');
+  // The detail belongs to exactly the problem it explains, so a client can trust one without the other.
+  if (value.proofFailure !== null && value.problem !== 'unsupported_effective_auth') {
+    throw new Error('Claude handoff names a proof failure without the problem it explains.');
+  }
   const hasProof = value.before !== null && value.after !== null
     && value.sourceAccessDigest !== null && value.targetAccessDigest !== null;
   const hasNoProof = value.before === null && value.after === null
@@ -838,6 +846,7 @@ export class AuthSwitchAuthorityClaudeHandoffModel extends plugins.nosqldb.Smart
   @plugins.nosqldb.svDb() public sealedOutgoing!: string | null;
   @plugins.nosqldb.svDb() public runningEffectiveAuth!: IStoredAuthorityClaudeHandoff['runningEffectiveAuth'];
   @plugins.nosqldb.svDb() public problem!: IStoredAuthorityClaudeHandoff['problem'];
+  @plugins.nosqldb.svDb() public proofFailure!: IStoredAuthorityClaudeHandoff['proofFailure'];
   @plugins.nosqldb.svDb() public startedAt!: string;
   @plugins.nosqldb.svDb() public updatedAt!: string;
   @plugins.nosqldb.svDb() public revision!: number;

package/ts/classes.authoritypreuse.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchPreuseOperation } from './authority-contract.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
 import { AuthSwitchAuthorityBroker } from './classes.authoritybroker.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
 import type { IStoredAuthorityPreuseOperation, TStoredAuthorityPreuseProblem } from './classes.authoritymodels.js';
@@ -250,7 +251,12 @@ export class AuthSwitchAuthorityPreuse {
   private async readStored(operationId: string): Promise<IStoredAuthorityPreuseOperation> {
     if (!uuid(operationId)) throw new Error('Invalid preuse operation ID.');
     const operation = await this.database.readOperation(operationId);
-    if (!operation || operation.kind !== 'preuse_openai') throw new Error('Preuse operation was not found.');
+    // One site answers both routes that take a preuse operation id, so a read and a cancel of something
+    // this authority does not hold say the same thing in the same code.
+    if (!operation || operation.kind !== 'preuse_openai') {
+      throw new AuthSwitchRefusal('not_found', 'This authority knows no preuse by that operation ID. '
+        + 'Start a new preuse and follow that one.');
+    }
     return operation;
   }
 

package/ts/classes.authorityservice.ts

@@ -1,34 +1,12 @@
 import * as plugins from './plugins.js';
+import { authSwitchAuthorityUnitDirectory, authSwitchAuthorityUnitName,
+  resolveAuthSwitchAuthorityPaths } from './authority-paths.js';
 import { AuthSwitchAuthorityDaemon } from './classes.authoritydaemon.js';
+import type { IClaudeNativeAuthorityOptions } from './classes.claudeauthority.js';
+import { ClaudeNativeAdapter, claudeNativeUserSettingsFiles,
+  resolveClaudeNativeHome } from './classes.claudenative.js';
 
-export interface IAuthSwitchAuthorityPaths {
-  runtimeDirectory: string;
-  dataDirectory: string;
-  databaseSocketPath: string;
-  authoritySocketPath: string;
-  runtimeSocketPath: string;
-  runtimeSocketDirectory: string;
-}
-
-/** Canonical per-user paths. An explicit runtime directory is also usable by a trusted container host. */
-export const resolveAuthSwitchAuthorityPaths = (runtimeDirectory = process.env.XDG_RUNTIME_DIR): IAuthSwitchAuthorityPaths => {
-  if (!runtimeDirectory || !plugins.path.isAbsolute(runtimeDirectory)) {
-    throw new Error('A private XDG_RUNTIME_DIR is required for authswitch authority.');
-  }
-  const home = plugins.os.userInfo().homedir;
-  const dataHome = process.env.XDG_DATA_HOME || plugins.path.join(home, '.local/share');
-  if (!plugins.path.isAbsolute(dataHome)) throw new Error('XDG_DATA_HOME must be an absolute path.');
-  const socketDirectory = plugins.path.join(runtimeDirectory, 'authswitch');
-  const runtimeSocketDirectory = plugins.path.join(socketDirectory, 'runtime');
-  return {
-    runtimeDirectory,
-    dataDirectory: plugins.path.join(dataHome, 'authswitch', 'authority'),
-    databaseSocketPath: plugins.path.join(socketDirectory, 'internal', 'db.sock'),
-    authoritySocketPath: plugins.path.join(socketDirectory, 'management', 'authority.sock'),
-    runtimeSocketPath: plugins.path.join(runtimeSocketDirectory, 'runtime.sock'),
-    runtimeSocketDirectory,
-  };
-};
+export { resolveAuthSwitchAuthorityPaths, type IAuthSwitchAuthorityPaths } from './authority-paths.js';
 
 /** Explicit installer and lifecycle operations for a user-scoped systemd service. */
 export class AuthSwitchAuthorityService {
@@ -36,9 +14,11 @@ export class AuthSwitchAuthorityService {
   public readonly unitFile: plugins.smartdaemon.SystemdUnitFile;
   public readonly definition: plugins.smartdaemon.SystemdServiceDefinition;
 
-  constructor(runtimeDirectory: string, unitDirectory?: string) {
+  /** The unit directory defaults to the one the legacy fence looks in for this user (`./authority-paths`). */
+  constructor(runtimeDirectory: string,
+    unitDirectory = authSwitchAuthorityUnitDirectory(process.env, plugins.os.userInfo().homedir)) {
     const packageRoot = plugins.path.dirname(plugins.path.dirname(plugins.fileURLToPath(import.meta.url)));
-    const options = { unitName: 'authswitch-authority.service', scope: 'user' as const, runtimeDirectory };
+    const options = { unitName: authSwitchAuthorityUnitName, scope: 'user' as const, runtimeDirectory };
     this.unit = new plugins.smartdaemon.SystemdUnit(options);
     this.unitFile = new plugins.smartdaemon.SystemdUnitFile({ ...options, unitDirectory });
     this.definition = new plugins.smartdaemon.SystemdServiceDefinition({
@@ -60,12 +40,44 @@ export class AuthSwitchAuthorityService {
   public stop(): Promise<plugins.smartdaemon.ISystemdUnitState> { return this.unit.stop(); }
 }
 
+/**
+ * The Claude native authority this user's daemon serves.
+ *
+ * It is wired whether or not Claude Code is installed: nothing here touches the filesystem, and every
+ * operation that needs the native home refuses until a verified import receipt has registered it. An
+ * environment that names a home this daemon cannot resolve is a named startup failure rather than a
+ * silently missing capability, because the same environment also decides which file the import reads.
+ */
+export const resolveAuthSwitchClaudeNativeAuthority = (env: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = plugins.os.homedir()): IClaudeNativeAuthorityOptions => {
+  const resolution = resolveClaudeNativeHome(env, homeDirectory);
+  if (resolution.kind === 'unusable') {
+    throw new Error(`Authswitch authority cannot locate Claude Code's native home: ${resolution.defect.problem}.`);
+  }
+  const { configDir, configFile, homeId } = resolution.home;
+  // The adapter re-derives which home Claude Code itself selects; it must read the environment this
+  // home was resolved from, or the two could disagree about the same host. Its settings sources are
+  // stated from that same home: this daemon's working directory is the service unit's own (the package
+  // root, see `AuthSwitchAuthorityService`), so a project settings file beside it selects nothing.
+  return { homeId, adapter: new ClaudeNativeAdapter({ configDir, configFile, env,
+    settingsFiles: claudeNativeUserSettingsFiles(configDir) }) };
+};
+
+/**
+ * The per-user daemon this package installs, and the one place that names this host's own legacy stores.
+ *
+ * Every other construction of `AuthSwitchAuthorityDaemon` -- a test, a consumer's harness, an embedding
+ * backend -- states its own locations or asks for no import surface, because a daemon that defaulted here
+ * would read the credentials of whichever user happened to start it.
+ */
 export const runAuthSwitchAuthorityDaemon = async (paths = resolveAuthSwitchAuthorityPaths()): Promise<void> => {
   const daemon = new AuthSwitchAuthorityDaemon({
     dataDirectory: paths.dataDirectory,
     socketPath: paths.databaseSocketPath,
     authoritySocketPath: paths.authoritySocketPath,
     runtimeSocketPath: paths.runtimeSocketPath,
+    claudeNative: resolveAuthSwitchClaudeNativeAuthority(),
+    legacyImport: { env: process.env, homeDirectory: plugins.os.homedir() },
   });
   await daemon.start();
   await new Promise<void>((resolve, reject) => {

package/ts/classes.claudeauthority.ts

@@ -1,9 +1,11 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchClaudeNativeHandoff } from './authority-contract.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
 import type { IStoredAuthorityAccount, IStoredAuthorityClaudeHandoff, IStoredAuthorityClaudeHome,
   IStoredAuthorityGrant, IStoredAuthorityNativePair } from './classes.authoritymodels.js';
-import { ClaudeNativeAdapter, type IClaudeNativeIdentity, type IClaudeNativeLogin,
+import { ClaudeNativeAdapter, ClaudeNativeEffectiveAuthUnsupportedError,
+  type IClaudeNativeIdentity, type IClaudeNativeLogin,
   type IClaudeNativeLockedSession, type IClaudeNativeSnapshot } from './classes.claudenative.js';
 import { ClaudeTokenRefresh } from './classes.claudetokenrefresh.js';
 import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
@@ -34,6 +36,7 @@ const publicHandoff = (handoff: IStoredAuthorityClaudeHandoff): IAuthSwitchClaud
   id: handoff.id, homeId: handoff.homeId, outgoingAccountId: handoff.outgoingAccountId,
   incomingAccountId: handoff.incomingAccountId, phase: handoff.phase, problem: handoff.problem,
   runningEffectiveAuth: handoff.runningEffectiveAuth, updatedAt: handoff.updatedAt,
+  ...(handoff.proofFailure === null ? {} : { proofFailure: handoff.proofFailure }),
 });
 
 /** Daemon-owned Claude refresh and a journaled transfer of one native home between two grants. */
@@ -137,7 +140,7 @@ export class ClaudeNativeAuthority {
     const account = await this.database.readAccount(grant.accountId);
     if (!account || account.removed) return;
     if (!(await this.database.hasVerifiedClaudeGrantReceipt(account.id, grant.id))) {
-      throw new Error('Claude refresh requires a verified import receipt.');
+      throw new AuthSwitchRefusal('claude_receipt_missing', 'Claude refresh requires a verified import receipt.');
     }
     const login = await this.unsealLogin(account, grant);
     if (rejectedGrantGeneration !== undefined && rejectedGrantGeneration > grant.grantGeneration) {
@@ -229,7 +232,7 @@ export class ClaudeNativeAuthority {
         throw new Error('Inactive Claude status authority changed.');
       }
       if (!(await this.database.hasVerifiedClaudeGrantReceipt(view.account.id, view.grant.id))) {
-        throw new Error('Claude status requires a verified import receipt.');
+        throw new AuthSwitchRefusal('claude_receipt_missing', 'Claude status requires a verified import receipt.');
       }
       const currentLogin = this.statusLogin(view.account, await this.unsealLogin(view.account, view.grant));
       if (!currentLogin.scopes.includes('user:profile')) {
@@ -342,7 +345,7 @@ export class ClaudeNativeAuthority {
         incomingAccountId: incoming.accountId, incomingGrantId: incoming.id, phase: 'reserved',
         before: null, after: null, sourceIdentity: identityFor(outgoingAccount),
         targetIdentity: identityFor(incomingAccount), sourceAccessDigest: null, targetAccessDigest: null,
-        sealedOutgoing: null, runningEffectiveAuth: null, problem: 'none', startedAt: now,
+        sealedOutgoing: null, runningEffectiveAuth: null, problem: 'none', proofFailure: null, startedAt: now,
         updatedAt: now, revision: 1, updateId,
       };
       return { home: this.homeStep(home, updateId, { pendingOperationId: operationId }), handoff,
@@ -369,7 +372,8 @@ export class ClaudeNativeAuthority {
 
   private async settle(operationId: string, phase: 'committed' | 'aborted' | 'quarantined',
     runningEffectiveAuth: IClaudeNativeSnapshot['runningEffectiveAuth'] | null,
-    problem: IStoredAuthorityClaudeHandoff['problem'] = 'none'): Promise<IAuthSwitchClaudeNativeHandoff> {
+    problem: IStoredAuthorityClaudeHandoff['problem'] = 'none',
+    proofFailure: IStoredAuthorityClaudeHandoff['proofFailure'] = null): Promise<IAuthSwitchClaudeNativeHandoff> {
     const context = await this.database.readClaudeHandoffContext(operationId);
     if (!context) throw new Error('Claude handoff operation is missing.');
     if (['committed', 'aborted', 'quarantined'].includes(context.handoff.phase)) return publicHandoff(context.handoff);
@@ -395,7 +399,7 @@ export class ClaudeNativeAuthority {
           : quarantined ? { status: 'quarantined' }
             : { pendingOperationId: null, status: 'ready' }),
         handoff: { ...handoff, phase, sealedOutgoing: quarantined ? handoff.sealedOutgoing : null,
-          runningEffectiveAuth, problem, updatedAt: now, revision: handoff.revision + 1, updateId },
+          runningEffectiveAuth, problem, proofFailure, updatedAt: now, revision: handoff.revision + 1, updateId },
         outgoing: this.grantStep(outgoing, updateId, now, committed
           ? { state: 'ready', owner: 'daemon', ciphertext: handoff.sealedOutgoing,
               accessExpiresAt: outgoingExpiry, problem: 'none',
@@ -448,8 +452,11 @@ export class ClaudeNativeAuthority {
     if (['committed', 'aborted', 'quarantined'].includes(context.handoff.phase)) return publicHandoff(context.handoff);
     try {
       return await this.options.adapter.withExclusiveHome(session => this.classify(operationId, session));
-    } catch {
-      return this.settle(operationId, 'quarantined', null, 'unsupported_effective_auth');
+    } catch (error) {
+      // Which condition of the proof failed is the one thing an owner can act on, so it is journaled
+      // rather than collapsed into the problem it explains.
+      return this.settle(operationId, 'quarantined', null, 'unsupported_effective_auth',
+        error instanceof ClaudeNativeEffectiveAuthUnsupportedError ? error.reason : null);
     }
   }
 
@@ -479,8 +486,13 @@ export class ClaudeNativeAuthority {
 
   private async performSwitch(accountId: string, loginId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
     const home = await this.database.readClaudeHome(this.options.homeId);
+    // Two different answers for the owner: there is no adopted home yet, or one move is already running.
+    if (home && home.status === 'ready' && home.pendingOperationId !== null) {
+      throw new AuthSwitchRefusal('claude_handoff_pending',
+        'A Claude handoff is already running for this home; wait for it to finish, then switch again.');
+    }
     if (!home || home.status !== 'ready' || home.pendingOperationId !== null) {
-      throw new Error('Verified Claude native home is unavailable or has a pending handoff.');
+      throw new AuthSwitchRefusal('claude_home_unregistered', 'Verified Claude native home is unavailable or has a pending handoff.');
     }
     await this.refreshInactiveGrant(loginId);
     const operationId = plugins.crypto.randomUUID();
@@ -517,7 +529,7 @@ export class ClaudeNativeAuthority {
 
   public async getHandoff(operationId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
     const handoff = await this.database.readClaudeHandoff(operationId);
-    if (!handoff || handoff.homeId !== this.options.homeId) throw new Error('Claude handoff operation was not found.');
+    if (!handoff || handoff.homeId !== this.options.homeId) throw new AuthSwitchRefusal('not_found', 'Claude handoff operation was not found.');
     return publicHandoff(handoff);
   }