@cortexkit/common-auth 0.4.1 → 0.4.3

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;

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);

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 };

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. */
@@ -129,6 +129,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 +151,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 +284,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).
@@ -553,6 +565,7 @@ 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)

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,21 @@ 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),
+ * and any identity or endpoint it records is the row's.
+ * `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 or endpoint than the row now holds.
+ */
+export type CredentialStampStatus = 'none' | 'bound' | 'missing' | 'malformed' | 'mismatched';
 /** One row of the pool as loaded. */
 export interface PoolRow {
     id: string;
@@ -74,6 +89,21 @@ export interface PoolRow {
      * 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

package/dist/store/schema.js

@@ -124,6 +124,45 @@ export function parseStamp(raw) {
         },
     };
 }
+/**
+ * Whether a binding a stamp records is the row's: an identity it names must
+ * be the row's recorded identity, and an endpoint it names must be the one
+ * the row sends its API key to. A binding without an identity says none was
+ * known when it was written, so an identity learnt since does not contradict
+ * it.
+ */
+function bindingAgrees(binding, credential, identity) {
+    if (binding.identity !== undefined && 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';
+    if (stamp.credentialEpoch !== credentialEpoch)
+        return 'mismatched';
+    if (stamp.binding && !bindingAgrees(stamp.binding, credential, identity))
+        return 'mismatched';
+    return 'bound';
+}
 export function classifyConfig(read) {
     if (!read.exists)
         return { status: 'ready', exists: false, config: {} };
@@ -302,6 +341,7 @@ export function buildRawRows(config, state, codec) {
                     hasEntry: Object.hasOwn(entries, id),
                     candidate: false,
                     invalid: 'roster',
+                    stamp: 'none',
                 });
             continue;
         }
@@ -311,6 +351,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 +363,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 +372,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

@@ -25,5 +25,11 @@ 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
+ * replacement's stamp, which binds the completed row, so it is not unbound:
+ * it stays out of routing only until its completion is written.
  */
-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

@@ -97,17 +97,23 @@ export function completeTornRows(config, state, codec) {
  * 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
+ * replacement's stamp, which binds the completed row, so it is not unbound:
+ * it stays out of routing only until its completion is written.
  */
-export function loadRows(config, state, codec) {
+export function loadRows(config, state, codec, options = {}) {
     const { config: whole, torn } = completeTornRows(config, state, codec);
     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.1",
+  "version": "0.4.3",
   "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": {