@cortexkit/common-auth 0.4.2 → 0.4.4

package/dist/store/attribution.js

@@ -1,7 +1,7 @@
 import { PoolOperationError } from './errors.js';
 import { toFailure, withTransaction } from './mutate.js';
 import { LockStack } from './refresh-lock.js';
-import { refusal, unknownRow } from './runtime.js';
+import { refusal, requireBound, unknownRow, } from './runtime.js';
 import { isCredentialEpoch } from './schema.js';
 /**
  * Merges a quota observation into a row's stored map under the store locks,
@@ -26,6 +26,7 @@ export async function recordQuota(rt, id, attribution, observation) {
             // has no such triple on disk, so no reading is recorded for it.
             if (!row.credential)
                 throw refusal('pull', id, 'no-credential', `row ${id} holds no credential`);
+            requireBound('pull', row);
             const entry = tx.entry(id);
             if (row.torn ||
                 !entry ||

package/dist/store/errors.d.ts

@@ -19,7 +19,7 @@ export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pul
  * lock outcomes (a wait that ran out, and a lease found lost); the rest are
  * refusals and failures of the operation itself.
  */
-export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'after-persist-hook' | 'unexpected';
+export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'after-persist-hook' | 'unexpected';
 /**
  * The single failure value of every store operation. `committed` is present
  * only when the operation had already written a credential to the state file

package/dist/store/index.d.ts

@@ -12,7 +12,7 @@ export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.j
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
 export type { AddInput, AddResult, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
 export type { PullReason } from './runtime.js';
-export type { ApiKeyCredential, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
+export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
 export type { PoolSettings, SettingsMutator, SettingsRead, UpdateSettingsOptions, UpdateSettingsResult, } from './settings.js';
 export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/mutate.d.ts

@@ -23,6 +23,12 @@ export interface StoreContext {
     hold?: (point: HoldPoint, rowId: string) => void | Promise<void>;
     /** Ids whose per-row entry a library write dropped in this process. */
     removedIds: Set<string>;
+    /**
+     * When true, rows whose credential stamp is not bound load `unbound` and
+     * the operations that use a credential refuse them (see
+     * `OpenPoolStoreOptions.requireCredentialStamps`).
+     */
+    requireCredentialStamps?: boolean;
 }
 export interface Snapshot {
     configExists: boolean;
@@ -94,8 +100,9 @@ export declare class Transaction {
     entry(id: string): Record<string, unknown> | undefined;
     setEntry(id: string, entry: Record<string, unknown>): void;
     /**
-     * Writes the config of every row torn between the writes of a replace as
-     * that replace would have left it (see `completeTornRows`), in one config
+     * Writes the config of every row torn between the writes of a replace, or
+     * of a write giving it its first identity, as that write would have left it
+     * (see `completeTornRows`), in one config
      * write ahead of the operation's own. The write is counted apart from the
      * operation's: it is setup, like a pull giving a row its entry, so a later
      * refusal still reports `before-first-write`.

package/dist/store/mutate.js

@@ -39,7 +39,9 @@ export async function readPool(ctx) {
         stateExists: state.exists,
         config: config.config,
         state: state.state,
-        rows: loadRows(config.config, state.state, ctx.codec),
+        rows: loadRows(config.config, state.state, ctx.codec, {
+            requireCredentialStamps: ctx.requireCredentialStamps === true,
+        }),
     };
 }
 /** The refusal for a pool that is not ready, as a failure value. */
@@ -86,7 +88,9 @@ export class Transaction {
      * `PoolRow.torn`).
      */
     rows() {
-        return loadRows(this.config, this.state, this.ctx.codec);
+        return loadRows(this.config, this.state, this.ctx.codec, {
+            requireCredentialStamps: this.ctx.requireCredentialStamps === true,
+        });
     }
     row(id) {
         return this.rows().find((row) => row.id === id);
@@ -123,14 +127,15 @@ export class Transaction {
         setEntryIn(this.config, id, entry);
     }
     /**
-     * Writes the config of every row torn between the writes of a replace as
-     * that replace would have left it (see `completeTornRows`), in one config
+     * Writes the config of every row torn between the writes of a replace, or
+     * of a write giving it its first identity, as that write would have left it
+     * (see `completeTornRows`), in one config
      * write ahead of the operation's own. The write is counted apart from the
      * operation's: it is setup, like a pull giving a row its entry, so a later
      * refusal still reports `before-first-write`.
      */
     async completeTorn() {
-        const { config, torn } = completeTornRows(this.config, this.state, this.ctx.codec);
+        const { config, torn } = completeTornRows(this.config, this.state, this.ctx.codec, { requireCredentialStamps: this.ctx.requireCredentialStamps === true });
         if (torn.length === 0)
             return;
         this.config = config;

package/dist/store/pool.d.ts

@@ -14,6 +14,19 @@ export interface OpenPoolStoreOptions {
     configPath: string;
     statePath: string;
     quota: QuotaCodec;
+    /**
+     * Refuse every credential this store did not stamp (default false, which
+     * loads unstamped and mis-stamped credentials as older writers left them).
+     * When true, a row whose `stamp` is not `bound` loads `unbound` and is no
+     * candidate, and every operation that would use or keep its credential or
+     * what was observed about it (`refresh`, quota pulls, `recordQuota`,
+     * `recordIdentity`, `rotate`, and an `add` of the same secret or onto the
+     * same credential-less row) refuses with `unbound-credential` before any
+     * provider call or write, checked again under the locks and at commit.
+     * Nothing makes such a row bound except `replace`, which starts a new
+     * credential epoch and drops what was observed about the old one.
+     */
+    requireCredentialStamps?: boolean;
     /** Injected clock for leases, refresh stamps and `addedAt`. */
     now?: () => number;
     /**

package/dist/store/pool.js

@@ -59,6 +59,7 @@ export function openPoolStore(options) {
             ...(options.onLockStep ? { onLockStep: options.onLockStep } : {}),
         },
         removedIds: memory.removedIds,
+        requireCredentialStamps: options.requireCredentialStamps === true,
         ...(options.logger ? { logger: options.logger } : {}),
         ...(options.onStep ? { onStep: options.onStep } : {}),
         ...(options.hold ? { hold: options.hold } : {}),

package/dist/store/pull.d.ts

@@ -1,6 +1,6 @@
 import { PoolOperationError } from './errors.js';
 import type { PoolLogger } from './hooks.js';
-import type { PullReason, StoreRuntime } from './runtime.js';
+import { type PullReason, type StoreRuntime } from './runtime.js';
 import type { StoredCredential } from './schema.js';
 /** What a pull is issued with: the credential and its attribution tuple. */
 export interface PullRequest {

package/dist/store/pull.js

@@ -2,6 +2,7 @@ import { recordQuota } from './attribution.js';
 import { PoolOperationError } from './errors.js';
 import { toFailure, withTransaction } from './mutate.js';
 import { LockStack } from './refresh-lock.js';
+import { requireBound } from './runtime.js';
 /**
  * Fires quota pulls without ever making a caller wait for one. A pull first
  * gives a row without a per-row entry its entry at epoch 1 (its own locked
@@ -50,6 +51,14 @@ export class PullScheduler {
         try {
             const request = await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
                 const row = tx.row(id);
+                // A row that would pull but for its unbound credential refuses, so
+                // the failure hook hears of it instead of the pull vanishing.
+                if (row?.unbound &&
+                    row.enabled &&
+                    row.type === 'oauth' &&
+                    row.credential &&
+                    !row.invalid)
+                    requireBound('pull', row);
                 // Disabled, API-key and credential-less rows never pull.
                 if (!row?.candidate || row.type !== 'oauth')
                     return undefined;

package/dist/store/refresh.js

@@ -3,7 +3,7 @@ import { assertNotInsideHook, runInsideHook } from './hooks.js';
 import { recordIdentityIn } from './identity.js';
 import { runOperation, withTransaction } from './mutate.js';
 import { rotateIn } from './rows.js';
-import { readRow, refusal, rowLockSpec } from './runtime.js';
+import { readRow, refusal, requireBound, rowLockSpec, } from './runtime.js';
 import { rotationStamp, rotationStampUntrusted, rowLockKey, } from './schema.js';
 function requireRefreshable(id, row) {
     if (!row)
@@ -47,6 +47,7 @@ export async function refreshRow(rt, id, provider, options = {}) {
             const captureProgress = { writes: 0 };
             const read = await withTransaction(ctx, locks, captureProgress, { operation: 'refresh', rowId: id }, async (tx) => {
                 let row = requireRefreshable(id, tx.row(id));
+                requireBound('refresh', row);
                 if (!row.hasEntry) {
                     tx.setEntry(id, { credentialEpoch: 1, needsFirstReading: true });
                     await tx.commitConfig();
@@ -113,6 +114,10 @@ export async function refreshRow(rt, id, provider, options = {}) {
                     kind: 'attribution',
                     message: `row ${id} changed credential while its refresh was in flight; the rotation is discarded`,
                 });
+            // The epoch fence above does not see a credential another writer
+            // swapped in under the same epoch; the stamp does, and committing
+            // the rotation would stamp the swapped row as bound.
+            requireBound('refresh', current);
             const reason = await options.refuse?.(current);
             if (reason !== undefined)
                 return { refused: reason };
@@ -128,13 +133,20 @@ export async function refreshRow(rt, id, provider, options = {}) {
                 refresh: result.refresh,
                 expires: result.expires,
             };
+            const learnt = current.identity === undefined && result.identity
+                ? result.identity
+                : undefined;
+            // The rotated credential's stamp names a learnt identity before the
+            // config records it, so a crash between the two writes is completed
+            // forward rather than leaving an identity no stamp proves.
             const stored = await rotateIn(rt, tx, id, credential, {
                 stamp: rotationStamp(prior, now),
+                identity: learnt,
             });
             let identity = current.identity;
-            if (current.identity === undefined && result.identity) {
-                recordIdentityIn(tx, id, result.identity);
-                identity = result.identity;
+            if (learnt !== undefined) {
+                recordIdentityIn(tx, id, learnt);
+                identity = learnt;
                 await tx.commitConfig();
             }
             return { stored, identity, refused: undefined };

package/dist/store/rows.d.ts

@@ -89,15 +89,19 @@ export type AddResult = {
 };
 /**
  * Writes a credential into the state file (one write), stamped with the
- * credential epoch the row's entry holds in `tx` (1 without an entry) and,
- * for a replace, the binding the config is about to get. A rotation is the
- * same lineage: no epoch bump, no identity or quota change. An API key must
- * belong to the endpoint the row holds in `tx` (see `onRowEndpoint`).
+ * credential epoch the row's entry holds in `tx` (1 without an entry) and a
+ * binding: for a replace, the one the config is about to get (and the stamp
+ * is marked as a replace's); for every other write, the row's config as it
+ * stands in `tx` with the identity the operation is about to record
+ * (`identity`, see `bindingInTx`). A rotation is the same lineage: no epoch
+ * bump, no identity or quota change. An API key must belong to the endpoint
+ * the row holds in `tx` (see `onRowEndpoint`).
  */
 export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string, given: RotateCredential, extra?: {
     stamp?: number;
     clearErrors?: boolean;
     binding?: CredentialBinding;
+    identity?: string;
 }): 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?: {

package/dist/store/rows.js

@@ -2,7 +2,7 @@ import { PoolOperationError } from './errors.js';
 import { assertNotInsideHook, runInsideHook } from './hooks.js';
 import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, recordIdentityIn, } from './identity.js';
 import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
-import { readRow, refusal, rowLockSpec, unknownRow, } from './runtime.js';
+import { readRow, refusal, requireBound, rowLockSpec, unknownRow, } from './runtime.js';
 import { CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
 import { bindReplacement } from './torn.js';
 /** Fields of a state entry that belong to the credential it replaces. */
@@ -50,12 +50,42 @@ function onRowEndpoint(tx, id, credential) {
         throw refusal(tx.info.operation, id, 'endpoint-mismatch', `row ${id} sends its key to another endpoint or header; a key for another endpoint is a replacement`);
     return { ...credential, baseURL, authHeader };
 }
+/**
+ * The binding of a credential written into a row without a replace: the
+ * config as it stands in `tx`, plus the identity the same operation is about
+ * to record (`learnt`), if any. The identity is the roster row's recorded
+ * one, read the way `buildRawRows` reads it. A learnt identity is stamped
+ * before the config records it, so a crash between the two writes leaves a
+ * stamp naming an identity the config lacks, which every reader completes
+ * forward (see `torn.ts`); the reverse order would leave a config identity
+ * no stamp proves. An API key's endpoint is the one it was checked against
+ * (see `onRowEndpoint`).
+ */
+function bindingInTx(tx, id, stored, learnt) {
+    const raw = tx.rosterRow(id);
+    const identity = learnt ??
+        (isRecord(raw) && typeof raw.accountId === 'string' && raw.accountId
+            ? raw.accountId
+            : undefined);
+    return {
+        ...(identity !== undefined ? { identity } : {}),
+        ...(stored.type === 'api'
+            ? {
+                baseURL: stored.baseURL,
+                authHeader: stored.authHeader ?? 'authorization-bearer',
+            }
+            : {}),
+    };
+}
 /**
  * Writes a credential into the state file (one write), stamped with the
- * credential epoch the row's entry holds in `tx` (1 without an entry) and,
- * for a replace, the binding the config is about to get. A rotation is the
- * same lineage: no epoch bump, no identity or quota change. An API key must
- * belong to the endpoint the row holds in `tx` (see `onRowEndpoint`).
+ * credential epoch the row's entry holds in `tx` (1 without an entry) and a
+ * binding: for a replace, the one the config is about to get (and the stamp
+ * is marked as a replace's); for every other write, the row's config as it
+ * stands in `tx` with the identity the operation is about to record
+ * (`identity`, see `bindingInTx`). A rotation is the same lineage: no epoch
+ * bump, no identity or quota change. An API key must belong to the endpoint
+ * the row holds in `tx` (see `onRowEndpoint`).
  */
 export async function rotateIn(rt, tx, id, given, extra = {}) {
     const credential = onRowEndpoint(tx, id, given);
@@ -79,11 +109,29 @@ export async function rotateIn(rt, tx, id, given, extra = {}) {
     tx.setStateAccount(id, {
         ...kept,
         ...stateFieldsFor(credential, stamp),
-        [CREDENTIAL_STAMP_KEY]: stampFor(stored, typeof epoch === 'number' ? epoch : 1, extra.binding),
+        [CREDENTIAL_STAMP_KEY]: stampFor(stored, typeof epoch === 'number' ? epoch : 1, extra.binding ?? bindingInTx(tx, id, stored, extra.identity), { replace: extra.binding !== undefined }),
     });
     await tx.commitState(stored);
     return stored;
 }
+/**
+ * Restamps a bound row's credential, unchanged, so its stamp names the
+ * identity the caller is about to record in the config (same epoch, same
+ * credential, one state write). Written before the config for the reason
+ * `bindingInTx` gives. A row whose stamp is not bound (possible only without
+ * `requireCredentialStamps`) gets no new stamp, because a fresh stamp would
+ * vouch for a credential this store never proved: its identity is recorded in
+ * the config only, and the row keeps the stamp status it had.
+ */
+async function stampIdentityIn(tx, row, identity) {
+    if (!row.credential || row.stamp !== 'bound')
+        return;
+    tx.setStateAccount(row.id, {
+        ...(tx.stateAccount(row.id) ?? {}),
+        [CREDENTIAL_STAMP_KEY]: stampFor(row.credential, row.credentialEpoch ?? 1, bindingInTx(tx, row.id, row.credential, identity)),
+    });
+    await tx.commitState();
+}
 function checkInput(operation, id, credential) {
     const idIssue = operation === 'add' ? idProblem(id) : undefined;
     if (idIssue)
@@ -129,6 +177,11 @@ export async function addRow(rt, input, options = {}) {
             const fingerprint = fingerprintOf(credential);
             const same = rows.find((row) => row.invalid === undefined && row.fingerprint === fingerprint);
             if (same) {
+                // Re-adding a secret whose stamp is not proved would rotate it in
+                // and keep the identity and quota recorded beside it, making that
+                // unproved record look bound. The add is refused instead, and the
+                // caller replaces the row, which starts a new credential epoch.
+                requireBound('add', same);
                 // The same secret is the same credential, so re-adding it rotates
                 // that row. An identity or endpoint given with it must match the
                 // row's; a different one is refused rather than silently replaced
@@ -146,6 +199,10 @@ export async function addRow(rt, input, options = {}) {
                     throw refusal('add', id, 'invalid-row', `row ${id} is invalid`);
                 if (existing.credential)
                     throw refusal('add', id, 'id-exists', `row ${id} already holds a credential`);
+                // Completing a credential-less row keeps its epoch, identity and
+                // quota; when stamps are required those belong to no proved
+                // credential, so the row must be replaced instead.
+                requireBound('add', existing);
                 if (existing.type !== credential.type)
                     throw refusal('add', id, 'type-mismatch', `row ${id} is a ${existing.type} row`);
                 if (identity !== undefined &&
@@ -275,6 +332,9 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
             const row = requireUsableRow('rotate', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged('rotate', id);
+            // A rotation keeps the row's epoch, identity and quota, so it must
+            // never be what stamps an unproved row as bound.
+            requireBound('rotate', row);
             // A rotation stays with one account: it may record the first
             // identity the row learns, but a credential of another known
             // account is a replacement (new epoch, quota and errors dropped).
@@ -282,7 +342,12 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
                 row.identity !== undefined &&
                 input.identity !== row.identity)
                 throw identityMismatch('rotate', id);
-            const stored = await rotateIn(rt, tx, id, credential);
+            const learnt = input.identity !== undefined && row.identity === undefined
+                ? input.identity
+                : undefined;
+            const stored = await rotateIn(rt, tx, id, credential, {
+                identity: learnt,
+            });
             let configChanged = false;
             if (!row.hasEntry) {
                 tx.setEntry(id, {
@@ -553,10 +618,15 @@ export async function recordRowIdentity(rt, id, identity, attribution, options =
             const row = requireUsableRow('recordIdentity', id, tx.row(id));
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged('recordIdentity', id);
+            requireBound('recordIdentity', row);
             if ((row.credentialEpoch ?? 1) !== captured)
                 throw refusal('recordIdentity', id, 'attribution', `the identity for ${id} was looked up for a credential the row no longer holds`, true);
             if (row.identity !== undefined && row.identity !== identity)
                 throw identityMismatch('recordIdentity', id);
+            // The stamp names the identity first; a crash before the config
+            // write leaves a row every reader completes forward.
+            if (row.identity === undefined)
+                await stampIdentityIn(tx, row, identity);
             const disabled = recordIdentityIn(tx, id, identity);
             await tx.commitConfig();
             return { id, disabled };

package/dist/store/runtime.d.ts

@@ -25,4 +25,12 @@ export declare function readRow(rt: StoreRuntime, operation: PoolOperation, id:
     row: PoolRow;
 }>;
 export declare function unknownRow(operation: PoolOperation, id: string): PoolOperationError;
+/**
+ * Refuses a row the store was told to distrust: opened with
+ * `requireCredentialStamps`, a row whose credential stamp is not bound loads
+ * `unbound` (see `PoolRow.unbound`). Called on every locked read of the row
+ * an operation acts on, before it calls a provider or writes, so a credential
+ * another writer swapped in while the operation waited is refused too.
+ */
+export declare function requireBound(operation: PoolOperation, row: PoolRow): void;
 export declare function refusal(operation: PoolOperation, id: string, kind: PoolOperationError['kind'], message: string, retryable?: boolean): PoolOperationError;

package/dist/store/runtime.js

@@ -33,6 +33,17 @@ export function unknownRow(operation, id) {
         message: `no row ${id} in the pool`,
     });
 }
+/**
+ * Refuses a row the store was told to distrust: opened with
+ * `requireCredentialStamps`, a row whose credential stamp is not bound loads
+ * `unbound` (see `PoolRow.unbound`). Called on every locked read of the row
+ * an operation acts on, before it calls a provider or writes, so a credential
+ * another writer swapped in while the operation waited is refused too.
+ */
+export function requireBound(operation, row) {
+    if (row.unbound)
+        throw refusal(operation, row.id, 'unbound-credential', `row ${row.id}'s credential is not the one this store stamped for it (stamp ${row.stamp}); replace it with fresh material`);
+}
 export function refusal(operation, id, kind, message, retryable = false) {
     return new PoolOperationError({
         operation,

package/dist/store/schema.d.ts

@@ -42,6 +42,27 @@ export interface QuotaCodec {
     validate(value: unknown): boolean;
     merge(stored: unknown | undefined, observation: unknown): unknown;
 }
+/**
+ * What the stamp beside a row's credential proves (see `CredentialStamp`).
+ *
+ * `none`: the row holds no credential, so there is nothing to stamp.
+ * `bound`: the stamp was written with this credential (its digest matches),
+ * names the row's credential epoch (1 for a row without a per-row entry),
+ * the identity it records (or its recording none) and any endpoint it
+ * records are the row's, and its dispatch digest matches everything a
+ * request would send (the OAuth access and refresh tokens and expiry; the API
+ * key with its `baseURL` and `authHeader`).
+ * `missing`: the credential carries no stamp (written by a writer that does
+ * not know about stamps, or one that dropped it).
+ * `malformed`: the stamp is not one this store writes (wrong shape, or an
+ * epoch outside the positive safe integers).
+ * `mismatched`: the stamp was written for another credential, epoch,
+ * identity, endpoint, or token to send than the row now holds.
+ * `legacy`: a well-formed stamp written with this credential's secret but
+ * with no dispatch digest (written by 0.4.3 or earlier), so it proves
+ * neither the token sent nor the account or endpoint it goes to.
+ */
+export type CredentialStampStatus = 'none' | 'bound' | 'missing' | 'malformed' | 'mismatched' | 'legacy';
 /** One row of the pool as loaded. */
 export interface PoolRow {
     id: string;
@@ -69,11 +90,29 @@ export interface PoolRow {
     /**
      * Set when a replace stopped between its two writes: the state file holds
      * the new credential, stamped with the epoch and the identity or endpoint
-     * it belongs to, and the config still holds the replaced row. The row is
-     * shown as the replace leaves it once completed, is never a candidate, and
-     * the next store write on it writes the config to match.
+     * it belongs to, and the config still holds the replaced row. Also set when
+     * a write that gives a row its first identity (`recordIdentity`, or a
+     * `rotate` or refresh that learns one) stopped after stamping the identity
+     * and before recording it in the config. The row is shown as the write
+     * leaves it once completed, is never a candidate, and the next store write
+     * on it writes the config to match.
      */
     torn?: true;
+    /**
+     * Whether the credential is the one the store last stamped for this row
+     * (see `CredentialStampStatus`). Every row the store loads carries it; a
+     * torn row reports the stamp of the row as it is shown completed. It is
+     * optional only so that rows built by hand (test fixtures) still type.
+     */
+    stamp?: CredentialStampStatus;
+    /**
+     * Set only when the store was opened with `requireCredentialStamps` and
+     * the row's `stamp` is not `bound`: the row is never a candidate, and
+     * `refresh`, quota pulls, `recordQuota`, `recordIdentity`, `rotate` and a
+     * re-`add` onto it refuse with `unbound-credential`. Only `replace` (or a
+     * new row) makes it usable again.
+     */
+    unbound?: true;
 }
 /**
  * Key, inside a state-file account entry, of the stamp naming what the
@@ -81,8 +120,9 @@ export interface PoolRow {
  */
 export declare const CREDENTIAL_STAMP_KEY = "commonAuthPool";
 /**
- * The config-side half of a replacement: the identity the new credential
- * belongs to (absent: none is known) and, for an API key, its endpoint.
+ * What the config holds for a credential when its stamp is written: the
+ * identity it belongs to (absent: none is known yet) and, for an API key, its
+ * endpoint. For a replace it is the config the replace is about to write.
  */
 export interface CredentialBinding {
     identity?: string;
@@ -93,14 +133,27 @@ export interface CredentialBinding {
  * Written beside every credential the store puts in the state file. It names
  * the credential epoch the credential belongs to and a digest of its secret,
  * so a stamp left beside a credential another writer put there afterwards is
- * recognisable and ignored. A replace also records the binding it gives the
- * row, which is what lets a reader complete a replace that stopped after
- * writing the credential.
+ * recognisable and ignored.
+ *
+ * `digest` covers only the refresh token or API key: it names the credential
+ * lineage, and torn-replace detection matches it, including against stamps
+ * older versions wrote, so it keeps that exact definition. `dispatch` covers
+ * everything a request sends (see `dispatchDigest`), so a token or endpoint
+ * changed beside an unchanged lineage secret is caught; stamps written by
+ * 0.4.3 or earlier lack it.
+ *
+ * `binding` is the config the credential was written beside (see
+ * `CredentialBinding`); every write since 0.4.4 records it, earlier versions
+ * only on replace. `replace` marks a stamp written by a replace, which is
+ * what lets a reader complete a replace that stopped after writing the
+ * credential: a stamp from any other write is never completed as torn.
  */
 export interface CredentialStamp {
     credentialEpoch: number;
     digest: string;
+    dispatch?: string;
     binding?: CredentialBinding;
+    replace?: true;
 }
 export type ConfigClassification = {
     status: 'ready';
@@ -137,7 +190,25 @@ export declare function fingerprintOf(credential: PoolCredential | StoredCredent
  * dedupe key.
  */
 export declare function credentialDigest(credential: PoolCredential | StoredCredential): string;
-export declare function stampFor(credential: PoolCredential | StoredCredential, credentialEpoch: number, binding?: CredentialBinding): CredentialStamp;
+/**
+ * The digest of everything a request made with the credential sends or is
+ * served by: the OAuth access token, refresh token and expiry (the expiry
+ * decides whether the access token is used or refreshed first), or the API
+ * key with the `baseURL` and header it is sent to. Its input prefix differs
+ * from both the fingerprint's and `credentialDigest`'s, so it never equals
+ * either. The parts are JSON-encoded as a list, so no two credentials share
+ * an input. An access token or expiry the state file cannot hold as loaded
+ * (not a string, not a finite number) counts as absent, which is how
+ * `buildRawRows` loads it back.
+ */
+export declare function dispatchDigest(credential: PoolCredential | StoredCredential): string;
+/**
+ * The stamp for a credential written into a row at `credentialEpoch`, beside
+ * the config `binding` describes. `replace` is set only by a replace.
+ */
+export declare function stampFor(credential: PoolCredential | StoredCredential, credentialEpoch: number, binding: CredentialBinding, options?: {
+    replace?: boolean;
+}): CredentialStamp;
 /**
  * A credential epoch is a positive safe integer. Above `MAX_SAFE_INTEGER`,
  * adding one may give back the same number, so a replace would not move the

package/dist/store/schema.js

@@ -69,11 +69,49 @@ export function credentialDigest(credential) {
         .update(`credential-stamp\0${secretOf(credential)}`)
         .digest('hex');
 }
-export function stampFor(credential, credentialEpoch, binding) {
+/**
+ * The digest of everything a request made with the credential sends or is
+ * served by: the OAuth access token, refresh token and expiry (the expiry
+ * decides whether the access token is used or refreshed first), or the API
+ * key with the `baseURL` and header it is sent to. Its input prefix differs
+ * from both the fingerprint's and `credentialDigest`'s, so it never equals
+ * either. The parts are JSON-encoded as a list, so no two credentials share
+ * an input. An access token or expiry the state file cannot hold as loaded
+ * (not a string, not a finite number) counts as absent, which is how
+ * `buildRawRows` loads it back.
+ */
+export function dispatchDigest(credential) {
+    const parts = credential.type === 'oauth'
+        ? [
+            'oauth',
+            typeof credential.access === 'string' ? credential.access : null,
+            credential.refresh,
+            typeof credential.expires === 'number' &&
+                Number.isFinite(credential.expires)
+                ? credential.expires
+                : null,
+        ]
+        : [
+            'api',
+            credential.apiKey,
+            credential.baseURL.trim(),
+            credential.authHeader ?? 'authorization-bearer',
+        ];
+    return createHash('sha256')
+        .update(`credential-dispatch\0${JSON.stringify(parts)}`)
+        .digest('hex');
+}
+/**
+ * The stamp for a credential written into a row at `credentialEpoch`, beside
+ * the config `binding` describes. `replace` is set only by a replace.
+ */
+export function stampFor(credential, credentialEpoch, binding, options = {}) {
     return {
         credentialEpoch,
         digest: credentialDigest(credential),
-        ...(binding ? { binding: { ...binding } } : {}),
+        dispatch: dispatchDigest(credential),
+        binding: { ...binding },
+        ...(options.replace ? { replace: true } : {}),
     };
 }
 /**
@@ -93,8 +131,21 @@ export function parseStamp(raw) {
         return undefined;
     if (typeof raw.digest !== 'string')
         return undefined;
+    if ('dispatch' in raw && typeof raw.dispatch !== 'string')
+        return undefined;
+    if ('replace' in raw && raw.replace !== true)
+        return undefined;
+    const marks = {
+        ...(typeof raw.dispatch === 'string' ? { dispatch: raw.dispatch } : {}),
+        ...(raw.replace === true ? { replace: true } : {}),
+    };
+    // Every stamp that carries a dispatch digest is written with a binding; one
+    // without is not a stamp this store writes, and it would leave the row's
+    // identity unchecked.
     if (!('binding' in raw))
-        return { credentialEpoch: epoch, digest: raw.digest };
+        return 'dispatch' in raw || 'replace' in raw
+            ? undefined
+            : { credentialEpoch: epoch, digest: raw.digest };
     const binding = raw.binding;
     if (!isRecord(binding))
         return undefined;
@@ -110,6 +161,7 @@ export function parseStamp(raw) {
     return {
         credentialEpoch: epoch,
         digest: raw.digest,
+        ...marks,
         binding: {
             ...(typeof binding.identity === 'string'
                 ? { identity: binding.identity }
@@ -124,6 +176,61 @@ export function parseStamp(raw) {
         },
     };
 }
+/**
+ * Whether the binding of a stamp is the row's: the identity it names (or its
+ * naming none) must be exactly the row's recorded identity, and an endpoint
+ * it names must be the one the row sends its API key to.
+ *
+ * Every write that gives a row an identity (`add`, `replace`, `rotate` or a
+ * refresh that learns one, `recordIdentity`) writes the stamp naming it
+ * before the config, so this store never leaves a config identity beside a
+ * stamp that names none or another: that is another writer's doing and is
+ * `mismatched`. The reverse, a stamp naming an identity beside a config that
+ * has none, is such a write stopped between its two writes: the row as
+ * `buildRawRows` reads it from the files is `mismatched`, but `loadRows`,
+ * which every reader goes through, shows it with the identity recorded (see
+ * `torn.ts`), where it is `bound`.
+ */
+function bindingAgrees(binding, credential, identity) {
+    if (binding.identity !== identity)
+        return false;
+    if (binding.baseURL !== undefined &&
+        (credential.type !== 'api' || credential.baseURL !== binding.baseURL))
+        return false;
+    if (binding.authHeader !== undefined &&
+        (credential.type !== 'api' || credential.authHeader !== binding.authHeader))
+        return false;
+    return true;
+}
+/**
+ * The stamp status of a loaded row (see `CredentialStampStatus`).
+ * `credentialEpoch` is undefined only when the row's per-row entry exists but
+ * failed validation, in which case no stamp can match it.
+ */
+function stampStatusOf(credential, credentialEpoch, identity, account) {
+    if (!credential)
+        return 'none';
+    if (!isRecord(account) || !Object.hasOwn(account, CREDENTIAL_STAMP_KEY))
+        return 'missing';
+    const stamp = parseStamp(account[CREDENTIAL_STAMP_KEY]);
+    if (!stamp)
+        return 'malformed';
+    if (stamp.digest !== credentialDigest(credential))
+        return 'mismatched';
+    // A stamp from 0.4.3 or earlier proves neither the token sent nor (its
+    // binding being optional and identity-lenient) the account, so it is
+    // reported as such whatever else it says, and never as bound.
+    if (stamp.dispatch === undefined)
+        return 'legacy';
+    if (stamp.credentialEpoch !== credentialEpoch)
+        return 'mismatched';
+    // `parseStamp` refuses a stamp with a dispatch digest and no binding.
+    if (!stamp.binding || !bindingAgrees(stamp.binding, credential, identity))
+        return 'mismatched';
+    if (stamp.dispatch !== dispatchDigest(credential))
+        return 'mismatched';
+    return 'bound';
+}
 export function classifyConfig(read) {
     if (!read.exists)
         return { status: 'ready', exists: false, config: {} };
@@ -302,6 +409,7 @@ export function buildRawRows(config, state, codec) {
                     hasEntry: Object.hasOwn(entries, id),
                     candidate: false,
                     invalid: 'roster',
+                    stamp: 'none',
                 });
             continue;
         }
@@ -311,6 +419,9 @@ export function buildRawRows(config, state, codec) {
         const entry = hasEntry ? parseEntry(entries[id], codec) : undefined;
         const credential = credentialFor(raw, stateAccounts[id]);
         const enabled = raw.enabled !== false;
+        const identity = typeof raw.accountId === 'string' && raw.accountId
+            ? raw.accountId
+            : undefined;
         const row = {
             id,
             type,
@@ -320,9 +431,7 @@ export function buildRawRows(config, state, codec) {
             candidate: false,
             ...(typeof raw.label === 'string' ? { label: raw.label } : {}),
             ...(typeof raw.addedAt === 'number' ? { addedAt: raw.addedAt } : {}),
-            ...(typeof raw.accountId === 'string' && raw.accountId
-                ? { identity: raw.accountId }
-                : {}),
+            ...(identity !== undefined ? { identity } : {}),
             ...(credential
                 ? { credential, fingerprint: fingerprintOf(credential) }
                 : {}),
@@ -331,6 +440,9 @@ export function buildRawRows(config, state, codec) {
                 ? { disabledReason: entry.disabledReason }
                 : {}),
             ...(entry && 'quota' in entry ? { quota: entry.quota } : {}),
+            // A row without a per-row entry is at credential epoch 1 (the epoch the
+            // store stamps and later gives it), so its stamp is checked against 1.
+            stamp: stampStatusOf(credential, entry ? entry.credentialEpoch : hasEntry ? undefined : 1, identity, stateAccounts[id]),
         };
         if (hasEntry && !entry) {
             row.invalid = 'entry';

package/dist/store/torn.d.ts

@@ -1,9 +1,19 @@
 import { type RowEditor } from './identity.js';
 import { type CredentialBinding, type CredentialStamp, type PoolRow, type QuotaCodec } from './schema.js';
-/** Stamps of rows torn between the two writes of a replace, by row id. */
-export declare function tornStamps(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): Map<string, CredentialStamp & {
-    binding: CredentialBinding;
-}>;
+/** How a row left between the two writes of an operation is completed. */
+export type TornCompletion = {
+    kind: 'replace';
+    stamp: CredentialStamp & {
+        binding: CredentialBinding;
+    };
+} | {
+    kind: 'identity';
+    identity: string;
+};
+/** Rows left between the two writes of an operation, by row id. */
+export declare function tornStamps(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, options?: {
+    requireCredentialStamps?: boolean;
+}): Map<string, TornCompletion>;
 /**
  * The config half of a replacement: the row's entry moves to the new epoch,
  * loses its quota and needs a first reading; its roster row gets the new
@@ -13,11 +23,13 @@ export declare function tornStamps(config: Record<string, unknown>, state: Recor
  */
 export declare function bindReplacement(editor: RowEditor, id: string, credentialEpoch: number, binding: CredentialBinding): void;
 /**
- * The config with every torn row completed as its replace would have left
- * it, and the ids completed. The config passed in is not modified; when
- * nothing is torn it is returned as is.
+ * The config with every torn row completed as its interrupted write would
+ * have left it, and the ids completed. The config passed in is not modified;
+ * when nothing is torn it is returned as is.
  */
-export declare function completeTornRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): {
+export declare function completeTornRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, options?: {
+    requireCredentialStamps?: boolean;
+}): {
     config: Record<string, unknown>;
     torn: string[];
 };
@@ -25,5 +37,12 @@ export declare function completeTornRows(config: Record<string, unknown>, state:
  * The rows every reader gets. A torn row is shown completed (the identity,
  * endpoint and epoch its stamp names, beside the credential it stamps), is
  * marked `torn` and is never a candidate; every other row is as on disk.
+ * With `requireCredentialStamps`, a row whose stamp is not `bound` is marked
+ * `unbound` and is never a candidate either. A torn row is shown with the
+ * stamp of the interrupted write, which binds the completed row, so it is not
+ * unbound; once a store write puts its completion on disk it is no longer
+ * torn and is a candidate again like any other row.
  */
-export declare function loadRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): PoolRow[];
+export declare function loadRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec, options?: {
+    requireCredentialStamps?: boolean;
+}): PoolRow[];

package/dist/store/torn.js

@@ -1,5 +1,5 @@
-import { disableIdentityDuplicates } from './identity.js';
-import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, entryIn, isRecord, parseStamp, rosterRowIn, setEntryIn, } from './schema.js';
+import { disableIdentityDuplicates, recordIdentityIn, } from './identity.js';
+import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, dispatchDigest, entryIn, isRecord, parseStamp, rosterRowIn, setEntryIn, } from './schema.js';
 /*
  * A replace changes both files: the state file gets the new credential and
  * the config gets the new epoch, identity or endpoint. It writes the state
@@ -15,11 +15,37 @@ import { buildRawRows, CREDENTIAL_STAMP_KEY, credentialDigest, entryIn, isRecord
  * A stamp counts only beside the credential it was written with (its digest
  * matches): a writer that does not know about stamps may put another
  * credential beside an old one, and that stamp then says nothing. A stamp at
- * or behind the config's epoch is never torn: this store's own writes leave
- * the state file ahead of the config, never behind it.
+ * or behind the config's epoch is never torn as a replace: this store's own
+ * writes leave the state file ahead of the config, never behind it.
+ *
+ * Only a replace's stamp is ever completed as a replace. Since 0.4.4 every
+ * stamp carries a binding, so a replace's says so itself (`replace: true`); a
+ * stamp written by 0.4.3 or earlier has no dispatch digest, and those
+ * versions wrote a binding only on replace, so such a stamp with a binding is
+ * a replace's. A stamp from any other write that sits ahead of the config was
+ * not left by a crash (those writes keep the row's epoch), and completing it
+ * would rewrite the row's identity and drop its quota on a foreign writer's
+ * say-so. With `requireCredentialStamps` a 0.4.3-shaped replace stamp is not
+ * completed either: it proves nothing about the token sent, so the strict
+ * store leaves the row as it is on disk (`legacy`, unbound) rather than act
+ * on it; a store without the option completes it as before.
+ *
+ * A write that gives a row its first identity (`recordIdentity`, or a
+ * `rotate` or refresh that learns one) follows the same order: the stamp
+ * naming the identity first, then the config recording it. A crash between
+ * leaves a stamp at the row's epoch, matching the credential beside it
+ * exactly (digest and dispatch digest), that names an identity the config
+ * does not record; that is completed forward the same way, by recording the
+ * identity.
  */
-/** Stamps of rows torn between the two writes of a replace, by row id. */
-export function tornStamps(config, state, codec) {
+/** Whether a well-formed stamp was written by a replace. */
+function isReplaceStamp(stamp) {
+    if (!stamp.binding)
+        return false;
+    return stamp.replace === true || stamp.dispatch === undefined;
+}
+/** Rows left between the two writes of an operation, by row id. */
+export function tornStamps(config, state, codec, options = {}) {
     const accounts = isRecord(state.accounts) ? state.accounts : {};
     const torn = new Map();
     for (const row of buildRawRows(config, state, codec)) {
@@ -36,9 +62,24 @@ export function tornStamps(config, state, codec) {
         if (stamp.digest !== credentialDigest(row.credential))
             continue;
         // A row without an entry is at epoch 1, as everywhere else.
-        if (stamp.credentialEpoch <= (row.credentialEpoch ?? 1))
-            continue;
-        torn.set(row.id, { ...stamp, binding: stamp.binding });
+        const epoch = row.credentialEpoch ?? 1;
+        if (stamp.credentialEpoch > epoch) {
+            if (!isReplaceStamp(stamp))
+                continue;
+            if (options.requireCredentialStamps && stamp.dispatch === undefined)
+                continue;
+            torn.set(row.id, {
+                kind: 'replace',
+                stamp: { ...stamp, binding: stamp.binding },
+            });
+        }
+        else if (stamp.credentialEpoch === epoch &&
+            stamp.dispatch !== undefined &&
+            stamp.dispatch === dispatchDigest(row.credential) &&
+            stamp.binding.identity !== undefined &&
+            row.identity === undefined) {
+            torn.set(row.id, { kind: 'identity', identity: stamp.binding.identity });
+        }
     }
     return torn;
 }
@@ -71,13 +112,13 @@ export function bindReplacement(editor, id, credentialEpoch, binding) {
         raw.authHeader = binding.authHeader;
 }
 /**
- * The config with every torn row completed as its replace would have left
- * it, and the ids completed. The config passed in is not modified; when
- * nothing is torn it is returned as is.
+ * The config with every torn row completed as its interrupted write would
+ * have left it, and the ids completed. The config passed in is not modified;
+ * when nothing is torn it is returned as is.
  */
-export function completeTornRows(config, state, codec) {
-    const stamps = tornStamps(config, state, codec);
-    if (stamps.size === 0)
+export function completeTornRows(config, state, codec, options = {}) {
+    const completions = tornStamps(config, state, codec, options);
+    if (completions.size === 0)
         return { config, torn: [] };
     const next = structuredClone(config);
     const editor = {
@@ -86,28 +127,39 @@ export function completeTornRows(config, state, codec) {
         entry: (id) => entryIn(next, id),
         setEntry: (id, entry) => setEntryIn(next, id, entry),
     };
-    for (const [id, stamp] of stamps)
-        bindReplacement(editor, id, stamp.credentialEpoch, stamp.binding);
-    for (const stamp of stamps.values())
-        if (stamp.binding.identity !== undefined)
-            disableIdentityDuplicates(editor, stamp.binding.identity);
-    return { config: next, torn: [...stamps.keys()] };
+    for (const [id, completion] of completions)
+        if (completion.kind === 'replace')
+            bindReplacement(editor, id, completion.stamp.credentialEpoch, completion.stamp.binding);
+    for (const [id, completion] of completions) {
+        if (completion.kind === 'identity')
+            recordIdentityIn(editor, id, completion.identity);
+        else if (completion.stamp.binding.identity !== undefined)
+            disableIdentityDuplicates(editor, completion.stamp.binding.identity);
+    }
+    return { config: next, torn: [...completions.keys()] };
 }
 /**
  * The rows every reader gets. A torn row is shown completed (the identity,
  * endpoint and epoch its stamp names, beside the credential it stamps), is
  * marked `torn` and is never a candidate; every other row is as on disk.
+ * With `requireCredentialStamps`, a row whose stamp is not `bound` is marked
+ * `unbound` and is never a candidate either. A torn row is shown with the
+ * stamp of the interrupted write, which binds the completed row, so it is not
+ * unbound; once a store write puts its completion on disk it is no longer
+ * torn and is a candidate again like any other row.
  */
-export function loadRows(config, state, codec) {
-    const { config: whole, torn } = completeTornRows(config, state, codec);
+export function loadRows(config, state, codec, options = {}) {
+    const { config: whole, torn } = completeTornRows(config, state, codec, options);
     const rows = buildRawRows(whole, state, codec);
-    if (torn.length === 0)
-        return rows;
     for (const row of rows) {
-        if (!torn.includes(row.id))
-            continue;
-        row.torn = true;
-        row.candidate = false;
+        if (torn.includes(row.id)) {
+            row.torn = true;
+            row.candidate = false;
+        }
+        if (options.requireCredentialStamps && row.stamp !== 'bound') {
+            row.unbound = true;
+            row.candidate = false;
+        }
     }
     return rows;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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": {