@modelprofile.com/authswitch 8.2.0 → 9.0.0

package/ts/classes.authoritybroker.ts

@@ -1,6 +1,6 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
-  IAuthSwitchOperation, IAuthSwitchSnapshot } from './authority-contract.js';
+  IAuthSwitchOperation, IAuthSwitchSnapshot, TAuthSwitchLoginOwnerTool } from './authority-contract.js';
 import { AuthSwitchRefusal } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
 import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
@@ -51,14 +51,57 @@ const tokenExpiry = (credential: TOpenAiCredential): string | null => {
   catch { return null; }
 };
 const openAiGrantId = (accountId: string): string => idHash('authswitch-grant-v1', accountId, 'openai_managed', 'chatgpt');
+
+/**
+ * What a caller is told when the answer is decided. Each states the repair and names no id, path or host.
+ *
+ * They are written once because several sites answer the same question: an operation id this authority does
+ * not hold is the same answer whether a read, a cancel or a start met it, and a client that branches on the
+ * code must not have to tell those apart.
+ */
+const unknownOperation = 'This authority knows no device sign-in by that operation ID. '
+  + 'Start a new sign-in and follow that one.';
+const loginNotBindable = 'This login cannot back a runtime binding. The authority must hold the login '
+  + 'itself, it must be the account\'s selected OpenAI login, and it must be ready. Reauthenticate the '
+  + 'account or choose another one.';
+const bindingUnauthorized = 'This runtime binding is not authorized. Bind the account again to obtain a '
+  + 'capability for it.';
+const bindingMoved = 'This runtime binding changed while its credential was being resolved. Bind the '
+  + 'account again.';
+const bindingNeedsReauth = 'The account no longer holds the login this binding was authorized for. '
+  + 'Reauthenticate the account, then bind it again.';
 const publicAccount = (account: IStoredAuthorityAccount): IAuthSwitchAccount => ({
   id: account.id, providerId: account.providerId, label: account.label, email: account.email,
   plan: account.plan, removed: account.removed, revision: account.revision,
   statusObservedAt: account.statusObservedAt,
 });
+
+/**
+ * Which native tool refreshes a grant, decided here because this is the one place that publishes a login.
+ *
+ * `owner` and `purpose` are what the authority stores; the tool is their meaning, and naming it here keeps
+ * every consumer from re-deriving it -- the derivation that is wrong as soon as two purposes share a tool,
+ * or one tool gains a second purpose. `daemon` and `none` have no native refresher at all, which is a value
+ * of its own rather than a missing one.
+ */
+const loginOwnerTool = (grant: IStoredAuthorityGrant): TAuthSwitchLoginOwnerTool | null => {
+  if (grant.owner === 'claude_native') return 'claude_code';
+  if (grant.owner !== 'legacy_native') return null;
+  switch (grant.purpose) {
+    case 'opencode_native': return 'opencode';
+    case 'openai_managed': return 'codex';
+    case 'claude_host_native': return 'claude_code';
+    // A container setup token is held for a container, not refreshed by a tool on this host.
+    case 'claude_container_setup': return null;
+    // A purpose added without deciding its tool fails the type check here rather than publishing `null`,
+    // which would claim the authority refreshes a login some tool actually holds.
+    default: { const unhandledPurpose: never = grant.purpose; return unhandledPurpose; }
+  }
+};
+
 const publicLogin = (grant: IStoredAuthorityGrant): IAuthSwitchLogin => ({
   id: grant.id, accountId: grant.accountId, providerId: grant.providerId, purpose: grant.purpose,
-  owner: grant.owner,
+  owner: grant.owner, ownerTool: loginOwnerTool(grant),
   health: grant.state === 'exchange_may_have_been_sent' ? 'refreshing'
     : grant.state === 'native' ? 'unverified'
       : grant.state === 'legacy_native_pending' || grant.state === 'handoff_pending' ? 'pending_handoff' : grant.state,
@@ -341,7 +384,7 @@ export class AuthSwitchAuthorityBroker {
   private async finishStartingOperation(operationId: string, state: 'failed' | 'interrupted',
     error: string): Promise<IStoredAuthorityDeviceOperation> {
     const current = await this.database.readOperation(operationId);
-    if (!current || current.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+    if (!current || current.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
     if (deviceOperationTerminal(current)) return current;
     if (current.state !== 'starting') throw new Error('Account operation already started its provider login.');
     const updateId = plugins.crypto.randomUUID();
@@ -407,7 +450,7 @@ export class AuthSwitchAuthorityBroker {
     let current: IStoredAuthorityDeviceOperation;
     try {
       const stored = await this.database.readOperation(id);
-      if (!stored || stored.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+      if (!stored || stored.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
       current = stored;
     } catch (error) {
       await Promise.allSettled([handle.cancel(), handle.close()]);
@@ -514,7 +557,7 @@ export class AuthSwitchAuthorityBroker {
   public async getOperation(operationId: string): Promise<IAuthSwitchOperation> {
     if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
     const operation = await this.database.readOperation(operationId);
-    if (!operation || operation.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+    if (!operation || operation.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
     return publicOperation(operation);
   }
 
@@ -538,7 +581,7 @@ export class AuthSwitchAuthorityBroker {
   public async cancelOperation(operationId: string): Promise<IAuthSwitchOperation> {
     if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
     const current = await this.database.readOperation(operationId);
-    if (!current || current.kind === 'preuse_openai') throw new Error('Account operation was not found.');
+    if (!current || current.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
     if (current.state === 'committing') throw new Error('Login is completing; check its operation status.');
     if (current.state !== 'starting' && current.state !== 'pending') return publicOperation(current);
     const updateId = plugins.crypto.randomUUID();
@@ -586,7 +629,7 @@ export class AuthSwitchAuthorityBroker {
         || grant.owner !== 'daemon'
         || grant.purpose !== input.purpose || account.providerId !== 'openai'
         || input.runtime === 'claude') {
-        throw new Error('Account is not available for this runtime.');
+        throw new AuthSwitchRefusal('login_unavailable', loginNotBindable);
       }
       return { id, accountId: input.accountId, grantId: grant.id, runtime: input.runtime, scopeId: input.scopeId,
         incarnationId: input.incarnationId, revision: (existing?.revision ?? 0) + 1,
@@ -624,21 +667,27 @@ export class AuthSwitchAuthorityBroker {
       const current = await this.database.readBindingContext(bindingId);
       const binding = current.binding;
       const expected = Buffer.from(binding?.capabilityHash ?? '0'.repeat(64), 'hex');
+      // A missing binding and a wrong capability are compared against the same zero hash on purpose, so
+      // nothing here tells a caller which it was. One code preserves exactly that, and it is truthful for
+      // both: this capability does not authorize anything, and binding again is the only repair.
       if (!binding || !plugins.crypto.timingSafeEqual(supplied, expected)) {
-        throw new Error('Runtime binding is not authorized.');
+        throw new AuthSwitchRefusal('binding_unauthorized', bindingUnauthorized);
       }
       if (originalBinding && (binding.id !== originalBinding.id
         || binding.capabilityHash !== originalBinding.capabilityHash
         || binding.accountId !== originalBinding.accountId || binding.grantId !== originalBinding.grantId
         || binding.incarnationId !== originalBinding.incarnationId
         || binding.grantAuthorizationGeneration !== originalBinding.grantAuthorizationGeneration)) {
-        throw new Error('Account binding changed during credential resolution.');
+        // The capability still matched, so what moved is the binding itself: another incarnation took the
+        // scope, or the account was reauthorized under it. The caller's repair is the one above -- bind
+        // again -- so it is the same code; a second one would name a difference no runtime can act on.
+        throw new AuthSwitchRefusal('binding_unauthorized', bindingMoved);
       }
       originalBinding ??= binding;
       if (!current.account || current.account.removed || !current.grant
         || current.grant.id !== binding.grantId
         || current.grant.authorizationGeneration !== binding.grantAuthorizationGeneration) {
-        throw new Error('Account needs reauthentication.');
+        throw new AuthSwitchRefusal('login_unavailable', bindingNeedsReauth);
       }
       return { account: current.account, grant: current.grant };
     }, minValidityMs, rejectedGrantGeneration);
@@ -660,6 +709,15 @@ export class AuthSwitchAuthorityBroker {
     }, minValidityMs, rejectedGrantGeneration);
   }
 
+  /**
+   * The shared managed-access loop, whose refusals are deliberately still unmarked faults.
+   *
+   * Its two callers repair differently: a runtime holding a binding binds again, while the usage reader has
+   * no binding at all and collapses everything into one usage problem. Naming a code here would either say
+   * "binding" to a caller that has none, or invent a second meaning for one that does, so the decision waits
+   * for the slice that gives the usage answer its own vocabulary. What a bound runtime can act on is decided
+   * before this point, in the view `resolveAccess` supplies.
+   */
   private async resolveManagedAccess(readView: () => Promise<{
     account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
   }>, minValidityMs: number, rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {

package/ts/classes.authorityclient.ts

@@ -174,8 +174,24 @@ export class AuthSwitchClient {
     if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 50 || heartbeatMs > 30_000) {
       throw new Error('Authswitch subscription heartbeat must be 50–30000 ms.');
     }
+    /**
+     * The pause between reconnection attempts, which never keeps its consumer's process alive.
+     *
+     * A subscription that cannot reach the daemon re-arms this timer for as long as that lasts, and during
+     * each pause it is the only handle this client holds -- the failed request already destroyed its socket.
+     * Referenced, that chain of 250 ms waits would hold an otherwise finished process open indefinitely,
+     * and it has nothing to finish: the wait itself does no work, and an abort clears it.
+     *
+     * An abort that already happened is checked before the timer is armed, because a signal fires once: a
+     * consumer that stops from inside its own disconnect callback aborts between this loop's last check and
+     * this call, and a listener added afterwards would never run. The pause would then be waited out in
+     * full, and since it holds nothing, a process whose only remaining handle it is can exit inside it --
+     * dropping the closing status this loop owes its consumer.
+     */
     const retry = () => new Promise<void>(resolve => {
+      if (signal.aborted) { resolve(); return; }
       const timer = setTimeout(() => { signal.removeEventListener('abort', aborted); resolve(); }, 250);
+      timer.unref();
       const aborted = () => { clearTimeout(timer); resolve(); };
       signal.addEventListener('abort', aborted, { once: true });
     });

package/ts/classes.authoritydaemon.ts

@@ -37,8 +37,39 @@ export interface IAuthSwitchAuthorityDaemonOptions extends IAuthSwitchAuthorityD
   claudeStatus?: ClaudeAccountStatus;
   /** Activated only after a verified backend source receipt has registered the native home. */
   claudeNative?: IClaudeNativeAuthorityOptions;
-  /** Where the one-time import reads the legacy stores. Defaults to this user's own locations. */
-  legacyImport?: IAuthSwitchAuthorityImportOptions;
+  /** Where the one-time import reads the legacy stores, or `'none'`. Never derived from this host here. */
+  legacyImport: TAuthSwitchAuthorityLegacyImport;
+}
+
+/**
+ * Where a daemon's one-time import reads, stated by whoever builds it.
+ *
+ * The legacy stores are this user's real credentials, so which host they are read from is never something a
+ * daemon decides for its caller: it is named, or the daemon is built with no import surface at all.
+ * `AuthSwitchAuthorityService`'s entry point is the one place that may name this host's own locations,
+ * because that is the daemon that exists to serve this host. The importer requires those two locations of
+ * every caller, so naming its options here is already the whole statement.
+ */
+export type TAuthSwitchAuthorityLegacyImport = IAuthSwitchAuthorityImportOptions | 'none';
+
+/** What a caller that named neither is told. It names the two answers and who may take the third. */
+const legacyImportRequired = 'Authswitch authority requires explicit legacy source locations: pass '
+  + 'legacyImport with an env and an absolute homeDirectory, or legacyImport: "none" for a daemon with no '
+  + 'account import. Only the authswitch service entry point may take them from this host.';
+
+/** What the import routes answer on a daemon that was built with no import surface. */
+const legacyImportAbsent = 'This authority was started without legacy source locations, so it serves no '
+  + 'account import.';
+
+/** The same check for a caller with types and one without: stated locations, or stated absence. */
+function assertStatedLegacyImport(value: unknown): asserts value is TAuthSwitchAuthorityLegacyImport {
+  if (value === 'none') return;
+  if (value === null || typeof value !== 'object'
+    || typeof (value as { env?: unknown }).env !== 'object' || (value as { env?: unknown }).env === null
+    || typeof (value as { homeDirectory?: unknown }).homeDirectory !== 'string'
+    || !plugins.path.isAbsolute((value as { homeDirectory: string }).homeDirectory)) {
+    throw new Error(legacyImportRequired);
+  }
 }
 
 const hasKeys = (value: unknown, keys: readonly string[]): value is Record<string, unknown> =>
@@ -83,7 +114,8 @@ export class AuthSwitchAuthorityDaemon {
   public readonly broker: AuthSwitchAuthorityBroker;
   public readonly usage: AuthSwitchAuthorityUsage;
   public readonly preuse: AuthSwitchAuthorityPreuse;
-  public readonly legacyImport: AuthSwitchAuthorityImport;
+  /** Absent on a daemon built with `legacyImport: 'none'`; its import routes then refuse. */
+  public readonly legacyImport?: AuthSwitchAuthorityImport;
   public readonly claudeNative?: ClaudeNativeAuthority;
   private readonly managementRouter = new plugins.typedrequest.TypedRouter();
   private readonly runtimeRouter = new plugins.typedrequest.TypedRouter();
@@ -106,6 +138,10 @@ export class AuthSwitchAuthorityDaemon {
   private closing = false;
 
   constructor(private readonly options: IAuthSwitchAuthorityDaemonOptions) {
+    // First, before anything is constructed: a daemon that was going to read the wrong host's credentials
+    // must not come into existence at all. The type states it and this states it again, because a caller
+    // without types is exactly the caller that would have defaulted here.
+    assertStatedLegacyImport(options.legacyImport);
     this.database = new AuthSwitchAuthorityDatabase(options);
     const provider = options.broker?.provider ?? new plugins.flexAccounts.OpenAiProviderAdapter();
     this.broker = new AuthSwitchAuthorityBroker(this.database, { ...options.broker, provider });
@@ -134,7 +170,9 @@ export class AuthSwitchAuthorityDaemon {
       provider,
     });
     this.preuse = new AuthSwitchAuthorityPreuse(this.database, this.broker, options.preuse);
-    this.legacyImport = new AuthSwitchAuthorityImport(this.database, options.legacyImport);
+    if (options.legacyImport !== 'none') {
+      this.legacyImport = new AuthSwitchAuthorityImport(this.database, options.legacyImport);
+    }
     if (options.claudeNative) {
       this.claudeNative = new ClaudeNativeAuthority(this.database, {
         ...options.claudeNative, onChanged: () => this.broker.notifyChanged(),
@@ -309,6 +347,7 @@ export class AuthSwitchAuthorityDaemon {
         if (request === null || typeof request !== 'object' || Array.isArray(request)
           || Object.keys(request).length !== 0) invalid();
         if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
+        if (!this.legacyImport) throw new AuthSwitchRefusal('import_refusal', legacyImportAbsent);
         return { inventory: await this.legacyImport.inventory() };
       }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchImportStatus>(
@@ -319,6 +358,7 @@ export class AuthSwitchAuthorityDaemon {
           || (request.limit !== undefined && (!Number.isSafeInteger(request.limit)
             || request.limit < 1 || request.limit > 128))) invalid();
         if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
+        if (!this.legacyImport) throw new AuthSwitchRefusal('import_refusal', legacyImportAbsent);
         return { status: await this.legacyImport.status(request) };
       }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchEvents>(
@@ -461,6 +501,7 @@ export class AuthSwitchAuthorityDaemon {
           || request.callerQuiescent !== true || request.acknowledgeRunOrder !== true
           || !validImportSubmission(request.submission)) invalid();
         if (this.closing) throw new AuthSwitchRefusal('authority_closing', 'Authswitch authority is closing.');
+        if (!this.legacyImport) throw new AuthSwitchRefusal('import_refusal', legacyImportAbsent);
         // 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

package/ts/classes.authoritydatabase.ts

@@ -1815,9 +1815,18 @@ export class AuthSwitchAuthorityDatabase {
           throw new Error('Migration completion requires a verified import of the same account and grant.');
         }
         if (current) {
+          // A row may follow its source's current bytes in exactly one state. `pending_native_owner` is a
+          // projection whose own tool still refreshes it: nothing rotating was ever sent for such a row and
+          // the authority holds no copy of its credential, so the file that tool has since rewritten is the
+          // same login and the row must be able to reach it -- otherwise the retry its own refusal asks for
+          // is impossible. It may never change the account or grant it named while doing so, and no other
+          // status may move its digest at all.
+          const followsSource = current.sourceDigest !== draft.sourceDigest;
           if (current.status === 'complete' || current.version !== draft.version
             || current.sourceKind !== draft.sourceKind || current.sourcePathHash !== draft.sourcePathHash
-            || current.sourceDigest !== draft.sourceDigest || draft.revision !== current.revision + 1) {
+            || (followsSource && (current.status !== 'pending_native_owner' || current.accountId === null
+              || current.accountId !== draft.accountId || current.grantId !== draft.grantId))
+            || draft.revision !== current.revision + 1) {
             throw new Error('Migration source identity or terminal status cannot change.');
           }
           const result = await AuthSwitchAuthorityMigrationLedgerModel.exact.transition({

package/ts/classes.authorityimport.ts

@@ -76,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;
@@ -189,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 => ({
@@ -227,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();
@@ -248,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);
@@ -308,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;
@@ -326,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'
@@ -428,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 };
     });
   }
@@ -513,7 +588,9 @@ 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, []);

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,37 +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 {
@@ -39,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({
@@ -86,6 +63,13 @@ export const resolveAuthSwitchClaudeNativeAuthority = (env: NodeJS.ProcessEnv =
     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,
@@ -93,6 +77,7 @@ export const runAuthSwitchAuthorityDaemon = async (paths = resolveAuthSwitchAuth
     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.cli.ts

@@ -4,7 +4,7 @@ import { CodexHarness } from './classes.codexharness.js';
 import { OpenCodeHarness } from './classes.opencodeharness.js';
 import { ClaudeCodeHarness } from './classes.claudecodeharness.js';
 import { AuthSwitchTui } from './classes.tui.js';
-import { AglAuthSwitchCoordinator, AuthSwitchOperations, authSwitchMutationReplacesLogin, type TAuthSwitchCoordinator, type TAuthSwitchMutation } from './classes.operations.js';
+import { AglAuthSwitchCoordinator, AuthSwitchOperations, authSwitchHostLegacyFence, authSwitchMutationReplacesLogin, type TAuthSwitchCoordinator, type TAuthSwitchLegacyFence, type TAuthSwitchMutation } from './classes.operations.js';
 import { readAccountList } from './classes.accountlist.js';
 import { AccountListRenderer } from './classes.listrenderer.js';
 import { accountLimits, activeAccounts, CondensedRenderer } from './classes.limits.js';
@@ -98,9 +98,20 @@ export class AuthSwitchCli {
   private readonly operations: AuthSwitchOperations;
   private get out(): plugins.smartconsole.SmartConsole { return this.console ??= new plugins.smartconsole.SmartConsole(); }
 
-  constructor(harnessesArg?: IAuthHarness[] | CodexSwitcher, coordinatorArg?: TAuthSwitchCoordinator) {
+  /**
+   * `legacyFenceArg` states which authority fences the mutations of injected harnesses.
+   *
+   * With no harnesses this command line is this host's, exactly as its default harnesses and its AGL
+   * coordinator are, and it is fenced by this host's authority. Injected harnesses write whatever stores
+   * their caller chose, so -- like the coordinator -- nothing of this host is assumed for them: they are
+   * fenced only by what the caller states, and by nothing when it states nothing.
+   */
+  constructor(harnessesArg?: IAuthHarness[] | CodexSwitcher, coordinatorArg?: TAuthSwitchCoordinator,
+    legacyFenceArg?: TAuthSwitchLegacyFence) {
     const coordinator = new AglAuthSwitchCoordinator();
-    this.operations = new AuthSwitchOperations(coordinatorArg ?? (harnessesArg === undefined ? request => coordinator.coordinate(request) : undefined));
+    this.operations = new AuthSwitchOperations(
+      coordinatorArg ?? (harnessesArg === undefined ? request => coordinator.coordinate(request) : undefined),
+      legacyFenceArg ?? (harnessesArg === undefined ? authSwitchHostLegacyFence() : 'none'));
     harnessesArg ??= [new CodexHarness(), new OpenCodeHarness(), new ClaudeCodeHarness()];
     // Preserve the published single-Codex constructor at the composition boundary.
     const harnesses = Array.isArray(harnessesArg) ? harnessesArg : [new CodexHarness(harnessesArg)];