@modelprofile.com/authswitch 6.4.0 → 7.0.0

package/ts/classes.claudeauthority.ts

@@ -0,0 +1,541 @@
+import * as plugins from './plugins.js';
+import type { IAuthSwitchClaudeNativeHandoff } 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,
+  type IClaudeNativeLockedSession, type IClaudeNativeSnapshot } from './classes.claudenative.js';
+import { ClaudeTokenRefresh } from './classes.claudetokenrefresh.js';
+import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
+import type { IClaudeLogin } from './classes.claudestatus.js';
+import type { IAuthSwitchUsageContext, IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
+
+export interface IClaudeNativeAuthorityOptions {
+  homeId: string;
+  adapter: ClaudeNativeAdapter;
+  secrets?: IAuthSwitchSecretCodec;
+  refresh?: ClaudeTokenRefresh;
+  now?: () => number;
+  onChanged?: () => void;
+}
+
+type TClaudeChange = Parameters<AuthSwitchAuthorityDatabase['changeClaudeHandoff']>[0]['change'];
+
+const hash = (value: string): string => plugins.crypto.createHash('sha256').update(value).digest('hex');
+const isHash = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const sameIdentity = (left: IClaudeNativeIdentity | null, right: IClaudeNativeIdentity): boolean =>
+  left?.accountUuid === right.accountUuid && left.organizationUuid === right.organizationUuid;
+const samePair = (left: IStoredAuthorityNativePair, right: IStoredAuthorityNativePair): boolean =>
+  left.credentialDigest === right.credentialDigest && left.configDigest === right.configDigest;
+const identityFor = (account: IStoredAuthorityAccount): IClaudeNativeIdentity => ({
+  accountUuid: account.subject, organizationUuid: account.workspaceId,
+});
+const publicHandoff = (handoff: IStoredAuthorityClaudeHandoff): IAuthSwitchClaudeNativeHandoff => ({
+  id: handoff.id, homeId: handoff.homeId, outgoingAccountId: handoff.outgoingAccountId,
+  incomingAccountId: handoff.incomingAccountId, phase: handoff.phase, problem: handoff.problem,
+  runningEffectiveAuth: handoff.runningEffectiveAuth, updatedAt: handoff.updatedAt,
+});
+
+/** Daemon-owned Claude refresh and a journaled transfer of one native home between two grants. */
+export class ClaudeNativeAuthority {
+  private readonly secrets: IAuthSwitchSecretCodec;
+  private readonly refresh: ClaudeTokenRefresh;
+  private readonly now: () => number;
+  private readonly activeRefreshes = new Map<string, Promise<void>>();
+  private readonly activeHandoffs = new Set<Promise<IAuthSwitchClaudeNativeHandoff>>();
+  private closed = false;
+
+  constructor(private readonly database: AuthSwitchAuthorityDatabase,
+    private readonly options: IClaudeNativeAuthorityOptions) {
+    if (!isHash(options.homeId)) throw new Error('Invalid configured Claude native home ID.');
+    this.secrets = options.secrets ?? new AuthSwitchTpmSecretCodec();
+    this.refresh = options.refresh ?? new ClaudeTokenRefresh();
+    this.now = options.now ?? Date.now;
+  }
+
+  private timestamp(): string { return new Date(this.now()).toISOString(); }
+  private changed(): void { this.options.onChanged?.(); }
+  private eventIds(): readonly [string, string] { return [plugins.crypto.randomUUID(), plugins.crypto.randomUUID()]; }
+  private grantStep(grant: IStoredAuthorityGrant, updateId: string, now: string,
+    changes: Partial<IStoredAuthorityGrant> = {}): IStoredAuthorityGrant {
+    return { ...grant, ...changes, revision: grant.revision + 1, statusObservedAt: now, updateId };
+  }
+  private homeStep(home: IStoredAuthorityClaudeHome, updateId: string,
+    changes: Partial<IStoredAuthorityClaudeHome>): IStoredAuthorityClaudeHome {
+    return { ...home, ...changes, revision: home.revision + 1, updateId };
+  }
+
+  private async sealLogin(grantId: string, login: IClaudeNativeLogin): Promise<string> {
+    const bytes = Buffer.from(JSON.stringify(login), 'utf8');
+    try { return await this.secrets.seal(grantId, bytes); }
+    finally { bytes.fill(0); }
+  }
+
+  private async unsealLogin(account: IStoredAuthorityAccount, grant: IStoredAuthorityGrant): Promise<IClaudeNativeLogin> {
+    if (grant.owner !== 'daemon' || grant.purpose !== 'claude_host_native' || grant.accountId !== account.id
+      || !grant.ciphertext) throw new Error('Claude grant is not available to the daemon.');
+    const bytes = await this.secrets.unseal(grant.id, grant.ciphertext);
+    try {
+      const value: unknown = JSON.parse(Buffer.from(bytes).toString('utf8'));
+      if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
+      const candidate = value as Record<string, unknown>;
+      if (!candidate.claudeAiOauth || typeof candidate.claudeAiOauth !== 'object'
+        || Array.isArray(candidate.claudeAiOauth) || !candidate.oauthAccount
+        || typeof candidate.oauthAccount !== 'object' || Array.isArray(candidate.oauthAccount)) throw new Error();
+      const login: IClaudeNativeLogin = {
+        claudeAiOauth: candidate.claudeAiOauth as Record<string, unknown>,
+        oauthAccount: candidate.oauthAccount as Record<string, unknown>,
+      };
+      if (login.oauthAccount.accountUuid !== account.subject
+        || login.oauthAccount.organizationUuid !== account.workspaceId) throw new Error();
+      return login;
+    } catch { throw new Error('Sealed Claude grant is invalid or belongs to another account.'); }
+    finally { bytes.fill(0); }
+  }
+
+  private async change(operationId: string, incomingGrantId: string,
+    make: (current: Parameters<TClaudeChange>[0], updateId: string) => ReturnType<TClaudeChange>) {
+    const updateId = plugins.crypto.randomUUID();
+    const result = await this.database.changeClaudeHandoff({ operationId, homeId: this.options.homeId,
+      incomingGrantId, updateId, eventIds: this.eventIds(), change: current => make(current, updateId) });
+    this.changed();
+    return result;
+  }
+
+  public async start(): Promise<void> {
+    await this.database.assertOpenAdmission();
+    await this.reconcilePending();
+  }
+
+  public async refreshInactiveGrant(grantId: string, rejectedGrantGeneration?: number,
+    minValidityMs = 300_000,
+    expectedGrant?: Pick<IStoredAuthorityGrant, 'revision' | 'grantGeneration' | 'ciphertext'>): Promise<void> {
+    await this.database.assertOpenAdmission();
+    if (!isHash(grantId) || this.closed || !Number.isSafeInteger(minValidityMs)
+      || minValidityMs < 0 || minValidityMs > 3_600_000
+      || (rejectedGrantGeneration !== undefined && (!Number.isSafeInteger(rejectedGrantGeneration)
+        || rejectedGrantGeneration < 1))) throw new Error('Invalid or closed Claude refresh request.');
+    const existing = this.activeRefreshes.get(grantId);
+    if (existing) return existing;
+    const task = this.performRefresh(grantId, rejectedGrantGeneration, minValidityMs, expectedGrant).finally(() => {
+      if (this.activeRefreshes.get(grantId) === task) this.activeRefreshes.delete(grantId);
+    });
+    this.activeRefreshes.set(grantId, task);
+    return task;
+  }
+
+  private async performRefresh(grantId: string, rejectedGrantGeneration?: number,
+    minValidityMs = 300_000,
+    expectedGrant?: Pick<IStoredAuthorityGrant, 'revision' | 'grantGeneration' | 'ciphertext'>): Promise<void> {
+    const grant = await this.database.readGrant(grantId);
+    if (expectedGrant && (!grant || grant.revision !== expectedGrant.revision
+      || grant.grantGeneration !== expectedGrant.grantGeneration
+      || grant.ciphertext !== expectedGrant.ciphertext)) {
+      throw new Error('Claude grant changed before status refresh.');
+    }
+    if (!grant || grant.purpose !== 'claude_host_native' || grant.owner !== 'daemon'
+      || !['ready', 'retry_wait'].includes(grant.state)
+      || (grant.state === 'retry_wait' && (grant.retryAt === null || Date.parse(grant.retryAt) > this.now()))) return;
+    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 and backup receipt.');
+    }
+    const login = await this.unsealLogin(account, grant);
+    if (rejectedGrantGeneration !== undefined && rejectedGrantGeneration > grant.grantGeneration) {
+      throw new Error('Claude rejected a future grant generation.');
+    }
+    if (!this.refresh.due(login.claudeAiOauth, minValidityMs)
+      && rejectedGrantGeneration !== grant.grantGeneration) return;
+    const attemptId = plugins.crypto.randomUUID();
+    await this.database.changeGrant(attemptId, grant.id, current => {
+      if (current.revision !== grant.revision || current.state !== grant.state
+        || current.owner !== 'daemon' || current.grantGeneration !== grant.grantGeneration) {
+        throw new Error('Claude grant changed before refresh began.');
+      }
+      return { ...current, state: 'exchange_may_have_been_sent', attemptId, retryAt: null,
+        revision: current.revision + 1, statusObservedAt: this.timestamp(), updateId: attemptId };
+    });
+    this.changed();
+    const outcome = await this.refresh.refreshForAuthority(login.claudeAiOauth);
+    if (!outcome.success) {
+      const updateId = plugins.crypto.randomUUID();
+      const retry = outcome.requestOutcome === 'notSent' && outcome.reason === 'provider_unavailable';
+      await this.database.changeGrant(updateId, grant.id, current => {
+        if (current.state !== 'exchange_may_have_been_sent' || current.attemptId !== attemptId) {
+          throw new Error('Claude grant changed during refresh.');
+        }
+        return { ...current, state: retry ? 'retry_wait' : 'needs_reauth', attemptId: null,
+          retryAt: retry ? new Date(this.now() + Math.min(30_000 * 2 ** Math.min(current.retryCount, 10), 1_800_000)).toISOString() : null,
+          retryCount: retry ? current.retryCount + 1 : current.retryCount,
+          problem: retry ? 'provider_unavailable' : 'exchange_uncertain',
+          revision: current.revision + 1, statusObservedAt: this.timestamp(), updateId };
+      });
+      this.changed();
+      return;
+    }
+    const refreshed: IClaudeNativeLogin = { oauthAccount: login.oauthAccount,
+      claudeAiOauth: { ...login.claudeAiOauth, ...outcome.tokens } };
+    const ciphertext = await this.sealLogin(grant.id, refreshed);
+    const updateId = plugins.crypto.randomUUID();
+    try {
+      await this.database.changeGrant(updateId, grant.id, current => {
+        if (current.state !== 'exchange_may_have_been_sent' || current.attemptId !== attemptId) {
+          throw new Error('Claude grant changed during refresh commit.');
+        }
+        return { ...current, state: 'ready', attemptId: null, retryAt: null, retryCount: 0,
+          problem: 'none', ciphertext, accessExpiresAt: new Date(outcome.tokens.expiresAt).toISOString(),
+          grantGeneration: current.grantGeneration + 1, revision: current.revision + 1,
+          statusObservedAt: this.timestamp(), updateId };
+      });
+      this.changed();
+    } catch {
+      // The pre-send marker is durable. Startup makes an unresolved rotation needs_reauth.
+      throw new Error('Claude refresh commit is uncertain; the previous token will not be replayed.');
+    }
+  }
+
+  private statusLogin(account: IStoredAuthorityAccount, login: IClaudeNativeLogin): IClaudeLogin {
+    const oauth = login.claudeAiOauth;
+    if (typeof oauth.accessToken !== 'string' || !oauth.accessToken
+      || typeof oauth.expiresAt !== 'number' || !Number.isFinite(oauth.expiresAt)
+      || !Array.isArray(oauth.scopes) || !oauth.scopes.every(scope => typeof scope === 'string')
+      || login.oauthAccount.accountUuid !== account.subject
+      || login.oauthAccount.organizationUuid !== account.workspaceId) {
+      throw new Error('Claude status login is incomplete or belongs to another account.');
+    }
+    return { accessToken: oauth.accessToken, scopes: [...oauth.scopes],
+      identity: identityFor(account),
+      ...(typeof oauth.subscriptionType === 'string' ? { plan: oauth.subscriptionType }
+        : account.plan ? { plan: account.plan } : {}) };
+  }
+
+  /** Backend-only inactive access. Only this owner may rotate, with a durable pre-send marker. */
+  public async resolveInactiveStatusLogin(context: IAuthSwitchUsageContext,
+    rejectedGrantGeneration: number | undefined, minValidityMs: number): Promise<{
+      login: IClaudeLogin; grantGeneration: number; expiresAt: string | null;
+    }> {
+    if (this.closed || !isHash(context.accountId) || !isHash(context.loginId)
+      || !Number.isSafeInteger(minValidityMs) || minValidityMs < 0 || minValidityMs > 3_600_000) {
+      throw new Error('Invalid or closed Claude status request.');
+    }
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const view = await this.database.readUsageAccessView(context.accountId, context.loginId);
+      if (!view || view.context.epoch !== context.epoch
+        || view.context.authorizationGeneration !== context.authorizationGeneration
+        || view.account.subject !== context.subjectId
+        || view.account.workspaceId !== context.workspaceId || view.account.removed
+        || view.account.providerId !== 'anthropic' || view.grant.providerId !== 'anthropic'
+        || view.grant.purpose !== 'claude_host_native' || view.grant.owner !== 'daemon'
+        || !['ready', 'retry_wait'].includes(view.grant.state)) {
+        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 and backup receipt.');
+      }
+      const currentLogin = this.statusLogin(view.account, await this.unsealLogin(view.account, view.grant));
+      if (!currentLogin.scopes.includes('user:profile')) {
+        const confirmed = await this.database.readUsageAccessView(context.accountId, context.loginId);
+        if (!confirmed || confirmed.context.epoch !== context.epoch
+          || confirmed.context.authorizationGeneration !== context.authorizationGeneration
+          || confirmed.account.subject !== view.account.subject
+          || confirmed.account.workspaceId !== view.account.workspaceId || confirmed.account.removed
+          || confirmed.grant.revision !== view.grant.revision
+          || confirmed.grant.grantGeneration !== view.grant.grantGeneration
+          || confirmed.grant.ciphertext !== view.grant.ciphertext
+          || confirmed.grant.owner !== 'daemon' || !['ready', 'retry_wait'].includes(confirmed.grant.state)) {
+          continue;
+        }
+        return { login: currentLogin, grantGeneration: view.grant.grantGeneration,
+          expiresAt: view.grant.accessExpiresAt };
+      }
+      await this.refreshInactiveGrant(view.grant.id, rejectedGrantGeneration, minValidityMs, view.grant);
+      const latest = await this.database.readUsageAccessView(context.accountId, context.loginId);
+      if (!latest || latest.context.epoch !== context.epoch
+        || latest.context.authorizationGeneration !== context.authorizationGeneration
+        || latest.account.subject !== context.subjectId
+        || latest.account.subject !== view.account.subject
+        || latest.account.workspaceId !== view.account.workspaceId || latest.account.removed
+        || latest.grant.owner !== 'daemon' || latest.grant.purpose !== 'claude_host_native'
+        || !['ready', 'retry_wait'].includes(latest.grant.state)) {
+        throw new Error('Inactive Claude status authority changed during refresh.');
+      }
+      const expiresAt = latest.grant.accessExpiresAt;
+      if (!expiresAt || Date.parse(expiresAt) <= this.now() + minValidityMs
+        || (rejectedGrantGeneration !== undefined
+          && latest.grant.grantGeneration <= rejectedGrantGeneration)) continue;
+      const login = this.statusLogin(latest.account, await this.unsealLogin(latest.account, latest.grant));
+      const confirmed = await this.database.readUsageAccessView(context.accountId, context.loginId);
+      if (!confirmed || confirmed.context.epoch !== context.epoch
+        || confirmed.context.authorizationGeneration !== context.authorizationGeneration
+        || confirmed.account.subject !== latest.account.subject
+        || confirmed.account.workspaceId !== latest.account.workspaceId
+        || confirmed.grant.revision !== latest.grant.revision
+        || confirmed.grant.grantGeneration !== latest.grant.grantGeneration
+        || confirmed.grant.ciphertext !== latest.grant.ciphertext
+        || confirmed.grant.owner !== 'daemon' || !['ready', 'retry_wait'].includes(confirmed.grant.state)) {
+        continue;
+      }
+      return { login, grantGeneration: latest.grant.grantGeneration, expiresAt };
+    }
+    throw new Error('Inactive Claude status credential is not safely available.');
+  }
+
+  /** Keep the exact native source and qualified vendor locks through status GET and publication. */
+  public async withNativeUsageSource(context: IAuthSwitchUsageContext,
+    action: (source: { context: IAuthSwitchUsageContext; login: IClaudeLogin;
+      readContext(): Promise<IAuthSwitchUsageContext | null> }) => Promise<IAuthSwitchUsageSnapshot>): Promise<IAuthSwitchUsageSnapshot> {
+    if (this.closed || !isHash(context.accountId) || !isHash(context.loginId)) {
+      throw new Error('Invalid or closed Claude native status request.');
+    }
+    await this.database.assertOpenAdmission();
+    return this.options.adapter.withExclusiveHome(async session => {
+      const inspect = async (): Promise<{ context: IAuthSwitchUsageContext; login: IClaudeLogin } | null> => {
+        const view = await this.database.readClaudeNativeUsageView(this.options.homeId,
+          context.accountId, context.loginId);
+        if (!view || view.context.epoch !== context.epoch
+          || view.context.authorizationGeneration !== context.authorizationGeneration
+          || view.context.grantGeneration !== context.grantGeneration
+          || view.account.subject !== context.subjectId
+          || view.account.workspaceId !== context.workspaceId) return null;
+        const snapshot = session.readStable();
+        if (!snapshot.login || !snapshot.identity || !snapshot.credentialDigest || !snapshot.configDigest
+          || !sameIdentity(snapshot.identity, identityFor(view.account))) return null;
+        const login = this.statusLogin(view.account, snapshot.login);
+        if (typeof snapshot.login.claudeAiOauth.expiresAt !== 'number'
+          || snapshot.login.claudeAiOauth.expiresAt <= this.now()) return null;
+        return { context: { ...view.context, nativeSource: {
+          homeId: this.options.homeId, credentialDigest: snapshot.credentialDigest,
+          configDigest: snapshot.configDigest, accessTokenDigest: hash(login.accessToken),
+        } }, login };
+      };
+      const initial = await inspect();
+      if (!initial) throw new Error('Qualified Claude native status source is unavailable.');
+      const result = await action({ ...initial, readContext: async () => (await inspect())?.context ?? null });
+      const final = await inspect();
+      if (!final || final.context.epoch !== initial.context.epoch
+        || final.context.accountId !== initial.context.accountId
+        || final.context.loginId !== initial.context.loginId
+        || final.context.subjectId !== initial.context.subjectId
+        || final.context.workspaceId !== initial.context.workspaceId
+        || final.context.providerId !== initial.context.providerId
+        || final.context.purpose !== initial.context.purpose
+        || final.context.owner !== initial.context.owner
+        || final.context.grantState !== initial.context.grantState
+        || final.context.removed !== initial.context.removed
+        || final.context.authorizationGeneration !== initial.context.authorizationGeneration
+        || final.context.grantGeneration !== initial.context.grantGeneration
+        || final.context.nativeSource?.credentialDigest !== initial.context.nativeSource?.credentialDigest
+        || final.context.nativeSource?.configDigest !== initial.context.nativeSource?.configDigest
+        || final.context.nativeSource?.accessTokenDigest !== initial.context.nativeSource?.accessTokenDigest) {
+        throw new Error('Claude native status source changed while it was read.');
+      }
+      return result;
+    });
+  }
+
+  private async reserve(operationId: string, targetAccountId: string, incomingGrantId: string): Promise<void> {
+    await this.change(operationId, incomingGrantId, ({ home, outgoing, incoming, outgoingAccount, incomingAccount }, updateId) => {
+      if (incoming.accountId !== targetAccountId || incomingAccount.id !== targetAccountId) {
+        throw new Error('Claude login does not belong to the selected account.');
+      }
+      const now = this.timestamp();
+      const handoff: IStoredAuthorityClaudeHandoff = {
+        id: operationId, homeId: home.id, outgoingAccountId: outgoing.accountId, outgoingGrantId: outgoing.id,
+        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,
+        updatedAt: now, revision: 1, updateId,
+      };
+      return { home: this.homeStep(home, updateId, { pendingOperationId: operationId }), handoff,
+        outgoing: this.grantStep(outgoing, updateId, now),
+        incoming: this.grantStep(incoming, updateId, now, { state: 'handoff_pending' }) };
+    });
+  }
+
+  private async prepare(operationId: string, incomingGrantId: string,
+    before: IStoredAuthorityNativePair, after: IStoredAuthorityNativePair,
+    sourceAccessDigest: string, targetAccessDigest: string, sealedOutgoing: string,
+    runningEffectiveAuth: IClaudeNativeSnapshot['runningEffectiveAuth']): Promise<void> {
+    await this.change(operationId, incomingGrantId, ({ home, handoff, outgoing, incoming }, updateId) => {
+      if (!handoff || handoff.phase !== 'reserved') throw new Error('Claude handoff reservation changed.');
+      const now = this.timestamp();
+      return { home: this.homeStep(home, updateId, {}),
+        handoff: { ...handoff, phase: 'prepared', before, after, sourceAccessDigest,
+          targetAccessDigest, sealedOutgoing, runningEffectiveAuth, updatedAt: now,
+          revision: handoff.revision + 1, updateId },
+        outgoing: this.grantStep(outgoing, updateId, now, { state: 'handoff_pending' }),
+        incoming: this.grantStep(incoming, updateId, now) };
+    });
+  }
+
+  private async settle(operationId: string, phase: 'committed' | 'aborted' | 'quarantined',
+    runningEffectiveAuth: IClaudeNativeSnapshot['runningEffectiveAuth'] | null,
+    problem: IStoredAuthorityClaudeHandoff['problem'] = 'none'): 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);
+    let outgoingExpiry: string | null = null;
+    if (phase === 'committed') {
+      if (!context.handoff.sealedOutgoing) throw new Error('Claude outgoing grant has no sealed journal proof.');
+      const outgoingGrant = { ...context.outgoing, owner: 'daemon' as const,
+        ciphertext: context.handoff.sealedOutgoing };
+      const login = await this.unsealLogin(context.outgoingAccount, outgoingGrant);
+      const expires = login.claudeAiOauth.expiresAt;
+      if (typeof expires !== 'number' || !Number.isFinite(expires)) throw new Error('Sealed outgoing Claude expiry is invalid.');
+      outgoingExpiry = new Date(expires).toISOString();
+    }
+    const result = await this.change(operationId, context.incoming.id, ({ home, handoff, outgoing, incoming }, updateId) => {
+      if (!handoff || !['reserved', 'prepared'].includes(handoff.phase)) throw new Error('Claude handoff phase changed.');
+      const now = this.timestamp();
+      const committed = phase === 'committed';
+      const quarantined = phase === 'quarantined';
+      return {
+        home: this.homeStep(home, updateId, committed
+          ? { activeAccountId: incoming.accountId, activeGrantId: incoming.id,
+              pendingOperationId: null, status: 'ready' }
+          : quarantined ? { status: 'quarantined' }
+            : { pendingOperationId: null, status: 'ready' }),
+        handoff: { ...handoff, phase, sealedOutgoing: quarantined ? handoff.sealedOutgoing : null,
+          runningEffectiveAuth, problem, 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',
+              grantGeneration: outgoing.grantGeneration + 1,
+              authorizationGeneration: outgoing.authorizationGeneration + 1 }
+          : quarantined ? { state: 'handoff_quarantined' }
+            : { state: 'native' }),
+        incoming: this.grantStep(incoming, updateId, now, committed
+          ? { state: 'native', owner: 'claude_native', ciphertext: null, accessExpiresAt: null,
+              problem: 'native_owner', grantGeneration: incoming.grantGeneration + 1,
+              authorizationGeneration: incoming.authorizationGeneration + 1 }
+          : quarantined ? { state: 'handoff_quarantined' }
+            : { state: 'ready' }),
+      };
+    });
+    return publicHandoff(result.handoff);
+  }
+
+  private async classify(operationId: string, session: IClaudeNativeLockedSession): Promise<IAuthSwitchClaudeNativeHandoff> {
+    const context = await this.database.readClaudeHandoffContext(operationId);
+    if (!context) throw new Error('Claude handoff operation is missing.');
+    const handoff = context.handoff;
+    if (['committed', 'aborted', 'quarantined'].includes(handoff.phase)) return publicHandoff(handoff);
+    let observed: IClaudeNativeSnapshot;
+    try { observed = session.readStable(); }
+    catch { return this.settle(operationId, 'quarantined', null, 'foreign_or_torn'); }
+    if (handoff.phase === 'reserved') {
+      return sameIdentity(observed.identity, handoff.sourceIdentity)
+        ? this.settle(operationId, 'aborted', observed.runningEffectiveAuth)
+        : this.settle(operationId, 'quarantined', observed.runningEffectiveAuth, 'foreign_or_torn');
+    }
+    const access = observed.login?.claudeAiOauth.accessToken;
+    const accessDigest = typeof access === 'string' ? hash(access) : null;
+    if (handoff.before && samePair(observed, handoff.before)
+      && sameIdentity(observed.identity, handoff.sourceIdentity)
+      && accessDigest === handoff.sourceAccessDigest) {
+      return this.settle(operationId, 'aborted', observed.runningEffectiveAuth);
+    }
+    if (handoff.after && samePair(observed, handoff.after)
+      && sameIdentity(observed.identity, handoff.targetIdentity)
+      && accessDigest === handoff.targetAccessDigest) {
+      return this.settle(operationId, 'committed', observed.runningEffectiveAuth);
+    }
+    return this.settle(operationId, 'quarantined', observed.runningEffectiveAuth, 'foreign_or_torn');
+  }
+
+  public async reconcileOperation(operationId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
+    const context = await this.database.readClaudeHandoffContext(operationId);
+    if (!context || context.handoff.homeId !== this.options.homeId) throw new Error('Claude handoff is unavailable on this home.');
+    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');
+    }
+  }
+
+  public async reconcilePending(): Promise<void> {
+    for (const phase of ['reserved', 'prepared'] as const) {
+      let after: string | null = null;
+      while (true) {
+        const page = await this.database.claudeHandoffsByPhase(phase, after);
+        if (!page.length) break;
+        for (const handoff of page) {
+          if (handoff.homeId === this.options.homeId) await this.reconcileOperation(handoff.id);
+        }
+        after = page.at(-1)!.id;
+      }
+    }
+  }
+
+  public async switchTo(accountId: string, loginId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
+    if (!isHash(accountId) || !isHash(loginId) || this.closed) {
+      throw new Error('Invalid or closed Claude handoff request.');
+    }
+    await this.database.assertOpenAdmission();
+    const task = this.performSwitch(accountId, loginId);
+    this.activeHandoffs.add(task);
+    try { return await task; }
+    finally { this.activeHandoffs.delete(task); }
+  }
+
+  private async performSwitch(accountId: string, loginId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
+    const home = await this.database.readClaudeHome(this.options.homeId);
+    if (!home || home.status !== 'ready' || home.pendingOperationId !== null) {
+      throw new Error('Verified Claude native home is unavailable or has a pending handoff.');
+    }
+    await this.refreshInactiveGrant(loginId);
+    const operationId = plugins.crypto.randomUUID();
+    await this.reserve(operationId, accountId, loginId);
+    try {
+      return await this.options.adapter.withExclusiveHome(async session => {
+        const before = session.readStable();
+        const context = await this.database.readClaudeHandoffContext(operationId);
+        if (!context || !sameIdentity(before.identity, context.handoff.sourceIdentity) || !before.login) {
+          return this.classify(operationId, session);
+        }
+        let outgoingProof: Awaited<ReturnType<IClaudeNativeLockedSession['verifyProfileIdentity']>>;
+        try { outgoingProof = await session.verifyProfileIdentity(before, context.handoff.sourceIdentity); }
+        catch {
+          return this.settle(operationId, 'quarantined', before.runningEffectiveAuth, 'foreign_or_torn');
+        }
+        const incomingLogin = await this.unsealLogin(context.incomingAccount, context.incoming);
+        const prepared = await session.prepareWrite({ expected: before,
+          expectedSourceIdentity: context.handoff.sourceIdentity, targetLogin: incomingLogin,
+          expectedIdentity: context.handoff.targetIdentity });
+        if (prepared.kind !== 'prepared') return this.classify(operationId, session);
+        const sealedOutgoing = await this.sealLogin(context.outgoing.id, before.login);
+        await this.prepare(operationId, loginId, prepared.plan.before, prepared.plan.after,
+          outgoingProof.accessTokenDigest, prepared.plan.profile.accessTokenDigest,
+          sealedOutgoing, before.runningEffectiveAuth);
+        session.writePreparedIfCurrent(prepared.plan);
+        return this.classify(operationId, session);
+      });
+    } catch {
+      const outcome = await this.reconcileOperation(operationId);
+      return { ...outcome, runningEffectiveAuth: 'unsupported_effective_auth' };
+    }
+  }
+
+  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.');
+    return publicHandoff(handoff);
+  }
+
+  public async listHandoffs(after: string | null, limit = 128): Promise<{
+    handoffs: IAuthSwitchClaudeNativeHandoff[]; nextCursor: string | null;
+  }> {
+    const page = await this.database.claudeHandoffsPage(after, limit);
+    return { handoffs: page.handoffs.filter(item => item.homeId === this.options.homeId).map(publicHandoff),
+      nextCursor: page.nextCursor };
+  }
+
+  public async close(): Promise<void> {
+    this.closed = true;
+    await Promise.allSettled(this.activeHandoffs);
+    await Promise.allSettled(this.activeRefreshes.values());
+  }
+}

package/ts/classes.claudecodeharness.ts

@@ -104,7 +104,8 @@ export class ClaudeCodeHarness extends FileHarness {
     const account = credentialRecord(credential.oauthAccount);
     if (!credentialText(oauth.accessToken) || !Array.isArray(oauth.scopes) || !oauth.scopes.every(scope => typeof scope === 'string')
       || !credentialText(account.accountUuid) || !credentialText(account.organizationUuid) || !credentialText(account.emailAddress)) throw new Error('Claude Code login or its matching account metadata is incomplete. Log in again with Claude Code before saving.');
-    return { slotId, identity: JSON.stringify([account.accountUuid, account.organizationUuid]), label: String(account.emailAddress).toLowerCase(), credential };
+    return { slotId, identity: JSON.stringify([account.accountUuid, account.organizationUuid]),
+      providerAccountId: String(account.accountUuid), label: String(account.emailAddress).toLowerCase(), credential };
   }
   /** Why this installation's login is not a subscriber file login this adapter can manage; null when it is. */
   private unavailableReason(): string | null {

package/ts/classes.claudecodelocks.ts

@@ -24,6 +24,18 @@ export interface IClaudeCodeLocksOptions {
   timeoutMs?: number;
 }
 
+/** The vendor locks may be lost while an awaited database operation is in flight. */
+export interface IClaudeCodeLockLease {
+  assertHeld(): void;
+}
+
+/** A callback may already have changed native files when releasing its locks fails. */
+export class ClaudeCodeLockOutcomeUnknownError extends Error {
+  constructor(public readonly actionCompleted: boolean) {
+    super('Claude Code native lock ownership could not be confirmed after the operation; reconcile its journal before retrying.');
+  }
+}
+
 const DEFAULT_TIMEOUT_MS = 15_000;
 const RETRY_MS = 250;
 
@@ -110,12 +122,67 @@ export class ClaudeCodeLocks {
     return note === null ? outcome.lines : [...outcome.lines, note];
   }
 
+  /** Keep every vendor lock across awaited authority journal and native-file operations. */
+  public async holdAsync<T>(actionArg: (lease: IClaudeCodeLockLease) => Promise<T>,
+    optionsArg: { timeoutMs?: number } = {}): Promise<T> {
+    const lockfile = await plugins.loadProperLockfile();
+    const deadline = Date.now() + (optionsArg.timeoutMs ?? this.timeoutMs);
+    const held: IHeldLock[] = [];
+    const unreleased: string[] = [];
+    let compromised = false;
+    let active = false;
+    const lease: IClaudeCodeLockLease = {
+      assertHeld: () => {
+        if (!active || compromised) throw new ClaudeCodeLockOutcomeUnknownError(false);
+      },
+    };
+    const releaseAll = async (): Promise<void> => {
+      active = false;
+      for (const lock of held.splice(0).reverse()) {
+        try { await lock.release(); }
+        catch { unreleased.push(lock.lockfilePath); }
+      }
+    };
+    let completed = false;
+    let value: T | undefined;
+    let failure: unknown;
+    try {
+      for (const directory of new Set([this.configDir, plugins.path.dirname(this.configFile)])) {
+        plugins.fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+      }
+      const locks = await this.locks();
+      for (;;) {
+        compromised = false;
+        const busy = await this.acquireAll(lockfile, locks, held, () => { compromised = true; }, true);
+        if (busy === null) {
+          active = true;
+          lease.assertHeld();
+          break;
+        }
+        await releaseAll();
+        if (unreleased.length) throw new ClaudeCodeLockOutcomeUnknownError(false);
+        if (Date.now() >= deadline) {
+          throw new Error(`Claude Code is refreshing or saving its login (${busy.lockfilePath} is held); nothing was changed. Try again in a moment.`);
+        }
+        await new Promise<void>(resolve => { setTimeout(resolve, Math.min(RETRY_MS, Math.max(1, deadline - Date.now()))); });
+      }
+      value = await actionArg(lease);
+      completed = true;
+      lease.assertHeld();
+    } catch (error) { failure = error; }
+    await releaseAll();
+    if (unreleased.length) throw new ClaudeCodeLockOutcomeUnknownError(completed);
+    if (failure !== undefined) throw failure;
+    return value as T;
+  }
+
   /** Takes the locks in order into `heldArg` and returns the first one another process holds, or null once all are held. */
   private async acquireAll(
     lockfileArg: plugins.TProperLockfile,
     locksArg: readonly IClaudeCodeLock[],
     heldArg: IHeldLock[],
     onCompromisedArg: (errorArg: Error) => void,
+    requireAllArg = false,
   ): Promise<IClaudeCodeLock | null> {
     for (const lock of locksArg) {
       try {
@@ -125,7 +192,9 @@ export class ClaudeCodeLocks {
         heldArg.push({ lockfilePath: lock.lockfilePath, release });
       } catch (error) {
         if (errorCode(error) === 'ELOCKED') return lock;
-        if (!lock.bestEffort) throw new Error(`Claude Code's lock ${lock.lockfilePath} could not be taken (${errorCode(error) ?? 'unknown error'}); nothing was changed.`);
+        if (requireAllArg || !lock.bestEffort) {
+          throw new Error(`Claude Code's lock ${lock.lockfilePath} could not be taken (${errorCode(error) ?? 'unknown error'}); nothing was changed.`);
+        }
       }
     }
     return null;