@starci/ai-router 0.2.1 → 0.4.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,197 @@
1
+ import type { MaybePromise, RouterCatalog } from "../types.js";
2
+ /** The limits of one virtual key; an absent field is no limit. Days and months are UTC. */
3
+ export interface KeyQuota {
4
+ readonly requestsPerMinute?: number;
5
+ /** Prompt plus completion tokens the provider reported. */
6
+ readonly tokensPerDay?: number;
7
+ /** Estimated cost, from usage and the model's configured cost; a model without a cost counts 0. */
8
+ readonly costPerDay?: number;
9
+ readonly costPerMonth?: number;
10
+ }
11
+ /** A virtual key as every surface shows it: its bindings and state, never its secret or hash. */
12
+ export interface VirtualKey {
13
+ /** The public id admin operations name it by (`key_<hex>`). */
14
+ readonly id: string;
15
+ readonly label: string;
16
+ readonly owner: string | null;
17
+ /** The key's prefix and last four characters, enough to recognise it: `sk-starci-<label>-...abcd`. */
18
+ readonly hint: string;
19
+ /** Profile names the key may call, or `*` for every profile. */
20
+ readonly profiles: readonly string[];
21
+ /** Model ids or aliases the key may call directly, or `*` for every model. */
22
+ readonly models: readonly string[];
23
+ /** False pins every call to the profile's or the named model; no fallback model is tried. */
24
+ readonly allowFallback: boolean;
25
+ readonly quota: KeyQuota;
26
+ readonly enabled: boolean;
27
+ /** Epoch milliseconds. */
28
+ readonly createdAt: number;
29
+ readonly rotatedAt: number | null;
30
+ readonly revokedAt: number | null;
31
+ /** True for a key mounted from a secret the app holds (`GatewayOptions.mountedKeys`): read only, never in the store. Absent otherwise. */
32
+ readonly mounted?: true;
33
+ }
34
+ /** A virtual key as a store holds it: the public record plus the SHA-256 of its secret. */
35
+ export interface StoredKey extends VirtualKey {
36
+ readonly hash: string;
37
+ }
38
+ /** What a new key is bound to. */
39
+ export interface KeySpec {
40
+ /** Lowercase letters, digits and underscores, 1 to 32 characters; it becomes part of the secret. */
41
+ readonly label: string;
42
+ readonly owner?: string;
43
+ readonly profiles?: readonly string[];
44
+ readonly models?: readonly string[];
45
+ /** Default true. */
46
+ readonly allowFallback?: boolean;
47
+ readonly quota?: KeyQuota;
48
+ /** Default true. */
49
+ readonly enabled?: boolean;
50
+ }
51
+ /**
52
+ * A key mounted from a secret the app already holds: the gateway keeps its hash and bindings in memory and never
53
+ * writes it to the store. The secret is `sk-starci-<label>-` and at least 32 more letters, digits, `_` or `-`; the key
54
+ * changes by changing the secret (or the bindings) and redeploying.
55
+ */
56
+ export interface MountedKeySpec extends KeySpec {
57
+ /** The secret, or a function read once at startup; only its SHA-256 is kept. */
58
+ readonly secret: string | (() => string);
59
+ }
60
+ /** The bindings of a key an update may change; the label and the secret stay. */
61
+ export type KeyPatch = Omit<KeySpec, "label">;
62
+ /** One settled request of a key: how it ended and what it consumed. No prompt, no end-user identifier. */
63
+ export interface UsageDelta {
64
+ /** `success`, `error:<class>` for a pool failure, `rejected:<reason>` for a request the gateway refused. */
65
+ readonly outcome: string;
66
+ readonly promptTokens: number;
67
+ readonly completionTokens: number;
68
+ readonly cost: number;
69
+ readonly latencyMs: number;
70
+ }
71
+ /** A key's usage over one UTC day. */
72
+ export interface UsageRow {
73
+ readonly keyId: string;
74
+ /** `YYYY-MM-DD`. */
75
+ readonly day: string;
76
+ readonly requests: number;
77
+ readonly succeeded: number;
78
+ readonly failed: number;
79
+ readonly promptTokens: number;
80
+ readonly completionTokens: number;
81
+ readonly cost: number;
82
+ /** The sum of every request's latency; divide by `requests` for the mean. */
83
+ readonly latencyMs: number;
84
+ readonly outcomes: Readonly<Record<string, number>>;
85
+ }
86
+ /**
87
+ * Where virtual keys and their usage live. The in-memory store is the default; `openSqliteKeyStore` is the durable
88
+ * one, and an adapter over another database implements the same methods (the SQLite schema is its reference).
89
+ */
90
+ export interface KeyStore {
91
+ /** Inserts or replaces a key by id. */
92
+ put(key: StoredKey): MaybePromise<void>;
93
+ get(id: string): MaybePromise<StoredKey | undefined>;
94
+ byHash(hash: string): MaybePromise<StoredKey | undefined>;
95
+ list(): MaybePromise<readonly StoredKey[]>;
96
+ /** Counts one request in the key's minute (epoch minutes) and returns the minute's count; a new minute starts at 1. Atomic. */
97
+ hit(id: string, minute: number): MaybePromise<number>;
98
+ /** Adds one settled request to the key's day. Atomic. */
99
+ record(id: string, day: string, delta: UsageDelta): MaybePromise<void>;
100
+ /** The key's days from `from` to `to`, both inclusive, oldest first. */
101
+ usage(id: string, from: string, to: string): MaybePromise<readonly UsageRow[]>;
102
+ close?(): MaybePromise<void>;
103
+ }
104
+ /** Adds a request to a day row; the stores share it so a row means the same everywhere. */
105
+ export declare function addToRow(row: UsageRow | undefined, keyId: string, day: string, delta: UsageDelta): UsageRow;
106
+ /** The default key store: one process's memory, lost on restart. */
107
+ export declare class MemoryKeyStore implements KeyStore {
108
+ #private;
109
+ /** Inserts or replaces a key. */
110
+ put(key: StoredKey): void;
111
+ /** Reads a key by id. */
112
+ get(id: string): StoredKey | undefined;
113
+ /** Reads a key by the hash of its secret. */
114
+ byHash(hash: string): StoredKey | undefined;
115
+ /** Lists every key. */
116
+ list(): readonly StoredKey[];
117
+ /** Counts a request in the key's minute. */
118
+ hit(id: string, minute: number): number;
119
+ /** Adds a settled request to the key's day. */
120
+ record(id: string, day: string, delta: UsageDelta): void;
121
+ /** The key's day rows in a range. */
122
+ usage(id: string, from: string, to: string): readonly UsageRow[];
123
+ }
124
+ /** Why an admin operation was refused: an unknown id, an invalid spec, a change to a revoked key, or a change to a mounted key. */
125
+ export declare class KeyAdminError extends Error {
126
+ readonly code: "not_found" | "invalid" | "revoked" | "mounted";
127
+ /** Builds the error. */
128
+ constructor(code: KeyAdminError["code"], message: string);
129
+ }
130
+ /**
131
+ * Why the gateway refused to start over its mounted keys: an invalid key, a label given twice, or a secret or id a
132
+ * stored key already holds. It names the label and the key id, never the secret.
133
+ */
134
+ export declare class MountedKeyError extends Error {
135
+ readonly code: "invalid" | "duplicate_label" | "collision";
136
+ /** The label of the mounted key refused. */
137
+ readonly label: string;
138
+ /** Builds the error. */
139
+ constructor(code: MountedKeyError["code"], label: string, message: string);
140
+ }
141
+ /** A newly issued or rotated key: the record, and the secret shown this once. */
142
+ export interface IssuedKey {
143
+ readonly key: VirtualKey;
144
+ readonly secret: string;
145
+ }
146
+ /** A key's usage over a range of days, with the totals of the range. */
147
+ export interface KeyUsage {
148
+ readonly key: VirtualKey;
149
+ readonly from: string;
150
+ readonly to: string;
151
+ readonly rows: readonly UsageRow[];
152
+ readonly totals: Omit<UsageRow, "keyId" | "day">;
153
+ }
154
+ /** The SHA-256 hex of a secret: what a store keeps instead of it. Keys are 192 random bits, so a fast hash is enough. */
155
+ export declare function hashSecret(secret: string): string;
156
+ /** The UTC day of an epoch time, `YYYY-MM-DD`. */
157
+ export declare function dayOf(time: number): string;
158
+ /** The id of a mounted key: stable per label, so its quota and usage carry over secret changes and deploys. */
159
+ export declare function mountedKeyId(label: string): string;
160
+ /** The public view of a stored key. */
161
+ export declare function publicKey(key: StoredKey): VirtualKey;
162
+ /** What a `KeyAdmin` is built with. */
163
+ export interface KeyAdminOptions {
164
+ /** With a catalog, a key may only name the pool's profiles and models. */
165
+ readonly catalog?: RouterCatalog;
166
+ readonly clock?: () => number;
167
+ /** Keys mounted from secrets the app holds, resolved in memory and never written to the store. */
168
+ readonly mounted?: readonly MountedKeySpec[];
169
+ }
170
+ /** Issues, lists, revokes, rotates and updates virtual keys over a store, and reports their usage; mounted keys are listed and read only. */
171
+ export declare class KeyAdmin {
172
+ #private;
173
+ readonly store: KeyStore;
174
+ /** Binds the admin to a store and resolves the mounted keys; an invalid or duplicated mounted key throws a `MountedKeyError`. */
175
+ constructor(store: KeyStore, options?: KeyAdminOptions);
176
+ /** Refuses a mounted key whose secret or id a stored key already holds; the gateway awaits it before it serves. */
177
+ checkMounted(): Promise<void>;
178
+ /** Issues a key; the secret is returned now and never again. */
179
+ create(spec: KeySpec): Promise<IssuedKey>;
180
+ /** Lists every key, mounted and stored, oldest first. */
181
+ list(): Promise<VirtualKey[]>;
182
+ /** Reads one key. */
183
+ get(id: string): Promise<VirtualKey>;
184
+ /** Revokes a key for good: its secret answers 401 from now on. Revoking twice is a no-op. */
185
+ revoke(id: string): Promise<VirtualKey>;
186
+ /** Replaces a key's secret, keeping its id, bindings and usage; the old secret answers 401 from now on. */
187
+ rotate(id: string): Promise<IssuedKey>;
188
+ /** Changes a key's bindings; a field left out keeps its value. */
189
+ update(id: string, patch: KeyPatch): Promise<VirtualKey>;
190
+ /** A key's usage per UTC day from `from` to `to` (default: the current month), with the totals. */
191
+ usage(id: string, range?: {
192
+ readonly from?: string;
193
+ readonly to?: string;
194
+ }): Promise<KeyUsage>;
195
+ /** The mounted or stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
196
+ authenticate(secret: string): Promise<StoredKey | undefined>;
197
+ }
@@ -0,0 +1,358 @@
1
+ import { createHash, randomBytes } from "node:crypto";
2
+ /** Adds a request to a day row; the stores share it so a row means the same everywhere. */
3
+ export function addToRow(row, keyId, day, delta) {
4
+ const success = delta.outcome === "success";
5
+ return {
6
+ keyId,
7
+ day,
8
+ requests: (row?.requests ?? 0) + 1,
9
+ succeeded: (row?.succeeded ?? 0) + (success ? 1 : 0),
10
+ failed: (row?.failed ?? 0) + (success ? 0 : 1),
11
+ promptTokens: (row?.promptTokens ?? 0) + delta.promptTokens,
12
+ completionTokens: (row?.completionTokens ?? 0) + delta.completionTokens,
13
+ cost: (row?.cost ?? 0) + delta.cost,
14
+ latencyMs: (row?.latencyMs ?? 0) + delta.latencyMs,
15
+ outcomes: { ...row?.outcomes, [delta.outcome]: (row?.outcomes[delta.outcome] ?? 0) + 1 },
16
+ };
17
+ }
18
+ /** The default key store: one process's memory, lost on restart. */
19
+ export class MemoryKeyStore {
20
+ #keys = new Map();
21
+ #rate = new Map();
22
+ #usage = new Map();
23
+ /** Inserts or replaces a key. */
24
+ put(key) {
25
+ this.#keys.set(key.id, key);
26
+ }
27
+ /** Reads a key by id. */
28
+ get(id) {
29
+ return this.#keys.get(id);
30
+ }
31
+ /** Reads a key by the hash of its secret. */
32
+ byHash(hash) {
33
+ for (const key of this.#keys.values())
34
+ if (key.hash === hash)
35
+ return key;
36
+ return undefined;
37
+ }
38
+ /** Lists every key. */
39
+ list() {
40
+ return [...this.#keys.values()];
41
+ }
42
+ /** Counts a request in the key's minute. */
43
+ hit(id, minute) {
44
+ const held = this.#rate.get(id);
45
+ const count = held?.minute === minute ? held.count + 1 : 1;
46
+ this.#rate.set(id, { minute, count });
47
+ return count;
48
+ }
49
+ /** Adds a settled request to the key's day. */
50
+ record(id, day, delta) {
51
+ const name = `${id}/${day}`;
52
+ this.#usage.set(name, addToRow(this.#usage.get(name), id, day, delta));
53
+ }
54
+ /** The key's day rows in a range. */
55
+ usage(id, from, to) {
56
+ return [...this.#usage.values()].filter((row) => row.keyId === id && row.day >= from && row.day <= to).sort((a, b) => a.day.localeCompare(b.day));
57
+ }
58
+ }
59
+ /** Why an admin operation was refused: an unknown id, an invalid spec, a change to a revoked key, or a change to a mounted key. */
60
+ export class KeyAdminError extends Error {
61
+ code;
62
+ /** Builds the error. */
63
+ constructor(code, message) {
64
+ super(message);
65
+ this.name = "KeyAdminError";
66
+ this.code = code;
67
+ }
68
+ }
69
+ /**
70
+ * Why the gateway refused to start over its mounted keys: an invalid key, a label given twice, or a secret or id a
71
+ * stored key already holds. It names the label and the key id, never the secret.
72
+ */
73
+ export class MountedKeyError extends Error {
74
+ code;
75
+ /** The label of the mounted key refused. */
76
+ label;
77
+ /** Builds the error. */
78
+ constructor(code, label, message) {
79
+ super(message);
80
+ this.name = "MountedKeyError";
81
+ this.code = code;
82
+ this.label = label;
83
+ }
84
+ }
85
+ const LABEL = /^[a-z0-9_]{1,32}$/;
86
+ const DAY = /^\d{4}-\d{2}-\d{2}$/;
87
+ /** The SHA-256 hex of a secret: what a store keeps instead of it. Keys are 192 random bits, so a fast hash is enough. */
88
+ export function hashSecret(secret) {
89
+ return createHash("sha256").update(secret, "utf8").digest("hex");
90
+ }
91
+ /** The UTC day of an epoch time, `YYYY-MM-DD`. */
92
+ export function dayOf(time) {
93
+ return new Date(time).toISOString().slice(0, 10);
94
+ }
95
+ /** The id of a mounted key: stable per label, so its quota and usage carry over secret changes and deploys. */
96
+ export function mountedKeyId(label) {
97
+ return `key_${hashSecret(`mounted:${label}`).slice(0, 16)}`;
98
+ }
99
+ /** The public view of a stored key. */
100
+ export function publicKey(key) {
101
+ return {
102
+ ...(key.mounted === true ? { mounted: true } : {}),
103
+ id: key.id,
104
+ label: key.label,
105
+ owner: key.owner,
106
+ hint: key.hint,
107
+ profiles: key.profiles,
108
+ models: key.models,
109
+ allowFallback: key.allowFallback,
110
+ quota: key.quota,
111
+ enabled: key.enabled,
112
+ createdAt: key.createdAt,
113
+ rotatedAt: key.rotatedAt,
114
+ revokedAt: key.revokedAt,
115
+ };
116
+ }
117
+ function invalid(message) {
118
+ return new KeyAdminError("invalid", message);
119
+ }
120
+ function names(value, field, known) {
121
+ // A spec arrives as JSON from the admin API, so its types are checked, not trusted.
122
+ const raw = value ?? [];
123
+ if (!Array.isArray(raw))
124
+ throw invalid(`${field} must be a list of names`);
125
+ const list = raw.filter((name) => typeof name === "string" && name !== "");
126
+ if (list.length !== raw.length)
127
+ throw invalid(`${field} must be a list of names`);
128
+ for (const name of list) {
129
+ if (name !== "*" && known !== null && !known.has(name))
130
+ throw invalid(`${field} names "${name}", which the pool does not serve`);
131
+ }
132
+ return [...new Set(list)];
133
+ }
134
+ function quotaOf(value) {
135
+ const quota = value ?? {};
136
+ const out = {};
137
+ for (const [field, integer] of [
138
+ ["requestsPerMinute", true],
139
+ ["tokensPerDay", true],
140
+ ["costPerDay", false],
141
+ ["costPerMonth", false],
142
+ ]) {
143
+ const limit = quota[field];
144
+ if (limit === undefined)
145
+ continue;
146
+ if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0 || (integer && !Number.isInteger(limit))) {
147
+ throw invalid(`quota.${field} must be a positive ${integer ? "integer" : "number"}`);
148
+ }
149
+ out[field] = limit;
150
+ }
151
+ const unknown = Object.keys(quota).filter((field) => !(field in out) && quota[field] !== undefined);
152
+ if (unknown.length > 0)
153
+ throw invalid(`quota has unknown fields: ${unknown.join(", ")}`);
154
+ return out;
155
+ }
156
+ function bool(value, field, fallback) {
157
+ if (value === undefined)
158
+ return fallback;
159
+ if (typeof value !== "boolean")
160
+ throw invalid(`${field} must be true or false`);
161
+ return value;
162
+ }
163
+ /** Reads a mounted key's secret once and checks its shape; a refusal names the label, never the value. */
164
+ function mountedSecret(spec, label) {
165
+ let secret;
166
+ try {
167
+ secret = typeof spec.secret === "function" ? spec.secret() : spec.secret;
168
+ }
169
+ catch {
170
+ // The reader's own failure may quote what it read, so it is not carried.
171
+ throw new MountedKeyError("invalid", label, `the secret of mounted key "${label}" could not be read`);
172
+ }
173
+ const prefix = `sk-starci-${label}-`;
174
+ if (typeof secret !== "string" || !secret.startsWith(prefix))
175
+ throw new MountedKeyError("invalid", label, `the secret of mounted key "${label}" must start with ${prefix}`);
176
+ if (!/^[A-Za-z0-9_-]{32,}$/.test(secret.slice(prefix.length))) {
177
+ throw new MountedKeyError("invalid", label, `the secret of mounted key "${label}" needs at least 32 letters, digits, "_" or "-" after ${prefix}`);
178
+ }
179
+ return secret;
180
+ }
181
+ /** Issues, lists, revokes, rotates and updates virtual keys over a store, and reports their usage; mounted keys are listed and read only. */
182
+ export class KeyAdmin {
183
+ store;
184
+ #clock;
185
+ #profiles;
186
+ #models;
187
+ /** The mounted keys by the hash of their secret, and by id; the secret itself is not kept. */
188
+ #mountedByHash = new Map();
189
+ #mountedById = new Map();
190
+ /** Binds the admin to a store and resolves the mounted keys; an invalid or duplicated mounted key throws a `MountedKeyError`. */
191
+ constructor(store, options = {}) {
192
+ this.store = store;
193
+ this.#clock = options.clock ?? Date.now;
194
+ const catalog = options.catalog;
195
+ this.#profiles = catalog === undefined ? null : new Set(catalog.profiles.map((profile) => profile.name));
196
+ this.#models = catalog === undefined ? null : new Set(catalog.models.flatMap((model) => [model.id, ...model.aliases]));
197
+ const now = this.#clock();
198
+ for (const spec of options.mounted ?? []) {
199
+ // Mounted keys may arrive from config, so their types are checked, not trusted.
200
+ const label = spec.label;
201
+ if (typeof label !== "string" || !LABEL.test(label))
202
+ throw new MountedKeyError("invalid", String(label), "a mounted key's label must be 1 to 32 lowercase letters, digits or underscores");
203
+ const id = mountedKeyId(label);
204
+ if (this.#mountedById.has(id))
205
+ throw new MountedKeyError("duplicate_label", label, `the mounted key label "${label}" is given twice`);
206
+ const secret = mountedSecret(spec, label);
207
+ let bindings;
208
+ try {
209
+ bindings = this.#bindings(spec, null);
210
+ }
211
+ catch (error) {
212
+ throw new MountedKeyError("invalid", label, `mounted key "${label}": ${error instanceof Error ? error.message : "invalid bindings"}`);
213
+ }
214
+ const key = {
215
+ id,
216
+ label,
217
+ hint: `sk-starci-${label}-...${secret.slice(-4)}`,
218
+ ...bindings,
219
+ createdAt: now,
220
+ rotatedAt: null,
221
+ revokedAt: null,
222
+ mounted: true,
223
+ hash: hashSecret(secret),
224
+ };
225
+ this.#mountedByHash.set(key.hash, key);
226
+ this.#mountedById.set(id, key);
227
+ }
228
+ }
229
+ /** Refuses a mounted key whose secret or id a stored key already holds; the gateway awaits it before it serves. */
230
+ async checkMounted() {
231
+ for (const key of this.#mountedById.values()) {
232
+ const byHash = await this.store.byHash(key.hash);
233
+ if (byHash !== undefined)
234
+ throw new MountedKeyError("collision", key.label, `the secret of mounted key "${key.label}" (${key.id}) is also the secret of stored key ${byHash.id}`);
235
+ if ((await this.store.get(key.id)) !== undefined)
236
+ throw new MountedKeyError("collision", key.label, `mounted key "${key.label}" has id ${key.id}, which a stored key already holds`);
237
+ }
238
+ }
239
+ #issue(label) {
240
+ const secret = `sk-starci-${label}-${randomBytes(24).toString("hex")}`;
241
+ return { secret, hash: hashSecret(secret), hint: `sk-starci-${label}-...${secret.slice(-4)}` };
242
+ }
243
+ #bindings(spec, base) {
244
+ const owner = spec.owner ?? base?.owner ?? null;
245
+ if (owner !== null && (typeof owner !== "string" || owner.length > 200))
246
+ throw invalid("owner must be a string of at most 200 characters");
247
+ const profiles = spec.profiles === undefined && base !== null ? base.profiles : names(spec.profiles, "profiles", this.#profiles);
248
+ const models = spec.models === undefined && base !== null ? base.models : names(spec.models, "models", this.#models);
249
+ if (profiles.length === 0 && models.length === 0)
250
+ throw invalid("a key needs at least one profile or model it may call");
251
+ return {
252
+ owner,
253
+ profiles,
254
+ models,
255
+ allowFallback: bool(spec.allowFallback, "allowFallback", base?.allowFallback ?? true),
256
+ quota: spec.quota === undefined && base !== null ? base.quota : quotaOf(spec.quota),
257
+ enabled: bool(spec.enabled, "enabled", base?.enabled ?? true),
258
+ };
259
+ }
260
+ async #find(id) {
261
+ const key = this.#mountedById.get(id) ?? (await this.store.get(id));
262
+ if (key === undefined)
263
+ throw new KeyAdminError("not_found", `no key has id "${id}"`);
264
+ return key;
265
+ }
266
+ /** A key an admin change may touch: a mounted key is refused. */
267
+ async #changeable(id) {
268
+ const key = await this.#find(id);
269
+ if (key.mounted === true)
270
+ throw new KeyAdminError("mounted", `key "${id}" is mounted from a secret the app holds: it changes by changing that secret and redeploying`);
271
+ return key;
272
+ }
273
+ /** Issues a key; the secret is returned now and never again. */
274
+ async create(spec) {
275
+ if (typeof spec.label !== "string" || !LABEL.test(spec.label))
276
+ throw invalid("label must be 1 to 32 lowercase letters, digits or underscores");
277
+ const issued = this.#issue(spec.label);
278
+ const key = {
279
+ id: `key_${randomBytes(8).toString("hex")}`,
280
+ label: spec.label,
281
+ hint: issued.hint,
282
+ ...this.#bindings(spec, null),
283
+ createdAt: this.#clock(),
284
+ rotatedAt: null,
285
+ revokedAt: null,
286
+ hash: issued.hash,
287
+ };
288
+ await this.store.put(key);
289
+ return { key: publicKey(key), secret: issued.secret };
290
+ }
291
+ /** Lists every key, mounted and stored, oldest first. */
292
+ async list() {
293
+ return [...this.#mountedById.values(), ...(await this.store.list())].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)).map(publicKey);
294
+ }
295
+ /** Reads one key. */
296
+ async get(id) {
297
+ return publicKey(await this.#find(id));
298
+ }
299
+ /** Revokes a key for good: its secret answers 401 from now on. Revoking twice is a no-op. */
300
+ async revoke(id) {
301
+ const key = await this.#changeable(id);
302
+ if (key.revokedAt !== null)
303
+ return publicKey(key);
304
+ const revoked = { ...key, enabled: false, revokedAt: this.#clock() };
305
+ await this.store.put(revoked);
306
+ return publicKey(revoked);
307
+ }
308
+ /** Replaces a key's secret, keeping its id, bindings and usage; the old secret answers 401 from now on. */
309
+ async rotate(id) {
310
+ const key = await this.#changeable(id);
311
+ if (key.revokedAt !== null)
312
+ throw new KeyAdminError("revoked", `key "${id}" is revoked`);
313
+ const issued = this.#issue(key.label);
314
+ const rotated = { ...key, hash: issued.hash, hint: issued.hint, rotatedAt: this.#clock() };
315
+ await this.store.put(rotated);
316
+ return { key: publicKey(rotated), secret: issued.secret };
317
+ }
318
+ /** Changes a key's bindings; a field left out keeps its value. */
319
+ async update(id, patch) {
320
+ const key = await this.#changeable(id);
321
+ if (key.revokedAt !== null)
322
+ throw new KeyAdminError("revoked", `key "${id}" is revoked`);
323
+ const updated = { ...key, ...this.#bindings(patch, key) };
324
+ await this.store.put(updated);
325
+ return publicKey(updated);
326
+ }
327
+ /** A key's usage per UTC day from `from` to `to` (default: the current month), with the totals. */
328
+ async usage(id, range = {}) {
329
+ const key = await this.#find(id);
330
+ const today = dayOf(this.#clock());
331
+ const from = range.from ?? `${today.slice(0, 8)}01`;
332
+ const to = range.to ?? today;
333
+ if (!DAY.test(from) || !DAY.test(to))
334
+ throw invalid("from and to must be days, YYYY-MM-DD");
335
+ const rows = await this.store.usage(id, from, to);
336
+ const outcomes = {};
337
+ const totals = { requests: 0, succeeded: 0, failed: 0, promptTokens: 0, completionTokens: 0, cost: 0, latencyMs: 0 };
338
+ for (const row of rows) {
339
+ totals.requests += row.requests;
340
+ totals.succeeded += row.succeeded;
341
+ totals.failed += row.failed;
342
+ totals.promptTokens += row.promptTokens;
343
+ totals.completionTokens += row.completionTokens;
344
+ totals.cost += row.cost;
345
+ totals.latencyMs += row.latencyMs;
346
+ for (const [outcome, count] of Object.entries(row.outcomes))
347
+ outcomes[outcome] = (outcomes[outcome] ?? 0) + count;
348
+ }
349
+ return { key: publicKey(key), from, to, rows, totals: { ...totals, outcomes } };
350
+ }
351
+ /** The mounted or stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
352
+ async authenticate(secret) {
353
+ if (!secret.startsWith("sk-starci-"))
354
+ return undefined;
355
+ const hash = hashSecret(secret);
356
+ return this.#mountedByHash.get(hash) ?? this.store.byHash(hash);
357
+ }
358
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,14 @@
1
+ /** The process entry of the gateway and its key commands: `node <package>/dist/gateway/run.js <command>`; it stops on SIGINT and SIGTERM. */
2
+ import { main } from "./cli.js";
3
+ const stop = new AbortController();
4
+ for (const signal of ["SIGINT", "SIGTERM"]) {
5
+ process.once(signal, () => {
6
+ stop.abort();
7
+ });
8
+ }
9
+ process.exitCode = await main(process.argv.slice(2), {
10
+ out: (text) => process.stdout.write(text),
11
+ err: (text) => process.stderr.write(text),
12
+ env: process.env,
13
+ signal: stop.signal,
14
+ });
@@ -0,0 +1,25 @@
1
+ import type { FetchLike } from "../types.js";
2
+ import type { KeyStoreConfig } from "./config-file.js";
3
+ import type { AiRouterGateway } from "./gateway.js";
4
+ import type { KeyStore } from "./keys.js";
5
+ /** Opens the key store a config file names. */
6
+ export declare function openKeyStore(config: KeyStoreConfig): Promise<KeyStore>;
7
+ /** What `serveGateway` takes: the config file, and overrides of its address (and, for tests, of `fetch`). */
8
+ export interface ServeOptions {
9
+ readonly config: string;
10
+ readonly port?: number;
11
+ readonly host?: string;
12
+ readonly fetch?: FetchLike;
13
+ /** Where secret references are read from. Default `process.env`. */
14
+ readonly env?: NodeJS.ProcessEnv;
15
+ readonly onError?: (error: unknown) => void;
16
+ }
17
+ /** A running gateway process: the gateway, where it listens, and how to stop it. */
18
+ export interface ServingGateway {
19
+ readonly gateway: AiRouterGateway;
20
+ readonly url: string;
21
+ /** Stops listening and closes the key store. */
22
+ close(): Promise<void>;
23
+ }
24
+ /** Loads a config file, builds the router and the key store, and listens: the whole `ai-router serve`. */
25
+ export declare function serveGateway(options: ServeOptions): Promise<ServingGateway>;
@@ -0,0 +1,38 @@
1
+ import { createRouter } from "../router.js";
2
+ import { loadGatewayConfig, readSecret } from "./config-file.js";
3
+ import { createGateway } from "./gateway.js";
4
+ import { MemoryKeyStore } from "./keys.js";
5
+ import { openSqliteKeyStore } from "./sqlite-key-store.js";
6
+ /** Opens the key store a config file names. */
7
+ export async function openKeyStore(config) {
8
+ return config.type === "sqlite" ? openSqliteKeyStore(config.path) : new MemoryKeyStore();
9
+ }
10
+ /** Loads a config file, builds the router and the key store, and listens: the whole `ai-router serve`. */
11
+ export async function serveGateway(options) {
12
+ const file = await loadGatewayConfig(options.config);
13
+ const router = createRouter(options.fetch === undefined ? file.pool : { ...file.pool, fetch: options.fetch });
14
+ const keys = await openKeyStore(file.gateway.keyStore);
15
+ const admin = file.gateway.adminToken;
16
+ const gateway = createGateway(router, {
17
+ keys,
18
+ maxBodyBytes: file.gateway.maxBodyBytes,
19
+ ...(admin === null ? {} : { adminToken: () => readSecret(admin, options.env) }),
20
+ ...(options.onError === undefined ? {} : { onError: options.onError }),
21
+ });
22
+ try {
23
+ const address = await gateway.listen(options.port ?? file.gateway.port, options.host ?? file.gateway.host);
24
+ return {
25
+ gateway,
26
+ url: address.url,
27
+ async close() {
28
+ await gateway.close();
29
+ await keys.close?.();
30
+ },
31
+ };
32
+ }
33
+ catch (error) {
34
+ await gateway.close();
35
+ await keys.close?.();
36
+ throw error;
37
+ }
38
+ }
@@ -0,0 +1,8 @@
1
+ import type { KeyStore } from "./keys.js";
2
+ /**
3
+ * The schema of the durable key store. It is plain SQL (SQLite here; the same tables carry over to Postgres with
4
+ * `BIGINT` times, `DOUBLE PRECISION` cost and `JSONB` lists), so an adapter for another database starts from it.
5
+ */
6
+ export declare const KEY_STORE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS ai_router_keys (\n id TEXT PRIMARY KEY,\n hash TEXT NOT NULL UNIQUE,\n label TEXT NOT NULL,\n owner TEXT,\n hint TEXT NOT NULL,\n profiles TEXT NOT NULL,\n models TEXT NOT NULL,\n allow_fallback INTEGER NOT NULL,\n quota TEXT NOT NULL,\n enabled INTEGER NOT NULL,\n created_at INTEGER NOT NULL,\n rotated_at INTEGER,\n revoked_at INTEGER\n);\nCREATE TABLE IF NOT EXISTS ai_router_key_rate (\n key_id TEXT PRIMARY KEY,\n minute INTEGER NOT NULL,\n count INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS ai_router_key_usage (\n key_id TEXT NOT NULL,\n day TEXT NOT NULL,\n requests INTEGER NOT NULL,\n succeeded INTEGER NOT NULL,\n failed INTEGER NOT NULL,\n prompt_tokens INTEGER NOT NULL,\n completion_tokens INTEGER NOT NULL,\n cost REAL NOT NULL,\n latency_ms INTEGER NOT NULL,\n outcomes TEXT NOT NULL,\n PRIMARY KEY (key_id, day)\n);\n";
7
+ /** Opens (and creates) the durable key store at a SQLite file path; `:memory:` gives a throwaway database. */
8
+ export declare function openSqliteKeyStore(path: string): Promise<KeyStore>;