@cortexkit/common-auth 0.4.0 → 0.4.1

package/dist/claustrum/roster.js

@@ -359,22 +359,42 @@ export function acceptVaultRoute(path, routeId) {
         };
     });
 }
-function holdsReceipt(row, receipt) {
+/**
+ * What a receipt may do to a row's quota: `hold` (the row holds the receipt's
+ * credential and account), `bind` (the row has never had a known account and
+ * the receipt proves one, so the row takes that account with the reading) or
+ * `refuse`.
+ */
+function receiptFence(row, receipt) {
     if (!memberIds(row).includes(receipt.credentialId))
-        return false;
+        return 'refuse';
     // While the vault makes no claim, the roster's own expectation proves
     // nothing about which account the reading came from.
     if (row.unclaimed &&
         (receipt.accountIdentitySource === 'expected' ||
             receipt.accountIdentitySource === 'none'))
-        return false;
+        return 'refuse';
     // Equality, never compatibility: a known account on one side does not match
-    // an absent one on the other. The one exception is a row still without any
-    // known account, reached by a receipt issued for it in that state; the
-    // credential id above is then the whole binding.
-    return (row.accountIdentity === receipt.accountIdentity ||
-        (row.accountIdentity === undefined &&
-            receipt.expectedAccountIdentity === undefined));
+    // an absent one on the other. The only absent-absent match is a row that
+    // has never had a known account and a receipt that names none either.
+    if (row.accountIdentity === receipt.accountIdentity)
+        return 'hold';
+    // A row that has never had a known account, reached by a receipt issued for
+    // it in that state whose served or parsed identity names an account. The
+    // reading belongs to that account, so keeping it without the account would
+    // let the next list that names a different account inherit it as if that
+    // account had been learned for the first time. The row takes the account
+    // with the reading instead: a later list naming another account is then a
+    // known replacement and inherits nothing. Only a single-credential row is
+    // bound, since one credential's account says nothing about the others.
+    if (row.accountIdentity === undefined &&
+        receipt.expectedAccountIdentity === undefined &&
+        receipt.accountIdentity !== undefined &&
+        (receipt.accountIdentitySource === 'asserted' ||
+            receipt.accountIdentitySource === 'parsed') &&
+        memberIds(row).length === 1)
+        return 'bind';
+    return 'refuse';
 }
 /**
  * Merge a quota observation into a vault row through `/quota`'s merge. The
@@ -386,13 +406,20 @@ function holdsReceipt(row, receipt) {
 export function recordVaultQuota(path, input) {
     return mutateVaultRoster(path, (current) => {
         const row = current?.rows.find((entry) => entry.routeId === input.routeId);
-        if (!current || !row || !holdsReceipt(row, input))
+        const fence = !current || !row ? 'refuse' : receiptFence(row, input);
+        if (!current || !row || fence === 'refuse')
             return { result: false };
         const quota = mergeQuotaObservation(row.quota, input.observation);
+        // A bound account is `unclaimed`: the vault's list has not named it, and
+        // the next projection keeps it as the account this credential last
+        // logged into until the vault names one.
+        const bound = fence === 'bind'
+            ? { accountIdentity: input.accountIdentity, unclaimed: true }
+            : {};
         return {
             next: {
                 ...current,
-                rows: current.rows.map((entry) => entry === row ? { ...entry, quota } : entry),
+                rows: current.rows.map((entry) => entry === row ? { ...entry, ...bound, quota } : entry),
             },
             result: true,
         };

package/dist/store/attribution.js

@@ -2,6 +2,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 { isCredentialEpoch } from './schema.js';
 /**
  * Merges a quota observation into a row's stored map under the store locks,
  * after attribution passes. Needs no row lock, so it is permitted from
@@ -12,6 +13,8 @@ export async function recordQuota(rt, id, attribution, observation) {
     const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
     const progress = { writes: 0 };
     try {
+        if (!isCredentialEpoch(attribution?.credentialEpoch))
+            throw refusal('pull', id, 'invalid-input', 'the credential epoch the reading was issued for must be a positive safe integer');
         await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
             const row = tx.row(id);
             if (!row)

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' | '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' | '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, StoredCredential, } from './schema.js';
+export type { ApiKeyCredential, 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

@@ -64,7 +64,10 @@ export declare class Transaction {
     readonly snapshot: Snapshot;
     private readonly locks;
     private readonly progress;
-    private readonly info;
+    readonly info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    };
     config: Record<string, unknown>;
     state: Record<string, unknown>;
     constructor(ctx: StoreContext, snapshot: Snapshot, locks: LockStack, progress: Progress, info: {

package/dist/store/pool.d.ts

@@ -6,7 +6,7 @@ import { type PullHook } from './pull.js';
 import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
 import { type AddInput, type AddResult, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
-import { type PoolCredential, type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
+import { type PoolCredential, type PoolRow, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.js';
 import { type SettingsMutator, type SettingsRead, type UpdateSettingsOptions, type UpdateSettingsResult } from './settings.js';
 export interface OpenPoolStoreOptions {
     /** The provider every row of this pool belongs to; keys the provider-wide lock. */
@@ -75,7 +75,13 @@ export interface PoolStore {
         credential: StoredCredential;
         credentialEpoch: number;
     }>;
-    rotate(id: string, credential: PoolCredential, input?: {
+    /**
+     * Refreshes the secret a row holds without changing its account or
+     * endpoint. Since 0.4.1 an API key may leave out `baseURL` and `authHeader`
+     * to keep the row's, and one that gives another is refused
+     * (`endpoint-mismatch`) before writing: that is a `replace`.
+     */
+    rotate(id: string, credential: RotateCredential, input?: {
         identity?: string;
     }, options?: RowOperationOptions): Promise<{
         id: string;

package/dist/store/rows.d.ts

@@ -3,7 +3,7 @@ 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 CredentialBinding, type PoolCredential, type PoolRow, type StoredCredential } from './schema.js';
+import { type CredentialBinding, type PoolCredential, type PoolRow, type RotateCredential, 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. */
@@ -91,9 +91,10 @@ 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.
+ * 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, credential: PoolCredential, extra?: {
+export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string, given: RotateCredential, extra?: {
     stamp?: number;
     clearErrors?: boolean;
     binding?: CredentialBinding;
@@ -106,7 +107,7 @@ export declare function replaceRow(rt: StoreRuntime, id: string, credential: Poo
     credential: StoredCredential;
     credentialEpoch: number;
 }>;
-export declare function rotateRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: {
+export declare function rotateRow(rt: StoreRuntime, id: string, credential: RotateCredential, input?: {
     identity?: string;
 }, options?: RowOperationOptions): Promise<{
     id: string;

package/dist/store/rows.js

@@ -3,7 +3,7 @@ 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 { CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isRecord, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.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. */
 const CREDENTIAL_STATE_FIELDS = [
@@ -13,13 +13,52 @@ const CREDENTIAL_STATE_FIELDS = [
     'lastRefreshedAt',
     'apiKey',
 ];
+/**
+ * The endpoint an API-key roster row sends its key to, as `buildRawRows` loads
+ * it: the trimmed `baseURL`, and a bearer header unless the row names
+ * `x-api-key`.
+ */
+function rowEndpoint(raw) {
+    return {
+        baseURL: String(raw.baseURL).trim(),
+        authHeader: raw.authHeader === 'x-api-key' ? 'x-api-key' : 'authorization-bearer',
+    };
+}
+/**
+ * The credential as it will sit in the row. The state file holds only an API
+ * key; its endpoint lives in the roster row. So an API key written into a row
+ * is sent wherever that row says, and one given for another `baseURL` or
+ * `authHeader` would silently be paired with an endpoint it was not issued
+ * for. A part the caller leaves out is the row's; a part it gives must equal
+ * the row's, else the write is refused (`endpoint-mismatch`) before anything
+ * is written. Moving a row to another endpoint is a `replace`, which writes
+ * the new endpoint first.
+ */
+function onRowEndpoint(tx, id, credential) {
+    if (credential.type !== 'api')
+        return credential;
+    const raw = tx.rosterRow(id);
+    if (!isRecord(raw)) {
+        if (credential.baseURL === undefined)
+            throw refusal(tx.info.operation, id, 'invalid-input', 'api credential needs a valid baseURL');
+        return { ...credential, baseURL: credential.baseURL };
+    }
+    const endpoint = rowEndpoint(raw);
+    const baseURL = credential.baseURL?.trim() ?? endpoint.baseURL;
+    const authHeader = credential.authHeader ?? endpoint.authHeader;
+    if (baseURL !== endpoint.baseURL || authHeader !== endpoint.authHeader)
+        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 };
+}
 /**
  * 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.
+ * 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, credential, extra = {}) {
+export async function rotateIn(rt, tx, id, given, extra = {}) {
+    const credential = onRowEndpoint(tx, id, given);
     const prior = tx.stateAccount(id);
     const priorStamp = typeof prior?.lastRefreshedAt === 'number'
         ? prior.lastRefreshedAt
@@ -35,17 +74,7 @@ export async function rotateIn(rt, tx, id, credential, extra = {}) {
         delete kept.lastQuotaRefreshError;
         delete kept.quota;
     }
-    const raw = tx.rosterRow(id);
-    const stored = credential.type === 'api' && isRecord(raw)
-        ? storedCredential({
-            ...credential,
-            baseURL: String(raw.baseURL ?? credential.baseURL),
-            ...(raw.authHeader === 'x-api-key' ||
-                raw.authHeader === 'authorization-bearer'
-                ? { authHeader: raw.authHeader }
-                : {}),
-        }, stamp)
-        : storedCredential(credential, stamp);
+    const stored = storedCredential(credential, stamp);
     const epoch = tx.entry(id)?.credentialEpoch;
     tx.setStateAccount(id, {
         ...kept,
@@ -59,7 +88,9 @@ function checkInput(operation, id, credential) {
     const idIssue = operation === 'add' ? idProblem(id) : undefined;
     if (idIssue)
         throw refusal(operation, id, 'invalid-input', idIssue);
-    const credentialIssue = credentialProblem(credential);
+    const credentialIssue = credentialProblem(credential, {
+        baseURLOptional: operation === 'rotate',
+    });
     if (credentialIssue)
         throw refusal(operation, id, 'invalid-input', credentialIssue);
 }
@@ -98,6 +129,14 @@ export async function addRow(rt, input, options = {}) {
             const fingerprint = fingerprintOf(credential);
             const same = rows.find((row) => row.invalid === undefined && row.fingerprint === fingerprint);
             if (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
+                // by what the row already holds.
+                if (identity !== undefined &&
+                    same.identity !== undefined &&
+                    identity !== same.identity)
+                    throw identityMismatch('add', same.id);
                 const stored = await rotateIn(rt, tx, same.id, credential);
                 return { id: same.id, outcome: 'rotated', credential: stored };
             }
@@ -109,6 +148,10 @@ 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`);
+                if (identity !== undefined &&
+                    existing.identity !== undefined &&
+                    identity !== existing.identity)
+                    throw identityMismatch('add', id);
                 // 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.
@@ -180,6 +223,11 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
                 throw keyChanged('replace', id);
             const priorEpoch = tx.entry(id)?.credentialEpoch;
             const credentialEpoch = (typeof priorEpoch === 'number' ? priorEpoch : 1) + 1;
+            // An epoch past the safe integer range could equal the one before
+            // it, so readers could not tell the new credential from the old.
+            // Refused before anything is written; the row keeps its credential.
+            if (!isCredentialEpoch(credentialEpoch))
+                throw refusal('replace', id, 'invalid-row', `row ${id}'s credential epoch cannot advance past ${Number.MAX_SAFE_INTEGER}; remove the row and add the new credential as a new row`);
             const binding = {
                 ...(input.identity !== undefined
                     ? { identity: input.identity }
@@ -494,9 +542,7 @@ export async function recordRowIdentity(rt, id, identity, attribution, options =
         const captured = isRecord(attribution)
             ? attribution.credentialEpoch
             : undefined;
-        if (typeof captured !== 'number' ||
-            !Number.isInteger(captured) ||
-            captured < 1)
+        if (!isCredentialEpoch(captured))
             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));

package/dist/store/schema.d.ts

@@ -25,6 +25,14 @@ export type ApiKeyCredential = {
     authHeader?: 'authorization-bearer' | 'x-api-key';
 };
 export type PoolCredential = OAuthCredential | ApiKeyCredential;
+/**
+ * What `rotate` takes. Rotation refreshes the secret of the endpoint a row
+ * already has, so an API key may leave out `baseURL` (and `authHeader`) to
+ * keep the row's; one it gives must equal the row's.
+ */
+export type RotateCredential = OAuthCredential | (Omit<ApiKeyCredential, 'baseURL'> & {
+    baseURL?: string;
+});
 /** A credential as stored: an OAuth credential also carries its refresh stamp. */
 export type StoredCredential = (OAuthCredential & {
     lastRefreshedAt?: number;
@@ -130,6 +138,12 @@ export declare function fingerprintOf(credential: PoolCredential | StoredCredent
  */
 export declare function credentialDigest(credential: PoolCredential | StoredCredential): string;
 export declare function stampFor(credential: PoolCredential | StoredCredential, credentialEpoch: number, binding?: CredentialBinding): 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
+ * epoch and nothing could tell the old credential's work from the new one's.
+ */
+export declare function isCredentialEpoch(value: unknown): value is number;
 /** 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. */
@@ -183,4 +197,6 @@ export declare function rosterRowFor(input: {
 /** The state-file fields a credential occupies, in the older readers' names. */
 export declare function stateFieldsFor(credential: PoolCredential, lastRefreshedAt: number | undefined): Record<string, unknown>;
 export declare function storedCredential(credential: PoolCredential, lastRefreshedAt: number | undefined): StoredCredential;
-export declare function credentialProblem(credential: unknown): string | undefined;
+export declare function credentialProblem(credential: unknown, options?: {
+    baseURLOptional?: boolean;
+}): string | undefined;

package/dist/store/schema.js

@@ -76,12 +76,20 @@ export function stampFor(credential, credentialEpoch, binding) {
         ...(binding ? { binding: { ...binding } } : {}),
     };
 }
+/**
+ * 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
+ * epoch and nothing could tell the old credential's work from the new one's.
+ */
+export function isCredentialEpoch(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
 /** 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)
+    if (!isCredentialEpoch(epoch))
         return undefined;
     if (typeof raw.digest !== 'string')
         return undefined;
@@ -190,7 +198,7 @@ function parseEntry(raw, codec) {
     if (!isRecord(raw))
         return undefined;
     const epoch = raw.credentialEpoch;
-    if (typeof epoch !== 'number' || !Number.isInteger(epoch) || epoch < 1)
+    if (!isCredentialEpoch(epoch))
         return undefined;
     if ('needsFirstReading' in raw && typeof raw.needsFirstReading !== 'boolean')
         return undefined;
@@ -395,7 +403,7 @@ export function storedCredential(credential, lastRefreshedAt) {
         ...(lastRefreshedAt !== undefined ? { lastRefreshedAt } : {}),
     };
 }
-export function credentialProblem(credential) {
+export function credentialProblem(credential, options = {}) {
     if (!isRecord(credential))
         return 'credential must be an object';
     if (credential.type === 'oauth') {
@@ -408,7 +416,8 @@ export function credentialProblem(credential) {
             return 'api credential needs an api key';
         if (credential.apiKey.trim() !== credential.apiKey)
             return 'api key must not carry surrounding whitespace';
-        if (!isValidBaseURL(credential.baseURL))
+        const omitted = options.baseURLOptional && credential.baseURL === undefined;
+        if (!omitted && !isValidBaseURL(credential.baseURL))
             return 'api credential needs a valid baseURL';
         return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {