@cortexkit/common-auth 0.10.0 → 0.11.1

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/auth-menu/ansi.d.ts

@@ -12,8 +12,10 @@ export declare const ANSI: {
     readonly dim: '\u001B[2m';
     readonly reset: '\u001B[0m';
 };
-export type KeyAction = 'up' | 'down' | 'enter' | 'escape' | 'escape-start' | null;
-/** Convert terminal key bytes into the small action set the menu accepts. */
+export type KeyAction = 'up' | 'down' | 'left' | 'right' | 'enter' | 'escape' | 'escape-start' | 'char' | null;
+/** Tokenize complete keys in one read; incomplete escape sequences are ignored. */
+export declare function parseKeys(data: Buffer | string): KeyAction[];
+/** Preserve the single-key parser for callers that only need the first token. */
 export declare function parseKey(data: Buffer | string): KeyAction;
 /** Remove colour codes, leaving the text an operator sees. */
 export declare function stripAnsi(input: string): string;

package/dist/auth-menu/ansi.js

@@ -12,20 +12,51 @@ export const ANSI = {
     dim: '\x1b[2m',
     reset: '\x1b[0m',
 };
-/** Convert terminal key bytes into the small action set the menu accepts. */
-export function parseKey(data) {
+/** Tokenize complete keys in one read; incomplete escape sequences are ignored. */
+export function parseKeys(data) {
     const value = data.toString();
-    if (value === '\x1b[A' || value === '\x1bOA')
-        return 'up';
-    if (value === '\x1b[B' || value === '\x1bOB')
-        return 'down';
-    if (value === '\r' || value === '\n')
-        return 'enter';
-    if (value === '\x03')
-        return 'escape';
-    if (value === '\x1b')
-        return 'escape-start';
-    return null;
+    const keys = [];
+    for (let index = 0; index < value.length;) {
+        const char = value[index];
+        if (char === '\x1b') {
+            const sequence = value.slice(index, index + 3);
+            const arrow = sequence[1] === '[' || sequence[1] === 'O' ? sequence[2] : undefined;
+            if (arrow && 'ABCD'.includes(arrow)) {
+                const action = { A: 'up', B: 'down', C: 'right', D: 'left' };
+                const parsed = action[arrow];
+                if (parsed)
+                    keys.push(parsed);
+                index += 3;
+            }
+            else if (index + 1 === value.length) {
+                // Only a chunk consisting solely of ESC gets the legacy Escape timeout.
+                if (index === 0)
+                    keys.push('escape-start');
+                index += 1;
+            }
+            else if ((value[index + 1] === '[' || value[index + 1] === 'O') &&
+                index + 2 >= value.length) {
+                // An incomplete escape prefix at the chunk boundary is not a key.
+                break;
+            }
+            else {
+                index += 1;
+            }
+            continue;
+        }
+        if (char === '\r' || char === '\n')
+            keys.push('enter');
+        else if (char === '\x03')
+            keys.push('escape');
+        else if (char && char >= ' ')
+            keys.push('char');
+        index += 1;
+    }
+    return keys;
+}
+/** Preserve the single-key parser for callers that only need the first token. */
+export function parseKey(data) {
+    return parseKeys(data)[0] ?? null;
 }
 const ANSI_PATTERN = `${String.fromCharCode(27)}\\[[0-9;]*m`;
 const ANSI_REGEX = new RegExp(ANSI_PATTERN, 'g');

package/dist/auth-menu/index.d.ts

@@ -1,7 +1,7 @@
 export type { AccountMenuOptions } from './accounts.js';
 export { accountMenuActions, addAccountAction, checkQuotasAction, deleteAllAction, listAccountsAction, MENU_DISABLE_REASON, poolHasCredential, quotaLines, reauthenticateAction, removeAccountAction, runAccountMenu, toggleAccountAction, } from './accounts.js';
 export type { KeyAction } from './ansi.js';
-export { ANSI, parseKey, stripAnsi, truncateAnsi } from './ansi.js';
+export { ANSI, parseKey, parseKeys, stripAnsi, truncateAnsi } from './ansi.js';
 export { confirm } from './confirm.js';
 export type { DoctorActionOptions, DoctorCheck, DoctorFinding, DoctorRepair, DoctorReport, RepairOutcome, } from './doctor.js';
 export { applyChosenRepairs, DOCTOR_CHECK_FAILED, doctorAction, formatDoctorReport, runDoctorChecks, } from './doctor.js';

package/dist/auth-menu/index.js

@@ -2,7 +2,7 @@
 // runtime, the OpenCode v1 `authorize` contract around it, and the account
 // actions built over the `/store` pool.
 export { accountMenuActions, addAccountAction, checkQuotasAction, deleteAllAction, listAccountsAction, MENU_DISABLE_REASON, poolHasCredential, quotaLines, reauthenticateAction, removeAccountAction, runAccountMenu, toggleAccountAction, } from './accounts.js';
-export { ANSI, parseKey, stripAnsi, truncateAnsi } from './ansi.js';
+export { ANSI, parseKey, parseKeys, stripAnsi, truncateAnsi } from './ansi.js';
 export { confirm } from './confirm.js';
 export { applyChosenRepairs, DOCTOR_CHECK_FAILED, doctorAction, formatDoctorReport, runDoctorChecks, } from './doctor.js';
 export { openBrowserForMenu, runMenuLogin } from './login.js';

package/dist/auth-menu/select.js

@@ -1,4 +1,4 @@
-import { ANSI, parseKey, truncateAnsi } from './ansi.js';
+import { ANSI, parseKeys, truncateAnsi } from './ansi.js';
 import { isInteractive } from './terminal.js';
 /** How long a lone Escape byte waits for the rest of an arrow-key sequence. */
 const ESCAPE_TIMEOUT_MS = 50;
@@ -109,30 +109,36 @@ export async function select(terminal, items, options) {
         };
         const onSignal = () => finish(null);
         const onKey = (data) => {
-            if (escapeTimeout) {
-                clearTimeout(escapeTimeout);
-                escapeTimeout = null;
-            }
-            switch (parseKey(data)) {
-                case 'up':
-                    cursor = (cursor - 1 + items.length) % items.length;
-                    render();
-                    break;
-                case 'down':
-                    cursor = (cursor + 1) % items.length;
-                    render();
-                    break;
-                case 'enter':
-                    finish(items[cursor]?.value ?? null);
-                    break;
-                case 'escape':
-                    finish(null);
-                    break;
-                case 'escape-start':
-                    // A bare Escape byte is also the start of an arrow-key sequence
-                    // that may arrive split across reads; only a lone one cancels.
-                    escapeTimeout = setTimeout(() => finish(null), ESCAPE_TIMEOUT_MS);
+            for (const key of parseKeys(data)) {
+                if (cleaned)
                     break;
+                if (escapeTimeout) {
+                    clearTimeout(escapeTimeout);
+                    escapeTimeout = null;
+                }
+                switch (key) {
+                    case 'up':
+                        cursor = (cursor - 1 + items.length) % items.length;
+                        render();
+                        break;
+                    case 'down':
+                        cursor = (cursor + 1) % items.length;
+                        render();
+                        break;
+                    case 'enter':
+                        finish(items[cursor]?.value ?? null);
+                        break;
+                    case 'escape':
+                        finish(null);
+                        break;
+                    case 'escape-start':
+                        // A bare Escape byte is also the start of an arrow-key sequence
+                        // that may arrive split across reads; only a lone one cancels.
+                        escapeTimeout = setTimeout(() => finish(null), ESCAPE_TIMEOUT_MS);
+                        break;
+                    default:
+                        break;
+                }
             }
         };
         signals?.once('SIGINT', onSignal);

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.10.0",
+  "version": "0.11.1",
   "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": {