@cortexkit/common-auth 0.3.0 → 0.4.0

package/dist/store/mutate.js

@@ -4,7 +4,8 @@ import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
 import { PoolOperationError, } from './errors.js';
 import { callFailureHook } from './hooks.js';
 import { LockStack, } from './refresh-lock.js';
-import { buildRows, classifyConfig, classifyState, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, } from './schema.js';
+import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, rosterRowIn, setEntryIn, } from './schema.js';
+import { completeTornRows, loadRows } from './torn.js';
 async function readJson(path) {
     let text;
     try {
@@ -38,7 +39,7 @@ export async function readPool(ctx) {
         stateExists: state.exists,
         config: config.config,
         state: state.state,
-        rows: buildRows(config.config, state.state, ctx.codec),
+        rows: loadRows(config.config, state.state, ctx.codec),
     };
 }
 /** The refusal for a pool that is not ready, as a failure value. */
@@ -79,8 +80,13 @@ export class Transaction {
         this.config = structuredClone(snapshot.config);
         this.state = structuredClone(snapshot.state);
     }
+    /**
+     * The rows as every reader loads them: a row torn between the writes of a
+     * replace is shown as that replace leaves it once completed (see
+     * `PoolRow.torn`).
+     */
     rows() {
-        return buildRows(this.config, this.state, this.ctx.codec);
+        return loadRows(this.config, this.state, this.ctx.codec);
     }
     row(id) {
         return this.rows().find((row) => row.id === id);
@@ -92,7 +98,8 @@ export class Transaction {
     }
     /** The first roster row with this id (the one the pool loads). */
     rosterRow(id) {
-        return this.roster().find((raw) => isRecord(raw) && raw.id === id);
+        this.roster();
+        return rosterRowIn(this.config, id);
     }
     /**
      * Drops every roster row carrying this id. The row's per-row entry goes with
@@ -106,25 +113,28 @@ export class Transaction {
         return roster.length - kept.length;
     }
     entries() {
-        if (!isRecord(this.config[POOL_KEY]))
-            this.config[POOL_KEY] = {};
-        const pool = this.config[POOL_KEY];
-        if (!isRecord(pool[POOL_ROWS_KEY]))
-            pool[POOL_ROWS_KEY] = {};
-        return pool[POOL_ROWS_KEY];
+        return ensureEntries(this.config);
     }
     entry(id) {
-        const entries = this.entries();
-        const entry = Object.hasOwn(entries, id) ? entries[id] : undefined;
-        return isRecord(entry) ? entry : undefined;
+        this.entries();
+        return entryIn(this.config, id);
     }
     setEntry(id, entry) {
-        Object.defineProperty(this.entries(), id, {
-            value: entry,
-            enumerable: true,
-            writable: true,
-            configurable: true,
-        });
+        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
+     * 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);
+        if (torn.length === 0)
+            return;
+        this.config = config;
+        await this.commitConfig({ counted: false });
     }
     stateAccount(id) {
         const accounts = isRecord(this.state.accounts) ? this.state.accounts : {};
@@ -152,7 +162,7 @@ export class Transaction {
      * key untouched. Entries for ids no longer in the roster are dropped here,
      * and remembered so the id is not reused in this process.
      */
-    async commitConfig() {
+    async commitConfig(options = {}) {
         const roster = this.roster();
         const rosterIds = new Set();
         for (const raw of roster)
@@ -184,7 +194,7 @@ export class Transaction {
                 [POOL_ROWS_KEY]: kept,
             },
         };
-        await this.write(this.ctx.configPath, next, 'config');
+        await this.write(this.ctx.configPath, next, 'config', options.counted ?? true);
         this.config = next;
     }
     /** Writes the state: every unrecognised top-level and per-row key kept. */
@@ -199,7 +209,7 @@ export class Transaction {
         if (committed)
             this.progress.committed = committed;
     }
-    async write(path, value, file) {
+    async write(path, value, file, counted = true) {
         await writeJsonAtomic(path, value, {
             beforeRename: async () => {
                 await this.ctx.onStep?.(`before-${file}-write`, this.info);
@@ -207,7 +217,8 @@ export class Transaction {
                 await this.locks.assertAll();
             },
         });
-        this.progress.writes++;
+        if (counted)
+            this.progress.writes++;
         await this.ctx.onStep?.(`after-${file}-write`, this.info);
     }
 }
@@ -258,9 +269,12 @@ export async function initializePool(ctx, dropKeys) {
 }
 /**
  * Runs `fn` under the store-lock list. The pool must be ready: a pending
- * migration or a load error refuses before anything is written.
+ * migration or a load error refuses before anything is written. Unless
+ * `completeTorn` is false, rows torn between the writes of a replace are
+ * completed first, so `fn` never sees one; the writes that only record
+ * readings or reorder the roster opt out and leave such rows as they are.
  */
-export async function withTransaction(ctx, locks, progress, info, fn) {
+export async function withTransaction(ctx, locks, progress, info, fn, options = {}) {
     const mark = locks.held.length;
     try {
         for (const spec of ctx.storeLocks)
@@ -268,7 +282,10 @@ export async function withTransaction(ctx, locks, progress, info, fn) {
         const result = await readPool(ctx);
         if (result.status !== 'ready')
             throw notReadyError(result, info.operation, info.rowId, progress.writes > 0 ? 'after-first-write' : 'before-first-write');
-        return await fn(new Transaction(ctx, result, locks, progress, info));
+        const tx = new Transaction(ctx, result, locks, progress, info);
+        if (options.completeTorn ?? true)
+            await tx.completeTorn();
+        return await fn(tx);
     }
     finally {
         await locks.releaseTo(mark);

package/dist/store/pool.d.ts

@@ -120,7 +120,14 @@ export interface PoolStore {
      * (`invalid-input`). Takes `extraLocks`, then the store locks.
      */
     updateSettings(mutator: SettingsMutator, options?: UpdateSettingsOptions): Promise<UpdateSettingsResult>;
-    recordIdentity(id: string, identity: string, options?: RowOperationOptions): Promise<{
+    /**
+     * Records the identity a lookup found for the row's credential. Since
+     * 0.3.1 it takes the credential epoch the lookup was issued for, and
+     * refuses a lookup that completes after the row was replaced
+     * (`attribution`) or a row recorded for another account
+     * (`identity-mismatch`).
+     */
+    recordIdentity(id: string, identity: string, attribution: Pick<Attribution, 'credentialEpoch'>, options?: RowOperationOptions): Promise<{
         id: string;
         disabled: string[];
     }>;

package/dist/store/pool.js

@@ -77,8 +77,13 @@ export function openPoolStore(options) {
         async load() {
             const result = await readPool(ctx);
             if (result.status === 'ready') {
+                // A torn row is no candidate, but its pull is fired too: the pull
+                // completes the row on disk before reading it, so an interrupted
+                // replace of an OAuth row heals at the next load.
                 for (const row of result.rows)
-                    if (row.candidate && row.type === 'oauth' && row.needsFirstReading)
+                    if ((row.candidate || (row.torn && row.enabled)) &&
+                        row.type === 'oauth' &&
+                        row.needsFirstReading)
                         pulls.fire(row.id, 'load');
             }
             return toLoad(result);
@@ -98,7 +103,7 @@ export function openPoolStore(options) {
         reorder: (ids, callOptions) => reorderRows(rt, ids, callOptions),
         readSettings: () => readPoolSettings(rt),
         updateSettings: (mutator, callOptions) => updatePoolSettings(rt, mutator, callOptions),
-        recordIdentity: (id, identity, callOptions) => recordRowIdentity(rt, id, identity, callOptions),
+        recordIdentity: (id, identity, attribution, callOptions) => recordRowIdentity(rt, id, identity, attribution, callOptions),
         refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
         recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),
         requestReading: (id) => pulls.fire(id, 'admission'),

package/dist/store/rows.d.ts

@@ -1,8 +1,9 @@
+import type { Attribution } from './attribution.js';
 import { PoolOperationError } from './errors.js';
 import { type Transaction } from './mutate.js';
 import type { PoolLockSpec } from './refresh-lock.js';
 import { type StoreRuntime } from './runtime.js';
-import { type PoolCredential, type PoolRow, type StoredCredential } from './schema.js';
+import { type CredentialBinding, type PoolCredential, type PoolRow, type StoredCredential } from './schema.js';
 export type FailureHook = (rowId: string, error: PoolOperationError) => void | Promise<void>;
 export interface RowOperationOptions {
     /** Called once, awaited, on every non-success path, before locks release. */
@@ -87,12 +88,15 @@ export type AddResult = {
     credential: StoredCredential;
 };
 /**
- * Writes a rotated credential into the state file (one write). A rotation is
- * the same lineage: no epoch bump, no identity or quota change.
+ * 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.
  */
 export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string, credential: PoolCredential, extra?: {
     stamp?: number;
     clearErrors?: boolean;
+    binding?: CredentialBinding;
 }): 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?: {
@@ -146,7 +150,16 @@ export declare function removeRow(rt: StoreRuntime, id: string, options?: Remove
  * An order equal to the current one writes nothing.
  */
 export declare function reorderRows(rt: StoreRuntime, ids: readonly string[], options?: ReorderOptions): Promise<ReorderResult>;
-export declare function recordRowIdentity(rt: StoreRuntime, id: string, identity: string, options?: RowOperationOptions): Promise<{
+/**
+ * Records the wire identity an identity lookup found for a row's credential.
+ * `attribution` is the credential epoch the lookup was issued for (a row
+ * without an entry is at epoch 1): a lookup that completes after the row was
+ * replaced is refused (`attribution`), as a quota reading would be, so the
+ * first credential's account is never recorded on the second credential. A
+ * row already recorded for another account refuses (`identity-mismatch`):
+ * that is a replacement, not something learnt about the same credential.
+ */
+export declare function recordRowIdentity(rt: StoreRuntime, id: string, identity: string, attribution: Pick<Attribution, 'credentialEpoch'>, options?: RowOperationOptions): Promise<{
     id: string;
     disabled: string[];
 }>;

package/dist/store/rows.js

@@ -3,7 +3,8 @@ 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 { credentialProblem, fingerprintOf, idProblem, isRecord, rosterRowFor, rotationStamp, rowLockKey, stateFieldsFor, storedCredential, } from './schema.js';
+import { CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, 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. */
 const CREDENTIAL_STATE_FIELDS = [
     'access',
@@ -13,8 +14,10 @@ const CREDENTIAL_STATE_FIELDS = [
     'apiKey',
 ];
 /**
- * Writes a rotated credential into the state file (one write). A rotation is
- * the same lineage: no epoch bump, no identity or quota change.
+ * 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.
  */
 export async function rotateIn(rt, tx, id, credential, extra = {}) {
     const prior = tx.stateAccount(id);
@@ -43,7 +46,12 @@ export async function rotateIn(rt, tx, id, credential, extra = {}) {
                 : {}),
         }, stamp)
         : storedCredential(credential, stamp);
-    tx.setStateAccount(id, { ...kept, ...stateFieldsFor(credential, stamp) });
+    const epoch = tx.entry(id)?.credentialEpoch;
+    tx.setStateAccount(id, {
+        ...kept,
+        ...stateFieldsFor(credential, stamp),
+        [CREDENTIAL_STAMP_KEY]: stampFor(stored, typeof epoch === 'number' ? epoch : 1, extra.binding),
+    });
     await tx.commitState(stored);
     return stored;
 }
@@ -64,6 +72,10 @@ function requireUsableRow(operation, id, row, credential) {
         throw refusal(operation, id, 'type-mismatch', `row ${id} holds a ${row.type} credential`);
     return row;
 }
+/** 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`);
+}
 /** Keying changed between the unlocked read and the locked one: retry. */
 function keyChanged(operation, id) {
     return refusal(operation, id, 'row-key-changed', `row ${id}'s wire identity changed while its lock was being taken`, true);
@@ -97,18 +109,19 @@ export async function addRow(rt, input, options = {}) {
                     throw refusal('add', id, 'id-exists', `row ${id} already holds a credential`);
                 if (existing.type !== credential.type)
                     throw refusal('add', id, 'type-mismatch', `row ${id} is a ${existing.type} row`);
-                // An earlier add wrote this row's config and stopped before the
-                // state write; writing the credential now completes it at epoch 1.
-                if (!existing.hasEntry) {
+                // A roster row without a credential (left by another writer, or
+                // by an add of an earlier version that stopped between its
+                // writes): writing the credential now completes it at epoch 1.
+                if (!existing.hasEntry)
                     tx.setEntry(id, {
                         credentialEpoch: 1,
                         needsFirstReading: credential.type === 'oauth',
                     });
-                    await tx.commitConfig();
-                }
                 const stored = await rotateIn(rt, tx, id, credential, {
                     clearErrors: true,
                 });
+                if (!existing.hasEntry)
+                    await tx.commitConfig();
                 return { id, outcome: 'completed', credential: stored };
             }
             tx.roster().push(rosterRowFor({
@@ -134,8 +147,14 @@ export async function addRow(rt, input, options = {}) {
                     outcome = 'added-disabled';
                 }
             }
-            await tx.commitConfig();
+            // The credential is written first. A crash before the config write
+            // then leaves a state entry no roster row names, which no reader
+            // loads and `remove` drops; written the other way round, the new
+            // roster row could load beside a credential left under its id by an
+            // interrupted removal. Nothing of such a leftover entry is kept.
+            tx.dropStateAccount(id);
             const stored = await rotateIn(rt, tx, id, credential);
+            await tx.commitConfig();
             return { id, outcome, credential: stored };
         });
     });
@@ -159,33 +178,33 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
             const row = requireUsableRow('replace', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged('replace', id);
-            const entry = tx.entry(id) ?? {};
-            const priorEpoch = typeof entry.credentialEpoch === 'number'
-                ? entry.credentialEpoch
-                : 1;
-            const credentialEpoch = priorEpoch + 1;
-            const nextEntry = {
-                ...entry,
-                credentialEpoch,
-                needsFirstReading: true,
+            const priorEpoch = tx.entry(id)?.credentialEpoch;
+            const credentialEpoch = (typeof priorEpoch === 'number' ? priorEpoch : 1) + 1;
+            const binding = {
+                ...(input.identity !== undefined
+                    ? { identity: input.identity }
+                    : {}),
+                ...(credential.type === 'api'
+                    ? {
+                        baseURL: credential.baseURL.trim(),
+                        authHeader: credential.authHeader ?? 'authorization-bearer',
+                    }
+                    : {}),
             };
-            delete nextEntry.quota;
-            tx.setEntry(id, nextEntry);
-            const raw = tx.rosterRow(id);
-            if (input.identity !== undefined)
-                raw.accountId = input.identity;
-            else
-                delete raw.accountId;
-            if (credential.type === 'api') {
-                raw.baseURL = credential.baseURL.trim();
-                raw.authHeader = credential.authHeader ?? 'authorization-bearer';
-            }
+            bindReplacement(tx, id, credentialEpoch, binding);
             if (input.identity !== undefined)
                 disableIdentityDuplicates(tx, input.identity);
-            await tx.commitConfig();
+            // The new credential goes first, stamped with the new epoch and the
+            // binding. A crash before the config write leaves the stamp ahead
+            // of the config: every reader shows the row torn (completed, never
+            // a candidate) and the next store write completes the config from
+            // the stamp, so no reader pairs either credential with the other
+            // account's identity or endpoint.
             const stored = await rotateIn(rt, tx, id, credential, {
                 clearErrors: true,
+                binding,
             });
+            await tx.commitConfig();
             return { id, credential: stored, credentialEpoch };
         });
     });
@@ -208,6 +227,13 @@ 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 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).
+            if (input.identity !== undefined &&
+                row.identity !== undefined &&
+                input.identity !== row.identity)
+                throw identityMismatch('rotate', id);
             const stored = await rotateIn(rt, tx, id, credential);
             let configChanged = false;
             if (!row.hasEntry) {
@@ -445,14 +471,33 @@ export async function reorderRows(rt, ids, options = {}) {
             tx.config.accounts = next;
             await tx.commitConfig();
             return { ids: order, outcome: 'reordered' };
-        });
+        }, 
+        // A reorder keeps every roster row and entry byte for byte, so it
+        // leaves a torn row for a write on that row to complete.
+        { completeTorn: false });
     });
 }
-export async function recordRowIdentity(rt, id, identity, options = {}) {
+/**
+ * Records the wire identity an identity lookup found for a row's credential.
+ * `attribution` is the credential epoch the lookup was issued for (a row
+ * without an entry is at epoch 1): a lookup that completes after the row was
+ * replaced is refused (`attribution`), as a quota reading would be, so the
+ * first credential's account is never recorded on the second credential. A
+ * row already recorded for another account refuses (`identity-mismatch`):
+ * that is a replacement, not something learnt about the same credential.
+ */
+export async function recordRowIdentity(rt, id, identity, attribution, options = {}) {
     assertNotInsideHook('recordIdentity');
     return runOperation(rt.ctx, 'recordIdentity', id, options.onFailure, async (locks, progress) => {
         if (typeof identity !== 'string' || identity.length === 0)
             throw refusal('recordIdentity', id, 'invalid-input', 'identity must be non-empty');
+        const captured = isRecord(attribution)
+            ? attribution.credentialEpoch
+            : undefined;
+        if (typeof captured !== 'number' ||
+            !Number.isInteger(captured) ||
+            captured < 1)
+            throw refusal('recordIdentity', id, 'invalid-input', 'the credential epoch the identity lookup was issued for is required');
         const { row: seen } = await readRow(rt, 'recordIdentity', id);
         await locks.acquire(rowLockSpec(rt, seen));
         await locks.acquire(options.providerLock ?? rt.providerLock);
@@ -462,6 +507,10 @@ export async function recordRowIdentity(rt, id, identity, options = {}) {
             const row = requireUsableRow('recordIdentity', id, tx.row(id));
             if (rowLockKey(row) !== rowLockKey(seen))
                 throw keyChanged('recordIdentity', id);
+            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);
             const disabled = recordIdentityIn(tx, id, identity);
             await tx.commitConfig();
             return { id, disabled };

package/dist/store/schema.d.ts

@@ -58,6 +58,41 @@ export interface PoolRow {
     candidate: boolean;
     /** Set when the roster row or the per-row entry failed validation. */
     invalid?: 'roster' | 'entry';
+    /**
+     * 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.
+     */
+    torn?: true;
+}
+/**
+ * Key, inside a state-file account entry, of the stamp naming what the
+ * credential beside it belongs to. Older readers ignore it.
+ */
+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.
+ */
+export interface CredentialBinding {
+    identity?: string;
+    baseURL?: string;
+    authHeader?: 'authorization-bearer' | 'x-api-key';
+}
+/**
+ * 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.
+ */
+export interface CredentialStamp {
+    credentialEpoch: number;
+    digest: string;
+    binding?: CredentialBinding;
 }
 export type ConfigClassification = {
     status: 'ready';
@@ -88,6 +123,15 @@ export declare function idProblem(id: unknown): string | undefined;
 /** Same URL rule the older readers apply to an API-key row's `baseURL`. */
 export declare function isValidBaseURL(value: unknown): boolean;
 export declare function fingerprintOf(credential: PoolCredential | StoredCredential): string;
+/**
+ * The digest a credential stamp carries. It is kept apart from the
+ * fingerprint (a different input prefix) so the persisted value is never the
+ * dedupe key.
+ */
+export declare function credentialDigest(credential: PoolCredential | StoredCredential): string;
+export declare function stampFor(credential: PoolCredential | StoredCredential, credentialEpoch: number, binding?: CredentialBinding): CredentialStamp;
+/** A well-formed stamp, or undefined for anything else (which is ignored). */
+export declare function parseStamp(raw: unknown): CredentialStamp | undefined;
 /** A parsed file, or the reason it could not be parsed. */
 export type FileRead = {
     exists: false;
@@ -102,12 +146,21 @@ export declare function classifyConfig(read: FileRead): ConfigClassification;
 export declare function classifyState(read: FileRead): StateClassification;
 export declare function rosterOf(config: Record<string, unknown>): unknown[];
 export declare function entriesOf(config: Record<string, unknown>): Record<string, unknown>;
+/** The first roster row with this id (the one the pool loads). */
+export declare function rosterRowIn(config: Record<string, unknown>, id: string): Record<string, unknown> | undefined;
+/** The per-row entries of a config, created (empty) when absent. */
+export declare function ensureEntries(config: Record<string, unknown>): Record<string, unknown>;
+export declare function entryIn(config: Record<string, unknown>, id: string): Record<string, unknown> | undefined;
+/** Sets an entry as an own property, so an id such as `toString` is safe. */
+export declare function setEntryIn(config: Record<string, unknown>, id: string, entry: Record<string, unknown>): void;
 /**
- * Builds the rows of a ready pool. A roster row the older readers would
- * reject, a duplicate id, or a malformed per-row entry makes that one row
- * invalid (never a candidate) and blocks nothing else.
+ * Builds the rows of a ready pool from the files exactly as they are, without
+ * looking at credential stamps (see `loadRows` for the rows every reader
+ * gets). A roster row the older readers would reject, a duplicate id, or a
+ * malformed per-row entry makes that one row invalid (never a candidate) and
+ * blocks nothing else.
  */
-export declare function buildRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): PoolRow[];
+export declare function buildRawRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): PoolRow[];
 /** The row-lock key: recorded wire identity when known, else the local id. */
 export declare function rowLockKey(row: Pick<PoolRow, 'id' | 'identity'>): string;
 /**

package/dist/store/schema.js

@@ -13,6 +13,11 @@ export const LEGACY_STORE_VERSION = 1;
  * strictly above it counts as absent when they compare two copies of a token.
  */
 export const REFRESH_STAMP_TOLERANCE_MS = 5 * 60_000;
+/**
+ * Key, inside a state-file account entry, of the stamp naming what the
+ * credential beside it belongs to. Older readers ignore it.
+ */
+export const CREDENTIAL_STAMP_KEY = POOL_KEY;
 export function isRecord(value) {
     return value != null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -46,11 +51,70 @@ export function isValidBaseURL(value) {
         return false;
     }
 }
-export function fingerprintOf(credential) {
-    const secret = credential.type === 'oauth'
+function secretOf(credential) {
+    return credential.type === 'oauth'
         ? `oauth\0${credential.refresh}`
         : `api\0${credential.apiKey}`;
-    return createHash('sha256').update(secret).digest('hex');
+}
+export function fingerprintOf(credential) {
+    return createHash('sha256').update(secretOf(credential)).digest('hex');
+}
+/**
+ * The digest a credential stamp carries. It is kept apart from the
+ * fingerprint (a different input prefix) so the persisted value is never the
+ * dedupe key.
+ */
+export function credentialDigest(credential) {
+    return createHash('sha256')
+        .update(`credential-stamp\0${secretOf(credential)}`)
+        .digest('hex');
+}
+export function stampFor(credential, credentialEpoch, binding) {
+    return {
+        credentialEpoch,
+        digest: credentialDigest(credential),
+        ...(binding ? { binding: { ...binding } } : {}),
+    };
+}
+/** A well-formed stamp, or undefined for anything else (which is ignored). */
+export function parseStamp(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const epoch = raw.credentialEpoch;
+    if (typeof epoch !== 'number' || !Number.isInteger(epoch) || epoch < 1)
+        return undefined;
+    if (typeof raw.digest !== 'string')
+        return undefined;
+    if (!('binding' in raw))
+        return { credentialEpoch: epoch, digest: raw.digest };
+    const binding = raw.binding;
+    if (!isRecord(binding))
+        return undefined;
+    if ('identity' in binding &&
+        (typeof binding.identity !== 'string' || !binding.identity))
+        return undefined;
+    if ('baseURL' in binding && !isValidBaseURL(binding.baseURL))
+        return undefined;
+    if ('authHeader' in binding &&
+        binding.authHeader !== 'authorization-bearer' &&
+        binding.authHeader !== 'x-api-key')
+        return undefined;
+    return {
+        credentialEpoch: epoch,
+        digest: raw.digest,
+        binding: {
+            ...(typeof binding.identity === 'string'
+                ? { identity: binding.identity }
+                : {}),
+            ...(typeof binding.baseURL === 'string'
+                ? { baseURL: binding.baseURL.trim() }
+                : {}),
+            ...(binding.authHeader === 'authorization-bearer' ||
+                binding.authHeader === 'x-api-key'
+                ? { authHeader: binding.authHeader }
+                : {}),
+        },
+    };
 }
 export function classifyConfig(read) {
     if (!read.exists)
@@ -176,12 +240,41 @@ function credentialFor(raw, stateEntry) {
             : {}),
     };
 }
+/** The first roster row with this id (the one the pool loads). */
+export function rosterRowIn(config, id) {
+    return rosterOf(config).find((raw) => isRecord(raw) && raw.id === id);
+}
+/** The per-row entries of a config, created (empty) when absent. */
+export function ensureEntries(config) {
+    if (!isRecord(config[POOL_KEY]))
+        config[POOL_KEY] = {};
+    const pool = config[POOL_KEY];
+    if (!isRecord(pool[POOL_ROWS_KEY]))
+        pool[POOL_ROWS_KEY] = {};
+    return pool[POOL_ROWS_KEY];
+}
+export function entryIn(config, id) {
+    const entries = entriesOf(config);
+    const entry = Object.hasOwn(entries, id) ? entries[id] : undefined;
+    return isRecord(entry) ? entry : undefined;
+}
+/** Sets an entry as an own property, so an id such as `toString` is safe. */
+export function setEntryIn(config, id, entry) {
+    Object.defineProperty(ensureEntries(config), id, {
+        value: entry,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
 /**
- * Builds the rows of a ready pool. A roster row the older readers would
- * reject, a duplicate id, or a malformed per-row entry makes that one row
- * invalid (never a candidate) and blocks nothing else.
+ * Builds the rows of a ready pool from the files exactly as they are, without
+ * looking at credential stamps (see `loadRows` for the rows every reader
+ * gets). A roster row the older readers would reject, a duplicate id, or a
+ * malformed per-row entry makes that one row invalid (never a candidate) and
+ * blocks nothing else.
  */
-export function buildRows(config, state, codec) {
+export function buildRawRows(config, state, codec) {
     const entries = entriesOf(config);
     const stateAccounts = stateAccountsOf(state);
     const seen = new Set();