@cortexkit/common-auth 0.11.0 → 0.11.2

package/README.md

@@ -7,4 +7,20 @@ Shared libraries for the CortexKit auth plugins for OpenCode and Pi: openai-auth
 - [OpenCode 2 transport spike](research/opencode2-transport/REPORT.md): can a plugin own the transport on OpenCode 2?
 - [OpenCode 2 native-driver spike](research/opencode2-thin/REPORT.md): multi-account support through hooks on OpenCode 2's built-in OpenAI driver.
 
+## Mutation catalogue
+
+A passing safety test proves little until it has been seen to fail. [`mutations.toml`](mutations.toml) is the checked-in catalogue: each row deliberately breaks one guard in `src/` (or a CI scan script) and names the Bun test that must fail because of it, so a guard cannot silently stop guarding. A row earns its place by guarding a silent, costly failure: lock exclusion, crash safety, credential loss or leakage, a single-use token used twice, misattributed quota, a wire contract, data loss. Style and cosmetics do not.
+
+The pinned [`ck-mutate`](https://github.com/cortexkit/commons/tree/7d08e73722fa3e79bbcc2607753978ab768f1c6b/crates/cortexkit-mutate) runner replays it from a clean tree. It installs and builds first (fixtures import `dist/`), checks each named test passes, applies the break, rebuilds, requires the test to fail, and restores the source byte for byte:
+
+```sh
+cargo install --locked --git https://github.com/cortexkit/commons --rev 7d08e73722fa3e79bbcc2607753978ab768f1c6b cortexkit-mutate
+ck-mutate check
+ck-mutate run --all
+ck-mutate run --diff origin/main
+ck-mutate run --only fs-lock-try-once-refuses-held-lock
+```
+
+Every row must report CAUGHT. Replay with the Bun version CI pins (1.3.14): the row `rpc-declared-oversize-413-half-closes` guards the RPC server's workaround for Bun 1.3.14 reusing a connection the server refused with 413. Bun 1.4.2 never reuses it, so that row survives there. Rows are command rows: `{test}` is a Bun `-t` filter, a regular expression over the full test name (describe names and test name joined by spaces), so ids are anchored, escaped, and spell each space `\s`. CI replays the rows a pull request's diff selects, the full catalogue on every push to main, and the full catalogue with `--broad` nightly. Never `git checkout` a file while a replay runs: it removes the mutation and fakes a survivor.
+
 Licensed under MIT; see [LICENSE](LICENSE).

package/dist/claustrum/custody.d.ts

@@ -87,6 +87,12 @@ export interface ClaustrumScopedAttempt {
      * in from the roster or from a token parse.
      */
     readonly assertedAccountIdentity?: string;
+    /**
+     * The non-secret Google Cloud project id the vault served in get_scoped for
+     * this attempt, if any. Never filled in from list_scoped, the roster or a
+     * token parse. A project change in the vault takes effect on the next send.
+     */
+    readonly projectId?: string;
     /**
      * Kept in memory only and hidden from JSON.stringify and object spreads, so
      * logging a receipt never leaks it. Authorize again for every dispatch and retry.

package/dist/claustrum/custody.js

@@ -298,6 +298,9 @@ export class ClaustrumScopedCustody {
             ...(assertedIdentity !== undefined && {
                 assertedAccountIdentity: assertedIdentity,
             }),
+            ...(served.projectId !== undefined && {
+                projectId: served.projectId,
+            }),
             recordVersion: served.recordVersion,
             expiresAtMs,
         }, 'accessToken', { value: accessToken, enumerable: false }));

package/dist/opencode2/errors.d.ts

@@ -2,7 +2,9 @@
  * Why an OpenCode 2 auth hook refused a request.
  *
  * - `no-account`: the adapter had no account to offer for this request, so
- *   the request is stopped before the host picks a transport.
+ *   the request is stopped before the host picks a transport. Also used when
+ *   session forgetting or installation disposal revokes an in-flight auth
+ *   selection: that selection no longer has an account it may send under.
  * - `host-credential-on-wire`: after every rewrite, a header still carried
  *   one of the host's placeholder credentials. Sending it would leak a
  *   non-routable value to the provider and fail with a confusing error.

package/dist/opencode2/install.js

@@ -129,6 +129,9 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     let warnedUnmarkedSend = false;
     const listeners = new Map();
     let seq = 0;
+    let disposed = false;
+    /** Only active hook calls are held; forgetting never leaves a session tombstone. */
+    const inFlight = new Map();
     const warn = (message, data) => {
         try {
             logger?.warn(message, data);
@@ -200,12 +203,47 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     const accountOf = (rec) => rec.accountId === undefined
         ? undefined
         : { ...rec.scope, accountId: rec.accountId };
-    const noAccount = (scope) => new OpenCode2AuthError({
+    const noAccount = (scope, message) => new OpenCode2AuthError({
         kind: 'no-account',
         providerID,
         sessionID: scope.sessionID,
         requestKind: scope.kind,
+        ...(message === undefined ? {} : { message }),
     });
+    const revokeSelections = (sessionID) => {
+        inFlight.get(sessionID)?.clear();
+        inFlight.delete(sessionID);
+    };
+    /**
+     * Owns selection through its transport handoff, not just the adapter calls.
+     * Deleting a session's set revokes its old calls without poisoning reuse of
+     * that id. Each await must recheck before calling the adapter or publishing.
+     */
+    const withSelection = async (scope, run) => {
+        const revoked = () => noAccount(scope, `${providerID} ${scope.kind} request has no account: its auth selection was revoked by session forgetting or installation disposal`);
+        if (disposed)
+            throw revoked();
+        let selections = inFlight.get(scope.sessionID);
+        if (!selections) {
+            selections = new Set();
+            inFlight.set(scope.sessionID, selections);
+        }
+        const token = {};
+        selections.add(token);
+        const assertActive = () => {
+            if (!selections.has(token))
+                throw revoked();
+        };
+        try {
+            return await run(assertActive);
+        }
+        finally {
+            selections.delete(token);
+            // An old call may settle after a new call has reused the session id.
+            if (selections.size === 0 && inFlight.get(scope.sessionID) === selections)
+                inFlight.delete(scope.sessionID);
+        }
+    };
     const guard = (scope, headers) => {
         for (const [name, value] of headers) {
             if (forbidden.some((secret) => value.includes(secret))) {
@@ -240,7 +278,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         }
     };
-    const select = async (scope, hook, transport) => {
+    const select = async (scope, hook, assertActive, transport) => {
         const key = keyOf(scope.sessionID, scope.kind);
         const retried = pendingRetries.get(key);
         pendingRetries.delete(key);
@@ -254,10 +292,12 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 : { rerouteFrom: retried.rerouteFrom }),
         };
         const accountId = await adapter.chooseAccount(input);
+        assertActive();
         let headers = {};
         let data;
         if (accountId !== undefined) {
             const result = await adapter.accountHeaders({ ...scope, accountId });
+            assertActive();
             if (isHeadersResult(result)) {
                 headers = result.headers;
                 data = result.attempt;
@@ -306,7 +346,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     // of the attempt it started. Choosing here too keeps a request that skipped
     // it from going out under the host credential, and a second send of the
     // same attempt from reusing the first send's attempt.
-    const bind = async (scope, hook, transport, mark) => {
+    const bind = async (scope, hook, transport, mark, assertActive) => {
         const key = keyOf(scope.sessionID, scope.kind);
         let rec = mark === undefined ? undefined : attempts.get(mark);
         if (rec?.key !== key)
@@ -322,7 +362,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         }
         if (!rec || rec.transport !== undefined || rec.ended)
-            rec = await select(scope, hook, transport);
+            rec = await select(scope, hook, assertActive, transport);
         else {
             rec.transport = transport;
             if (rec.attempt)
@@ -443,18 +483,20 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     };
     const scoped = { providerID };
     const registrations = [];
-    registrations.push(await ctx.session.hook('model.request', async (draft) => {
-        const rec = await select(scopeOf(draft), 'model.request');
+    registrations.push(await ctx.session.hook('model.request', (draft) => withSelection(scopeOf(draft), async (assertActive) => {
+        const rec = await select(scopeOf(draft), 'model.request', assertActive);
+        assertActive();
         if (rec.accountId === undefined)
             throw noAccount(rec.scope);
         applyHeaderEdits(draft.headers, {
             ...rec.headers,
             [ATTEMPT_HEADER]: rec.id,
         });
-    }, scoped));
-    registrations.push(await ctx.session.hook('http.request', async (draft) => {
+    }), scoped));
+    registrations.push(await ctx.session.hook('http.request', (draft) => withSelection(scopeOf(draft), async (assertActive) => {
         const mark = draft.request.headers.get(ATTEMPT_HEADER) ?? undefined;
-        const rec = await bind(scopeOf(draft), 'http.request', 'http', mark);
+        const rec = await bind(scopeOf(draft), 'http.request', 'http', mark, assertActive);
+        assertActive();
         const account = accountOf(rec);
         const attempt = rec.attempt;
         if (!account || !attempt)
@@ -475,6 +517,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                         request,
                         attempt,
                     })) ?? request;
+                assertActive();
             }
             const headers = new Headers(request.headers);
             headers.delete(ATTEMPT_HEADER);
@@ -484,7 +527,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             byRequest.set(final, rec);
             draft.request = final;
         });
-    }, scoped));
+    }), scoped));
     registrations.push(await ctx.session.hook('http.response', async (draft) => {
         const rec = byRequest.get(draft.request);
         if (!rec) {
@@ -554,7 +597,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         if (response !== original)
             draft.response = response;
     }, scoped));
-    registrations.push(await ctx.session.hook('experimental.ws.handshake', async (draft) => {
+    registrations.push(await ctx.session.hook('experimental.ws.handshake', (draft) => withSelection(scopeOf(draft), async (assertActive) => {
         let mark;
         for (const name of Object.keys(draft.headers)) {
             if (name.toLowerCase() !== ATTEMPT_HEADER)
@@ -562,7 +605,8 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             mark ??= draft.headers[name];
             delete draft.headers[name];
         }
-        const rec = await bind(scopeOf(draft), 'experimental.ws.handshake', 'ws', mark);
+        const rec = await bind(scopeOf(draft), 'experimental.ws.handshake', 'ws', mark, assertActive);
+        assertActive();
         const account = accountOf(rec);
         const attempt = rec.attempt;
         if (!account || !attempt)
@@ -578,7 +622,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 draft.url = url;
             guard(rec.scope, Object.entries(draft.headers));
         });
-    }, scoped));
+    }), scoped));
     const rewriteFrame = adapter.rewriteWebSocketFrame?.bind(adapter);
     if (rewriteFrame) {
         registrations.push(await ctx.session.hook('experimental.ws.send', async (draft) => {
@@ -624,68 +668,79 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             return;
         }
         const rec = picked;
-        rec.judged = true;
-        let decision = hostDecision;
-        let reason;
-        let rerouteFrom;
-        const attempt = rec.attempt;
-        if (rec.accountId === undefined || !attempt) {
-            decision = { retry: false };
-            reason = 'no-account';
-        }
-        else if (rec.outputStarted) {
-            // The user has already seen part of this answer; a retry would
-            // send it again.
-            decision = { retry: false };
-            reason = 'output-started';
-        }
-        else {
-            if (!rec.limit) {
-                const signal = adapter.limitFromError?.(draft.error, attempt);
-                if (signal)
-                    noteLimit(rec, signal, 'error');
+        await withSelection(rec.scope, async (assertActive) => {
+            rec.judged = true;
+            let decision = hostDecision;
+            let reason;
+            let rerouteFrom;
+            const attempt = rec.attempt;
+            if (rec.accountId === undefined || !attempt) {
+                decision = { retry: false };
+                reason = 'no-account';
             }
-            // The next `chooseAccount` should see whatever the plugin learnt
-            // from how this attempt ended.
-            if (rec.ended)
-                await rec.ended;
-            if (rec.limit) {
-                await rec.limit.delivered;
-                rec.rerouted = true;
-                rerouteFrom = { accountId: rec.accountId, limit: rec.limit.signal };
-                // No delay: the next attempt goes to another account, and the
-                // host would otherwise wait out the refused account's backoff,
-                // or not retry at all for errors it deems final.
-                decision = { retry: true, delay: 0 };
-                reason = 'reroute';
+            else if (rec.outputStarted) {
+                // The user has already seen part of this answer; a retry would
+                // send it again.
+                decision = { retry: false };
+                reason = 'output-started';
             }
             else {
-                reason = 'host-decides';
+                if (!rec.limit) {
+                    const signal = adapter.limitFromError?.(draft.error, attempt);
+                    if (signal)
+                        noteLimit(rec, signal, 'error');
+                }
+                // The next `chooseAccount` should see whatever the plugin learnt
+                // from how this attempt ended.
+                if (rec.ended) {
+                    await rec.ended;
+                    assertActive();
+                }
+                if (rec.limit) {
+                    await rec.limit.delivered;
+                    assertActive();
+                    rec.rerouted = true;
+                    rerouteFrom = {
+                        accountId: rec.accountId,
+                        limit: rec.limit.signal,
+                    };
+                    // No delay: the next attempt goes to another account, and the
+                    // host would otherwise wait out the refused account's backoff,
+                    // or not retry at all for errors it deems final.
+                    decision = { retry: true, delay: 0 };
+                    reason = 'reroute';
+                }
+                else {
+                    reason = 'host-decides';
+                }
             }
-        }
-        draft.decision = decision;
-        // The host's retry runs `model.request` again for this attempt's
-        // session and kind; that next attempt, and no other attempt of the
-        // session, is told what this one ended with.
-        if (decision.retry && rec.accountId !== undefined) {
-            pendingRetries.set(rec.key, {
-                sessionID: rec.scope.sessionID,
-                accountId: rec.accountId,
-                ...(rerouteFrom === undefined ? {} : { rerouteFrom }),
+            draft.decision = decision;
+            // The host's retry runs `model.request` again for this attempt's
+            // session and kind; that next attempt, and no other attempt of the
+            // session, is told what this one ended with.
+            if (decision.retry && rec.accountId !== undefined) {
+                pendingRetries.set(rec.key, {
+                    sessionID: rec.scope.sessionID,
+                    accountId: rec.accountId,
+                    ...(rerouteFrom === undefined ? {} : { rerouteFrom }),
+                });
+            }
+            await emit('retry', {
+                sessionID: draft.sessionID,
+                ...(rec.accountId === undefined
+                    ? {}
+                    : { accountId: rec.accountId }),
+                kind: rec.scope.kind,
+                attempt: draft.attempt,
+                reason,
+                hostDecision,
+                decision,
+                ...(attempt === undefined ? {} : { handle: attempt }),
             });
-        }
-        await emit('retry', {
-            sessionID: draft.sessionID,
-            ...(rec.accountId === undefined ? {} : { accountId: rec.accountId }),
-            kind: rec.scope.kind,
-            attempt: draft.attempt,
-            reason,
-            hostDecision,
-            decision,
-            ...(attempt === undefined ? {} : { handle: attempt }),
         });
     }, scoped));
     const forgetSession = (sessionID) => {
+        revokeSelections(sessionID);
         for (const rec of [...attempts.values()]) {
             if (rec.scope.sessionID !== sessionID)
                 continue;
@@ -716,7 +771,6 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         })();
     }
-    let disposed = false;
     return {
         on(event, listener) {
             let set = listeners.get(event);
@@ -741,6 +795,8 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             if (disposed)
                 return;
             disposed = true;
+            for (const sessionID of inFlight.keys())
+                revokeSelections(sessionID);
             abort.abort();
             for (const rec of attempts.values())
                 abandon(rec, 'the installation was disposed');

package/dist/opencode2/types.d.ts

@@ -381,10 +381,13 @@ export interface OpenCode2AuthInstallation<Q, A = unknown> {
      * handle.
      */
     accountFor(sessionID: string, kind: RequestKind): string | undefined;
-    /** Drops every attempt of a session. Session deletion does this itself. */
+    /**
+     * Drops every attempt and revokes in-flight auth selections of a session.
+     * Session deletion does this itself. Later requests may reuse the session id.
+     */
     forgetSession(sessionID: string): void;
     /** Number of attempts held. */
     readonly size: number;
-    /** Removes every hook and stops listening for session deletion. */
+    /** Removes every hook, revokes in-flight auth and stops listening for session deletion. */
     dispose(): Promise<void>;
 }

package/dist/rpc/rpc-server.js

@@ -293,10 +293,10 @@ export async function startRpcServer(options) {
         token,
         async stop() {
             await new Promise((resolve) => {
-                server.close(() => resolve());
-                // Stop accepting connections before ending requests that may never finish.
+                // Bun's close() disables closeAllConnections(), and a peer sending
+                // incomplete headers may not have reached the tracked connection set.
                 server.closeAllConnections?.();
-                // Bun exposes closeAllConnections but leaves partial requests open.
+                server.close(() => resolve());
                 for (const socket of connections)
                     socket.destroy();
             });

package/dist/store/index.d.ts

@@ -12,7 +12,7 @@ export type { PullHook, PullRequest } from './pull.js';
 export type { ProviderRefresh, ProviderRefreshResult, RefreshOptions, RefreshOutcome, } from './refresh.js';
 export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
-export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, RowTransitionOptions, RowTransitionResult, } from './rows.js';
+export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, RowTransitionOptions, RowTransitionResult, RowWriteOptions, } from './rows.js';
 export type { PullReason } from './runtime.js';
 export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, ProviderStateCodec, ProviderStateDrop, ProviderStateReplacement, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, PROVIDER_STATE_KEY, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';

package/dist/store/pool.d.ts

@@ -6,7 +6,7 @@ import { type ProviderStateMutator, type UpdateProviderStateResult } from './pro
 import { type PullHook } from './pull.js';
 import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
-import { type AddInput, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult } from './rows.js';
+import { type AddInput, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult, type RowWriteOptions } from './rows.js';
 import { type PoolCredential, type PoolRow, type ProviderStateCodec, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.js';
 import { type SettingsMutator, type SettingsRead, type UpdateSettingsOptions, type UpdateSettingsResult } from './settings.js';
 export interface OpenPoolStoreOptions {
@@ -100,8 +100,10 @@ export interface PoolStore {
      * Gives a row a new credential and a new credential epoch. Since 0.6.0 the
      * row's provider state is whatever `ProviderStateCodec.onReplace` returns;
      * without that hook it is `input.providerState`, else cleared.
+     * Optional `attribution` fences the write on the prior credential under the
+     * locks, before any write or replacement hook; see `RowWriteOptions`.
      */
-    replace(id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
+    replace(id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
         id: string;
         credential: StoredCredential;
         credentialEpoch: number;
@@ -111,8 +113,9 @@ export interface PoolStore {
      * endpoint. Since 0.4.1 an API key may leave out `baseURL` and `authHeader`
      * to keep the row's, and one that gives another is refused
      * (`endpoint-mismatch`) before writing: that is a `replace`.
+     * Takes the same optional attribution fence as `replace` (`RowWriteOptions`).
      */
-    rotate(id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
+    rotate(id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
         id: string;
         credential: StoredCredential;
     }>;

package/dist/store/provider-state.js

@@ -53,6 +53,9 @@ export function replacementProviderState(codec, row, credentialEpoch, identity,
             : structuredClone(row.providerState), {
             id: row.id,
             credentialEpoch,
+            ...(row.identity !== undefined
+                ? { previousIdentity: row.identity }
+                : {}),
             ...(identity !== undefined ? { identity } : {}),
             ...(incoming !== undefined
                 ? { incoming: structuredClone(incoming) }

package/dist/store/rows.d.ts

@@ -20,6 +20,20 @@ export interface RowOperationOptions {
      */
     extraLocks?: readonly PoolLockSpec[];
 }
+/** Options of `replace` and `rotate`. Without `attribution` a call behaves as before. */
+export interface RowWriteOptions extends RowOperationOptions {
+    /**
+     * The credential epoch and recorded identity the caller read the row at
+     * when it decided on this write; an identity left out means the row had
+     * none. Compared exactly, under the row and store locks, before any write
+     * or replacement hook, including the completion of an interrupted replace.
+     * The call is refused (`attribution`, retryable, nothing written) once the
+     * row holds another epoch or identity, so a write decided on an older
+     * credential never overwrites the one that replaced it. `disable`, `enable`,
+     * `recordQuota` and `updateProviderState` take the same fence.
+     */
+    attribution?: Attribution;
+}
 /**
  * Options of `disable`, `enable` and `remove`. The provider-wide lock guards
  * changes to the recorded identity a row lock is named by; none of these
@@ -127,12 +141,12 @@ export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string,
     transition?: StampedTransition;
 }): Promise<StoredCredential>;
 export declare function addRow(rt: StoreRuntime, input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
-export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
+export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
     id: string;
     credential: StoredCredential;
     credentialEpoch: number;
 }>;
-export declare function rotateRow(rt: StoreRuntime, id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
+export declare function rotateRow(rt: StoreRuntime, id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
     id: string;
     credential: StoredCredential;
 }>;

package/dist/store/rows.js

@@ -179,6 +179,22 @@ function requireUsableRow(operation, id, row, credential) {
         throw refusal(operation, id, 'type-mismatch', `row ${id} holds a ${row.type} credential`);
     return row;
 }
+function validateAttribution(operation, id, fence) {
+    if (fence !== undefined &&
+        !isCredentialEpoch(isRecord(fence) ? fence.credentialEpoch : undefined))
+        throw refusal(operation, id, 'invalid-input', 'the attribution must name a credential epoch that is a positive safe integer');
+}
+/** Exact recorded identity, including absence, is part of a credential fence. */
+function assertRowAttribution(operation, id, row, fence) {
+    if (!row)
+        throw unknownRow(operation, id);
+    // A row that failed validation has no usable credential epoch to compare.
+    if (row.invalid)
+        throw refusal(operation, id, 'invalid-row', `row ${id} failed validation`);
+    if ((row.credentialEpoch ?? 1) !== fence.credentialEpoch ||
+        row.identity !== fence.identity)
+        throw refusal(operation, id, 'attribution', `the ${operation} of ${id} was issued for a credential or account the row no longer holds`, true);
+}
 /** The row is recorded for another account than the one given. */
 function identityMismatch(operation, id) {
     return refusal(operation, id, 'identity-mismatch', `row ${id} is recorded for another account; a credential of a different account is a replacement`);
@@ -318,6 +334,7 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
     const { ctx } = rt;
     const result = await runOperation(ctx, 'replace', id, options.onFailure, async (locks, progress) => {
         checkInput('replace', id, credential);
+        validateAttribution('replace', id, options.attribution);
         const incoming = input.providerState === undefined
             ? undefined
             : acceptProviderState(ctx.providerState, 'replace', id, input.providerState);
@@ -328,6 +345,15 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
         for (const extra of options.extraLocks ?? [])
             await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'replace', rowId: id }, async (tx) => {
+            if (options.attribution !== undefined) {
+                // A replace interrupted between its two file writes is read as
+                // already done: tx.row shows its new epoch and identity. Compare
+                // the fence with that row before finishing the interrupted write
+                // on disk, so a stale caller does not even complete a replacement
+                // it was never issued for.
+                assertRowAttribution('replace', id, tx.row(id), options.attribution);
+                await tx.completeTorn();
+            }
             const row = requireUsableRow('replace', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged('replace', id);
@@ -368,7 +394,7 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
             });
             await tx.commitConfig();
             return { id, credential: stored, credentialEpoch };
-        });
+        }, { completeTorn: options.attribution === undefined });
     });
     if (credential.type === 'oauth')
         rt.firePull(id, 'replace');
@@ -379,6 +405,7 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
     const { ctx } = rt;
     return runOperation(ctx, 'rotate', id, options.onFailure, async (locks, progress) => {
         checkInput('rotate', id, credential);
+        validateAttribution('rotate', id, options.attribution);
         const incoming = input.providerState === undefined
             ? undefined
             : acceptProviderState(ctx.providerState, 'rotate', id, input.providerState);
@@ -389,6 +416,10 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
         for (const extra of options.extraLocks ?? [])
             await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'rotate', rowId: id }, async (tx) => {
+            if (options.attribution !== undefined) {
+                assertRowAttribution('rotate', id, tx.row(id), options.attribution);
+                await tx.completeTorn();
+            }
             const row = requireUsableRow('rotate', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged('rotate', id);
@@ -428,7 +459,7 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
             if (configChanged)
                 await tx.commitConfig();
             return { id, credential: stored };
-        });
+        }, { completeTorn: options.attribution === undefined });
     });
 }
 /**
@@ -451,9 +482,7 @@ async function transitionRow(rt, operation, id, flag, options) {
     const fence = options.attribution;
     const mutator = options.providerState;
     return runOperation(ctx, operation, id, options.onFailure, async (locks, progress) => {
-        if (fence !== undefined &&
-            !isCredentialEpoch(isRecord(fence) ? fence.credentialEpoch : undefined))
-            throw refusal(operation, id, 'invalid-input', 'the attribution must name a credential epoch that is a positive safe integer');
+        validateAttribution(operation, id, fence);
         if (mutator !== undefined) {
             if (typeof mutator !== 'function')
                 throw refusal(operation, id, 'invalid-input', 'the provider-state mutator must be a function');
@@ -477,14 +506,8 @@ async function transitionRow(rt, operation, id, flag, options) {
                 throw unknownRow(operation, id);
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged(operation, id);
-            if (fence !== undefined) {
-                // An invalid entry has no epoch to compare the fence with.
-                if (row.invalid)
-                    throw refusal(operation, id, 'invalid-row', `row ${id} failed validation`);
-                if ((row.credentialEpoch ?? 1) !== fence.credentialEpoch ||
-                    row.identity !== fence.identity)
-                    throw refusal(operation, id, 'attribution', `the ${operation} of ${id} was issued for a credential or account the row no longer holds`, true);
-            }
+            if (fence !== undefined)
+                assertRowAttribution(operation, id, row, fence);
             if (flag.enabled &&
                 row.disabledReason?.startsWith(IDENTITY_CONTRADICTED_REASON_PREFIX))
                 throw refusal('enable', id, 'identity-contradicted', `row ${id} needs an identity-validated credential replacement before it can be enabled`);

package/dist/store/schema.d.ts

@@ -52,14 +52,16 @@ export interface QuotaCodec {
     merge(stored: unknown | undefined, observation: unknown): unknown;
 }
 /**
- * What `ProviderStateCodec.onReplace` is told about a replacement: the row,
- * the credential epoch the new credential starts, the identity the replace
- * records (absent: none), and the provider state the caller handed to
- * `replace`, if any.
+ * What `ProviderStateCodec.onReplace` is told about a replacement: the row id,
+ * the credential epoch the new credential starts, `previousIdentity` (the
+ * identity the locked row recorded before the replace), `identity` (the
+ * identity the replace records), and the provider state the caller handed to
+ * `replace`, if any. Each identity is absent when none was recorded.
  */
 export interface ProviderStateReplacement {
     id: string;
     credentialEpoch: number;
+    previousIdentity?: string;
     identity?: string;
     incoming?: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {