agl 40.4.0 → 40.5.0

package/ts_authswitch/classes.authoritybroker.ts

@@ -5,10 +5,15 @@ import type { IOpenAiLoginHandle, IOpenAiOAuthCredential } from './interfaces.op
 import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
   IAuthSwitchNativeAssignment, IAuthSwitchOperation, IAuthSwitchSnapshot, IReq_AuthSwitchSnapshot,
   TAuthSwitchLoginOwnerTool, TAuthSwitchRevocation } from './authority-contract.js';
-import { AuthSwitchRefusal, isAuthSwitchReserveLiftHours, isAuthSwitchAccountLabel, isAuthSwitchLapsesAt, isAuthSwitchMaxUsagePercent } from './authority-contract.js';
-import { AuthSwitchAuthorityDatabase, authorityBindPurpose, type TStoredNativeHome } from './classes.authoritydatabase.js';
-import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
-  IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
+import { AuthSwitchRefusal, authSwitchKeyHint, isAuthSwitchReserveLiftHours, isAuthSwitchAccountLabel, isAuthSwitchLapsesAt,
+  isAuthSwitchMaxUsagePercent, type TAuthSwitchApiKeyProvider } from './authority-contract.js';
+import { authSwitchApiKeyOtherProvider, authSwitchApiKeyProviderNames, authSwitchApiKeyVerifier,
+  type TAuthSwitchApiKeyVerdict, type TAuthSwitchApiKeyVerifier } from './authority-apikeys.js';
+import { isAuthSwitchSpendLimitMicroUsd } from './authority-spend.js';
+import { AuthSwitchAuthorityDatabase, authorityBindPurpose, authSwitchBindPurposes, type TAuthSwitchBindPurpose,
+  type TStoredNativeHome } from './classes.authoritydatabase.js';
+import { authorityApiKeyProvider, type IStoredAuthorityAccount, type IStoredAuthorityBinding,
+  type IStoredAuthorityGrant, type IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
 import type { IAuthSwitchUsageContext } from './classes.authorityusage.js';
 import type { IClaudeNativeLogin } from './classes.claudenative.js';
 import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
@@ -24,11 +29,10 @@ export interface IAuthSwitchAuthorityBrokerOptions {
   now?: () => number;
   proactive?: boolean;
   /**
-   * Asks Anthropic whether it accepts an API key before the authority stores it: by default a read of the models
-   * the key may use. It fails with `AnthropicApiKeyAuthError` for a key Anthropic rejected, otherwise with whatever
-   * kept the question from being answered.
+   * Asks a provider whether it accepts an API key before the authority stores it (`TAuthSwitchApiKeyVerifier`): by
+   * default a read of the models the key may use (`authSwitchApiKeyVerifier`).
    */
-  verifyAnthropicApiKey?: (apiKey: string, signal: AbortSignal) => Promise<void>;
+  verifyApiKey?: TAuthSwitchApiKeyVerifier;
 }
 
 export interface IAuthSwitchResolvedAccess {
@@ -87,15 +91,34 @@ const tokenExpiry = (credential: TOpenAiCredential): string | null => {
 const revocationBudgetMs = 10_000;
 const openAiGrantId = (accountId: string): string => idHash('authswitch-grant-v1', accountId, 'openai_managed', 'chatgpt');
 /**
- * An Anthropic API key's account is named by a digest of the key, the one identity a key has: the same key always
- * lands on the same account, and nothing stored or published reveals the key.
+ * An API key's account is named by a digest of the key, the one identity a key has: the same key always lands on the
+ * same account, and nothing stored or published reveals the key. An Anthropic key keeps the digest it always had.
  */
-const anthropicApiKeySubject = (apiKey: string): string => idHash('authswitch-anthropic-api-key', apiKey);
+const apiKeySubject = (providerIdArg: 'anthropic' | 'openai', apiKey: string): string =>
+  idHash(`authswitch-${providerIdArg}-api-key`, apiKey);
 /** The workspace of an API-key account: a key names no organization the authority can read. */
-const anthropicApiKeyWorkspace = 'api-key';
-const anthropicApiKeyAudience = 'anthropic-api';
-/** How long Anthropic is given to answer whether it accepts a key being added. */
-const anthropicApiKeyVerifyTimeoutMs = 15_000;
+const apiKeyWorkspace = 'api-key';
+/** Whether an account is an API key's, which its workspace states (`IAuthSwitchAccount.organizationId`). */
+const isApiKeyAccount = (account: IStoredAuthorityAccount): boolean => account.workspaceId === apiKeyWorkspace;
+/** Each provider's key: the purpose and audience of its grant, the account label without one given. */
+const apiKeyGrants: Readonly<Record<TAuthSwitchApiKeyProvider, {
+  purpose: 'anthropic_api_key' | 'openai_api_key'; audience: string; label: string;
+}>> = Object.freeze({
+  anthropic: { purpose: 'anthropic_api_key', audience: 'anthropic-api', label: 'Anthropic API key' },
+  openai: { purpose: 'openai_api_key', audience: 'openai-api', label: 'OpenAI API key' },
+});
+/**
+ * What a sealed key is, one kind per provider: `{ kind, apiKey }`. Sealed data is never migrated, so a kind stays as it
+ * was first written; the provider is the grant's, and the kind must be that provider's.
+ */
+const apiKeySealedKinds: Readonly<Record<TAuthSwitchApiKeyProvider, string>> = Object.freeze({
+  anthropic: 'anthropicApiKey',
+  openai: 'openaiApiKey',
+});
+/** The shortest key the authority holds: its hint shows four characters, which must stay a small part of it. */
+const apiKeyMinimumLength = 16;
+/** How long a provider is given to answer whether it accepts a key being added. */
+const apiKeyVerifyTimeoutMs = 15_000;
 
 /**
  * What a caller is told when the answer is decided. Each states the repair and names no id, path or host.
@@ -107,7 +130,7 @@ const anthropicApiKeyVerifyTimeoutMs = 15_000;
 const unknownOperation = 'This authority knows no device sign-in by that operation ID. '
   + 'Start a new sign-in and follow that one.';
 const loginNotBindable = 'This login cannot back a runtime binding. The authority must hold the login '
-  + 'itself, it must be the account\'s selected login, and it must be ready; a Claude login and an Anthropic API key '
+  + 'itself, it must be the account\'s selected login, and it must be ready; a Claude login and an API key '
   + 'back only the gateway runtime. Reauthenticate the account or choose another one.';
 const bindingUnauthorized = 'This runtime binding is not authorized. Bind the account again to obtain a '
   + 'capability for it.';
@@ -119,12 +142,21 @@ const loginNeedsReauth = 'This account\'s sign-in has ended. Reauthenticate the
   + 'sign-in; a runtime bound to it binds again afterwards.';
 const accessNotFresh = 'The provider could not renew this account\'s access yet. Try the request again '
   + 'shortly; the authority keeps retrying the renewal.';
-const apiKeyRejected = 'Anthropic no longer accepts this account\'s API key. Add a valid key with '
-  + '`authswitch account add anthropic-api-key`, or remove the account.';
+/** A key its provider no longer accepts: keys are not renewed, so a new key takes its place. */
+const apiKeyRejected = (providerIdArg: TAuthSwitchApiKeyProvider): string => `${authSwitchApiKeyProviderNames[providerIdArg]
+  .name} no longer accepts this account's API key. Add a new key, then remove this account.`;
+/**
+ * The spend limit rule (`isAuthSwitchSpendLimitMicroUsd`), spelled out like the label rule: an owner-facing instruction
+ * carries no bare number.
+ */
+const spendLimitRule = 'A monthly spend limit is a whole number of cents, from one cent to one million dollars. Choose '
+  + 'another amount, or clear it.';
+const notOnApiKey = 'An API key account has no usage windows to keep a reserve of. Set its monthly spend limit '
+  + 'instead.';
 const publicAccount = (account: IStoredAuthorityAccount): IAuthSwitchAccount => ({
   id: account.id, providerId: account.providerId, label: account.label, email: account.email,
   plan: account.plan, organizationId: account.workspaceId, maxUsagePercent: account.maxUsagePercent, reserveLiftUntil: account.reserveLiftUntil,
-  lapsesAt: account.lapsesAt,
+  lapsesAt: account.lapsesAt, spendLimitMicroUsd: account.spendLimitMicroUsd, keyHint: account.keyHint,
   removed: account.removed, revision: account.revision, statusObservedAt: account.statusObservedAt,
 });
 
@@ -148,6 +180,7 @@ const loginOwnerTool = (grant: IStoredAuthorityGrant): TAuthSwitchLoginOwnerTool
     case 'claude_container_setup': return null;
     // An API key is never renewed, and no tool on this host holds one.
     case 'anthropic_api_key': return null;
+    case 'openai_api_key': return null;
     // A purpose added without deciding its tool fails the type check here rather than publishing `null`,
     // which would claim the authority refreshes a login some tool actually holds.
     default: { const unhandledPurpose: never = grant.purpose; return unhandledPurpose; }
@@ -215,7 +248,7 @@ export class AuthSwitchAuthorityBroker {
   private readonly secrets: IAuthSwitchSecretCodec;
   private readonly now: () => number;
   private readonly proactive: boolean;
-  private readonly verifyAnthropicApiKey: (apiKey: string, signal: AbortSignal) => Promise<void>;
+  private readonly verifyApiKey: TAuthSwitchApiKeyVerifier;
   private readonly starts = new Map<string, IStartingOperation>();
   private readonly operations = new Map<string, IManagedOperation>();
   private readonly refreshes = new Map<string, Promise<void>>();
@@ -235,9 +268,7 @@ export class AuthSwitchAuthorityBroker {
     this.secrets = options.secrets ?? new AuthSwitchTpmSecretCodec();
     this.now = options.now ?? Date.now;
     this.proactive = options.proactive ?? true;
-    this.verifyAnthropicApiKey = options.verifyAnthropicApiKey ?? (async (apiKey, signal) => {
-      await plugins.flexAnthropic.listAnthropicApiKeyModels({ apiKey }, { signal });
-    });
+    this.verifyApiKey = options.verifyApiKey ?? authSwitchApiKeyVerifier();
     // Both access paths renew within the same five minutes (`claudeRefreshMarginMs`, `isDue`).
     this.access = new AuthSwitchAccessCache({ now: () => this.now(), marginMs: claudeRefreshMarginMs,
       maxEntries: accessCacheEntries });
@@ -644,7 +675,7 @@ export class AuthSwitchAuthorityBroker {
             revision: existing.revision + 1, statusObservedAt: now, updateId: commitId }
           : { id: identity.id, providerId: 'openai', issuer: 'openai', subject: identity.subject,
             workspaceId: identity.workspaceId, label: identity.email ?? `OpenAI ${identity.workspaceId}`,
-            email: identity.email, plan: identity.plan, primaryGrantId: grantId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, removed: false,
+            email: identity.email, plan: identity.plan, primaryGrantId: grantId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, spendLimitMicroUsd: null, keyHint: null, removed: false,
             revision: 1, statusObservedAt: now, updateId: commitId };
         const grant: IStoredAuthorityGrant = oldGrant
           ? { ...oldGrant, state: 'ready', owner: 'daemon', ciphertext,
@@ -784,6 +815,7 @@ export class AuthSwitchAuthorityBroker {
     const updateId = plugins.crypto.randomUUID();
     const updated = await this.database.changeAccount(updateId, accountId, account => {
       if (!account || account.removed || account.revision !== expectedRevision) throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
+      if (isApiKeyAccount(account)) throw new AuthSwitchRefusal('invalid_input', notOnApiKey);
       return { ...account, maxUsagePercent, revision: account.revision + 1, updateId,
         statusObservedAt: new Date(this.now()).toISOString() };
     });
@@ -802,6 +834,7 @@ export class AuthSwitchAuthorityBroker {
       if (!account || account.removed || account.revision !== expectedRevision) {
         throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
       }
+      if (isApiKeyAccount(account)) throw new AuthSwitchRefusal('invalid_input', notOnApiKey);
       if (account.maxUsagePercent === null || account.maxUsagePercent === 100) {
         throw new AuthSwitchRefusal('invalid_input', 'This account has no reserve to lift.');
       }
@@ -813,6 +846,30 @@ export class AuthSwitchAuthorityBroker {
     return publicAccount(updated.account);
   }
 
+  /**
+   * Sets or clears an API key account's monthly spend limit, as `setAccountMaxUsage` changes a sign-in's threshold.
+   * A key's limit applies from the next request on, to the month's spend so far.
+   */
+  public async setAccountSpendLimit(accountId: string, expectedRevision: number,
+    spendLimitMicroUsd: number | null): Promise<IAuthSwitchAccount> {
+    if (!isId(accountId) || !validRevision(expectedRevision)) throw new Error('Invalid account change.');
+    if (spendLimitMicroUsd !== null && !isAuthSwitchSpendLimitMicroUsd(spendLimitMicroUsd)) {
+      throw new AuthSwitchRefusal('invalid_input', spendLimitRule);
+    }
+    const updateId = plugins.crypto.randomUUID();
+    const updated = await this.database.changeAccount(updateId, accountId, account => {
+      if (!account || account.removed || account.revision !== expectedRevision) throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
+      if (!isApiKeyAccount(account)) {
+        throw new AuthSwitchRefusal('invalid_input', 'Only an API key account has a spend limit. Set a sign-in\'s '
+          + 'maximum usage instead.');
+      }
+      return { ...account, spendLimitMicroUsd, revision: account.revision + 1, updateId,
+        statusObservedAt: new Date(this.now()).toISOString() };
+    });
+    this.publish();
+    return publicAccount(updated.account);
+  }
+
   /**
    * Sets or clears the date an account's subscription ends, as `setAccountMaxUsage` changes its threshold. The date is
    * stored in its ISO 8601 UTC form; a past one is kept as given and means the account lapsed already.
@@ -886,7 +943,7 @@ export class AuthSwitchAuthorityBroker {
    * Whether this daemon renews logins of a bind purpose: Claude logins only with its Claude renewer configured. An
    * API key never needs renewing.
    */
-  private renews(purposeArg: 'openai_managed' | 'claude_host_native' | 'anthropic_api_key'): boolean {
+  private renews(purposeArg: TAuthSwitchBindPurpose): boolean {
     return purposeArg !== 'claude_host_native' || this.claudeGrants !== undefined;
   }
 
@@ -896,14 +953,14 @@ export class AuthSwitchAuthorityBroker {
    */
   private bindableNow(grant: IStoredAuthorityGrant, storedBindable: boolean): boolean {
     return storedBindable && (grant.purpose === 'openai_managed' || grant.purpose === 'claude_host_native'
-      || grant.purpose === 'anthropic_api_key') && this.renews(grant.purpose);
+      || grant.purpose === 'anthropic_api_key' || grant.purpose === 'openai_api_key') && this.renews(grant.purpose);
   }
 
   public async bindAccount(input: { accountId: string; loginId: string;
-    purpose: 'openai_managed' | 'claude_host_native' | 'anthropic_api_key'; runtime: IAuthSwitchBinding['runtime'];
+    purpose: TAuthSwitchBindPurpose; runtime: IAuthSwitchBinding['runtime'];
     scopeId: string; incarnationId: string }): Promise<{ binding: IAuthSwitchBinding; capability: string }> {
     if (!isId(input.accountId) || !isId(input.loginId)
-      || !['openai_managed', 'claude_host_native', 'anthropic_api_key'].includes(input.purpose)
+      || !authSwitchBindPurposes.includes(input.purpose)
       || !['flex', 'codex', 'opencode', 'claude', 'gateway'].includes(input.runtime)
       || !safeScope(input.scopeId, 512) || !safeScope(input.incarnationId, 256)) throw new Error('Invalid account binding.');
     // A Claude login reaches Claude Code itself through the native switch; it backs only the inference gateway,
@@ -912,8 +969,8 @@ export class AuthSwitchAuthorityBroker {
     if (claude && (input.runtime !== 'gateway' || !this.renews(input.purpose))) {
       throw new AuthSwitchRefusal('login_unavailable', loginNotBindable);
     }
-    // An Anthropic API key backs the gateway alone too: the proxy runs Flex's Claude models on it.
-    if (input.purpose === 'anthropic_api_key' && input.runtime !== 'gateway') {
+    // An API key backs the gateway alone too: the proxy relays requests on it at API prices.
+    if ((input.purpose === 'anthropic_api_key' || input.purpose === 'openai_api_key') && input.runtime !== 'gateway') {
       throw new AuthSwitchRefusal('login_unavailable', loginNotBindable);
     }
     if (claude && !(await this.database.hasVerifiedClaudeGrantReceipt(input.accountId, input.loginId))) {
@@ -1050,10 +1107,12 @@ export class AuthSwitchAuthorityBroker {
   }>, minValidityMs: number, rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {
     for (let attempt = 0; attempt < 4; attempt++) {
       const { account, grant } = await readView();
+      // An API key is resolved as a key whatever its provider, so an OpenAI key never reaches the ChatGPT path below.
+      if (attempt === 0 && (grant.purpose === 'anthropic_api_key' || grant.purpose === 'openai_api_key')) {
+        return this.resolveApiKeyAccess(readView, rejectedGrantGeneration);
+      }
       if (attempt === 0 && account.providerId === 'anthropic' && grant.providerId === 'anthropic') {
-        return grant.purpose === 'anthropic_api_key'
-          ? this.resolveAnthropicApiKeyAccess(readView, rejectedGrantGeneration)
-          : this.resolveClaudeAccess(readView, minValidityMs, rejectedGrantGeneration);
+        return this.resolveClaudeAccess(readView, minValidityMs, rejectedGrantGeneration);
       }
       if (account.removed || grant.accountId !== account.id || grant.id !== account.primaryGrantId
         || account.providerId !== 'openai' || grant.providerId !== 'openai') {
@@ -1176,17 +1235,18 @@ export class AuthSwitchAuthorityBroker {
   }
 
   /**
-   * A bound Anthropic API key, with the refusals `resolveManagedAccess` gives. A key is never renewed: one Anthropic
-   * rejected for exactly this generation ends (`needs_reauth`, `provider_rejected`), and only adding a key it accepts
-   * brings the account back.
+   * A bound Anthropic or OpenAI API key, with the refusals `resolveManagedAccess` gives. A key is never renewed: one its
+   * provider rejected for exactly this generation ends (`needs_reauth`, `provider_rejected`), and only adding a key the
+   * provider accepts brings the account back.
    */
-  private async resolveAnthropicApiKeyAccess(readView: () => Promise<{
+  private async resolveApiKeyAccess(readView: () => Promise<{
     account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
   }>, rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {
     for (let attempt = 0; attempt < 4; attempt++) {
       const { account, grant } = await readView();
       if (account.removed || grant.accountId !== account.id || grant.id !== account.primaryGrantId
-        || account.providerId !== 'anthropic' || grant.providerId !== 'anthropic' || grant.purpose !== 'anthropic_api_key'
+        || (grant.purpose !== 'anthropic_api_key' && grant.purpose !== 'openai_api_key')
+        || account.providerId !== authorityApiKeyProvider(grant.purpose) || grant.providerId !== account.providerId
         || grant.owner !== 'daemon') {
         throw this.loginEnded(grant.id);
       }
@@ -1209,9 +1269,9 @@ export class AuthSwitchAuthorityBroker {
       if (grant.state !== 'ready') {
         this.access.drop(grant.id);
         throw new AuthSwitchRefusal('login_needs_reauth',
-          grant.problem === 'provider_rejected' ? apiKeyRejected : loginNeedsReauth);
+          grant.problem === 'provider_rejected' ? apiKeyRejected(authorityApiKeyProvider(grant.purpose)) : loginNeedsReauth);
       }
-      const access = await this.access.open(account, grant, () => this.openAnthropicApiKeyAccess(account, grant));
+      const access = await this.access.open(account, grant, () => this.openApiKeyAccess(account, grant));
       const latest = await readView();
       if (latest.account.removed || latest.account.id !== account.id
         || latest.account.primaryGrantId !== latest.grant.id || latest.account.subject !== account.subject
@@ -1227,49 +1287,80 @@ export class AuthSwitchAuthorityBroker {
     throw new Error('Account credential rotated repeatedly during resolution; retry the request.');
   }
 
-  /** The key a daemon-held Anthropic API key grant seals, proven to be the key its account is named by. */
-  private async openAnthropicApiKeyAccess(account: IStoredAuthorityAccount,
+  /**
+   * The key a daemon-held API key grant seals, proven to be the key its account is named by: its provider's sealed
+   * kind (`apiKeySealedKinds`) and a key whose digest is the account's subject.
+   */
+  private async openApiKeyAccess(account: IStoredAuthorityAccount,
     grant: IStoredAuthorityGrant): Promise<IAuthSwitchGrantAccess> {
-    if (!grant.ciphertext || grant.owner !== 'daemon' || grant.purpose !== 'anthropic_api_key'
+    if (!grant.ciphertext || grant.owner !== 'daemon'
+      || (grant.purpose !== 'anthropic_api_key' && grant.purpose !== 'openai_api_key')
       || grant.accountId !== account.id) throw new Error('Account has no daemon-owned API key.');
+    const providerId = authorityApiKeyProvider(grant.purpose);
     const bytes = await this.secrets.unseal(grant.id, grant.ciphertext);
     try {
       const value: unknown = JSON.parse(Buffer.from(bytes).toString('utf8'));
       const record = value && typeof value === 'object' ? value as Record<string, unknown> : {};
-      if (record.kind !== 'anthropicApiKey' || typeof record.apiKey !== 'string' || !record.apiKey
-        || anthropicApiKeySubject(record.apiKey) !== account.subject) throw new Error();
+      if (record.kind !== apiKeySealedKinds[providerId] || typeof record.apiKey !== 'string' || !record.apiKey
+        || apiKeySubject(providerId, record.apiKey) !== account.subject) throw new Error();
       return { accessToken: record.apiKey, expiresAt: Infinity };
     } catch { throw new Error('Stored API key is invalid or belongs to another account.'); }
     finally { bytes.fill(0); }
   }
 
   /**
-   * Adds an Anthropic API key as an account of its own once Anthropic accepted it. The key is sealed like every login
-   * the authority holds and never answered on the management socket again. A key the authority holds already is
-   * refused while its account is ready; adding it after its account was removed, or after Anthropic rejected it,
-   * brings that account back with a new authorization, so a runtime bound to it binds again.
+   * Adds an Anthropic or OpenAI API key as an account of its own once its provider accepted it. A key that begins the
+   * way the other provider's keys do is refused before any request. The key is sealed like every login the authority
+   * holds and never answered on the management socket again; the account keeps only how it ends (`keyHint`). A key the
+   * authority holds already is refused while its account is ready; adding it after its account was removed, or after
+   * its provider rejected it, brings that account back with a new authorization, so a runtime bound to it binds again,
+   * and with the spend limit it had unless the request names one.
    */
-  public async addAnthropicApiKey(apiKey: string, label?: string): Promise<{ account: IAuthSwitchAccount; loginId: string }> {
-    if (typeof apiKey !== 'string' || apiKey.length === 0 || apiKey.length > 512 || !/^[\x21-\x7e]+$/.test(apiKey)) {
-      throw new AuthSwitchRefusal('invalid_input', 'An Anthropic API key is one word of printable characters, as the '
-        + 'Claude Console shows it. Paste the key again.');
+  public async addApiKey(providerId: TAuthSwitchApiKeyProvider, apiKey: string, label?: string,
+    spendLimitMicroUsd?: number): Promise<{ account: IAuthSwitchAccount; loginId: string }> {
+    if (providerId !== 'anthropic' && providerId !== 'openai') throw new Error('Invalid API key provider.');
+    const provider = authSwitchApiKeyProviderNames[providerId];
+    if (typeof apiKey !== 'string' || apiKey.length < apiKeyMinimumLength || apiKey.length > 512
+      || !/^[\x21-\x7e]+$/.test(apiKey)) {
+      throw new AuthSwitchRefusal('invalid_input', `An ${provider.name} API key is one word of printable characters, as `
+        + `${provider.console} shows it. Paste the key again.`);
+    }
+    const other = authSwitchApiKeyOtherProvider(providerId, apiKey);
+    if (other !== null) {
+      throw new AuthSwitchRefusal('invalid_input', `This is an ${authSwitchApiKeyProviderNames[other].name} API key, by `
+        + `how it begins. Add it as an ${authSwitchApiKeyProviderNames[other].name} key, or paste the ${provider.name} key.`);
     }
     if (label !== undefined && !isAuthSwitchAccountLabel(label)) {
       throw new AuthSwitchRefusal('invalid_input', 'An account label has between one and one hundred and twenty-eight '
         + 'characters, with no space at either end and no control character. Choose another label.');
     }
+    if (spendLimitMicroUsd !== undefined && !isAuthSwitchSpendLimitMicroUsd(spendLimitMicroUsd)) {
+      throw new AuthSwitchRefusal('invalid_input', spendLimitRule);
+    }
     if (this.closed) throw new Error('Authswitch authority is closing.');
+    let verdict: TAuthSwitchApiKeyVerdict;
     try {
-      await this.verifyAnthropicApiKey(apiKey, AbortSignal.timeout(anthropicApiKeyVerifyTimeoutMs));
-    } catch (error) {
-      throw new AuthSwitchRefusal('api_key_unverified', error instanceof plugins.flexAnthropic.AnthropicApiKeyAuthError
-        ? 'Anthropic rejected this API key. Check that it is an active key from the Claude Console, then add it again.'
-        : 'Anthropic could not be asked whether it accepts this API key. Try again shortly.');
+      verdict = await this.verifyApiKey(providerId, apiKey, AbortSignal.timeout(apiKeyVerifyTimeoutMs));
+    } catch {
+      // The provider's own words are left out: an error may quote the request, and with it the key.
+      throw new AuthSwitchRefusal('api_key_unverified', `${provider.name} could not be asked whether it accepts this `
+        + 'API key. Try again shortly.');
+    }
+    if (verdict === 'rejected') {
+      throw new AuthSwitchRefusal('api_key_unverified', `${provider.name} rejected this API key. Check that it is an `
+        + `active key from ${provider.console}, then add it again.`);
+    }
+    if (verdict === 'forbidden') {
+      throw new AuthSwitchRefusal('api_key_unverified', `${provider.name} accepts this API key but does not let it `
+        + 'list models, which is how AGL checks a key. Give the key read access to models (or all permissions) in '
+        + `${provider.console}, then add it again.`);
     }
-    const subject = anthropicApiKeySubject(apiKey);
-    const accountId = idHash('authswitch-account-v1', 'anthropic', subject, anthropicApiKeyWorkspace);
-    const grantId = idHash('authswitch-grant-v1', accountId, 'anthropic_api_key', anthropicApiKeyAudience);
-    const bytes = Buffer.from(JSON.stringify({ kind: 'anthropicApiKey', apiKey }), 'utf8');
+    const kind = apiKeyGrants[providerId];
+    const subject = apiKeySubject(providerId, apiKey);
+    const accountId = idHash('authswitch-account-v1', providerId, subject, apiKeyWorkspace);
+    const grantId = idHash('authswitch-grant-v1', accountId, kind.purpose, kind.audience);
+    const keyHint = authSwitchKeyHint(apiKey);
+    const bytes = Buffer.from(JSON.stringify({ kind: apiKeySealedKinds[providerId], apiKey }), 'utf8');
     let ciphertext: string;
     try { ciphertext = await this.secrets.seal(grantId, bytes); }
     finally { bytes.fill(0); }
@@ -1282,18 +1373,20 @@ export class AuthSwitchAuthorityBroker {
           + 'instead of adding the key again.');
       }
       const account: IStoredAuthorityAccount = existing
-        ? { ...existing, label: label ?? existing.label, primaryGrantId: grantId, removed: false,
+        ? { ...existing, label: label ?? existing.label, primaryGrantId: grantId, keyHint,
+          spendLimitMicroUsd: spendLimitMicroUsd ?? existing.spendLimitMicroUsd, removed: false,
           revision: existing.revision + 1, statusObservedAt: now, updateId }
-        : { id: accountId, providerId: 'anthropic', issuer: 'anthropic', subject, workspaceId: anthropicApiKeyWorkspace,
-          label: label ?? 'Anthropic API key', email: null, plan: null, primaryGrantId: grantId, maxUsagePercent: null, reserveLiftUntil: null,
-          lapsesAt: null, removed: false, revision: 1, statusObservedAt: now, updateId };
+        : { id: accountId, providerId, issuer: providerId, subject, workspaceId: apiKeyWorkspace,
+          label: label ?? kind.label, email: null, plan: null, primaryGrantId: grantId, maxUsagePercent: null,
+          reserveLiftUntil: null, lapsesAt: null, spendLimitMicroUsd: spendLimitMicroUsd ?? null, keyHint,
+          removed: false, revision: 1, statusObservedAt: now, updateId };
       const grant: IStoredAuthorityGrant = oldGrant
         ? { ...oldGrant, state: 'ready', owner: 'daemon', ciphertext, grantGeneration: oldGrant.grantGeneration + 1,
           authorizationGeneration: oldGrant.authorizationGeneration + 1, revision: oldGrant.revision + 1,
           accessExpiresAt: null, attemptId: null, retryAt: null, retryCount: 0, problem: 'none', statusObservedAt: now,
           updateId }
-        : { id: grantId, accountId, providerId: 'anthropic', purpose: 'anthropic_api_key',
-          audience: anthropicApiKeyAudience, state: 'ready', owner: 'daemon', grantGeneration: 1,
+        : { id: grantId, accountId, providerId, purpose: kind.purpose,
+          audience: kind.audience, state: 'ready', owner: 'daemon', grantGeneration: 1,
           authorizationGeneration: 1, revision: 1, ciphertext, accessExpiresAt: null, attemptId: null, retryAt: null,
           retryCount: 0, problem: 'none', statusObservedAt: now, updateId };
       return { account, grant };