@cortexkit/common-auth 0.3.0 → 0.4.1

package/dist/claustrum/roster.d.ts

@@ -1,6 +1,6 @@
 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 { ClaustrumScopedAttempt, ClaustrumScopedCustody, SkippedVaultRecord, 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
@@ -27,10 +27,25 @@ export interface VaultRosterRow {
      * row is the last good projection kept as it was rather than dropped.
      */
     stale?: true;
+    /**
+     * The vault's latest list named no account for `credentialId`, so
+     * `accountIdentity` is the last account that credential was known to log
+     * into, kept until the vault names one again. It proves neither that the
+     * credential still logs into that account nor that it changed accounts.
+     */
+    unclaimed?: true;
 }
 export interface VaultRosterFile {
     version: 1;
     view?: string;
+    /**
+     * False when the vault's reply carried records this consumer could not use.
+     * An incomplete reply never removes an account it may still hold: every
+     * previous member it does not account for is kept.
+     */
+    complete: boolean;
+    /** The unusable records of an incomplete reply: a safe id and a fixed reason. */
+    rejected?: SkippedVaultRecord[];
     rows: VaultRosterRow[];
     declined: DeclinedAccount[];
 }
@@ -52,6 +67,16 @@ export declare const DEFAULT_ROUTE_PREFIX = "vault:";
  * 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.
+ *
+ * A record listed without an identity keeps the last account it was known to
+ * log into (the row is marked `unclaimed`). Dropping that binding would let a
+ * later different account look like an identity learned for the first time
+ * and inherit the first account's route and quota.
+ *
+ * A reply with unusable records is incomplete: a previous member it does not
+ * account for (its record was rejected, or a rejected record has no usable id
+ * and could be any of them) is kept, as an alias of its live account or as a
+ * `stale` row. Only a complete reply removes an account.
  */
 export declare function projectVaultRoster(previous: VaultRosterFile | undefined, inventory: VaultInventory, options?: ProjectionOptions): VaultRosterFile;
 /**
@@ -76,16 +101,22 @@ export declare function mutateVaultRoster<T>(path: string, change: (current: Vau
 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>;
+/**
+ * The receipt fields a quota or profile observation must carry to say which
+ * send (credential and account) it came from. Pass the
+ * `ClaustrumScopedAttempt` that send was authorized with.
+ */
+export type QuotaReceipt = Pick<ClaustrumScopedAttempt, 'credentialId' | 'accountIdentity' | 'accountIdentitySource' | 'expectedAccountIdentity'>;
 /**
  * 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.
+ * write is fenced on the receipt the reading was taken with: it lands only
+ * while the row still holds that receipt's credential (as representative or
+ * alias) and account, 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: {
+export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
     routeId: string;
     observation: QuotaObservation;
-    accountIdentity?: string;
 }): Promise<boolean>;
 /**
  * Discover and commit the roster. The lease covers the list call and the
@@ -101,3 +132,62 @@ export declare function refreshVaultRoster(options: {
     signal?: AbortSignal;
     projection?: ProjectionOptions | (() => ProjectionOptions);
 }): Promise<VaultRosterFile | undefined>;
+/**
+ * A host-owned main account as last verified from the vault: the plugin's
+ * logical route, the credential that serves it and the account it logs into.
+ */
+export interface VaultPrimaryBinding {
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+    view: string;
+}
+export type VaultPrimaryUnavailableReason = 'malformed' | 'unclaimed' | 'incomplete' | 'identity-changed';
+export type VaultPrimary = 
+/**
+ * Main is bound. `replaced` is the previous binding when it named a
+ * different account: everything owned by that account (quota, profile,
+ * backoff, cache affinity) must be dropped, and outstanding observations
+ * for it fenced, even though the logical route stays the same.
+ */
+{
+    status: 'ready';
+    binding: VaultPrimaryBinding;
+    replaced?: VaultPrimaryBinding;
+}
+/** A complete reply lists no primary record: there is no main. */
+ | {
+    status: 'absent';
+}
+/**
+ * The reply cannot say who main is. Not the same as absent: the last
+ * verified binding is handed back untouched, and serving it still needs a
+ * fresh receipt that matches it.
+ */
+ | {
+    status: 'unavailable';
+    reason: VaultPrimaryUnavailableReason;
+    lastVerified?: VaultPrimaryBinding;
+};
+/**
+ * The seam for a plugin that keeps a main account: one fixed account the host
+ * owns under a logical route, outside the pool's rotating rows. The library
+ * has no main convention of its own: the plugin names the
+ * vault record that holds the role (`primaryCredentialId`) and its logical
+ * route. Main follows the account that record claims; another credential of
+ * that same account may serve it when the record itself is not active, but a
+ * credential of any other account is never promoted into main.
+ *
+ * Inputs are the plugin's filtered inventory, whether that inventory is
+ * complete (defaults to the reply having no unusable records; pass the
+ * roster's `complete` or false to override), the previous verified binding
+ * and, on the request path, the account the chosen request expects.
+ */
+export declare function resolveVaultPrimary(input: {
+    inventory: VaultInventory;
+    complete?: boolean;
+    previous?: VaultPrimaryBinding;
+    expectedAccountIdentity?: string;
+    primaryCredentialId: string;
+    routeId: string;
+}): VaultPrimary;

package/dist/claustrum/roster.js

@@ -3,7 +3,7 @@ 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';
+import { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
 export const DEFAULT_ROUTE_PREFIX = 'vault:';
 function hash(value) {
     return createHash('sha256').update(value).digest('hex');
@@ -15,51 +15,88 @@ function defaultLabel(credential) {
     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(member) {
+    return member.identity !== undefined
+        ? `identity:${member.identity}`
+        : `credential:${member.credential.credentialId}`;
 }
-function groupKey(credential) {
-    return credential.accountIdentity !== undefined
-        ? `identity:${credential.accountIdentity}`
-        : `credential:${credential.credentialId}`;
+function memberIds(row) {
+    return [row.credentialId, ...(row.aliases ?? [])];
 }
 /**
  * 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.
+ *
+ * A record listed without an identity keeps the last account it was known to
+ * log into (the row is marked `unclaimed`). Dropping that binding would let a
+ * later different account look like an identity learned for the first time
+ * and inherit the first account's route and quota.
+ *
+ * A reply with unusable records is incomplete: a previous member it does not
+ * account for (its record was rejected, or a rejected record has no usable id
+ * and could be any of them) is kept, as an alias of its live account or as a
+ * `stale` row. Only a complete reply removes an account.
  */
 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);
+    // Declines follow the account and outlive its records, so none is pruned.
+    const declined = [...(previous?.declined ?? [])];
+    const complete = inventory.skipped.length === 0;
+    const listed = new Set(inventory.credentials.map((credential) => credential.credentialId));
+    const rejectedIds = new Set(inventory.skipped.flatMap((record) => record.credentialId === undefined ? [] : [record.credentialId]));
+    const unrecoverable = inventory.skipped.some((record) => record.credentialId === undefined);
+    const unaccounted = (id) => !listed.has(id) && (rejectedIds.has(id) || unrecoverable);
+    const lastKnown = new Map();
+    for (const row of previousRows) {
+        if (row.accountIdentity === undefined)
+            continue;
+        for (const id of memberIds(row))
+            if (!lastKnown.has(id))
+                lastKnown.set(id, row.accountIdentity);
+    }
     const groups = new Map();
     for (const credential of inventory.credentials) {
-        const key = groupKey(credential);
+        const member = credential.accountIdentity !== undefined
+            ? { credential, identity: credential.accountIdentity, claimed: true }
+            : {
+                credential,
+                identity: lastKnown.get(credential.credentialId),
+                claimed: false,
+            };
+        const key = groupKey(member);
         const group = groups.get(key) ?? [];
-        group.push(credential);
+        group.push(member);
         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 byId = (left, right) => left.credential.credentialId.localeCompare(right.credential.credentialId);
+    const sortedGroups = [...groups.values()]
+        .map((group) => group.toSorted(byId))
+        .sort((left, right) => (left[0] && right[0] ? byId(left[0], right[0]) : 0));
+    for (const ordered of sortedGroups) {
+        const identity = ordered[0]?.identity;
+        const active = ordered.filter((entry) => entry.credential.state === 'active');
+        const usable = active.length ? active : ordered;
+        // A record that claims the account itself is preferred over one that is
+        // only remembered as belonging to it.
+        const claimed = usable.filter((entry) => entry.claimed);
+        const choices = claimed.length ? claimed : usable;
+        const members = new Set(ordered.map((entry) => entry.credential.credentialId));
+        // An unknown previous account may be learned now; a known one must match.
         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)
+            memberIds(row).some((id) => members.has(id)) &&
+            (row.accountIdentity === undefined || row.accountIdentity === identity));
+        const chosen = choices.find((entry) => entry.credential.credentialId === bound?.credentialId) ?? choices[0];
+        if (!chosen)
             continue;
-        const identity = representative.accountIdentity;
+        const representative = chosen.credential;
         const existing = bound ??
             (identity === undefined
                 ? undefined
@@ -74,9 +111,15 @@ export function projectVaultRoster(previous, inventory, options = {}) {
                 routeId = `${base}~${suffix}`;
         }
         taken.add(routeId);
-        const aliases = ordered
-            .map((entry) => entry.credentialId)
-            .filter((id) => id !== representative.credentialId);
+        const retained = existing ? memberIds(existing).filter(unaccounted) : [];
+        const aliases = [
+            ...new Set([
+                ...ordered.map((entry) => entry.credential.credentialId),
+                ...retained,
+            ]),
+        ]
+            .filter((id) => id !== representative.credentialId)
+            .sort((left, right) => left.localeCompare(right));
         const mapped = options.mapAccount?.(representative) ?? {};
         projected.push({
             previousIndex: existing ? previousRows.indexOf(existing) : Infinity,
@@ -94,22 +137,38 @@ export function projectVaultRoster(previous, inventory, options = {}) {
                 ...(representative.orgName !== undefined && {
                     orgName: representative.orgName,
                 }),
-                enabled: !ordered.some((entry) => isDeclined(declined, entry.credentialId, entry.accountIdentity)),
+                enabled: ![representative.credentialId, ...aliases].some((id) => isDeclined(declined, id, identity)),
                 addedAt: existing?.addedAt ?? now,
                 ...(existing?.quota !== undefined && { quota: existing.quota }),
+                ...(!chosen.claimed && identity !== undefined && { unclaimed: true }),
             },
         });
     }
-    // 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]));
+    // An account the reply does not account for keeps its last good projection:
+    // a rejected record must not read as the account having been removed. A
+    // credential this reply lists belongs to the live row it was projected into,
+    // so it is taken out of the stale row: otherwise one credential could be
+    // authorized, and its readings recorded, under two account bindings. A
+    // stale row left with no member is dropped.
     previousRows.forEach((row, previousIndex) => {
-        if (used.has(row) || !skippedIds.has(row.credentialId))
+        if (used.has(row) || !memberIds(row).some(unaccounted))
             return;
         if (taken.has(row.routeId))
             return;
+        const [credentialId, ...aliases] = memberIds(row).filter((id) => !listed.has(id));
+        if (credentialId === undefined)
+            return;
         taken.add(row.routeId);
-        projected.push({ previousIndex, row: { ...row, stale: true } });
+        const { aliases: _previousAliases, ...rest } = row;
+        projected.push({
+            previousIndex,
+            row: {
+                ...rest,
+                credentialId,
+                ...(aliases.length && { aliases }),
+                stale: true,
+            },
+        });
     });
     projected.sort((left, right) => left.previousIndex === right.previousIndex
         ? left.row.credentialId.localeCompare(right.row.credentialId)
@@ -117,6 +176,15 @@ export function projectVaultRoster(previous, inventory, options = {}) {
     return {
         version: 1,
         view: inventory.view,
+        complete,
+        ...(!complete && {
+            rejected: inventory.skipped.map((record) => ({
+                ...(record.credentialId !== undefined && {
+                    credentialId: record.credentialId,
+                }),
+                reason: record.reason,
+            })),
+        }),
         rows: projected.map((entry) => entry.row),
         declined,
     };
@@ -156,16 +224,40 @@ function decodeRow(value) {
         (value.aliases !== undefined &&
             (!Array.isArray(value.aliases) ||
                 !value.aliases.every((alias) => typeof alias === 'string'))) ||
-        (value.quota !== undefined && !isQuotaMap(value.quota)))
+        (value.quota !== undefined && !isQuotaMap(value.quota)) ||
+        (value.stale !== undefined && value.stale !== true) ||
+        (value.unclaimed !== undefined && value.unclaimed !== true))
         return undefined;
     return value;
 }
+const SKIPPED_REASONS = new Set([
+    'empty credential id',
+    'duplicate credential id',
+    'blank account identity',
+    'empty state',
+]);
+function decodeRejected(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const records = [];
+    for (const entry of value) {
+        if (!isRecord(entry) ||
+            !optionalString(entry.credentialId) ||
+            typeof entry.reason !== 'string' ||
+            !SKIPPED_REASONS.has(entry.reason))
+            return undefined;
+        records.push(entry);
+    }
+    return records;
+}
 function decodeRoster(value) {
     if (!isRecord(value) ||
         value.version !== 1 ||
         !optionalString(value.view) ||
         !Array.isArray(value.rows) ||
-        !Array.isArray(value.declined))
+        !Array.isArray(value.declined) ||
+        (value.complete !== undefined && typeof value.complete !== 'boolean') ||
+        (value.rejected !== undefined && !decodeRejected(value.rejected)))
         throw new ClaustrumConsumerError('invalid-state', 'Claustrum roster file is not valid');
     const rows = [];
     for (const entry of value.rows) {
@@ -182,9 +274,14 @@ function decodeRoster(value) {
             throw new ClaustrumConsumerError('invalid-state', 'Claustrum roster file is not valid');
         declined.push(entry);
     }
+    const rejected = decodeRejected(value.rejected);
     return {
         version: 1,
         ...(typeof value.view === 'string' && { view: value.view }),
+        // A file written before completeness was recorded came from a reply
+        // that was used whole, so it reads as complete.
+        complete: value.complete !== false,
+        ...(rejected && { rejected }),
         rows,
         declined,
     };
@@ -255,34 +352,74 @@ export function acceptVaultRoute(path, routeId) {
         return {
             next: {
                 ...current,
-                declined: acceptAccount(current.declined, [
-                    row.credentialId,
-                    ...(row.aliases ?? []),
-                ]),
+                declined: acceptAccount(current.declined, memberIds(row), row.accountIdentity),
                 rows: current.rows.map((entry) => entry === row ? { ...entry, enabled: true } : entry),
             },
             result: undefined,
         };
     });
 }
+/**
+ * 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 '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 'refuse';
+    // Equality, never compatibility: a known account on one side does not match
+    // 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
- * 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.
+ * write is fenced on the receipt the reading was taken with: it lands only
+ * while the row still holds that receipt's credential (as representative or
+ * alias) and account, 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))
+        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,
         };
@@ -332,3 +469,58 @@ export async function refreshVaultRoster(options) {
         await lease.release();
     }
 }
+/**
+ * The seam for a plugin that keeps a main account: one fixed account the host
+ * owns under a logical route, outside the pool's rotating rows. The library
+ * has no main convention of its own: the plugin names the
+ * vault record that holds the role (`primaryCredentialId`) and its logical
+ * route. Main follows the account that record claims; another credential of
+ * that same account may serve it when the record itself is not active, but a
+ * credential of any other account is never promoted into main.
+ *
+ * Inputs are the plugin's filtered inventory, whether that inventory is
+ * complete (defaults to the reply having no unusable records; pass the
+ * roster's `complete` or false to override), the previous verified binding
+ * and, on the request path, the account the chosen request expects.
+ */
+export function resolveVaultPrimary(input) {
+    const { inventory, previous } = input;
+    const unavailable = (reason) => ({
+        status: 'unavailable',
+        reason,
+        ...(previous && { lastVerified: previous }),
+    });
+    const record = inventory.credentials.find((credential) => credential.credentialId === input.primaryCredentialId);
+    if (!record) {
+        if (inventory.skipped.some((skipped) => skipped.credentialId === input.primaryCredentialId))
+            return unavailable('malformed');
+        // A rejected record without a usable id could be the primary record.
+        const incomplete = input.complete === false ||
+            inventory.skipped.some((skipped) => skipped.credentialId === undefined);
+        return incomplete ? unavailable('incomplete') : { status: 'absent' };
+    }
+    const identity = record.accountIdentity;
+    if (identity === undefined)
+        return unavailable('unclaimed');
+    if (input.expectedAccountIdentity !== undefined &&
+        input.expectedAccountIdentity !== identity)
+        return unavailable('identity-changed');
+    const representative = record.state === 'active'
+        ? record
+        : (inventory.credentials
+            .filter((credential) => credential.accountIdentity === identity &&
+            credential.state === 'active')
+            .toSorted((left, right) => left.credentialId.localeCompare(right.credentialId))[0] ?? record);
+    const binding = {
+        routeId: input.routeId,
+        credentialId: representative.credentialId,
+        accountIdentity: identity,
+        view: inventory.view,
+    };
+    return {
+        status: 'ready',
+        binding,
+        ...(previous &&
+            previous.accountIdentity !== identity && { replaced: previous }),
+    };
+}

package/dist/commands/builtins.d.ts

@@ -1,6 +1,6 @@
 import type { AddInput, PoolLockSpec, PoolRow, PoolStore, RemoveOptions } from '../store/index.js';
 import type { CommandInvocation, KnobValues, MenuChoice, MenuKnob } from './model.js';
-import type { ResolvedSection } from './seam.js';
+import { type ResolvedSection } from './seam.js';
 /**
  * What a plugin's login hands back. `ready` adds the account now. `pending`
  * means the user must finish somewhere else (a browser, a device code):

package/dist/commands/builtins.js

@@ -4,6 +4,7 @@
 // the same locks as any other writer of those files.
 import { isQuotaMap, projectQuota, } from '../quota/index.js';
 import { DEFAULT_FORMER_MAIN_ID, orderForPlacement, resolveRoutingMode, } from '../routing/index.js';
+import { projectFailure, } from './seam.js';
 /** `disabledReason` recorded when the user disables an account from the menu. */
 export const MENU_DISABLED_REASON = 'disabled from the command menu';
 function isRecord(value) {
@@ -99,8 +100,12 @@ function addedText(name, result) {
             return `${name} was already in the pool; its credential was updated.`;
     }
 }
+/**
+ * What the user is told about a failed late login: the projected message,
+ * never the exception's own text, which can quote the login's request.
+ */
 function failureMessage(error) {
-    return error instanceof Error ? error.message : String(error);
+    return projectFailure(error).text;
 }
 async function snapshot(store) {
     const load = await store.read();

package/dist/commands/index.d.ts

@@ -6,5 +6,5 @@ export type { ActionDefinition, ActionInput, ActionOutcome, CommandApplyRequest,
 export { SECTION_SLOTS } from './model.js';
 export type { PiMenuOptions, PiMenuUi } from './pi.js';
 export { runPiCommandMenu } from './pi.js';
-export type { SeamLogger } from './seam.js';
-export { DEFAULT_IRREVERSIBLE_CONFIRMATION } from './seam.js';
+export type { ProjectedFailure, SeamLogger, TextRedactor } from './seam.js';
+export { ACTION_FAILED, CommandError, createTextRedactor, DEFAULT_IRREVERSIBLE_CONFIRMATION, projectFailure, } from './seam.js';

package/dist/commands/index.js

@@ -2,4 +2,4 @@ export { MENU_DISABLED_REASON } from './builtins.js';
 export { createCommandMenu, parseApplyRequest } from './menu.js';
 export { SECTION_SLOTS } from './model.js';
 export { runPiCommandMenu } from './pi.js';
-export { DEFAULT_IRREVERSIBLE_CONFIRMATION } from './seam.js';
+export { ACTION_FAILED, CommandError, createTextRedactor, DEFAULT_IRREVERSIBLE_CONFIRMATION, projectFailure, } from './seam.js';

package/dist/commands/menu.d.ts

@@ -1,3 +1,4 @@
+import { type RedactionOptions } from '../logger/index.js';
 import type { PoolLockSpec, PoolStore } from '../store/index.js';
 import { type AccountsSectionOptions, type LimitsSectionOptions, type QuotaSectionOptions, type RoutingSectionOptions } from './builtins.js';
 import type { CommandApplyRequest, CommandApplyResult, CommandDialogPayload, CommandInvocation, PluginExtraSection, PluginSection } from './model.js';
@@ -22,6 +23,13 @@ export interface CommandMenuOptions {
     extras?: readonly PluginExtraSection[];
     /** Receives the seam's warnings and failed actions; defaults to the library logger. */
     logger?: SeamLogger;
+    /**
+     * The provider's secret shapes, added to the redactor every string that
+     * leaves the menu goes through (payloads and notifications). Without a
+     * pattern for its key format, a plugin's API key quoted in an outcome's
+     * text is not recognised.
+     */
+    redaction?: RedactionOptions;
     now?: () => number;
 }
 export interface CommandMenu {