@cortexkit/common-auth 0.4.3 → 0.4.5

package/dist/store/mutate.d.ts

@@ -100,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

@@ -127,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/refresh.js

@@ -133,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

@@ -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)
@@ -294,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, {
@@ -570,6 +623,10 @@ export async function recordRowIdentity(rt, id, identity, attribution, options =
                 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/schema.d.ts

@@ -48,15 +48,21 @@ export interface QuotaCodec {
  * `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.
+ * 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 or endpoint than the row now holds.
+ * 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';
+export type CredentialStampStatus = 'none' | 'bound' | 'missing' | 'malformed' | 'mismatched' | 'legacy';
 /** One row of the pool as loaded. */
 export interface PoolRow {
     id: string;
@@ -84,9 +90,12 @@ 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;
     /**
@@ -111,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;
@@ -123,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';
@@ -167,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 }
@@ -125,14 +177,22 @@ 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.
+ * 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 !== undefined && binding.identity !== identity)
+    if (binding.identity !== identity)
         return false;
     if (binding.baseURL !== undefined &&
         (credential.type !== 'api' || credential.baseURL !== binding.baseURL))
@@ -157,9 +217,17 @@ function stampStatusOf(credential, credentialEpoch, identity, account) {
         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';
-    if (stamp.binding && !bindingAgrees(stamp.binding, credential, identity))
+    // `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';
 }

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[];
 };
@@ -27,8 +39,9 @@ export declare function completeTornRows(config: Record<string, unknown>, state:
  * 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.
+ * 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, options?: {
     requireCredentialStamps?: boolean;

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,66 @@ 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 strict store also completes a replace only when its stamp describes what
+ * the completed row would send: the stamp's dispatch digest must be that of
+ * the credential beside it, with an API key moved to the endpoint the binding
+ * names. The lineage digest alone covers the refresh token or API key, so
+ * without this check another writer that changed only the access token, the
+ * expiry or the endpoint would still have the strict store rewrite the row's
+ * epoch, identity and quota before refusing the row as unbound. A store
+ * without the option never compared dispatch digests here and still does not.
+ *
+ * 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) {
+/**
+ * The credential a torn replace leaves once its config write lands: the
+ * credential loaded beside the stamp, with the endpoint the stamp's binding
+ * names. Only an API key's endpoint lives in the config (an OAuth credential
+ * is entirely in the state file, which the replace has already written). A
+ * replace that moves a key to a new endpoint leaves the old `baseURL` and
+ * `authHeader` in the config until its config write, so the binding's
+ * `baseURL` and `authHeader` are the ones the replacement will be sent with.
+ */
+function projectedReplacement(credential, binding) {
+    if (credential.type !== 'api')
+        return credential;
+    return {
+        ...credential,
+        ...(binding.baseURL !== undefined ? { baseURL: binding.baseURL } : {}),
+        ...(binding.authHeader !== undefined
+            ? { authHeader: binding.authHeader }
+            : {}),
+    };
+}
+/** 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 +91,37 @@ 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) {
+                if (stamp.dispatch === undefined)
+                    continue;
+                // `digest` covers only the refresh token or API key, so another
+                // writer may still have changed the access token, the expiry or the
+                // endpoint the stamp names. `dispatch` covers all of what a request
+                // sends; completing the replace when it disagrees would move the
+                // row's epoch, identity and quota on a stamp that does not describe
+                // the credential. So the replacement as it would be sent (the loaded
+                // credential with the binding's endpoint) must have the stamp's
+                // dispatch digest; otherwise the row stays as on disk (unbound).
+                if (stamp.dispatch !==
+                    dispatchDigest(projectedReplacement(row.credential, stamp.binding)))
+                    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 +154,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,12 +169,16 @@ 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,
@@ -99,11 +186,12 @@ export function completeTornRows(config, state, codec) {
  * 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.
+ * 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, options = {}) {
-    const { config: whole, torn } = completeTornRows(config, state, codec);
+    const { config: whole, torn } = completeTornRows(config, state, codec, options);
     const rows = buildRawRows(whole, state, codec);
     for (const row of rows) {
         if (torn.includes(row.id)) {

package/package.json

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