@modelprofile.com/authswitch 8.1.0 → 8.2.0

package/ts/classes.authoritydaemon.ts

@@ -10,10 +10,10 @@ 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 { AuthSwitchRefusal } from './authority-contract.js';
 import type { IReq_AuthSwitchImportInventory, IReq_AuthSwitchImportStatus, IReq_AuthSwitchImportSubmit,
   TAuthSwitchImportSubmission } from './authority-import-contract.js';
-import { AuthSwitchAuthorityImport, AuthSwitchImportRefusal,
+import { AuthSwitchAuthorityImport,
   type IAuthSwitchAuthorityImportOptions } from './classes.authorityimport.js';
 import { authSwitchBindingCapabilityHash, AuthSwitchAuthorityBroker,
   type IAuthSwitchAuthorityBrokerOptions } from './classes.authoritybroker.js';
@@ -44,6 +44,8 @@ export interface IAuthSwitchAuthorityDaemonOptions extends IAuthSwitchAuthorityD
 const hasKeys = (value: unknown, keys: readonly string[]): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value)
   && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+// A malformed request is a caller's own bug, not an instruction for an owner, so it stays what it was:
+// its own text, no refusal marker. A client must not present it as something the owner can act on.
 const invalid = (): never => { throw new plugins.typedrequest.TypedResponseError('Invalid authswitch authority request.'); };
 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'
@@ -202,7 +204,7 @@ export class AuthSwitchAuthorityDaemon {
     const prepare = async (): Promise<void> => {
       if (this.closing || this.drainingAccounts.has(request.accountId)
         || this.preuseAccounts.has(request.accountId)) {
-        throw new Error('Account runtime drain is already in progress.');
+        throw new AuthSwitchRefusal('account_busy', 'Account runtime drain is already in progress.');
       }
       this.drainingAccounts.add(request.accountId);
       this.deviceDrainOwners.set(request.accountId, request.operationId);
@@ -229,46 +231,67 @@ export class AuthSwitchAuthorityDaemon {
     });
   }
 
+  /**
+   * One handler, with the only place a refusal becomes a marked answer.
+   *
+   * Both routers register through here, so a handler states its refusal by throwing `AuthSwitchRefusal`
+   * and never touches the wire shape; anything else it throws stays the transport's sanitised fault,
+   * which is what keeps "the outcome is unknown" distinguishable from "here is what to do instead".
+   */
+  private handler<T extends ITypedRequest>(method: T['method'],
+    run: plugins.typedrequest.THandlerFunction<T>): plugins.typedrequest.TypedHandler<T> {
+    return new plugins.typedrequest.TypedHandler<T>(method, async (request, tools) => {
+      try { return await run(request, tools); }
+      catch (error) {
+        if (error instanceof AuthSwitchRefusal) {
+          throw new plugins.typedrequest.TypedResponseError(error.message, error.data);
+        }
+        throw error;
+      }
+    });
+  }
+
   private register(): void {
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchUsage>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchUsage>(
       'authswitch.authority.usage', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)
           || !Object.hasOwn(request, 'accountId') || !Object.hasOwn(request, 'loginId')
           || Object.keys(request).some(key => !['accountId', 'loginId', 'force'].includes(key))
           || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
           || (request.force !== undefined && typeof request.force !== 'boolean')) invalid();
-        if (this.closing) throw new Error('Authswitch authority is closing.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         return { usage: await this.usage.get(request.accountId, request.loginId, request.force ?? false) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchSwitchClaudeNative>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchSwitchClaudeNative>(
       'authswitch.authority.claude.switch', async request => {
         if (!hasKeys(request, ['accountId', 'loginId', 'purpose'])
           || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
           || request.purpose !== 'claude_host_native') invalid();
-        if (this.closing || !this.claudeNative) throw new Error('Claude native handoff is unavailable.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
+        if (!this.claudeNative) throw new AuthSwitchRefusal('claude_home_unregistered', 'Claude native handoff is unavailable.');
         return { handoff: await this.claudeNative.switchTo(request.accountId, request.loginId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchClaudeNativeHandoff>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchClaudeNativeHandoff>(
       'authswitch.authority.claude.handoff', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
-        if (!this.claudeNative) throw new Error('Claude native handoff is unavailable.');
+        if (!this.claudeNative) throw new AuthSwitchRefusal('claude_home_unregistered', 'Claude native handoff is unavailable.');
         return { handoff: await this.claudeNative.getHandoff(request.operationId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchClaudeNativeHandoffs>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchClaudeNativeHandoffs>(
       'authswitch.authority.claude.handoffs', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)
           || Object.keys(request).some(key => !['after', 'limit'].includes(key))) invalid();
-        if (!this.claudeNative) throw new Error('Claude native handoff is unavailable.');
+        if (!this.claudeNative) throw new AuthSwitchRefusal('claude_home_unregistered', 'Claude native handoff is unavailable.');
         return this.claudeNative.listHandoffs(request.after ?? null, request.limit ?? 128);
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchSnapshot>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchSnapshot>(
       'authswitch.authority.snapshot', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)) invalid();
         const keys = Object.keys(request);
         if (keys.some(key => !['accountAfter', 'loginAfter', 'bindingAfter', 'limit'].includes(key))) invalid();
         return { snapshot: await this.broker.snapshot(request) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchDoctor>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchDoctor>(
       'authswitch.authority.doctor', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)) invalid();
         const cursorKeys = ['accountAfter', 'loginAfter', 'codexHomeAfter', 'claudeHomeAfter',
@@ -279,63 +302,63 @@ 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>(
+    this.managementRouter.addTypedHandler(this.handler<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.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         return { inventory: await this.legacyImport.inventory() };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchImportStatus>(
+    this.managementRouter.addTypedHandler(this.handler<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.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         return { status: await this.legacyImport.status(request) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchEvents>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchEvents>(
       'authswitch.authority.events', async (request, tools) => {
         if (!hasKeys(request, ['epoch', 'afterRevision', 'waitMs'])) invalid();
         return this.broker.events(request.epoch, request.afterRevision, request.waitMs, tools?.abortSignal);
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBeginAdd>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchBeginAdd>(
       'authswitch.authority.add', async request => {
         if (!hasKeys(request, ['operationId', 'providerId', 'flow']) || typeof request.operationId !== 'string'
           || request.providerId !== 'openai' || request.flow !== 'device') invalid();
-        if (this.closing) throw new Error('Authswitch authority is closing.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         return { operation: await this.broker.beginAddOpenAi(request.operationId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBeginReauth>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchBeginReauth>(
       'authswitch.authority.reauth', async request => {
         if (!hasKeys(request, ['operationId', 'accountId', 'loginId', 'purpose', 'flow']) || request.flow !== 'device'
           || typeof request.operationId !== 'string'
           || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
           || request.purpose !== 'openai_managed') invalid();
-        if (this.closing) throw new Error('Authswitch authority is closing.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         return { operation: await this.beginReauthOpenAi(request) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchGetOperation>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchGetOperation>(
       'authswitch.authority.operation', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
         return { operation: await this.broker.getOperation(request.operationId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchListOperations>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchListOperations>(
       'authswitch.authority.operations', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)
           || Object.keys(request).some(key => !['after', 'limit'].includes(key))) invalid();
         return this.broker.listOperations(request.after ?? null, request.limit ?? 128);
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchCancelOperation>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchCancelOperation>(
       'authswitch.authority.cancel', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
         return { operation: await this.broker.cancelOperation(request.operationId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchStartPreuse>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchStartPreuse>(
       'authswitch.authority.preuse.start', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)
           || !['operationId', 'accountId', 'loginId', 'purpose', 'prompt'].every(key => Object.hasOwn(request, key))
@@ -344,7 +367,7 @@ export class AuthSwitchAuthorityDaemon {
           || typeof request.loginId !== 'string' || request.purpose !== 'openai_managed'
           || typeof request.prompt !== 'string'
           || (request.model !== undefined && typeof request.model !== 'string')) invalid();
-        if (this.closing) throw new Error('Authswitch authority is closing.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         const reservation: IPreuseAccountReservation = { operationId: request.operationId };
         let ownsReservation = false;
         const release = (): void => {
@@ -371,28 +394,28 @@ export class AuthSwitchAuthorityDaemon {
           throw error;
         }
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchGetPreuse>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchGetPreuse>(
       'authswitch.authority.preuse.operation', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
         return { operation: await this.preuse.get(request.operationId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchCancelPreuse>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchCancelPreuse>(
       'authswitch.authority.preuse.cancel', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
         return { operation: await this.preuse.cancel(request.operationId) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchRenameAccount>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchRenameAccount>(
       'authswitch.authority.rename', async request => {
         if (!hasKeys(request, ['accountId', 'expectedRevision', 'label']) || typeof request.accountId !== 'string'
           || typeof request.expectedRevision !== 'number' || typeof request.label !== 'string') invalid();
         return { account: await this.broker.renameAccount(request.accountId, request.expectedRevision, request.label) };
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchRemoveAccount>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchRemoveAccount>(
       'authswitch.authority.remove', async request => {
         if (!hasKeys(request, ['accountId', 'expectedRevision']) || typeof request.accountId !== 'string'
           || typeof request.expectedRevision !== 'number') invalid();
         if (this.drainingAccounts.has(request.accountId) || this.preuseAccounts.has(request.accountId)) {
-          throw new Error('Account runtime drain is already in progress.');
+          throw new AuthSwitchRefusal('account_busy', 'Account runtime drain is already in progress.');
         }
         this.drainingAccounts.add(request.accountId);
         try {
@@ -400,7 +423,7 @@ export class AuthSwitchAuthorityDaemon {
           return { account: await this.broker.removeAccount(request.accountId, request.expectedRevision) };
         } finally { this.drainingAccounts.delete(request.accountId); }
       }));
-    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBindAccount>(
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchBindAccount>(
       'authswitch.authority.bind', async request => {
         if (!hasKeys(request, ['accountId', 'loginId', 'purpose', 'runtime', 'scopeId', 'incarnationId'])
           || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
@@ -408,7 +431,7 @@ export class AuthSwitchAuthorityDaemon {
           || typeof request.incarnationId !== 'string') invalid();
         return this.broker.bindAccount(request);
       }));
-    this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchResolveAccess>(
+    this.runtimeRouter.addTypedHandler(this.handler<IReq_AuthSwitchResolveAccess>(
       'authswitch.authority.resolveAccess', async request => {
         if ((typeof request !== 'object' || request === null || Array.isArray(request))
           || !['bindingId', 'capability', 'minValidityMs'].every(key => Object.hasOwn(request, key))
@@ -417,41 +440,33 @@ export class AuthSwitchAuthorityDaemon {
           || !validBindingId(request.bindingId) || !validBindingCapability(request.capability)
           || typeof request.minValidityMs !== 'number'
           || (request.rejectedGrantGeneration !== undefined && typeof request.rejectedGrantGeneration !== 'number')) invalid();
-        if (this.closing) throw new Error('Authswitch authority is closing.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         const finish = this.beginRuntimeBindingAccess(this.runtimeBindingKey(request.bindingId, request.capability));
         try {
           return await this.broker.resolveAccess(request.bindingId, request.capability, request.minValidityMs,
             request.rejectedGrantGeneration);
         } finally { finish(); }
       }));
-    this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchReleaseBinding>(
+    this.runtimeRouter.addTypedHandler(this.handler<IReq_AuthSwitchReleaseBinding>(
       'authswitch.authority.release', async request => {
         if (!hasKeys(request, ['bindingId', 'capability'])
           || !validBindingId(request.bindingId) || !validBindingCapability(request.capability)) invalid();
-        if (this.closing) throw new Error('Authswitch authority is closing.');
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
         return this.releaseRuntimeBinding(request.bindingId, request.capability);
       }));
-    this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchImportSubmit>(
+    this.runtimeRouter.addTypedHandler(this.handler<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;
-        }
+        if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
+        // An importer refusal is an `AuthSwitchRefusal` like every other, so the one conversion in
+        // `handler()` marks it. What stays special is its meaning: an UNMARKED failure of this route
+        // leaves the import outcome unknown, and the source must be read with `import.status` rather
+        // than submitted again.
+        return { result: await this.legacyImport.submit({ submission: request.submission,
+          callerQuiescent: true, acknowledgeRunOrder: true }) };
       }));
   }
 
@@ -593,13 +608,13 @@ export class AuthSwitchAuthorityDaemon {
         const run = home.activeRun;
         if (!run) continue;
         const survivor = await findManagedCodexProcess(run.socketPath);
-        if (survivor) throw new Error('A managed Codex app-server still owns this account; stop its work before changing the account.');
+        if (survivor) throw new AuthSwitchRefusal('account_busy', 'A managed Codex app-server still owns this account; stop its work before changing the account.');
         if (run.pid === null || run.startedAt === null) {
-          throw new Error('A managed Codex launch has uncertain process ownership; reconcile it before changing the account.');
+          throw new AuthSwitchRefusal('account_busy', 'A managed Codex launch has uncertain process ownership; reconcile it before changing the account.');
         }
         try {
           process.kill(run.pid, 0);
-          throw new Error('A managed Codex process identity is still present; reconcile it before changing the account.');
+          throw new AuthSwitchRefusal('account_busy', 'A managed Codex process identity is still present; reconcile it before changing the account.');
         } catch (error) {
           if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH')) throw error;
         }

package/ts/classes.authoritydatabase.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
 import {
   AuthSwitchAuthorityAccountModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityClaudeHandoffModel,
   AuthSwitchAuthorityClaudeHomeModel, AuthSwitchAuthorityCodexHomeModel, AuthSwitchAuthorityEnrollmentModel,
@@ -358,7 +359,7 @@ export class AuthSwitchAuthorityDatabase {
             || account.primaryGrantId !== intent.grantId || !grant || grant.accountId !== intent.accountId
             || grant.providerId !== 'openai' || grant.purpose !== 'openai_managed'
             || grant.owner !== 'daemon' || ['removed', 'exchange_may_have_been_sent'].includes(grant.state)) {
-            throw new Error('Selected OpenAI login is unavailable for reauthentication.');
+            throw new AuthSwitchRefusal('login_unavailable', 'Selected OpenAI login is unavailable for reauthentication.');
           }
           expectedGrantGeneration = grant.grantGeneration;
         }
@@ -1038,9 +1039,9 @@ export class AuthSwitchAuthorityDatabase {
         if (accountStored && accountStored.primaryGrantId !== grantId) {
           throw new Error('Primary grant identity cannot be replaced.');
         }
-        if (grantStored && ['legacy_native', 'claude_native'].includes(grantStored.owner)
-          && draft.grant.owner === 'daemon') {
-          throw new Error('Native ownership requires a verified handoff.');
+        // A device login commits daemon ownership; it is no proof that a native owner has stopped refreshing.
+        if (grantStored && transfersGrantRefresher(grantStored.owner, draft.grant.owner)) {
+          throw new Error(grantRefresherTransferRefusal(grantStored.owner, draft.grant.owner));
         }
         const completed: IStoredAuthorityDeviceOperation = {
           ...operation, state: 'complete', prompt: null,
@@ -1093,10 +1094,14 @@ export class AuthSwitchAuthorityDatabase {
         if (draft.id !== grantId || draft.accountId !== account.id || draft.updateId !== updateId) {
           throw new Error('Grant change has an invalid identity.');
         }
+        // This writer carries no handoff proof, so it may only move a grant within the ownership it already has.
+        if (transfersGrantRefresher(grant.owner, draft.owner)) {
+          throw new Error(grantRefresherTransferRefusal(grant.owner, draft.owner));
+        }
         if (grant.purpose === 'claude_host_native' && draft.state === 'exchange_may_have_been_sent'
           && grant.state !== 'exchange_may_have_been_sent'
           && !(await this.hasVerifiedClaudeGrantReceipt(account.id, grant.id, session))) {
-          throw new Error('Claude refresh requires a verified import receipt.');
+          throw new AuthSwitchRefusal('claude_receipt_missing', 'Claude refresh requires a verified import receipt.');
         }
         const accountDraft: IStoredAuthorityAccount = { ...account, revision: account.revision + 1,
           statusObservedAt: draft.statusObservedAt, updateId };
@@ -1166,7 +1171,7 @@ export class AuthSwitchAuthorityDatabase {
         const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
         const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
         if (!metaStored || !accountStored || accountStored.removed || accountStored.revision !== expectedRevision) {
-          throw new Error('Account changed; refresh before removing.');
+          throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before removing.');
         }
         const account = AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored);
         const scan = async (visit: (grant: IStoredAuthorityGrant,
@@ -1185,13 +1190,13 @@ export class AuthSwitchAuthorityDatabase {
         await scan(async grant => {
           if (grant.state === 'removed') return;
           if (grant.owner === 'claude_native' || grant.owner === 'legacy_native') {
-            throw new Error('Stop the native owner and complete its handoff before removing this account.');
+            throw new AuthSwitchRefusal('native_owner_holds_login', 'Stop the native owner and complete its handoff before removing this account.');
           }
           if (grant.state === 'exchange_may_have_been_sent') {
-            throw new Error('Wait for the account refresh to finish before removing it.');
+            throw new AuthSwitchRefusal('account_busy', 'Wait for the account refresh to finish before removing it.');
           }
           if (['handoff_pending', 'handoff_quarantined'].includes(grant.state)) {
-            throw new Error('Resolve the Claude native handoff before removing this account.');
+            throw new AuthSwitchRefusal('claude_handoff_pending', 'Resolve the Claude native handoff before removing this account.');
           }
         });
         await scan(async (grant, stored) => {
@@ -1530,7 +1535,15 @@ export class AuthSwitchAuthorityDatabase {
     return { handoffs, nextCursor: stored.length > limit ? handoffs.at(-1)!.id : null };
   }
 
-  /** Only a verified backend import receipt may adopt a native home. No startup autodiscovery exists. */
+  /**
+   * Only a verified backend import receipt may adopt a native home. No startup autodiscovery exists.
+   *
+   * `import.submit` is the one route that reaches this, so its two decided outcomes -- a home another grant
+   * holds, and a login another home already holds -- answer with the importer's published code: the
+   * transaction refused, the ledger row stays `verified` and nothing rotating was sent, while an unmarked
+   * failure of that route means the outcome is unknown and the source must be read with `import.status`
+   * instead. The ambiguous write below keeps that unmarked meaning, because it genuinely is unknown.
+   */
   public async registerClaudeHomeFromReceipt(input: { homeId: string; accountId: string; grantId: string;
     receiptId: string; sourceDigest: string; accountUuid: string; organizationUuid: string;
     updateId: string; now: string }): Promise<IStoredAuthorityClaudeHome> {
@@ -1558,7 +1571,7 @@ export class AuthSwitchAuthorityDatabase {
         }
         if (current) {
           if (current.activeAccountId !== accountId || current.activeGrantId !== grantId) {
-            throw new Error('Claude native home belongs to another grant.');
+            throw new AuthSwitchRefusal('import_refusal', 'Claude native home belongs to another grant.');
           }
           return AuthSwitchAuthorityClaudeHomeModel.exact.toPersisted(current);
         }
@@ -1575,6 +1588,11 @@ export class AuthSwitchAuthorityDatabase {
         || !['ambiguous_write', 'unique_conflict'].includes(error.code)) throw error;
       const home = await this.readClaudeHome(homeId);
       if (home?.updateId === updateId && home.activeAccountId === accountId && home.activeGrantId === grantId) return home;
+      // One grant, one home: the unique index refused a second home for a login another one already holds.
+      if (error.code === 'unique_conflict') {
+        throw new AuthSwitchRefusal('import_refusal',
+          'This Claude login is already registered to another native home.');
+      }
       throw new Error('Claude native home registration outcome is unknown.');
     }
   }

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';
@@ -168,8 +169,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); };
@@ -504,10 +514,28 @@ export class AuthSwitchAuthorityImport {
       throw error;
     }
     await this.moveLedger(record.id, 'verified', identity.accountId, identity.grantId);
+    if (record.sourceKind === 'claude_native') await this.adoptClaudeHome(record, identity);
     await this.moveLedger(record.id, 'complete', identity.accountId, identity.grantId);
     return this.result(record, 'complete', identity, []);
   }
 
+  /**
+   * Adopts the native Claude home this source is, so the daemon may serve `claude.*` for it.
+   *
+   * The verified receipt is the only thing that may adopt a home, and the source id it was earned with is
+   * the home id, so nothing else has to be trusted here. Re-submitting the same source returns the same
+   * home record rather than writing a second one.
+   */
+  private async adoptClaudeHome(record: ILegacySourceRecord,
+    identity: { accountId: string; subject: string; workspaceId: string; grantId: string }): Promise<void> {
+    await this.database.registerClaudeHomeFromReceipt({
+      homeId: record.sourcePathHash, accountId: identity.accountId, grantId: identity.grantId,
+      receiptId: record.id, sourceDigest: record.sourceDigest,
+      accountUuid: identity.subject, organizationUuid: identity.workspaceId,
+      updateId: plugins.crypto.randomUUID(), now: this.stamp(),
+    });
+  }
+
   /** The non-rotating proof: the stored access token is asked about itself and must name this account. */
   private async proveWithoutRotation(record: ILegacySourceRecord,
     identity: { accountId: string; subject: string; workspaceId: string },

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.authorityservice.ts

@@ -1,5 +1,8 @@
 import * as plugins from './plugins.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;
@@ -60,12 +63,36 @@ 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) }) };
+};
+
 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(),
   });
   await daemon.start();
   await new Promise<void>((resolve, reject) => {