@starci/ai-router 0.3.0 → 0.4.1
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.
- package/CHANGELOG.md +10 -0
- package/README.md +35 -1
- package/dist/ai-router-gateway.module.js +12 -1
- package/dist/gateway/gateway.d.ts +14 -1
- package/dist/gateway/gateway.js +9 -1
- package/dist/gateway/index.d.ts +2 -2
- package/dist/gateway/index.js +1 -1
- package/dist/gateway/keys.d.ts +41 -10
- package/dist/gateway/keys.js +102 -12
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.4.1 - 2026-10-30
|
|
4
|
+
|
|
5
|
+
- Changed: the lint configuration is TypeScript (eslint.config.ts, loaded through jiti 2.7.0, an exact devDependency) and typechecked with the package; no runtime change.
|
|
6
|
+
|
|
7
|
+
## 0.4.0 - 2026-10-30
|
|
8
|
+
|
|
9
|
+
- Added: mounted keys, `GatewayOptions.mountedKeys` (and so `AiRouterGatewayModule`'s options): virtual keys from secrets the app already holds (`{ label, secret: string | (() => string), owner?, profiles?, models?, allowFallback?, quota?, enabled? }`, the `MountedKeySpec` type), so a deploy needs no `keys create`. Each secret is read once at startup, must start with `sk-starci-<label>-` followed by at least 32 letters, digits, `_` or `-`, and is kept only as its SHA-256 with its bindings in memory; a mounted key is never written to the key store. A bearer token is matched against the mounted keys before the store. Each mounted key has the stable id `key_` + 16 hex of `sha256("mounted:<label>")`, so its quota counters and usage rows survive a new secret and every deploy.
|
|
10
|
+
- Added: `MountedKeyError` (`code` `invalid`, `duplicate_label` or `collision`, and the `label`), naming the label and key id, never the secret. An invalid mounted key or a label given twice throws from `createGateway`; a secret or id a stored key already holds rejects the new `gateway.ready()`, which `listen`, `handle` and `AiRouterGatewayModule` (whose gateway provider is now async) await, so the app refuses to start.
|
|
11
|
+
- Added: `VirtualKey.mounted` (`true` on a mounted key, absent otherwise); `KeyAdmin.list` and `get` show mounted keys, and `revoke`, `rotate` and `update` refuse one with the new `KeyAdminError` code `mounted`, which the admin API answers 409 `key_mounted`. `KeyAdmin`'s options are the exported `KeyAdminOptions` (`catalog`, `clock`, `mounted`).
|
|
12
|
+
|
|
3
13
|
## 0.3.0 - 2026-10-28
|
|
4
14
|
|
|
5
15
|
- Added: an OpenAI-compatible HTTP gateway over the same router (`createGateway(router, options)`): `POST /v1/chat/completions` (SSE streaming in OpenAI's chunk format, ending with `[DONE]`), `POST /v1/embeddings`, `GET /v1/models` (the profiles and pool models the calling key may use), `GET /health`, and OpenAI error objects with 400, 401, 403, 404, 413, 429 (with `Retry-After`), 502, 503 and 504. A request's `model` names a profile or a pool model id or alias.
|
package/README.md
CHANGED
|
@@ -141,6 +141,40 @@ Keys live in a key store. `{ type: memory }` loses them on restart; `{ type: sql
|
|
|
141
141
|
interface; `KEY_STORE_SCHEMA` is the reference schema (it carries over to Postgres with `BIGINT` times,
|
|
142
142
|
`DOUBLE PRECISION` cost and `JSONB` lists).
|
|
143
143
|
|
|
144
|
+
### Mounted keys
|
|
145
|
+
|
|
146
|
+
An app that already holds a key's secret (an env variable, a mounted secret file) mounts it with `mountedKeys`, so a
|
|
147
|
+
deploy needs no `keys create`. A mounted key is never written to the store: the gateway reads each secret once at
|
|
148
|
+
startup, keeps only its SHA-256 and bindings in memory, and authenticates a bearer token against the mounted keys before
|
|
149
|
+
the store.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
AiRouterGatewayModule.registerAsync({
|
|
153
|
+
useFactory: async () => ({
|
|
154
|
+
keys: await openSqliteKeyStore("/data/keys.sqlite"),
|
|
155
|
+
mountedKeys: [
|
|
156
|
+
// The secret is sk-starci-<label>- and at least 32 letters, digits, "_" or "-": openssl rand -hex 24
|
|
157
|
+
{ label: "nivo_lite", secret: () => readFileSync("/run/secrets/nivo_lite_ai_key", "utf8").trim(), profiles: ["lesson"], owner: "nivo-lite", quota: { costPerMonth: 20 } },
|
|
158
|
+
],
|
|
159
|
+
listen: true,
|
|
160
|
+
}),
|
|
161
|
+
})
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
| case | what happens |
|
|
165
|
+
|---|---|
|
|
166
|
+
| a request bears the secret | it authenticates as the mounted key, with its bindings and quota |
|
|
167
|
+
| the key's id | `key_` and 16 hex of `sha256("mounted:<label>")`: stable per label, so its quota counters and usage rows carry over a new secret and every deploy |
|
|
168
|
+
| a new secret for the label, or new bindings | change it and redeploy; the old secret answers 401 |
|
|
169
|
+
| `GET /admin/keys`, `GET /admin/keys/{id}`, usage | listed and read like a stored key, with `mounted: true` |
|
|
170
|
+
| revoke, rotate or update (`PATCH`) | refused, 409 `key_mounted` (`KeyAdminError` code `mounted`): it changes by changing the secret and redeploying |
|
|
171
|
+
| a secret not starting with `sk-starci-<label>-`, too short after it, or a function that throws | `createGateway` throws `MountedKeyError` (`invalid`); the Nest module fails at init |
|
|
172
|
+
| a label given twice | `MountedKeyError` (`duplicate_label`) |
|
|
173
|
+
| a stored key holds the same secret or the same id | `ready()` rejects with `MountedKeyError` (`collision`); `listen`, `handle` and the Nest module wait for `ready()`, so the app refuses to start |
|
|
174
|
+
|
|
175
|
+
A refusal names the label and key id, never the secret, and drops the cause of a secret function that threw (its
|
|
176
|
+
message may quote what it read). The key's `hint` shows the last four characters, as for every key.
|
|
177
|
+
|
|
144
178
|
### Admin API
|
|
145
179
|
|
|
146
180
|
Guarded by `Authorization: Bearer <admin token>` (403 `admin_disabled` when no token is configured).
|
|
@@ -148,7 +182,7 @@ Guarded by `Authorization: Bearer <admin token>` (403 `admin_disabled` when no t
|
|
|
148
182
|
| route | does |
|
|
149
183
|
|---|---|
|
|
150
184
|
| `POST /admin/keys` | create from a key spec; 201 `{ key, secret }` |
|
|
151
|
-
| `GET /admin/keys` | list (never a secret or hash) |
|
|
185
|
+
| `GET /admin/keys` | list (never a secret or hash), mounted keys with `mounted: true` |
|
|
152
186
|
| `GET /admin/keys/{id}`, `PATCH /admin/keys/{id}` | read, or change bindings (`owner`, `profiles`, `models`, `allowFallback`, `quota`, `enabled`) |
|
|
153
187
|
| `POST /admin/keys/{id}/revoke` | revoke for good |
|
|
154
188
|
| `POST /admin/keys/{id}/rotate` | new secret, same id, bindings and usage; 200 `{ key, secret }` |
|
|
@@ -21,7 +21,18 @@ function withGateway(base, name) {
|
|
|
21
21
|
{
|
|
22
22
|
provide: token,
|
|
23
23
|
inject: [getAiRouterToken(name), MODULE_OPTIONS_TOKEN],
|
|
24
|
-
|
|
24
|
+
// The mounted keys are checked against the store here, so a refused key fails the app at init.
|
|
25
|
+
useFactory: async (router, options) => {
|
|
26
|
+
const gateway = createGateway(router, options);
|
|
27
|
+
try {
|
|
28
|
+
await gateway.ready();
|
|
29
|
+
}
|
|
30
|
+
catch (error) {
|
|
31
|
+
await gateway.close();
|
|
32
|
+
throw error;
|
|
33
|
+
}
|
|
34
|
+
return gateway;
|
|
35
|
+
},
|
|
25
36
|
},
|
|
26
37
|
{
|
|
27
38
|
// Nest calls the lifecycle hooks of every provider instance that has them.
|
|
@@ -1,11 +1,19 @@
|
|
|
1
1
|
import type { IncomingMessage, ServerResponse } from "node:http";
|
|
2
2
|
import type { AiRouter, MaybePromise } from "../types.js";
|
|
3
3
|
import { KeyAdmin } from "./keys.js";
|
|
4
|
-
import type { KeyStore } from "./keys.js";
|
|
4
|
+
import type { KeyStore, MountedKeySpec } from "./keys.js";
|
|
5
5
|
/** How a gateway is built over a router. */
|
|
6
6
|
export interface GatewayOptions {
|
|
7
7
|
/** Where virtual keys and their usage live. */
|
|
8
8
|
readonly keys: KeyStore;
|
|
9
|
+
/**
|
|
10
|
+
* Keys mounted from secrets the app already holds, so a deploy needs no `keys create`. Each secret is read once
|
|
11
|
+
* here, checked to start with `sk-starci-<label>-`, and kept only as its SHA-256; the key is never written to
|
|
12
|
+
* the store, has the stable id `key_<16 hex>` of its label (its quota and usage survive a new secret), lists with
|
|
13
|
+
* `mounted: true`, and refuses revoke, rotate and update. An invalid key or a label given twice throws a
|
|
14
|
+
* `MountedKeyError` here; a secret or id a stored key holds rejects `ready()`.
|
|
15
|
+
*/
|
|
16
|
+
readonly mountedKeys?: readonly MountedKeySpec[];
|
|
9
17
|
/** Returns the admin token at each admin request; absent, or an empty answer, turns the admin API off. */
|
|
10
18
|
readonly adminToken?: () => MaybePromise<string | undefined>;
|
|
11
19
|
/** The largest request body read, in bytes. Default 4 MiB. */
|
|
@@ -19,6 +27,11 @@ export interface GatewayOptions {
|
|
|
19
27
|
export interface AiRouterGateway {
|
|
20
28
|
/** The key administration the admin API and the CLI share. */
|
|
21
29
|
readonly admin: KeyAdmin;
|
|
30
|
+
/**
|
|
31
|
+
* Resolves once the mounted keys are checked against the store, and rejects with a `MountedKeyError` when a stored
|
|
32
|
+
* key holds a mounted key's secret or id. `listen`, `handle` and the Nest module wait for it.
|
|
33
|
+
*/
|
|
34
|
+
ready(): Promise<void>;
|
|
22
35
|
/** Answers one HTTP request; mount it on any Node HTTP server or framework (a body a framework parsed is used as is). */
|
|
23
36
|
handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
|
|
24
37
|
/** Listens on a port (0: any free port) and resolves to the bound address. */
|
package/dist/gateway/gateway.js
CHANGED
|
@@ -130,7 +130,10 @@ function write(response, text) {
|
|
|
130
130
|
export function createGateway(router, options) {
|
|
131
131
|
const clock = options.clock ?? Date.now;
|
|
132
132
|
const catalog = router.catalog();
|
|
133
|
-
const admin = new KeyAdmin(options.keys, { catalog, clock });
|
|
133
|
+
const admin = new KeyAdmin(options.keys, { catalog, clock, ...(options.mountedKeys === undefined ? {} : { mounted: options.mountedKeys }) });
|
|
134
|
+
const checked = admin.checkMounted();
|
|
135
|
+
// A refusal surfaces through ready(), listen() and handle(); it must not also be an unhandled rejection.
|
|
136
|
+
checked.catch(() => undefined);
|
|
134
137
|
const maxBody = options.maxBodyBytes ?? DEFAULT_MAX_BODY;
|
|
135
138
|
const servers = new Set();
|
|
136
139
|
// A stream's usage reaches the gateway through the attempt event of its request id.
|
|
@@ -385,6 +388,8 @@ export function createGateway(router, options) {
|
|
|
385
388
|
return new GatewayError(404, "key_not_found", error.message);
|
|
386
389
|
if (error.code === "revoked")
|
|
387
390
|
return new GatewayError(409, "key_revoked", error.message);
|
|
391
|
+
if (error.code === "mounted")
|
|
392
|
+
return new GatewayError(409, "key_mounted", error.message);
|
|
388
393
|
return new GatewayError(400, "invalid_key_spec", error.message);
|
|
389
394
|
}
|
|
390
395
|
async function adminApi(request, response, path, url) {
|
|
@@ -478,6 +483,7 @@ export function createGateway(router, options) {
|
|
|
478
483
|
}
|
|
479
484
|
async function handle(request, response) {
|
|
480
485
|
try {
|
|
486
|
+
await checked;
|
|
481
487
|
await route(request, response);
|
|
482
488
|
}
|
|
483
489
|
catch (error) {
|
|
@@ -496,8 +502,10 @@ export function createGateway(router, options) {
|
|
|
496
502
|
}
|
|
497
503
|
return {
|
|
498
504
|
admin,
|
|
505
|
+
ready: () => checked,
|
|
499
506
|
handle,
|
|
500
507
|
async listen(port, host = "127.0.0.1") {
|
|
508
|
+
await checked;
|
|
501
509
|
const server = createServer((request, response) => {
|
|
502
510
|
void handle(request, response);
|
|
503
511
|
});
|
package/dist/gateway/index.d.ts
CHANGED
|
@@ -7,8 +7,8 @@ export { loadGatewayConfig, parseGatewayConfig } from "./config-file.js";
|
|
|
7
7
|
export type { GatewayFileConfig, GatewaySettings, KeyStoreConfig, SecretRef } from "./config-file.js";
|
|
8
8
|
export { createGateway } from "./gateway.js";
|
|
9
9
|
export type { AiRouterGateway, GatewayOptions } from "./gateway.js";
|
|
10
|
-
export { KeyAdmin, KeyAdminError, MemoryKeyStore } from "./keys.js";
|
|
11
|
-
export type { IssuedKey, KeyPatch, KeyQuota, KeySpec, KeyStore, KeyUsage, StoredKey, UsageDelta, UsageRow, VirtualKey } from "./keys.js";
|
|
10
|
+
export { KeyAdmin, KeyAdminError, MemoryKeyStore, MountedKeyError } from "./keys.js";
|
|
11
|
+
export type { IssuedKey, KeyAdminOptions, KeyPatch, KeyQuota, KeySpec, KeyStore, KeyUsage, MountedKeySpec, StoredKey, UsageDelta, UsageRow, VirtualKey } from "./keys.js";
|
|
12
12
|
export { openKeyStore, serveGateway } from "./serve.js";
|
|
13
13
|
export type { ServeOptions, ServingGateway } from "./serve.js";
|
|
14
14
|
export { KEY_STORE_SCHEMA, openSqliteKeyStore } from "./sqlite-key-store.js";
|
package/dist/gateway/index.js
CHANGED
|
@@ -2,6 +2,6 @@ export { AiRouterError } from "../errors.js";
|
|
|
2
2
|
export { createRouter } from "../router.js";
|
|
3
3
|
export { loadGatewayConfig, parseGatewayConfig } from "./config-file.js";
|
|
4
4
|
export { createGateway } from "./gateway.js";
|
|
5
|
-
export { KeyAdmin, KeyAdminError, MemoryKeyStore } from "./keys.js";
|
|
5
|
+
export { KeyAdmin, KeyAdminError, MemoryKeyStore, MountedKeyError } from "./keys.js";
|
|
6
6
|
export { openKeyStore, serveGateway } from "./serve.js";
|
|
7
7
|
export { KEY_STORE_SCHEMA, openSqliteKeyStore } from "./sqlite-key-store.js";
|
package/dist/gateway/keys.d.ts
CHANGED
|
@@ -28,6 +28,8 @@ export interface VirtualKey {
|
|
|
28
28
|
readonly createdAt: number;
|
|
29
29
|
readonly rotatedAt: number | null;
|
|
30
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;
|
|
31
33
|
}
|
|
32
34
|
/** A virtual key as a store holds it: the public record plus the SHA-256 of its secret. */
|
|
33
35
|
export interface StoredKey extends VirtualKey {
|
|
@@ -46,6 +48,15 @@ export interface KeySpec {
|
|
|
46
48
|
/** Default true. */
|
|
47
49
|
readonly enabled?: boolean;
|
|
48
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
|
+
}
|
|
49
60
|
/** The bindings of a key an update may change; the label and the secret stay. */
|
|
50
61
|
export type KeyPatch = Omit<KeySpec, "label">;
|
|
51
62
|
/** One settled request of a key: how it ended and what it consumed. No prompt, no end-user identifier. */
|
|
@@ -110,12 +121,23 @@ export declare class MemoryKeyStore implements KeyStore {
|
|
|
110
121
|
/** The key's day rows in a range. */
|
|
111
122
|
usage(id: string, from: string, to: string): readonly UsageRow[];
|
|
112
123
|
}
|
|
113
|
-
/** Why an admin operation was refused: an unknown id, an invalid spec, or a change to a
|
|
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. */
|
|
114
125
|
export declare class KeyAdminError extends Error {
|
|
115
|
-
readonly code: "not_found" | "invalid" | "revoked";
|
|
126
|
+
readonly code: "not_found" | "invalid" | "revoked" | "mounted";
|
|
116
127
|
/** Builds the error. */
|
|
117
128
|
constructor(code: KeyAdminError["code"], message: string);
|
|
118
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
|
+
}
|
|
119
141
|
/** A newly issued or rotated key: the record, and the secret shown this once. */
|
|
120
142
|
export interface IssuedKey {
|
|
121
143
|
readonly key: VirtualKey;
|
|
@@ -133,20 +155,29 @@ export interface KeyUsage {
|
|
|
133
155
|
export declare function hashSecret(secret: string): string;
|
|
134
156
|
/** The UTC day of an epoch time, `YYYY-MM-DD`. */
|
|
135
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;
|
|
136
160
|
/** The public view of a stored key. */
|
|
137
161
|
export declare function publicKey(key: StoredKey): VirtualKey;
|
|
138
|
-
/**
|
|
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. */
|
|
139
171
|
export declare class KeyAdmin {
|
|
140
172
|
#private;
|
|
141
173
|
readonly store: KeyStore;
|
|
142
|
-
/** Binds the admin to a store
|
|
143
|
-
constructor(store: KeyStore, options?:
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
});
|
|
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>;
|
|
147
178
|
/** Issues a key; the secret is returned now and never again. */
|
|
148
179
|
create(spec: KeySpec): Promise<IssuedKey>;
|
|
149
|
-
/** Lists every key, oldest first. */
|
|
180
|
+
/** Lists every key, mounted and stored, oldest first. */
|
|
150
181
|
list(): Promise<VirtualKey[]>;
|
|
151
182
|
/** Reads one key. */
|
|
152
183
|
get(id: string): Promise<VirtualKey>;
|
|
@@ -161,6 +192,6 @@ export declare class KeyAdmin {
|
|
|
161
192
|
readonly from?: string;
|
|
162
193
|
readonly to?: string;
|
|
163
194
|
}): Promise<KeyUsage>;
|
|
164
|
-
/** The stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
|
|
195
|
+
/** The mounted or stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
|
|
165
196
|
authenticate(secret: string): Promise<StoredKey | undefined>;
|
|
166
197
|
}
|
package/dist/gateway/keys.js
CHANGED
|
@@ -56,7 +56,7 @@ export class MemoryKeyStore {
|
|
|
56
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
57
|
}
|
|
58
58
|
}
|
|
59
|
-
/** Why an admin operation was refused: an unknown id, an invalid spec, or a change to a
|
|
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
60
|
export class KeyAdminError extends Error {
|
|
61
61
|
code;
|
|
62
62
|
/** Builds the error. */
|
|
@@ -66,6 +66,22 @@ export class KeyAdminError extends Error {
|
|
|
66
66
|
this.code = code;
|
|
67
67
|
}
|
|
68
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
|
+
}
|
|
69
85
|
const LABEL = /^[a-z0-9_]{1,32}$/;
|
|
70
86
|
const DAY = /^\d{4}-\d{2}-\d{2}$/;
|
|
71
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. */
|
|
@@ -76,9 +92,14 @@ export function hashSecret(secret) {
|
|
|
76
92
|
export function dayOf(time) {
|
|
77
93
|
return new Date(time).toISOString().slice(0, 10);
|
|
78
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
|
+
}
|
|
79
99
|
/** The public view of a stored key. */
|
|
80
100
|
export function publicKey(key) {
|
|
81
101
|
return {
|
|
102
|
+
...(key.mounted === true ? { mounted: true } : {}),
|
|
82
103
|
id: key.id,
|
|
83
104
|
label: key.label,
|
|
84
105
|
owner: key.owner,
|
|
@@ -139,19 +160,81 @@ function bool(value, field, fallback) {
|
|
|
139
160
|
throw invalid(`${field} must be true or false`);
|
|
140
161
|
return value;
|
|
141
162
|
}
|
|
142
|
-
/**
|
|
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. */
|
|
143
182
|
export class KeyAdmin {
|
|
144
183
|
store;
|
|
145
184
|
#clock;
|
|
146
185
|
#profiles;
|
|
147
186
|
#models;
|
|
148
|
-
/**
|
|
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`. */
|
|
149
191
|
constructor(store, options = {}) {
|
|
150
192
|
this.store = store;
|
|
151
193
|
this.#clock = options.clock ?? Date.now;
|
|
152
194
|
const catalog = options.catalog;
|
|
153
195
|
this.#profiles = catalog === undefined ? null : new Set(catalog.profiles.map((profile) => profile.name));
|
|
154
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
|
+
}
|
|
155
238
|
}
|
|
156
239
|
#issue(label) {
|
|
157
240
|
const secret = `sk-starci-${label}-${randomBytes(24).toString("hex")}`;
|
|
@@ -175,11 +258,18 @@ export class KeyAdmin {
|
|
|
175
258
|
};
|
|
176
259
|
}
|
|
177
260
|
async #find(id) {
|
|
178
|
-
const key = await this.store.get(id);
|
|
261
|
+
const key = this.#mountedById.get(id) ?? (await this.store.get(id));
|
|
179
262
|
if (key === undefined)
|
|
180
263
|
throw new KeyAdminError("not_found", `no key has id "${id}"`);
|
|
181
264
|
return key;
|
|
182
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
|
+
}
|
|
183
273
|
/** Issues a key; the secret is returned now and never again. */
|
|
184
274
|
async create(spec) {
|
|
185
275
|
if (typeof spec.label !== "string" || !LABEL.test(spec.label))
|
|
@@ -198,10 +288,9 @@ export class KeyAdmin {
|
|
|
198
288
|
await this.store.put(key);
|
|
199
289
|
return { key: publicKey(key), secret: issued.secret };
|
|
200
290
|
}
|
|
201
|
-
/** Lists every key, oldest first. */
|
|
291
|
+
/** Lists every key, mounted and stored, oldest first. */
|
|
202
292
|
async list() {
|
|
203
|
-
|
|
204
|
-
return [...keys].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)).map(publicKey);
|
|
293
|
+
return [...this.#mountedById.values(), ...(await this.store.list())].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)).map(publicKey);
|
|
205
294
|
}
|
|
206
295
|
/** Reads one key. */
|
|
207
296
|
async get(id) {
|
|
@@ -209,7 +298,7 @@ export class KeyAdmin {
|
|
|
209
298
|
}
|
|
210
299
|
/** Revokes a key for good: its secret answers 401 from now on. Revoking twice is a no-op. */
|
|
211
300
|
async revoke(id) {
|
|
212
|
-
const key = await this.#
|
|
301
|
+
const key = await this.#changeable(id);
|
|
213
302
|
if (key.revokedAt !== null)
|
|
214
303
|
return publicKey(key);
|
|
215
304
|
const revoked = { ...key, enabled: false, revokedAt: this.#clock() };
|
|
@@ -218,7 +307,7 @@ export class KeyAdmin {
|
|
|
218
307
|
}
|
|
219
308
|
/** Replaces a key's secret, keeping its id, bindings and usage; the old secret answers 401 from now on. */
|
|
220
309
|
async rotate(id) {
|
|
221
|
-
const key = await this.#
|
|
310
|
+
const key = await this.#changeable(id);
|
|
222
311
|
if (key.revokedAt !== null)
|
|
223
312
|
throw new KeyAdminError("revoked", `key "${id}" is revoked`);
|
|
224
313
|
const issued = this.#issue(key.label);
|
|
@@ -228,7 +317,7 @@ export class KeyAdmin {
|
|
|
228
317
|
}
|
|
229
318
|
/** Changes a key's bindings; a field left out keeps its value. */
|
|
230
319
|
async update(id, patch) {
|
|
231
|
-
const key = await this.#
|
|
320
|
+
const key = await this.#changeable(id);
|
|
232
321
|
if (key.revokedAt !== null)
|
|
233
322
|
throw new KeyAdminError("revoked", `key "${id}" is revoked`);
|
|
234
323
|
const updated = { ...key, ...this.#bindings(patch, key) };
|
|
@@ -259,10 +348,11 @@ export class KeyAdmin {
|
|
|
259
348
|
}
|
|
260
349
|
return { key: publicKey(key), from, to, rows, totals: { ...totals, outcomes } };
|
|
261
350
|
}
|
|
262
|
-
/** The stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
|
|
351
|
+
/** The mounted or stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
|
|
263
352
|
async authenticate(secret) {
|
|
264
353
|
if (!secret.startsWith("sk-starci-"))
|
|
265
354
|
return undefined;
|
|
266
|
-
|
|
355
|
+
const hash = hashSecret(secret);
|
|
356
|
+
return this.#mountedByHash.get(hash) ?? this.store.byHash(hash);
|
|
267
357
|
}
|
|
268
358
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@starci/ai-router",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "A router for OpenAI-compatible calls across a pool of keys, models and providers: an OpenAI-compatible gateway with virtual keys, quotas and usage (the ai-router bin), a NestJS module (AiRouterModule, AiRouterService, AiRouterGatewayModule), and createRouter for plain Node, with health-aware selection, circuit breakers, rate-limit awareness, failover, model fallback and redacted telemetry.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai",
|
|
@@ -87,6 +87,7 @@
|
|
|
87
87
|
"@nestjs/testing": "12.1.3",
|
|
88
88
|
"@types/node": "24.19.2",
|
|
89
89
|
"eslint": "10.13.0",
|
|
90
|
+
"jiti": "2.7.0",
|
|
90
91
|
"reflect-metadata": "0.2.2",
|
|
91
92
|
"rxjs": "7.8.2",
|
|
92
93
|
"typescript": "5.9.3",
|