agl 40.4.0 → 40.5.0

package/ts_authswitch/classes.authoritydatabase.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
-import { AuthSwitchRefusal, authSwitchPreemptibleRuntimes } from './authority-contract.js';
+import { AuthSwitchRefusal, authSwitchPreemptibleRuntimes, type IAuthSwitchSpendAnswer } from './authority-contract.js';
+import { authSwitchSpendExhausted, authSwitchSpendPeriod, type IAuthSwitchSpendReading } from './authority-spend.js';
 import {
   AuthSwitchAuthorityAccountModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityClaudeContainerHomeModel,
   AuthSwitchAuthorityClaudeHandoffModel, AuthSwitchAuthorityClaudeHomeModel, AuthSwitchAuthorityCodexHandoffModel,
@@ -7,6 +8,9 @@ import {
   AuthSwitchAuthorityEventModel, AuthSwitchAuthorityGrantModel, AuthSwitchAuthorityHandoffModel,
   AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityMigrationLedgerModel, AuthSwitchAuthorityOperationModel,
   AuthSwitchAuthorityUsageModel, authorityUsageId, assertStoredAuthorityAccount,
+  AuthSwitchAuthoritySpendEntryModel, AuthSwitchAuthoritySpendPeriodModel, authoritySpendEntryId, authoritySpendPeriodId,
+  assertStoredAuthoritySpendEntry, assertStoredAuthoritySpendPeriod, type IStoredAuthoritySpendEntry,
+  type IStoredAuthoritySpendPeriod,
   AuthSwitchAuthorityUsageEstimateModel, authorityUsageEstimateId, assertStoredAuthorityUsageEstimate,
   assertStoredAuthorityBinding, assertStoredAuthorityClaudeContainerHome, assertStoredAuthorityClaudeHandoff,
   assertStoredAuthorityClaudeHome, assertStoredAuthorityCodexHandoff, assertStoredAuthorityCodexHostHome,
@@ -221,24 +225,50 @@ const storedOperation = (stored: Parameters<typeof AuthSwitchAuthorityOperationM
 const claudeReceiptSourceKinds: readonly IStoredAuthorityMigrationLedger['sourceKind'][] =
   ['authswitch_stash', 'authswitch_backup', 'claude_native', 'claude_signin'];
 
+/** The purposes of a login a runtime binds: a ChatGPT login, a Claude login, or an Anthropic or OpenAI API key. */
+export type TAuthSwitchBindPurpose = 'openai_managed' | 'claude_host_native' | 'anthropic_api_key' | 'openai_api_key';
+
+export const authSwitchBindPurposes: readonly TAuthSwitchBindPurpose[] =
+  ['openai_managed', 'claude_host_native', 'anthropic_api_key', 'openai_api_key'];
+
 /**
  * The purpose a runtime bind of this login is accepted under, as far as the stored records decide it, or `null`:
  * the account is not removed, and the login is its selected, ready, daemon-held login of the account's own provider
- * -- its ChatGPT login (`openai_managed`), its Claude login (`claude_host_native`) or its Anthropic API key
- * (`anthropic_api_key`). A Claude login further needs a verified import receipt (`hasVerifiedClaudeGrantReceipt`) and
- * the daemon's Claude renewer. The authority page's `bindableGrantIds` and the bind itself both decide by this, so a
- * login published as bindable is one a bind accepts.
+ * -- its ChatGPT login (`openai_managed`), its Claude login (`claude_host_native`) or its Anthropic or OpenAI API key
+ * (`anthropic_api_key`, `openai_api_key`). A Claude login further needs a verified import receipt
+ * (`hasVerifiedClaudeGrantReceipt`) and the daemon's Claude renewer. The authority page's `bindableGrantIds` and the
+ * bind itself both decide by this, so a login published as bindable is one a bind accepts.
  */
 export const authorityBindPurpose = (account: IStoredAuthorityAccount, grant: IStoredAuthorityGrant):
-'openai_managed' | 'claude_host_native' | 'anthropic_api_key' | null => {
+TAuthSwitchBindPurpose | null => {
   if (account.removed || grant.accountId !== account.id || grant.id !== account.primaryGrantId || grant.state !== 'ready'
     || grant.owner !== 'daemon' || grant.providerId !== account.providerId) return null;
   if (grant.purpose === 'openai_managed' && grant.providerId === 'openai') return 'openai_managed';
   if (grant.purpose === 'claude_host_native' && grant.providerId === 'anthropic') return 'claude_host_native';
   if (grant.purpose === 'anthropic_api_key' && grant.providerId === 'anthropic') return 'anthropic_api_key';
+  if (grant.purpose === 'openai_api_key' && grant.providerId === 'openai') return 'openai_api_key';
   return null;
 };
 
+/** How far ahead of the authority's clock a reported answer may have ended: a proxy clock off by more is a fault. */
+const spendClockSkewMs = 86_400_000;
+/** The most entries and months of earlier months one spend report deletes; the rest go with the next reports. */
+const spendPruneBatch = 256;
+
+/** An API key's grant of its account: the key of the account's provider, which the account's workspace names. */
+const isApiKeyGrant = (account: IStoredAuthorityAccount, grant: IStoredAuthorityGrant): boolean =>
+  grant.accountId === account.id && account.workspaceId === 'api-key' && grant.providerId === account.providerId
+  && ((grant.purpose === 'anthropic_api_key' && grant.providerId === 'anthropic')
+    || (grant.purpose === 'openai_api_key' && grant.providerId === 'openai'));
+
+/** A month's reading from its stored total, or an empty one, with the account's limit as it stands. */
+const spendReading = (period: ReturnType<typeof authSwitchSpendPeriod>, stored: IStoredAuthoritySpendPeriod | null,
+  limitMicroUsd: number | null): IAuthSwitchSpendReading => ({
+  period: period.key, periodStart: period.start, resetAt: period.end,
+  spentMicroUsd: stored?.spentMicroUsd ?? 0, limitMicroUsd, answers: stored?.answers ?? 0,
+  unpricedAnswers: stored?.unpricedAnswers ?? 0, lastAnswerAt: stored?.lastAnswerAt ?? null,
+});
+
 /** Separate account, grant, binding and journal records; the only global record is a revision counter. */
 export class AuthSwitchAuthorityDatabase {
   private engine?: plugins.nosqldbEngine.LocalNoSqlDb;
@@ -966,6 +996,140 @@ export class AuthSwitchAuthorityDatabase {
     });
   }
 
+  /**
+   * An API key's spend in the month `nowArg` falls in, with its account's spend limit as it stands. Refused
+   * (`login_unavailable`) for any login but an API key of its account.
+   */
+  public async readSpend(accountId: string, loginId: string, nowArg: number): Promise<IAuthSwitchSpendReading> {
+    this.db();
+    if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(loginId)) throw new Error('Invalid authority spend identity.');
+    const period = authSwitchSpendPeriod(nowArg);
+    return this.transaction(async session => {
+      const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+      const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: loginId }, { session });
+      const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+      const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+      if (!account || !grant || !isApiKeyGrant(account, grant)) {
+        throw new AuthSwitchRefusal('login_unavailable', 'Only an API key\'s login has a spend.');
+      }
+      const stored = await AuthSwitchAuthoritySpendPeriodModel.exact.findStoredOne(
+        { id: authoritySpendPeriodId(accountId, period.key) }, { session });
+      return spendReading(period, stored ? AuthSwitchAuthoritySpendPeriodModel.exact.toPersisted(stored) : null,
+        account.spendLimitMicroUsd);
+    });
+  }
+
+  /**
+   * Records a spend report of an API key's login in one transaction: each answer's entry, the totals of the months they
+   * count in, and an account event when the report changed whether the key is at its limit or began the month's spend,
+   * so a reader of the snapshot reads the key's usage again. An entry recorded already with the same content is no
+   * change; one with other content refuses the whole report, naming the answer. An answer of a month before the previous
+   * one counts nowhere: only the current and the previous month are kept, and entries and totals of earlier months are
+   * deleted here, a bounded number per report. A removed key's spend is recorded too, so its account keeps the month's
+   * spend if the key comes back. Answers `changed` with the reading of the month `nowArg` falls in.
+   */
+  public async recordSpend(accountId: string, loginId: string, answers: readonly IAuthSwitchSpendAnswer[],
+    nowArg: number): Promise<{ reading: IAuthSwitchSpendReading; changed: boolean }> {
+    this.db();
+    if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(loginId)) throw new Error('Invalid authority spend identity.');
+    const current = authSwitchSpendPeriod(nowArg);
+    const previous = authSwitchSpendPeriod(Date.parse(current.start) - 1);
+    const updateId = plugins.crypto.randomUUID();
+    try {
+      return await this.transaction(async session => {
+        const metaStored = await AuthSwitchAuthorityMetaModel.exact.findStoredOne({ id: 'authswitch-authority' }, { session });
+        const accountStored = await AuthSwitchAuthorityAccountModel.exact.findStoredOne({ id: accountId }, { session });
+        const grantStored = await AuthSwitchAuthorityGrantModel.exact.findStoredOne({ id: loginId }, { session });
+        if (!metaStored) throw new Error('Authswitch authority metadata is missing.');
+        const account = accountStored ? AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored) : null;
+        const grant = grantStored ? AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored) : null;
+        if (!account || !grant || !isApiKeyGrant(account, grant)) {
+          throw new AuthSwitchRefusal('login_unavailable', 'Only an API key\'s login records spend.');
+        }
+        const added = new Map<string, { spent: number; answers: number; unpriced: number; last: string }>();
+        for (const answer of answers) {
+          const endedAt = Date.parse(answer.endedAt);
+          if (endedAt > nowArg + spendClockSkewMs) {
+            throw new AuthSwitchRefusal('invalid_input', `The spend report names answer ${answer.answerId} as ending more `
+              + 'than a day after the account service\'s clock; check the clocks, the report is refused.');
+          }
+          const period = authSwitchSpendPeriod(endedAt).key;
+          if (period < previous.key) continue;
+          const entry: IStoredAuthoritySpendEntry = { id: authoritySpendEntryId(accountId, answer.answerId), accountId,
+            answerId: answer.answerId, period, endedAt: answer.endedAt, model: answer.model,
+            serviceTier: answer.serviceTier, microUsd: answer.microUsd, priceSource: answer.priceSource };
+          assertStoredAuthoritySpendEntry(entry);
+          const inserted = await AuthSwitchAuthoritySpendEntryModel.exact.insert(entry, { session });
+          if (inserted.status === 'conflict') {
+            throw new AuthSwitchRefusal('invalid_input', `The spend report names answer ${answer.answerId}, which the `
+              + 'account service recorded with other content; the report is refused.');
+          }
+          if (inserted.status !== 'inserted') continue;
+          const sum = added.get(period) ?? { spent: 0, answers: 0, unpriced: 0, last: answer.endedAt };
+          added.set(period, { spent: sum.spent + (answer.microUsd ?? 0), answers: sum.answers + 1,
+            unpriced: sum.unpriced + (answer.microUsd === null ? 1 : 0),
+            last: Date.parse(answer.endedAt) > Date.parse(sum.last) ? answer.endedAt : sum.last });
+        }
+        const readPeriod = async (key: string): Promise<{
+          stored: Awaited<ReturnType<typeof AuthSwitchAuthoritySpendPeriodModel.exact.findStoredOne>>;
+          persisted: IStoredAuthoritySpendPeriod | null }> => {
+          const stored = await AuthSwitchAuthoritySpendPeriodModel.exact.findStoredOne(
+            { id: authoritySpendPeriodId(accountId, key) }, { session });
+          return { stored, persisted: stored ? AuthSwitchAuthoritySpendPeriodModel.exact.toPersisted(stored) : null };
+        };
+        const before = (await readPeriod(current.key)).persisted;
+        let after = before;
+        for (const [key, sum] of added) {
+          const { stored, persisted } = await readPeriod(key);
+          const next: IStoredAuthoritySpendPeriod = {
+            id: authoritySpendPeriodId(accountId, key), accountId, period: key,
+            spentMicroUsd: (persisted?.spentMicroUsd ?? 0) + sum.spent, answers: (persisted?.answers ?? 0) + sum.answers,
+            unpricedAnswers: (persisted?.unpricedAnswers ?? 0) + sum.unpriced,
+            lastAnswerAt: persisted?.lastAnswerAt && Date.parse(persisted.lastAnswerAt) > Date.parse(sum.last)
+              ? persisted.lastAnswerAt : sum.last,
+            revision: (persisted?.revision ?? 0) + 1, updateId,
+          };
+          assertStoredAuthoritySpendPeriod(next);
+          if (stored) {
+            const changed = await AuthSwitchAuthoritySpendPeriodModel.exact.transition({ current: stored,
+              change: model => Object.assign(model, next) }, { session });
+            if (changed.status !== 'transitioned') throw new Error('Spend total changed while it was recorded.');
+          } else {
+            const inserted = await AuthSwitchAuthoritySpendPeriodModel.exact.insert(next, { session });
+            if (inserted.status !== 'inserted') throw new Error('Spend total changed while it was recorded.');
+          }
+          if (key === current.key) after = next;
+        }
+        const limit = account.spendLimitMicroUsd;
+        const reading = spendReading(current, after, limit);
+        const changed = (before === null && after !== null)
+          || authSwitchSpendExhausted(spendReading(current, before, limit), nowArg) !== authSwitchSpendExhausted(reading, nowArg);
+        if (changed) {
+          await this.appendEvent(session, AuthSwitchAuthorityMetaModel.exact.toPersisted(metaStored), updateId, 'account',
+            accountId);
+        }
+        // Only the current and the previous month are kept.
+        for (const stale of await AuthSwitchAuthoritySpendEntryModel.exact.findStored({ filter: { accountId,
+          period: { $lt: previous.key } }, sort: { accountId: 1, period: 1, id: 1 }, limit: spendPruneBatch, session })) {
+          const deleted = await AuthSwitchAuthoritySpendEntryModel.exact.delete({ current: stale }, { session });
+          if (deleted.status !== 'deleted') throw new Error('Spend entry changed while it was deleted.');
+        }
+        for (const stale of await AuthSwitchAuthoritySpendPeriodModel.exact.findStored({ filter: { accountId,
+          period: { $lt: previous.key } }, sort: { accountId: 1, period: 1 }, limit: spendPruneBatch, session })) {
+          const deleted = await AuthSwitchAuthoritySpendPeriodModel.exact.delete({ current: stale }, { session });
+          if (deleted.status !== 'deleted') throw new Error('Spend total changed while it was deleted.');
+        }
+        return { reading, changed };
+      });
+    } catch (error) {
+      if (error instanceof plugins.nosqldb.SmartdataExactPersistenceError && error.code === 'ambiguous_write') {
+        // A repeat of the report is no change once it committed, so the caller sends it again.
+        throw new Error('The spend report\'s outcome is unknown; send it again.');
+      }
+      throw error;
+    }
+  }
+
   /** Delete one login's usage estimate, if one is stored. */
   public async deleteUsageEstimate(accountId: string, loginId: string): Promise<void> {
     this.db();
@@ -1002,7 +1166,12 @@ export class AuthSwitchAuthorityDatabase {
           AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored),
           AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored));
         if (!sameUsageContext(context, actual) || actual.removed) return false;
-        if (actual.providerId === 'openai') {
+        if (actual.purpose === 'anthropic_api_key' || actual.purpose === 'openai_api_key') {
+          // An API key's record holds its payment problem alone, while the key is ready (`assertStoredAuthorityUsage`).
+          if (!isApiKeyGrant(AuthSwitchAuthorityAccountModel.exact.toPersisted(accountStored),
+            AuthSwitchAuthorityGrantModel.exact.toPersisted(grantStored)) || actual.owner !== 'daemon'
+            || context.nativeSource !== null || actual.grantState !== 'ready') return false;
+        } else if (actual.providerId === 'openai') {
           if (actual.owner !== 'daemon' || actual.purpose !== 'openai_managed'
             || context.nativeSource !== null || !['ready', 'retry_wait'].includes(actual.grantState)) return false;
         } else if (actual.providerId === 'anthropic' && actual.purpose === 'claude_host_native') {
@@ -1111,7 +1280,8 @@ export class AuthSwitchAuthorityDatabase {
       for (const grant of grantPage) {
         const account = grantAccountById.get(grant.accountId);
         const purpose = account ? authorityBindPurpose(account, grant) : null;
-        if (purpose === 'openai_managed' || purpose === 'anthropic_api_key' || purpose === 'claude_host_native'
+        if (purpose === 'openai_managed' || purpose === 'anthropic_api_key' || purpose === 'openai_api_key'
+          || purpose === 'claude_host_native'
           && await this.hasVerifiedClaudeGrantReceipt(grant.accountId, grant.id, session)) bindableGrantIds.add(grant.id);
       }
       // Both lists hold the first `limit + 1` ids past the cursor, so their merge holds the page and says whether

package/ts_authswitch/classes.authorityimport.ts

@@ -687,7 +687,7 @@ export class AuthSwitchGrantImport {
         removed: false, revision: existing.revision + 1, statusObservedAt: this.stamp(), updateId }
       : { id: identity.accountId, providerId: plan.providerId, issuer: plan.providerId,
         subject: identity.subject, workspaceId: identity.workspaceId, label, email: record.email,
-        plan: record.plan, primaryGrantId: grantId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, removed: false, revision: 1,
+        plan: record.plan, primaryGrantId: grantId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, spendLimitMicroUsd: null, keyHint: null, removed: false, revision: 1,
         statusObservedAt: this.stamp(), updateId };
   }
 

package/ts_authswitch/classes.authoritymodels.ts

@@ -1,10 +1,11 @@
 import * as plugins from './plugins.js';
-import { isAuthSwitchLapsesAt, isAuthSwitchMaxUsagePercent, type IAuthSwitchPreuseFailure, type IAuthSwitchPreuseLimit,
+import { isAuthSwitchKeyHint, isAuthSwitchLapsesAt, isAuthSwitchSpendAnswer, isAuthSwitchMaxUsagePercent, type IAuthSwitchPreuseFailure, type IAuthSwitchPreuseLimit,
   type TAuthSwitchClaudeProofFailure, type TAuthSwitchCodexProofFailure, type TAuthSwitchLoginOwner,
   type TAuthSwitchLoginPrompt } from './authority-contract.js';
 import type { IAuthSwitchStoredUsage, IAuthSwitchStoredUsageEstimate } from './classes.authorityusage.js';
 import { isAuthSwitchUsageEstimateState } from './classes.authorityusageestimate.js';
 import { isAuthSwitchUsageObservation } from './authority-usageheaders.js';
+import { authSwitchSpendPeriod, isAuthSwitchSpendLimitMicroUsd, isAuthSwitchSpendPeriodKey } from './authority-spend.js';
 
 export interface IStoredAuthorityMeta {
   id: 'authswitch-authority';
@@ -29,6 +30,10 @@ export interface IStoredAuthorityAccount {
   reserveLiftUntil: string | null;
   /** When the account's subscription ends, ISO 8601 UTC, or `null` while it renews (`IAuthSwitchAccount.lapsesAt`). */
   lapsesAt: string | null;
+  /** An API key account's monthly spend limit in micro-dollars, or `null` (`IAuthSwitchAccount.spendLimitMicroUsd`). */
+  spendLimitMicroUsd: number | null;
+  /** How an API key account's key ends, or `null` (`IAuthSwitchAccount.keyHint`). */
+  keyHint: string | null;
   removed: boolean;
   revision: number;
   statusObservedAt: string;
@@ -36,7 +41,15 @@ export interface IStoredAuthorityAccount {
 }
 
 export type TStoredGrantPurpose =
-  | 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native' | 'anthropic_api_key';
+  | 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native' | 'anthropic_api_key'
+  | 'openai_api_key';
+
+/** The purposes of an API key's login: a key the authority alone holds, which nothing renews. */
+export const authorityApiKeyPurposes: readonly TStoredGrantPurpose[] = ['anthropic_api_key', 'openai_api_key'];
+
+/** The provider whose key an API key purpose holds. */
+export const authorityApiKeyProvider = (purposeArg: 'anthropic_api_key' | 'openai_api_key'): 'anthropic' | 'openai' =>
+  purposeArg === 'anthropic_api_key' ? 'anthropic' : 'openai';
 
 /** Each purpose has its own grant, ownership, generation and refresh state. */
 export interface IStoredAuthorityGrant {
@@ -104,6 +117,43 @@ export interface IStoredAuthorityUsageEstimate extends IAuthSwitchStoredUsageEst
 export const authorityUsageEstimateId = (accountId: string, loginId: string): string =>
   plugins.crypto.createHash('sha256').update(JSON.stringify(['authswitch-usage-estimate', accountId, loginId])).digest('hex');
 
+/**
+ * One answer AGL's inference proxy relayed on an API key, as the spend report named it (`IAuthSwitchSpendAnswer`): the
+ * ledger's record of what it cost. Its content is the report's alone, so a repeat of the report is the same document and
+ * a report of the same answer with other content is a conflict. Kept for the current and the previous month.
+ */
+export interface IStoredAuthoritySpendEntry {
+  id: string;
+  accountId: string;
+  answerId: string;
+  /** The month the answer counts in, `YYYY-MM` of `endedAt` in UTC. */
+  period: string;
+  endedAt: string;
+  model: string;
+  serviceTier: string | null;
+  microUsd: number | null;
+  priceSource: string | null;
+}
+
+export const authoritySpendEntryId = (accountId: string, answerId: string): string =>
+  plugins.crypto.createHash('sha256').update(JSON.stringify(['authswitch-spend-entry', accountId, answerId])).digest('hex');
+
+/** What an API key spent in one month, the sum of its entries of that month (`IAuthSwitchSpendReading`). */
+export interface IStoredAuthoritySpendPeriod {
+  id: string;
+  accountId: string;
+  period: string;
+  spentMicroUsd: number;
+  answers: number;
+  unpricedAnswers: number;
+  lastAnswerAt: string | null;
+  revision: number;
+  updateId: string;
+}
+
+export const authoritySpendPeriodId = (accountId: string, period: string): string =>
+  plugins.crypto.createHash('sha256').update(JSON.stringify(['authswitch-spend-period', accountId, period])).digest('hex');
+
 export interface IStoredAuthorityBinding {
   id: string;
   accountId: string;
@@ -525,15 +575,26 @@ const usageClaudeStatus = (value: unknown): boolean => object(value)
     && exactKeys(value.rateLimit, ['retryAt'])
     && (value.rateLimit.retryAt === null || iso(value.rateLimit.retryAt))));
 /**
- * A payment problem on a Claude login's usage record (`IAuthSwitchPaymentProblem`): when it was seen, and the
- * subscription read before it or null. Each subscription value is bounded like a fact's text.
+ * A payment problem on a usage record (`IAuthSwitchPaymentProblem`): when it was seen, and the subscription read before
+ * it or null. Each subscription value is bounded like a fact's text. A billing problem states no cause, exactly as every
+ * Claude login's record always did; an API key's `spend_cap` or `quota` states its cause with no subscription, and a
+ * `spend_cap` lifts at the end of the month it was seen in (`until`), never at another time.
  */
-const usagePaymentProblem = (value: unknown): boolean => object(value)
-  && exactKeys(value, ['at', 'subscription']) && iso(value.at)
-  && (value.subscription === null || (object(value.subscription)
-    && exactKeys(value.subscription, ['status', 'createdAt'])
-    && (value.subscription.status === null || usageStatusText(value.subscription.status))
-    && (value.subscription.createdAt === null || usageStatusText(value.subscription.createdAt))));
+const usagePaymentProblem = (value: unknown): boolean => object(value) && iso(value.at)
+  && ((exactKeys(value, ['at', 'subscription'])
+    && (value.subscription === null || (object(value.subscription)
+      && exactKeys(value.subscription, ['status', 'createdAt'])
+      && (value.subscription.status === null || usageStatusText(value.subscription.status))
+      && (value.subscription.createdAt === null || usageStatusText(value.subscription.createdAt)))))
+    || (exactKeys(value, ['at', 'subscription', 'cause']) && value.subscription === null && value.cause === 'quota')
+    || (exactKeys(value, ['at', 'subscription', 'cause', 'until']) && value.subscription === null
+      && value.cause === 'spend_cap' && value.until === authSwitchSpendPeriod(Date.parse(value.at as string)).end));
+
+/** An API key's login: a key the authority alone holds, of the account's provider. */
+const usageApiKeyContext = (context: Record<string, unknown>): boolean =>
+  ((context.providerId === 'anthropic' && context.purpose === 'anthropic_api_key')
+    || (context.providerId === 'openai' && context.purpose === 'openai_api_key'))
+  && context.owner === 'daemon' && context.nativeSource === null && context.grantState === 'ready';
 const usageReading = (value: unknown): boolean => object(value)
   && (value.kind === 'openai' ? exactKeys(value, ['kind', 'rateLimits']) && usageRateLimits(value.rateLimits)
     : value.kind === 'anthropic' && exactKeys(value, ['kind', 'status'])
@@ -543,12 +604,31 @@ const storedUsageKeys = ['id', 'accountId', 'loginId', 'context', 'updateId', 'r
   'staleUntil', 'lastAttemptAt', 'nextAttemptAt', 'failures', 'problem'] as const;
 
 /**
- * A credential-free usage record. `paymentProblem` is present only while a Claude login is held with one, never as null
- * or undefined: an accounts service of 40.2.0 or older refuses every record that has the member.
+ * A credential-free usage record. `paymentProblem` is present only while a Claude login or an API key is held with one,
+ * never as null or undefined: an accounts service of 40.2.0 or older refuses every record that has the member. An API
+ * key's record holds nothing but its payment problem: the authority reads no usage of a key, whose spend is its ledger's.
  */
 export const assertStoredAuthorityUsage: (value: unknown) => asserts value is IStoredAuthorityUsage = value => {
+  if (object(value) && object(value.context) && usageApiKeyContext(value.context)) {
+    if (!(exactKeys(value, storedUsageKeys) || (exactKeys(value, [...storedUsageKeys, 'paymentProblem'])
+      && usagePaymentProblem(value.paymentProblem) && object(value.paymentProblem)
+      && value.paymentProblem.subscription === null))
+      || !hash(value.accountId) || !hash(value.loginId) || value.id !== authorityUsageId(value.accountId, value.loginId)
+      || !exactKeys(value.context, ['epoch', 'accountId', 'loginId', 'subjectId', 'workspaceId', 'providerId', 'purpose',
+        'owner', 'grantState', 'removed', 'authorizationGeneration', 'grantGeneration', 'nativeSource'])
+      || !uuid(value.context.epoch) || value.context.accountId !== value.accountId || value.context.loginId !== value.loginId
+      || !bounded(value.context.subjectId) || value.context.workspaceId !== 'api-key' || value.context.removed !== false
+      || !revision(value.context.authorizationGeneration) || !revision(value.context.grantGeneration)
+      || !uuid(value.updateId) || value.reading !== null || value.observedAt !== null || value.currentUntil !== null
+      || value.staleUntil !== null || !iso(value.lastAttemptAt) || value.nextAttemptAt !== value.lastAttemptAt
+      || value.failures !== 0 || value.problem !== 'none') {
+      throw new Error('Invalid credential-free authority usage record.');
+    }
+    return;
+  }
   if (!object(value) || !(exactKeys(value, storedUsageKeys)
     || (exactKeys(value, [...storedUsageKeys, 'paymentProblem']) && usagePaymentProblem(value.paymentProblem)
+      && object(value.paymentProblem) && !Object.hasOwn(value.paymentProblem, 'cause')
       && object(value.context) && value.context.providerId === 'anthropic'))
     || !hash(value.accountId) || !hash(value.loginId)
     || value.id !== authorityUsageId(value.accountId, value.loginId)
@@ -614,6 +694,31 @@ export const assertStoredAuthorityUsageEstimate: (value: unknown) => asserts val
     }
   };
 
+export const assertStoredAuthoritySpendEntry: (value: unknown) => asserts value is IStoredAuthoritySpendEntry = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'accountId', 'answerId', 'period', 'endedAt', 'model', 'serviceTier',
+    'microUsd', 'priceSource']) || !hash(value.accountId) || typeof value.answerId !== 'string'
+    || value.id !== authoritySpendEntryId(value.accountId, value.answerId) || !isAuthSwitchSpendPeriodKey(value.period)
+    || !isAuthSwitchSpendAnswer({ answerId: value.answerId, endedAt: value.endedAt, model: value.model,
+      serviceTier: value.serviceTier, microUsd: value.microUsd, priceSource: value.priceSource })
+    || authSwitchSpendPeriod(Date.parse(value.endedAt as string)).key !== value.period) {
+    throw new Error('Invalid authority spend entry.');
+  }
+};
+
+export const assertStoredAuthoritySpendPeriod: (value: unknown) => asserts value is IStoredAuthoritySpendPeriod = value => {
+  if (!object(value) || !exactKeys(value, ['id', 'accountId', 'period', 'spentMicroUsd', 'answers', 'unpricedAnswers',
+    'lastAnswerAt', 'revision', 'updateId']) || !hash(value.accountId) || !isAuthSwitchSpendPeriodKey(value.period)
+    || value.id !== authoritySpendPeriodId(value.accountId, value.period)
+    || !revision(value.spentMicroUsd) || !revision(value.answers) || !revision(value.unpricedAnswers)
+    || (value.unpricedAnswers as number) > (value.answers as number)
+    || (value.answers === 0) !== (value.lastAnswerAt === null)
+    || (value.lastAnswerAt !== null && (!iso(value.lastAnswerAt)
+      || authSwitchSpendPeriod(Date.parse(value.lastAnswerAt)).key !== value.period))
+    || !revision(value.revision) || !uuid(value.updateId)) {
+    throw new Error('Invalid authority spend period.');
+  }
+};
+
 export const assertStoredAuthorityMeta: (value: unknown) => asserts value is IStoredAuthorityMeta = value => {
   if (!object(value) || !exactKeys(value, ['id', 'epoch', 'revision', 'updateId'])
     || value.id !== 'authswitch-authority' || !uuid(value.epoch)
@@ -622,7 +727,8 @@ export const assertStoredAuthorityMeta: (value: unknown) => asserts value is ISt
 
 export const assertStoredAuthorityAccount: (value: unknown) => asserts value is IStoredAuthorityAccount = value => {
   if (!object(value) || !exactKeys(value, ['id', 'providerId', 'issuer', 'subject', 'workspaceId', 'label',
-    'email', 'plan', 'primaryGrantId', 'maxUsagePercent', 'reserveLiftUntil', 'lapsesAt', 'removed', 'revision', 'statusObservedAt', 'updateId'])
+    'email', 'plan', 'primaryGrantId', 'maxUsagePercent', 'reserveLiftUntil', 'lapsesAt', 'spendLimitMicroUsd', 'keyHint',
+    'removed', 'revision', 'statusObservedAt', 'updateId'])
     || !hash(value.id) || typeof value.providerId !== 'string'
     || !/^[a-z][a-z0-9-]{0,63}$/.test(value.providerId)
     || !bounded(value.issuer) || !bounded(value.subject) || !bounded(value.workspaceId)
@@ -632,6 +738,8 @@ export const assertStoredAuthorityAccount: (value: unknown) => asserts value is
     || (value.maxUsagePercent !== null && !isAuthSwitchMaxUsagePercent(value.maxUsagePercent))
     || (value.reserveLiftUntil !== null && !iso(value.reserveLiftUntil))
     || (value.lapsesAt !== null && (!iso(value.lapsesAt) || !isAuthSwitchLapsesAt(value.lapsesAt)))
+    || (value.spendLimitMicroUsd !== null && !isAuthSwitchSpendLimitMicroUsd(value.spendLimitMicroUsd))
+    || (value.keyHint !== null && !isAuthSwitchKeyHint(value.keyHint))
     || typeof value.removed !== 'boolean' || !revision(value.revision)
     || !iso(value.statusObservedAt) || !uuid(value.updateId)) throw new Error('Invalid authswitch account record.');
 };
@@ -642,8 +750,8 @@ export const assertStoredAuthorityGrant: (value: unknown) => asserts value is IS
     'accessExpiresAt', 'attemptId', 'retryAt', 'retryCount', 'problem', 'statusObservedAt', 'updateId'])
     || !hash(value.id) || !hash(value.accountId)
     || typeof value.providerId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(value.providerId)
-    || !['openai_managed', 'claude_host_native', 'claude_container_setup', 'opencode_native', 'anthropic_api_key']
-      .includes(String(value.purpose))
+    || !['openai_managed', 'claude_host_native', 'claude_container_setup', 'opencode_native', 'anthropic_api_key',
+      'openai_api_key'].includes(String(value.purpose))
     || !bounded(value.audience)
     || !['ready', 'exchange_may_have_been_sent', 'retry_wait', 'needs_reauth', 'native', 'legacy_native_pending', 'handoff_pending', 'handoff_quarantined', 'removed'].includes(String(value.state))
     || !['daemon', 'claude_native', 'codex_native', 'legacy_native', 'none'].includes(String(value.owner))
@@ -682,10 +790,11 @@ export const assertStoredAuthorityGrant: (value: unknown) => asserts value is IS
   if (value.purpose === 'claude_container_setup' && value.owner !== 'daemon' && value.owner !== 'none') {
     throw new Error('Container setup grant has a native owner.');
   }
-  // An Anthropic API key is the authority's alone: no native tool holds or renews it.
-  if (value.purpose === 'anthropic_api_key' && (value.providerId !== 'anthropic'
-    || (value.owner !== 'daemon' && value.owner !== 'none'))) {
-    throw new Error('Anthropic API key grant has incompatible custody.');
+  // An API key is the authority's alone: no native tool holds or renews it.
+  if ((value.purpose === 'anthropic_api_key' || value.purpose === 'openai_api_key')
+    && (value.providerId !== authorityApiKeyProvider(value.purpose)
+      || (value.owner !== 'daemon' && value.owner !== 'none'))) {
+    throw new Error('API key grant has incompatible custody.');
   }
 };
 
@@ -1189,6 +1298,8 @@ export class AuthSwitchAuthorityAccountModel extends plugins.nosqldb.SmartDataDb
   @plugins.nosqldb.svDb() public maxUsagePercent!: number | null;
   @plugins.nosqldb.svDb() public reserveLiftUntil!: string | null;
   @plugins.nosqldb.svDb() public lapsesAt!: string | null;
+  @plugins.nosqldb.svDb() public spendLimitMicroUsd!: number | null;
+  @plugins.nosqldb.svDb() public keyHint!: string | null;
   @plugins.nosqldb.svDb() public removed!: boolean;
   @plugins.nosqldb.svDb() public revision!: number;
   @plugins.nosqldb.svDb() public statusObservedAt!: string;
@@ -1259,6 +1370,41 @@ export class AuthSwitchAuthorityUsageEstimateModel extends plugins.nosqldb.Smart
   @plugins.nosqldb.svDb() public observation!: IAuthSwitchStoredUsageEstimate['observation'];
 }
 
+@plugins.nosqldb.compoundIndex({ name: 'authority_spend_entry_account_period', key: { accountId: 1, period: 1, id: 1 } })
+@plugins.nosqldb.managed({ collectionName: 'authswitch_authority_spend_entries' })
+@plugins.nosqldb.exactPersistence({ assertDocument: assertStoredAuthoritySpendEntry })
+export class AuthSwitchAuthoritySpendEntryModel extends plugins.nosqldb.SmartDataDbDoc<AuthSwitchAuthoritySpendEntryModel,
+  IStoredAuthoritySpendEntry> {
+  declare static exact: plugins.nosqldb.TExact<AuthSwitchAuthoritySpendEntryModel>;
+  @plugins.nosqldb.unI() public id!: string;
+  @plugins.nosqldb.svDb() public accountId!: string;
+  @plugins.nosqldb.svDb() public answerId!: string;
+  @plugins.nosqldb.svDb() public period!: string;
+  @plugins.nosqldb.svDb() public endedAt!: string;
+  @plugins.nosqldb.svDb() public model!: string;
+  @plugins.nosqldb.svDb() public serviceTier!: string | null;
+  @plugins.nosqldb.svDb() public microUsd!: number | null;
+  @plugins.nosqldb.svDb() public priceSource!: string | null;
+}
+
+@plugins.nosqldb.compoundIndex({ name: 'authority_spend_period_account_period', key: { accountId: 1, period: 1 },
+  options: { unique: true } })
+@plugins.nosqldb.managed({ collectionName: 'authswitch_authority_spend_periods' })
+@plugins.nosqldb.exactPersistence({ assertDocument: assertStoredAuthoritySpendPeriod })
+export class AuthSwitchAuthoritySpendPeriodModel extends plugins.nosqldb.SmartDataDbDoc<AuthSwitchAuthoritySpendPeriodModel,
+  IStoredAuthoritySpendPeriod> {
+  declare static exact: plugins.nosqldb.TExact<AuthSwitchAuthoritySpendPeriodModel>;
+  @plugins.nosqldb.unI() public id!: string;
+  @plugins.nosqldb.svDb() public accountId!: string;
+  @plugins.nosqldb.svDb() public period!: string;
+  @plugins.nosqldb.svDb() public spentMicroUsd!: number;
+  @plugins.nosqldb.svDb() public answers!: number;
+  @plugins.nosqldb.svDb() public unpricedAnswers!: number;
+  @plugins.nosqldb.svDb() public lastAnswerAt!: string | null;
+  @plugins.nosqldb.svDb() public revision!: number;
+  @plugins.nosqldb.svDb() public updateId!: string;
+}
+
 @plugins.nosqldb.compoundIndex({ name: 'authority_binding_account_id', key: { accountId: 1, id: 1 } })
 @plugins.nosqldb.managed({ collectionName: 'authswitch_authority_bindings' })
 @plugins.nosqldb.exactPersistence({ assertDocument: assertStoredAuthorityBinding })

package/ts_authswitch/classes.authorityregistry.ts

@@ -6,6 +6,7 @@ import {
   AuthSwitchAuthorityCodexHostHomeModel, AuthSwitchAuthorityEnrollmentModel,
   AuthSwitchAuthorityEventModel, AuthSwitchAuthorityGrantModel, AuthSwitchAuthorityHandoffModel,
   AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityMigrationLedgerModel, AuthSwitchAuthorityOperationModel,
+  AuthSwitchAuthoritySpendEntryModel, AuthSwitchAuthoritySpendPeriodModel,
   AuthSwitchAuthorityUsageEstimateModel, AuthSwitchAuthorityUsageModel,
 } from './classes.authoritymodels.js';
 
@@ -42,6 +43,8 @@ export const authorityModelRegistry: readonly IAuthorityModelEntry[] = Object.fr
   define('authswitch_authority_meta', AuthSwitchAuthorityMetaModel),
   define('authswitch_authority_migration_ledger', AuthSwitchAuthorityMigrationLedgerModel),
   define('authswitch_authority_operations', AuthSwitchAuthorityOperationModel),
+  define('authswitch_authority_spend_entries', AuthSwitchAuthoritySpendEntryModel),
+  define('authswitch_authority_spend_periods', AuthSwitchAuthoritySpendPeriodModel),
   define('authswitch_authority_usage', AuthSwitchAuthorityUsageModel),
   define('authswitch_authority_usage_estimates', AuthSwitchAuthorityUsageEstimateModel),
 ]);