@cortexkit/common-auth 0.2.5 → 0.2.7

package/dist/claustrum/host-slot.js

@@ -0,0 +1,72 @@
+import { ClaustrumConsumerError } from './errors.js';
+/**
+ * The host's own auth slot (OpenCode's stored login for the provider, Pi's
+ * equivalent) must hold something, or the host drops the provider. Under
+ * custody it holds this placeholder: an OAuth-shaped value that is never a
+ * credential. Its empty access token also makes the vault's sealer refuse it,
+ * should it ever be offered for import.
+ */
+export const CUSTODY_PLACEHOLDER_PREFIX = 'claustrum-tombstone:v1:';
+export function custodyPlaceholderKey(provider) {
+    return `${CUSTODY_PLACEHOLDER_PREFIX}${provider}`;
+}
+export function custodyPlaceholder(provider) {
+    return {
+        type: 'oauth',
+        access: '',
+        refresh: custodyPlaceholderKey(provider),
+        expires: 0,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isCustodyPlaceholderValue(value) {
+    return (typeof value === 'string' && value.startsWith(CUSTODY_PLACEHOLDER_PREFIX));
+}
+export function isCustodyPlaceholder(auth, provider) {
+    if (!isRecord(auth) || auth.type !== 'oauth')
+        return false;
+    return auth.refresh === custodyPlaceholderKey(provider);
+}
+export function classifyHostSlot(auth, provider) {
+    if (isCustodyPlaceholder(auth, provider))
+        return 'placeholder';
+    if (isRecord(auth) &&
+        auth.type === 'oauth' &&
+        typeof auth.refresh === 'string' &&
+        auth.refresh.length > 0 &&
+        !isCustodyPlaceholderValue(auth.refresh))
+        return 'login';
+    if (isRecord(auth) &&
+        auth.type === 'api' &&
+        typeof auth.key === 'string' &&
+        auth.key.length > 0)
+        return 'login';
+    return 'empty';
+}
+/**
+ * Check the host slot against the plugin's mode before serving anything.
+ *
+ * - Custody mode with a real login in the slot fails closed: someone signed in
+ *   through the host while the vault owns the accounts, and serving either the
+ *   login or the vault would silently pick one. The plugin surfaces the error
+ *   and the user chooses (leave custody, or remove the login).
+ * - Local mode with the placeholder in the slot also fails: there is no local
+ *   credential to serve, and the user has to sign in.
+ *
+ * Returns the slot content when the combination is consistent.
+ */
+export function assertHostSlotMatchesMode(input) {
+    const content = classifyHostSlot(input.auth, input.provider);
+    if (input.mode === 'custody' && content === 'login')
+        throw new ClaustrumConsumerError('host-slot-login', `${input.provider} has a host login while its accounts are vault-custodied; refusing to serve until one is removed`);
+    if (input.mode === 'local' && content === 'placeholder')
+        throw new ClaustrumConsumerError('host-slot-placeholder', `${input.provider} host slot holds the vault placeholder; sign in to use local accounts`);
+    return content;
+}
+/** Refuse to run a local token refresh with the placeholder as the refresh token. */
+export function assertNotCustodyPlaceholder(refreshToken, provider) {
+    if (isCustodyPlaceholderValue(refreshToken))
+        throw new ClaustrumConsumerError('placeholder-refresh', `${provider} credentials are vault-custodied; local token refresh is forbidden`);
+}

package/dist/claustrum/index.d.ts

@@ -1 +1,18 @@
-export {};
+import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import type { ClaustrumScopedClient } from './custody.js';
+export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
+export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
+export { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultInventory, } from './custody.js';
+export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, type EnrollmentDisposition, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
+export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
+export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
+export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, pruneDeclined, } from './interlock.js';
+export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, readVaultRoster, recordVaultQuota, refreshVaultRoster, type VaultRosterFile, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+/**
+ * Connect the client that lists and fetches this consumer's vault credentials
+ * on the request path. `connectionFile` is required: this library
+ * reads no environment, so the plugin resolves the vault's connection file.
+ */
+export declare function connectClaustrumScopedClient(options: ClaustrumClientOptions & {
+    connectionFile: string;
+}): Promise<ClaustrumScopedClient>;

package/dist/claustrum/index.js

@@ -1,2 +1,22 @@
-// Placeholder so the export resolves until this subpath is built.
-export {};
+// Claustrum vault custody shared by the auth plugins: scoped enrollment (run
+// from setup), discovery of this consumer's vault accounts as rows for this
+// package's `/routing` subpath, per-send authorization, 401 reporting, the
+// declined-account interlock and the host-slot guard. Needs the optional
+// peer `@cortexkit/claustrum-client`.
+import { ClaustrumClient, } from '@cortexkit/claustrum-client';
+export { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
+export { ClaustrumConsumer, } from './consumer.js';
+export { ClaustrumScopedCustody, decideScopedRetryAfter401, isScopedCredentialRotation, SERVING_MARGIN_MS, } from './custody.js';
+export { ClaustrumEnrollmentManager, classifyEnrollmentError, connectClaustrumEnrollmentClient, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
+export { ClaustrumConsumerError, } from './errors.js';
+export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
+export { acceptAccount, declineAccount, isDeclined, pruneDeclined, } from './interlock.js';
+export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
+/**
+ * Connect the client that lists and fetches this consumer's vault credentials
+ * on the request path. `connectionFile` is required: this library
+ * reads no environment, so the plugin resolves the vault's connection file.
+ */
+export function connectClaustrumScopedClient(options) {
+    return ClaustrumClient.connect(options);
+}

package/dist/claustrum/interlock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The declined-account interlock: the user's "do not use this vault account",
+ * kept on the consumer side because the vault has no notion of it.
+ *
+ * An entry is keyed on the credential id plus the provider identity the
+ * credential logged into, never on the record version, so a token refresh
+ * cannot lift it. It is sticky whenever either side's identity is unknown: an
+ * adapter that makes no identity claim cannot prove the account changed. It
+ * lifts on its own only when both identities are known and differ, which
+ * means the credential now logs into a different account than the one the
+ * user declined.
+ */
+export interface DeclinedAccount {
+    readonly credentialId: string;
+    readonly accountIdentity?: string;
+}
+export declare function isDeclined(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): boolean;
+/**
+ * Drop entries the vault has proven stale: the same credential id now listed
+ * with a known identity that differs from the declined one. Entries for
+ * credentials that are not listed stay, so an account that leaves and comes
+ * back is still declined.
+ */
+export declare function pruneDeclined(entries: readonly DeclinedAccount[], listed: readonly {
+    credentialId: string;
+    accountIdentity?: string;
+}[]): DeclinedAccount[];
+export declare function declineAccount(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): DeclinedAccount[];
+export declare function acceptAccount(entries: readonly DeclinedAccount[], credentialIds: readonly string[]): DeclinedAccount[];

package/dist/claustrum/interlock.js

@@ -0,0 +1,36 @@
+function matches(entry, credentialId, accountIdentity) {
+    return (entry.credentialId === credentialId &&
+        (entry.accountIdentity === undefined ||
+            accountIdentity === undefined ||
+            entry.accountIdentity === accountIdentity));
+}
+export function isDeclined(entries, credentialId, accountIdentity) {
+    return entries.some((entry) => matches(entry, credentialId, accountIdentity));
+}
+/**
+ * Drop entries the vault has proven stale: the same credential id now listed
+ * with a known identity that differs from the declined one. Entries for
+ * credentials that are not listed stay, so an account that leaves and comes
+ * back is still declined.
+ */
+export function pruneDeclined(entries, listed) {
+    return entries.filter((entry) => {
+        const current = listed.find((credential) => credential.credentialId === entry.credentialId);
+        return !(current &&
+            entry.accountIdentity !== undefined &&
+            current.accountIdentity !== undefined &&
+            current.accountIdentity !== entry.accountIdentity);
+    });
+}
+export function declineAccount(entries, credentialId, accountIdentity) {
+    return [
+        ...entries.filter((entry) => entry.credentialId !== credentialId),
+        {
+            credentialId,
+            ...(accountIdentity !== undefined && { accountIdentity }),
+        },
+    ];
+}
+export function acceptAccount(entries, credentialIds) {
+    return entries.filter((entry) => !credentialIds.includes(entry.credentialId));
+}

package/dist/claustrum/roster.d.ts

@@ -0,0 +1,103 @@
+import { type QuotaMap, type QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import type { ClaustrumScopedCustody, VaultCredential, VaultCredentialType, VaultInventory } from './custody.js';
+import { type DeclinedAccount } from './interlock.js';
+/**
+ * One vault account as the pool sees it. It carries no bearer material: the
+ * access token is fetched from the vault for every send. Several vault
+ * records logged into the same provider account collapse into one row, so
+ * duplicate logins never count as extra quota.
+ */
+export interface VaultRosterRow {
+    routeId: string;
+    credentialId: string;
+    credentialType: VaultCredentialType;
+    accountIdentity?: string;
+    /** Other credential ids logged into the same provider account. */
+    aliases?: string[];
+    state: string;
+    label: string;
+    email?: string;
+    orgName?: string;
+    enabled: boolean;
+    addedAt: number;
+    quota?: QuotaMap;
+    /**
+     * The vault listed this record in a form this consumer could not use, so the
+     * row is the last good projection kept as it was rather than dropped.
+     */
+    stale?: true;
+}
+export interface VaultRosterFile {
+    version: 1;
+    view?: string;
+    rows: VaultRosterRow[];
+    declined: DeclinedAccount[];
+}
+/** How a vault credential is presented in the pool. */
+export type AccountMapper = (credential: VaultCredential) => {
+    label?: string;
+};
+export interface ProjectionOptions {
+    /** Ids already used by local rows; a vault route never takes one. */
+    reservedRouteIds?: ReadonlySet<string>;
+    /** Prefix for vault route ids, so they read differently from local ids. */
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    now?: number;
+}
+export declare const DEFAULT_ROUTE_PREFIX = "vault:";
+/**
+ * Project the vault's list onto the previous roster. Pure: callers serialize
+ * discovery and commit. Route ids, quota and the time an account was added
+ * survive for the same account; a credential that now logs into a different
+ * known account gets a new route id and no inherited quota.
+ */
+export declare function projectVaultRoster(previous: VaultRosterFile | undefined, inventory: VaultInventory, options?: ProjectionOptions): VaultRosterFile;
+/**
+ * The rows `/routing` selects among. Only enabled, active accounts route;
+ * a declined or cold vault account stays listed for the menu but never
+ * reaches admission.
+ */
+export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
+export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
+/**
+ * Read, change and write the roster under its write lock. `change` returns
+ * undefined to leave the file as it is.
+ */
+export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined) => Promise<{
+    next?: VaultRosterFile;
+    result: T;
+}> | {
+    next?: VaultRosterFile;
+    result: T;
+}): Promise<T>;
+/** Mark a vault account declined; it stays listed but never routes. */
+export declare function declineVaultRoute(path: string, routeId: string): Promise<undefined>;
+/** Lift the user's decline for a vault account and every alias of it. */
+export declare function acceptVaultRoute(path: string, routeId: string): Promise<undefined>;
+/**
+ * Merge a quota observation into a vault row through `/quota`'s merge. The
+ * write is fenced on the account: an observation taken for an identity the
+ * row no longer holds is dropped, so a slow read for a replaced account can
+ * never land on its successor. Returns whether the observation was kept.
+ */
+export declare function recordVaultQuota(path: string, input: {
+    routeId: string;
+    observation: QuotaObservation;
+    accountIdentity?: string;
+}): Promise<boolean>;
+/**
+ * Discover and commit the roster. The lease covers the list call and the
+ * commit, not just the write: an opaque view cannot tell a delayed old reply
+ * from a newer one, so a run that lost its lease is refused at commit. A
+ * failed list, or custody switching off mid-run, never writes anything; a
+ * peer holding the lease means its last committed roster is served instead.
+ */
+export declare function refreshVaultRoster(options: {
+    path: string;
+    custody: Pick<ClaustrumScopedCustody, 'discover'>;
+    isActive?: () => boolean | Promise<boolean>;
+    signal?: AbortSignal;
+    projection?: ProjectionOptions | (() => ProjectionOptions);
+}): Promise<VaultRosterFile | undefined>;

package/dist/claustrum/roster.js

@@ -0,0 +1,334 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { acquireRefreshFileLock, withLock, writeJsonAtomic, } from '../fs/index.js';
+import { isQuotaMap, mergeQuotaObservation, } from '../quota/index.js';
+import { ClaustrumConsumerError } from './errors.js';
+import { acceptAccount, declineAccount, isDeclined, pruneDeclined, } from './interlock.js';
+export const DEFAULT_ROUTE_PREFIX = 'vault:';
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function defaultLabel(credential) {
+    // `oauth:<provider>:<label>` is the vault's conventional spelling; use the
+    // trailing label when present and fall back to the account's email.
+    const parts = credential.credentialId.split(':');
+    const label = parts.length >= 3 ? parts.slice(2).join(':').trim() : undefined;
+    return label || credential.email || credential.credentialId;
+}
+function compatible(left, right) {
+    return left === undefined || right === undefined || left === right;
+}
+function groupKey(credential) {
+    return credential.accountIdentity !== undefined
+        ? `identity:${credential.accountIdentity}`
+        : `credential:${credential.credentialId}`;
+}
+/**
+ * Project the vault's list onto the previous roster. Pure: callers serialize
+ * discovery and commit. Route ids, quota and the time an account was added
+ * survive for the same account; a credential that now logs into a different
+ * known account gets a new route id and no inherited quota.
+ */
+export function projectVaultRoster(previous, inventory, options = {}) {
+    const now = options.now ?? Date.now();
+    const prefix = options.routePrefix ?? DEFAULT_ROUTE_PREFIX;
+    const reserved = options.reservedRouteIds ?? new Set();
+    const previousRows = previous?.rows ?? [];
+    const declined = pruneDeclined(previous?.declined ?? [], inventory.credentials);
+    const groups = new Map();
+    for (const credential of inventory.credentials) {
+        const key = groupKey(credential);
+        const group = groups.get(key) ?? [];
+        group.push(credential);
+        groups.set(key, group);
+    }
+    const used = new Set();
+    const taken = new Set(reserved);
+    const projected = [];
+    const sortedGroups = [...groups.values()].sort((left, right) => (left[0]?.credentialId ?? '').localeCompare(right[0]?.credentialId ?? ''));
+    for (const group of sortedGroups) {
+        const ordered = group.toSorted((left, right) => left.credentialId.localeCompare(right.credentialId));
+        const active = ordered.filter((entry) => entry.state === 'active');
+        const choices = active.length ? active : ordered;
+        const members = new Set(ordered.map((entry) => entry.credentialId));
+        const bound = previousRows.find((row) => !used.has(row) &&
+            members.has(row.credentialId) &&
+            compatible(row.accountIdentity, ordered.find((entry) => entry.credentialId === row.credentialId)
+                ?.accountIdentity));
+        const representative = choices.find((entry) => entry.credentialId === bound?.credentialId) ??
+            choices[0];
+        if (!representative)
+            continue;
+        const identity = representative.accountIdentity;
+        const existing = bound ??
+            (identity === undefined
+                ? undefined
+                : previousRows.find((row) => !used.has(row) && row.accountIdentity === identity));
+        if (existing)
+            used.add(existing);
+        let routeId = existing?.routeId;
+        if (!routeId || reserved.has(routeId)) {
+            const base = `${prefix}${representative.credentialId}${identity === undefined ? '' : `~${hash(identity).slice(0, 10)}`}`;
+            routeId = base;
+            for (let suffix = 2; taken.has(routeId); suffix++)
+                routeId = `${base}~${suffix}`;
+        }
+        taken.add(routeId);
+        const aliases = ordered
+            .map((entry) => entry.credentialId)
+            .filter((id) => id !== representative.credentialId);
+        const mapped = options.mapAccount?.(representative) ?? {};
+        projected.push({
+            previousIndex: existing ? previousRows.indexOf(existing) : Infinity,
+            row: {
+                routeId,
+                credentialId: representative.credentialId,
+                credentialType: representative.credentialType,
+                ...(identity !== undefined && { accountIdentity: identity }),
+                ...(aliases.length && { aliases }),
+                state: representative.state,
+                label: mapped.label?.trim() || defaultLabel(representative),
+                ...(representative.email !== undefined && {
+                    email: representative.email,
+                }),
+                ...(representative.orgName !== undefined && {
+                    orgName: representative.orgName,
+                }),
+                enabled: !ordered.some((entry) => isDeclined(declined, entry.credentialId, entry.accountIdentity)),
+                addedAt: existing?.addedAt ?? now,
+                ...(existing?.quota !== undefined && { quota: existing.quota }),
+            },
+        });
+    }
+    // A record skipped as malformed keeps its last good projection: skipping it
+    // must not read as the account having been removed from the vault.
+    const skippedIds = new Set(inventory.skipped.flatMap((record) => record.credentialId === undefined ? [] : [record.credentialId]));
+    previousRows.forEach((row, previousIndex) => {
+        if (used.has(row) || !skippedIds.has(row.credentialId))
+            return;
+        if (taken.has(row.routeId))
+            return;
+        taken.add(row.routeId);
+        projected.push({ previousIndex, row: { ...row, stale: true } });
+    });
+    projected.sort((left, right) => left.previousIndex === right.previousIndex
+        ? left.row.credentialId.localeCompare(right.row.credentialId)
+        : left.previousIndex - right.previousIndex);
+    return {
+        version: 1,
+        view: inventory.view,
+        rows: projected.map((entry) => entry.row),
+        declined,
+    };
+}
+/**
+ * The rows `/routing` selects among. Only enabled, active accounts route;
+ * a declined or cold vault account stays listed for the menu but never
+ * reaches admission.
+ */
+export function vaultRoutingRows(roster) {
+    return (roster?.rows ?? [])
+        .filter((row) => row.enabled && row.state === 'active')
+        .map((row) => ({
+        id: row.routeId,
+        kind: row.credentialType === 'oauth' ? 'oauth' : 'api-key',
+        ...(row.quota !== undefined && { quota: row.quota }),
+    }));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function optionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function decodeRow(value) {
+    if (!isRecord(value) ||
+        typeof value.routeId !== 'string' ||
+        typeof value.credentialId !== 'string' ||
+        (value.credentialType !== 'oauth' && value.credentialType !== 'api_key') ||
+        typeof value.state !== 'string' ||
+        typeof value.label !== 'string' ||
+        typeof value.enabled !== 'boolean' ||
+        typeof value.addedAt !== 'number' ||
+        !optionalString(value.accountIdentity) ||
+        !optionalString(value.email) ||
+        !optionalString(value.orgName) ||
+        (value.aliases !== undefined &&
+            (!Array.isArray(value.aliases) ||
+                !value.aliases.every((alias) => typeof alias === 'string'))) ||
+        (value.quota !== undefined && !isQuotaMap(value.quota)))
+        return undefined;
+    return value;
+}
+function decodeRoster(value) {
+    if (!isRecord(value) ||
+        value.version !== 1 ||
+        !optionalString(value.view) ||
+        !Array.isArray(value.rows) ||
+        !Array.isArray(value.declined))
+        throw new ClaustrumConsumerError('invalid-state', 'Claustrum roster file is not valid');
+    const rows = [];
+    for (const entry of value.rows) {
+        const row = decodeRow(entry);
+        if (!row)
+            throw new ClaustrumConsumerError('invalid-state', 'Claustrum roster file is not valid');
+        rows.push(row);
+    }
+    const declined = [];
+    for (const entry of value.declined) {
+        if (!isRecord(entry) ||
+            typeof entry.credentialId !== 'string' ||
+            !optionalString(entry.accountIdentity))
+            throw new ClaustrumConsumerError('invalid-state', 'Claustrum roster file is not valid');
+        declined.push(entry);
+    }
+    return {
+        version: 1,
+        ...(typeof value.view === 'string' && { view: value.view }),
+        rows,
+        declined,
+    };
+}
+export async function readVaultRoster(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new ClaustrumConsumerError('invalid-state', 'Claustrum roster file is not valid');
+    }
+    return decodeRoster(value);
+}
+const WRITE_LOCK = {
+    name: 'claustrum-roster-write',
+    ttlMs: 10_000,
+    timeoutMs: 5_000,
+};
+const DISCOVERY_LEASE = { name: 'claustrum-roster', ttlMs: 30_000 };
+/**
+ * Read, change and write the roster under its write lock. `change` returns
+ * undefined to leave the file as it is.
+ */
+export async function mutateVaultRoster(path, change) {
+    return withLock(path, WRITE_LOCK, async (lock) => {
+        const current = await readVaultRoster(path);
+        const { next, result } = await change(current);
+        if (next) {
+            await lock.assertOwned();
+            await writeJsonAtomic(path, next);
+        }
+        return result;
+    });
+}
+/** Mark a vault account declined; it stays listed but never routes. */
+export function declineVaultRoute(path, routeId) {
+    return mutateVaultRoster(path, (current) => {
+        const row = current?.rows.find((entry) => entry.routeId === routeId);
+        if (!current || !row)
+            throw new ClaustrumConsumerError('route-unavailable', 'Claustrum route is not in the roster');
+        const declined = declineAccount(current.declined, row.credentialId, row.accountIdentity);
+        return {
+            next: {
+                ...current,
+                declined,
+                rows: current.rows.map((entry) => entry === row ? { ...entry, enabled: false } : entry),
+            },
+            result: undefined,
+        };
+    });
+}
+/** Lift the user's decline for a vault account and every alias of it. */
+export function acceptVaultRoute(path, routeId) {
+    return mutateVaultRoster(path, (current) => {
+        const row = current?.rows.find((entry) => entry.routeId === routeId);
+        if (!current || !row)
+            throw new ClaustrumConsumerError('route-unavailable', 'Claustrum route is not in the roster');
+        return {
+            next: {
+                ...current,
+                declined: acceptAccount(current.declined, [
+                    row.credentialId,
+                    ...(row.aliases ?? []),
+                ]),
+                rows: current.rows.map((entry) => entry === row ? { ...entry, enabled: true } : entry),
+            },
+            result: undefined,
+        };
+    });
+}
+/**
+ * Merge a quota observation into a vault row through `/quota`'s merge. The
+ * write is fenced on the account: an observation taken for an identity the
+ * row no longer holds is dropped, so a slow read for a replaced account can
+ * never land on its successor. Returns whether the observation was kept.
+ */
+export function recordVaultQuota(path, input) {
+    return mutateVaultRoster(path, (current) => {
+        const row = current?.rows.find((entry) => entry.routeId === input.routeId);
+        if (!current ||
+            !row ||
+            !compatible(row.accountIdentity, input.accountIdentity))
+            return { result: false };
+        const quota = mergeQuotaObservation(row.quota, input.observation);
+        return {
+            next: {
+                ...current,
+                rows: current.rows.map((entry) => entry === row ? { ...entry, quota } : entry),
+            },
+            result: true,
+        };
+    });
+}
+/**
+ * Discover and commit the roster. The lease covers the list call and the
+ * commit, not just the write: an opaque view cannot tell a delayed old reply
+ * from a newer one, so a run that lost its lease is refused at commit. A
+ * failed list, or custody switching off mid-run, never writes anything; a
+ * peer holding the lease means its last committed roster is served instead.
+ */
+export async function refreshVaultRoster(options) {
+    options.signal?.throwIfAborted();
+    const active = async () => (await options.isActive?.()) ?? true;
+    if (!(await active()))
+        return undefined;
+    const lease = await acquireRefreshFileLock({
+        ...DISCOVERY_LEASE,
+        path: options.path,
+        renew: true,
+    });
+    if (!lease) {
+        const persisted = await readVaultRoster(options.path);
+        options.signal?.throwIfAborted();
+        if (!persisted?.view)
+            throw new ClaustrumConsumerError('roster-busy', 'Claustrum account discovery is already in progress');
+        return persisted;
+    }
+    try {
+        const inventory = await options.custody.discover(options.signal);
+        options.signal?.throwIfAborted();
+        return await mutateVaultRoster(options.path, async (current) => {
+            if (!(await active()))
+                return { result: undefined };
+            options.signal?.throwIfAborted();
+            await lease.assertOwned();
+            const projection = typeof options.projection === 'function'
+                ? options.projection()
+                : options.projection;
+            const next = projectVaultRoster(current, inventory, projection);
+            const changed = JSON.stringify(current) !== JSON.stringify(next);
+            return { ...(changed && { next }), result: next };
+        });
+    }
+    finally {
+        await lease.release();
+    }
+}