@cortexkit/common-auth 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,282 @@
1
+ // The per-row quota map: what the pool knows about one row's limits.
2
+ //
3
+ // A row's quota is a set of keyed limits. Each key is a (scope, window label)
4
+ // pair: the scope is `all` for a limit that binds every request, or a model
5
+ // family name for a limit that binds only that family; the label names the
6
+ // window the provider reports (for example `primary` or `secondary`). Each key
7
+ // holds one entry, which is either a reading, a retirement tombstone (the key
8
+ // held a reading until an authoritative observation stopped reporting it), or
9
+ // an absence record (an authoritative observation reported the key as having
10
+ // no limit before any reading was seen). Tombstones and absence records are
11
+ // evidence that the key is known to be unlimited; a missing key is unknown.
12
+ //
13
+ // Beside the limits sits the credit budget, a third pressure axis with its own
14
+ // reset clock. It is a tri-state: absent (never reported), a reading, or
15
+ // cleared (the provider reported that no budget exists).
16
+ //
17
+ // Provider-named counters and the prepaid credits record sit beside them too,
18
+ // each judged by its own observation time rather than the limits'.
19
+ //
20
+ // The map is plain JSON so the store can persist it without interpreting it.
21
+
22
+ /** The scope of a limit that binds every request regardless of model. */
23
+ export const ALL_SCOPE = 'all'
24
+
25
+ /** The window label required when an admission call supplies none. */
26
+ export const DEFAULT_REQUIRED_LABELS: readonly string[] = Object.freeze([
27
+ 'primary',
28
+ ])
29
+
30
+ export interface QuotaReadingEntry {
31
+ scope: string
32
+ label: string
33
+ kind: 'reading'
34
+ checkedAt: number
35
+ usedPercent: number
36
+ /** ISO timestamp at which the window resets, as the provider reported it. */
37
+ resetsAt?: string
38
+ /** Window length in minutes, when the provider reported one. */
39
+ windowMinutes?: number
40
+ }
41
+
42
+ export interface QuotaRetiredEntry {
43
+ scope: string
44
+ label: string
45
+ kind: 'retired'
46
+ retiredAt: number
47
+ }
48
+
49
+ export interface QuotaAbsentEntry {
50
+ scope: string
51
+ label: string
52
+ kind: 'absent'
53
+ checkedAt: number
54
+ }
55
+
56
+ export type QuotaEntry =
57
+ | QuotaReadingEntry
58
+ | QuotaRetiredEntry
59
+ | QuotaAbsentEntry
60
+
61
+ export interface CreditBudgetReading {
62
+ kind: 'reading'
63
+ checkedAt: number
64
+ /** The provider's own verdict that the budget is spent. */
65
+ reached: boolean
66
+ remainingPercent?: number
67
+ usedPercent?: number
68
+ resetsAt?: string
69
+ limit?: number
70
+ used?: number
71
+ remaining?: number
72
+ unit?: string
73
+ }
74
+
75
+ export interface CreditBudgetCleared {
76
+ kind: 'cleared'
77
+ checkedAt: number
78
+ }
79
+
80
+ export type CreditBudgetEntry = CreditBudgetReading | CreditBudgetCleared
81
+
82
+ export interface QuotaCounter {
83
+ value: number
84
+ checkedAt: number
85
+ }
86
+
87
+ /**
88
+ * Prepaid credits a provider account holds beside its rate-limit windows (for
89
+ * example a ChatGPT workspace's credits, which keep requests working after a
90
+ * window is used up). This is a state, not a count or the spend budget: the
91
+ * account has credits or not, they may be unlimited, and the provider may
92
+ * report a balance. It carries its own observation time.
93
+ */
94
+ export interface QuotaCredits {
95
+ hasCredits: boolean
96
+ unlimited: boolean
97
+ /** The balance the provider reported, when it reported one. */
98
+ balance?: number
99
+ /** The provider's verdict that the overage allowance is used up. */
100
+ overageLimitReached?: boolean
101
+ checkedAt: number
102
+ }
103
+
104
+ export interface QuotaMap {
105
+ limits: QuotaEntry[]
106
+ /** Absent means no observation has reported on the budget yet. */
107
+ budget?: CreditBudgetEntry
108
+ /** Provider-named counts, each with its own observation time. */
109
+ counters?: Record<string, QuotaCounter>
110
+ /** Absent means no observation has reported on prepaid credits yet. */
111
+ credits?: QuotaCredits
112
+ }
113
+
114
+ export function emptyQuotaMap(): QuotaMap {
115
+ return { limits: [] }
116
+ }
117
+
118
+ /** The time an entry speaks for: its reading, retirement or absence time. */
119
+ export function entryTime(entry: QuotaEntry): number {
120
+ return entry.kind === 'retired' ? entry.retiredAt : entry.checkedAt
121
+ }
122
+
123
+ export function limitKey(scope: string, label: string): string {
124
+ // JSON-encoding the pair keeps keys unambiguous for any scope or label text.
125
+ return JSON.stringify([scope, label])
126
+ }
127
+
128
+ function isRecord(value: unknown): value is Record<string, unknown> {
129
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
130
+ }
131
+
132
+ function isFiniteNumber(value: unknown): value is number {
133
+ return typeof value === 'number' && Number.isFinite(value)
134
+ }
135
+
136
+ function isName(value: unknown): value is string {
137
+ return typeof value === 'string' && value.length > 0
138
+ }
139
+
140
+ function optional(
141
+ record: Record<string, unknown>,
142
+ key: string,
143
+ check: (value: unknown) => boolean,
144
+ ): boolean {
145
+ return record[key] === undefined || check(record[key])
146
+ }
147
+
148
+ function isPositiveFinite(value: unknown): boolean {
149
+ return isFiniteNumber(value) && value > 0
150
+ }
151
+
152
+ function isString(value: unknown): boolean {
153
+ return typeof value === 'string'
154
+ }
155
+
156
+ function isQuotaEntry(value: unknown): value is QuotaEntry {
157
+ if (!isRecord(value) || !isName(value.scope) || !isName(value.label)) {
158
+ return false
159
+ }
160
+ switch (value.kind) {
161
+ case 'reading':
162
+ return (
163
+ isFiniteNumber(value.checkedAt) &&
164
+ isFiniteNumber(value.usedPercent) &&
165
+ optional(value, 'resetsAt', isString) &&
166
+ optional(value, 'windowMinutes', isPositiveFinite)
167
+ )
168
+ case 'retired':
169
+ return isFiniteNumber(value.retiredAt)
170
+ case 'absent':
171
+ return isFiniteNumber(value.checkedAt)
172
+ default:
173
+ return false
174
+ }
175
+ }
176
+
177
+ export function isCreditBudgetEntry(
178
+ value: unknown,
179
+ ): value is CreditBudgetEntry {
180
+ if (!isRecord(value) || !isFiniteNumber(value.checkedAt)) return false
181
+ if (value.kind === 'cleared') return true
182
+ return (
183
+ value.kind === 'reading' &&
184
+ typeof value.reached === 'boolean' &&
185
+ optional(value, 'remainingPercent', isFiniteNumber) &&
186
+ optional(value, 'usedPercent', isFiniteNumber) &&
187
+ optional(value, 'resetsAt', isString) &&
188
+ optional(value, 'limit', isFiniteNumber) &&
189
+ optional(value, 'used', isFiniteNumber) &&
190
+ optional(value, 'remaining', isFiniteNumber) &&
191
+ optional(value, 'unit', isString)
192
+ )
193
+ }
194
+
195
+ function isQuotaCounter(value: unknown): value is QuotaCounter {
196
+ return (
197
+ isRecord(value) &&
198
+ isFiniteNumber(value.value) &&
199
+ Number.isInteger(value.value) &&
200
+ value.value >= 0 &&
201
+ isFiniteNumber(value.checkedAt)
202
+ )
203
+ }
204
+
205
+ export function isQuotaCounters(
206
+ value: unknown,
207
+ ): value is Record<string, QuotaCounter> {
208
+ return isRecord(value) && Object.values(value).every(isQuotaCounter)
209
+ }
210
+
211
+ function isBoolean(value: unknown): boolean {
212
+ return typeof value === 'boolean'
213
+ }
214
+
215
+ /** True when `value` is a well-formed prepaid-credits record. */
216
+ export function isQuotaCredits(value: unknown): value is QuotaCredits {
217
+ return (
218
+ isRecord(value) &&
219
+ typeof value.hasCredits === 'boolean' &&
220
+ typeof value.unlimited === 'boolean' &&
221
+ optional(value, 'balance', isFiniteNumber) &&
222
+ optional(value, 'overageLimitReached', isBoolean) &&
223
+ isFiniteNumber(value.checkedAt)
224
+ )
225
+ }
226
+
227
+ /** Keep usable counters without letting one malformed count hide a quota map. */
228
+ export function readQuotaCounters(
229
+ value: unknown,
230
+ ): Record<string, QuotaCounter> | undefined {
231
+ if (!isRecord(value)) return undefined
232
+ const entries = Object.entries(value).filter(([, entry]) =>
233
+ isQuotaCounter(entry),
234
+ )
235
+ return entries.length === 0
236
+ ? undefined
237
+ : (Object.fromEntries(entries) as Record<string, QuotaCounter>)
238
+ }
239
+
240
+ /**
241
+ * Decode persisted quota, dropping malformed counters or a malformed credits
242
+ * record but not limit or budget evidence.
243
+ */
244
+ export function decodeQuotaMap(value: unknown): QuotaMap | undefined {
245
+ // A valid map is returned as the same object, so stored quota keeps the
246
+ // identity it had before counters and credits existed. A map with a
247
+ // malformed counter or credits record is copied with those malformed
248
+ // fields left out.
249
+ if (isQuotaMap(value)) return value
250
+ if (!isRecord(value)) return undefined
251
+ const { counters: rawCounters, credits: rawCredits, ...rest } = value
252
+ if (!isQuotaMap(rest)) return undefined
253
+ const counters = readQuotaCounters(rawCounters)
254
+ const credits = isQuotaCredits(rawCredits) ? rawCredits : undefined
255
+ return {
256
+ ...rest,
257
+ ...(counters === undefined ? {} : { counters }),
258
+ ...(credits === undefined ? {} : { credits }),
259
+ }
260
+ }
261
+
262
+ /**
263
+ * True when `value` is a well-formed quota map. Unrecognised top-level keys
264
+ * are tolerated (and preserved by merge) so a newer writer's additions
265
+ * survive; a malformed entry, a duplicated (scope, label) key or a malformed
266
+ * budget makes the whole map invalid.
267
+ */
268
+ export function isQuotaMap(value: unknown): value is QuotaMap {
269
+ if (!isRecord(value) || !Array.isArray(value.limits)) return false
270
+ const seen = new Set<string>()
271
+ for (const entry of value.limits) {
272
+ if (!isQuotaEntry(entry)) return false
273
+ const key = limitKey(entry.scope, entry.label)
274
+ if (seen.has(key)) return false
275
+ seen.add(key)
276
+ }
277
+ return (
278
+ optional(value, 'budget', isCreditBudgetEntry) &&
279
+ optional(value, 'counters', isQuotaCounters) &&
280
+ optional(value, 'credits', isQuotaCredits)
281
+ )
282
+ }
@@ -0,0 +1,223 @@
1
+ // Projection of a keyed quota map onto one request scope.
2
+ //
3
+ // The selection primitives carried from openai-auth judge an account by a
4
+ // short list of windows; the keyed map can hold many (scope, label) keys. The
5
+ // projection resolves exactly one entry per window label for the request's
6
+ // scope, orders the result the way the primitives expect, and carries each
7
+ // entry's (scope, label) so a decision names the limit it judged rather than
8
+ // the position it occupied.
9
+
10
+ import {
11
+ ALL_SCOPE,
12
+ type CreditBudgetReading,
13
+ isQuotaCredits,
14
+ type QuotaCounter,
15
+ type QuotaCredits,
16
+ type QuotaEntry,
17
+ type QuotaMap,
18
+ readQuotaCounters,
19
+ } from './map.js'
20
+
21
+ export interface ProjectedLimit {
22
+ scope: string
23
+ label: string
24
+ kind: 'reading' | 'retired' | 'absent'
25
+ /** The reading, retirement or absence time. */
26
+ checkedAt: number
27
+ /** The stored window length; undefined when the provider reported none. */
28
+ windowMinutes?: number
29
+ /** Present on readings only. */
30
+ usedPercent?: number
31
+ /** Present on readings only: `100 - usedPercent`. */
32
+ remainingPercent?: number
33
+ resetsAt?: string
34
+ }
35
+
36
+ export interface ProjectedBudget {
37
+ checkedAt: number
38
+ reached: boolean
39
+ remainingPercent?: number
40
+ resetsAt?: string
41
+ }
42
+
43
+ /**
44
+ * A named group of windows, such as antigravity-auth's `Gemini` and
45
+ * `Other models`: every window stored under `scope` belongs to it, and
46
+ * `label` is the group's display name.
47
+ */
48
+ export interface QuotaGroup {
49
+ scope: string
50
+ label: string
51
+ }
52
+
53
+ export interface ProjectedQuota {
54
+ scope: string
55
+ /** One entry per label: longest known window first, unknown lengths last. */
56
+ limits: readonly ProjectedLimit[]
57
+ /**
58
+ * The oldest reading time among the limits (or, with no reading, the oldest
59
+ * evidence time), so a projection is only as fresh as its stalest limit.
60
+ */
61
+ checkedAt?: number
62
+ /** Present only when the stored budget is a reading, not cleared. */
63
+ budget?: ProjectedBudget
64
+ counters?: Record<string, QuotaCounter>
65
+ /** The stored prepaid credits, unchanged in every scope. */
66
+ credits?: QuotaCredits
67
+ /**
68
+ * The named groups the windows belong to, in the order the plugin lists
69
+ * them. Set only by a plugin whose windows all belong to such groups; the
70
+ * narrow form then shows one item per group (see `formatQuota`).
71
+ * `projectQuota` never sets it.
72
+ */
73
+ groups?: readonly QuotaGroup[]
74
+ }
75
+
76
+ function project(entry: QuotaEntry): ProjectedLimit {
77
+ if (entry.kind === 'retired') {
78
+ return {
79
+ scope: entry.scope,
80
+ label: entry.label,
81
+ kind: 'retired',
82
+ checkedAt: entry.retiredAt,
83
+ }
84
+ }
85
+ if (entry.kind === 'absent') {
86
+ return {
87
+ scope: entry.scope,
88
+ label: entry.label,
89
+ kind: 'absent',
90
+ checkedAt: entry.checkedAt,
91
+ }
92
+ }
93
+ return {
94
+ scope: entry.scope,
95
+ label: entry.label,
96
+ kind: 'reading',
97
+ checkedAt: entry.checkedAt,
98
+ usedPercent: entry.usedPercent,
99
+ remainingPercent: 100 - entry.usedPercent,
100
+ ...(entry.windowMinutes === undefined
101
+ ? {}
102
+ : { windowMinutes: entry.windowMinutes }),
103
+ ...(entry.resetsAt === undefined ? {} : { resetsAt: entry.resetsAt }),
104
+ }
105
+ }
106
+
107
+ function compareLimits(left: ProjectedLimit, right: ProjectedLimit): number {
108
+ const leftKnown = left.windowMinutes !== undefined
109
+ const rightKnown = right.windowMinutes !== undefined
110
+ if (leftKnown !== rightKnown) return leftKnown ? -1 : 1
111
+ if (leftKnown && rightKnown && left.windowMinutes !== right.windowMinutes) {
112
+ return (right.windowMinutes ?? 0) - (left.windowMinutes ?? 0)
113
+ }
114
+ if (left.label !== right.label) return left.label < right.label ? -1 : 1
115
+ return 0
116
+ }
117
+
118
+ function projectBudget(budget: CreditBudgetReading): ProjectedBudget {
119
+ return {
120
+ checkedAt: budget.checkedAt,
121
+ reached: budget.reached,
122
+ ...(budget.remainingPercent === undefined
123
+ ? {}
124
+ : { remainingPercent: budget.remainingPercent }),
125
+ ...(budget.resetsAt === undefined ? {} : { resetsAt: budget.resetsAt }),
126
+ }
127
+ }
128
+
129
+ /**
130
+ * Resolves `map` for a request in `scope` (`all` or a model family). A family
131
+ * request sees only its own family's keys and the `all` keys.
132
+ *
133
+ * The label decides how a family limit relates to a general one. Under the
134
+ * same label, the family reading replaces the `all` reading: use this only
135
+ * when the provider's family figure is a more specific view of the same cap.
136
+ * Under different labels both limits are projected and every consumer judges
137
+ * both, so a family cap that applies on top of a general cap must be stored
138
+ * under its own label; otherwise the general cap is hidden from a family
139
+ * request. A family tombstone or absence record says only that no
140
+ * family-specific limit exists, so it does not hide an `all` entry for the
141
+ * same label and is used only when there is none.
142
+ */
143
+ export function projectQuota(
144
+ map: QuotaMap | undefined,
145
+ scope: string = ALL_SCOPE,
146
+ ): ProjectedQuota {
147
+ const byLabel = new Map<string, QuotaEntry>()
148
+ for (const entry of map?.limits ?? []) {
149
+ if (entry.scope !== scope && entry.scope !== ALL_SCOPE) continue
150
+ const current = byLabel.get(entry.label)
151
+ if (current === undefined) {
152
+ byLabel.set(entry.label, entry)
153
+ continue
154
+ }
155
+ const family = entry.scope === ALL_SCOPE ? current : entry
156
+ const general = entry.scope === ALL_SCOPE ? entry : current
157
+ byLabel.set(entry.label, family.kind === 'reading' ? family : general)
158
+ }
159
+ const limits = [...byLabel.values()].map(project).sort(compareLimits)
160
+ const readings = limits.filter((limit) => limit.kind === 'reading')
161
+ const stamped = readings.length > 0 ? readings : limits
162
+ const checkedAt =
163
+ stamped.length > 0
164
+ ? Math.min(...stamped.map((limit) => limit.checkedAt))
165
+ : undefined
166
+ const budget =
167
+ map?.budget?.kind === 'reading' ? projectBudget(map.budget) : undefined
168
+ const counters = readQuotaCounters(map?.counters)
169
+ const credits = isQuotaCredits(map?.credits) ? map.credits : undefined
170
+ return {
171
+ scope,
172
+ limits,
173
+ ...(checkedAt === undefined ? {} : { checkedAt }),
174
+ ...(budget === undefined ? {} : { budget }),
175
+ ...(counters === undefined ? {} : { counters }),
176
+ ...(credits === undefined ? {} : { credits }),
177
+ }
178
+ }
179
+
180
+ export interface ExhaustionReset {
181
+ resetsAt: string
182
+ resetAtMs: number
183
+ }
184
+
185
+ /**
186
+ * The credit budget's own exhaustion signal. Admission and the sticky
187
+ * routing decision to move a session off its pinned row both use it, so the
188
+ * two agree on what "spent" means. `reached` is the provider's
189
+ * verdict (the percentage is only a display value), and the check fails open
190
+ * on a missing, unparsable or already-passed reset.
191
+ */
192
+ export function budgetExhaustedResetAt(
193
+ quota: Pick<ProjectedQuota, 'budget'> | null | undefined,
194
+ now: number,
195
+ ): ExhaustionReset | undefined {
196
+ const budget = quota?.budget
197
+ if (budget?.reached !== true || typeof budget.resetsAt !== 'string') {
198
+ return undefined
199
+ }
200
+ const resetAtMs = Date.parse(budget.resetsAt)
201
+ if (!Number.isFinite(resetAtMs) || resetAtMs <= now) return undefined
202
+ return { resetsAt: budget.resetsAt, resetAtMs }
203
+ }
204
+
205
+ /** True for a reading at or beyond its whole window. */
206
+ export function readsExhausted(limit: ProjectedLimit): boolean {
207
+ return (
208
+ limit.kind === 'reading' &&
209
+ typeof limit.usedPercent === 'number' &&
210
+ Number.isFinite(limit.usedPercent) &&
211
+ limit.usedPercent >= 100
212
+ )
213
+ }
214
+
215
+ /** The reset time of a limit when it parses and lies after `now`. */
216
+ export function futureResetAt(
217
+ limit: ProjectedLimit,
218
+ now: number,
219
+ ): number | undefined {
220
+ if (typeof limit.resetsAt !== 'string') return undefined
221
+ const resetAtMs = Date.parse(limit.resetsAt)
222
+ return Number.isFinite(resetAtMs) && resetAtMs > now ? resetAtMs : undefined
223
+ }