@openllmsh/sdk 2.10.19-alpha.2 → 2.10.19-alpha.3

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.
@@ -26842,6 +26842,31 @@
26842
26842
  }
26843
26843
  ]
26844
26844
  },
26845
+ "reset_epoch": {
26846
+ "anyOf": [
26847
+ {
26848
+ "type": "number"
26849
+ },
26850
+ {
26851
+ "type": "string",
26852
+ "enum": [
26853
+ "Infinity",
26854
+ "-Infinity",
26855
+ "NaN"
26856
+ ]
26857
+ }
26858
+ ]
26859
+ },
26860
+ "subject_id": {
26861
+ "anyOf": [
26862
+ {
26863
+ "type": "string"
26864
+ },
26865
+ {
26866
+ "type": "null"
26867
+ }
26868
+ ]
26869
+ },
26845
26870
  "unlock_sent": {
26846
26871
  "type": "boolean"
26847
26872
  },
@@ -26899,6 +26924,8 @@
26899
26924
  "failure_code",
26900
26925
  "vault_key_id",
26901
26926
  "key_id",
26927
+ "reset_epoch",
26928
+ "subject_id",
26902
26929
  "unlock_sent",
26903
26930
  "boot",
26904
26931
  "created_at",
@@ -26916,7 +26943,9 @@
26916
26943
  {
26917
26944
  "type": "string",
26918
26945
  "enum": [
26919
- "machine_gone"
26946
+ "machine_gone",
26947
+ "machine_moved",
26948
+ "no_machine_available"
26920
26949
  ]
26921
26950
  },
26922
26951
  {
@@ -27408,6 +27437,31 @@
27408
27437
  }
27409
27438
  ]
27410
27439
  },
27440
+ "reset_epoch": {
27441
+ "anyOf": [
27442
+ {
27443
+ "type": "number"
27444
+ },
27445
+ {
27446
+ "type": "string",
27447
+ "enum": [
27448
+ "Infinity",
27449
+ "-Infinity",
27450
+ "NaN"
27451
+ ]
27452
+ }
27453
+ ]
27454
+ },
27455
+ "subject_id": {
27456
+ "anyOf": [
27457
+ {
27458
+ "type": "string"
27459
+ },
27460
+ {
27461
+ "type": "null"
27462
+ }
27463
+ ]
27464
+ },
27411
27465
  "unlock_sent": {
27412
27466
  "type": "boolean"
27413
27467
  },
@@ -27465,6 +27519,8 @@
27465
27519
  "failure_code",
27466
27520
  "vault_key_id",
27467
27521
  "key_id",
27522
+ "reset_epoch",
27523
+ "subject_id",
27468
27524
  "unlock_sent",
27469
27525
  "boot",
27470
27526
  "created_at",
@@ -27482,7 +27538,9 @@
27482
27538
  {
27483
27539
  "type": "string",
27484
27540
  "enum": [
27485
- "machine_gone"
27541
+ "machine_gone",
27542
+ "machine_moved",
27543
+ "no_machine_available"
27486
27544
  ]
27487
27545
  },
27488
27546
  {
@@ -27580,6 +27638,31 @@
27580
27638
  }
27581
27639
  ]
27582
27640
  },
27641
+ "reset_epoch": {
27642
+ "anyOf": [
27643
+ {
27644
+ "type": "number"
27645
+ },
27646
+ {
27647
+ "type": "string",
27648
+ "enum": [
27649
+ "Infinity",
27650
+ "-Infinity",
27651
+ "NaN"
27652
+ ]
27653
+ }
27654
+ ]
27655
+ },
27656
+ "subject_id": {
27657
+ "anyOf": [
27658
+ {
27659
+ "type": "string"
27660
+ },
27661
+ {
27662
+ "type": "null"
27663
+ }
27664
+ ]
27665
+ },
27583
27666
  "unlock_sent": {
27584
27667
  "type": "boolean"
27585
27668
  },
@@ -27637,6 +27720,8 @@
27637
27720
  "failure_code",
27638
27721
  "vault_key_id",
27639
27722
  "key_id",
27723
+ "reset_epoch",
27724
+ "subject_id",
27640
27725
  "unlock_sent",
27641
27726
  "boot",
27642
27727
  "created_at",
@@ -27654,7 +27739,9 @@
27654
27739
  {
27655
27740
  "type": "string",
27656
27741
  "enum": [
27657
- "machine_gone"
27742
+ "machine_gone",
27743
+ "machine_moved",
27744
+ "no_machine_available"
27658
27745
  ]
27659
27746
  },
27660
27747
  {
@@ -28157,6 +28244,31 @@
28157
28244
  }
28158
28245
  ]
28159
28246
  },
28247
+ "reset_epoch": {
28248
+ "anyOf": [
28249
+ {
28250
+ "type": "number"
28251
+ },
28252
+ {
28253
+ "type": "string",
28254
+ "enum": [
28255
+ "Infinity",
28256
+ "-Infinity",
28257
+ "NaN"
28258
+ ]
28259
+ }
28260
+ ]
28261
+ },
28262
+ "subject_id": {
28263
+ "anyOf": [
28264
+ {
28265
+ "type": "string"
28266
+ },
28267
+ {
28268
+ "type": "null"
28269
+ }
28270
+ ]
28271
+ },
28160
28272
  "unlock_sent": {
28161
28273
  "type": "boolean"
28162
28274
  },
@@ -28214,6 +28326,8 @@
28214
28326
  "failure_code",
28215
28327
  "vault_key_id",
28216
28328
  "key_id",
28329
+ "reset_epoch",
28330
+ "subject_id",
28217
28331
  "unlock_sent",
28218
28332
  "boot",
28219
28333
  "created_at",
@@ -28231,7 +28345,9 @@
28231
28345
  {
28232
28346
  "type": "string",
28233
28347
  "enum": [
28234
- "machine_gone"
28348
+ "machine_gone",
28349
+ "machine_moved",
28350
+ "no_machine_available"
28235
28351
  ]
28236
28352
  },
28237
28353
  {
@@ -28734,6 +28850,31 @@
28734
28850
  }
28735
28851
  ]
28736
28852
  },
28853
+ "reset_epoch": {
28854
+ "anyOf": [
28855
+ {
28856
+ "type": "number"
28857
+ },
28858
+ {
28859
+ "type": "string",
28860
+ "enum": [
28861
+ "Infinity",
28862
+ "-Infinity",
28863
+ "NaN"
28864
+ ]
28865
+ }
28866
+ ]
28867
+ },
28868
+ "subject_id": {
28869
+ "anyOf": [
28870
+ {
28871
+ "type": "string"
28872
+ },
28873
+ {
28874
+ "type": "null"
28875
+ }
28876
+ ]
28877
+ },
28737
28878
  "unlock_sent": {
28738
28879
  "type": "boolean"
28739
28880
  },
@@ -28791,6 +28932,8 @@
28791
28932
  "failure_code",
28792
28933
  "vault_key_id",
28793
28934
  "key_id",
28935
+ "reset_epoch",
28936
+ "subject_id",
28794
28937
  "unlock_sent",
28795
28938
  "boot",
28796
28939
  "created_at",
@@ -28808,7 +28951,9 @@
28808
28951
  {
28809
28952
  "type": "string",
28810
28953
  "enum": [
28811
- "machine_gone"
28954
+ "machine_gone",
28955
+ "machine_moved",
28956
+ "no_machine_available"
28812
28957
  ]
28813
28958
  },
28814
28959
  {
@@ -29311,6 +29456,31 @@
29311
29456
  }
29312
29457
  ]
29313
29458
  },
29459
+ "reset_epoch": {
29460
+ "anyOf": [
29461
+ {
29462
+ "type": "number"
29463
+ },
29464
+ {
29465
+ "type": "string",
29466
+ "enum": [
29467
+ "Infinity",
29468
+ "-Infinity",
29469
+ "NaN"
29470
+ ]
29471
+ }
29472
+ ]
29473
+ },
29474
+ "subject_id": {
29475
+ "anyOf": [
29476
+ {
29477
+ "type": "string"
29478
+ },
29479
+ {
29480
+ "type": "null"
29481
+ }
29482
+ ]
29483
+ },
29314
29484
  "unlock_sent": {
29315
29485
  "type": "boolean"
29316
29486
  },
@@ -29368,6 +29538,8 @@
29368
29538
  "failure_code",
29369
29539
  "vault_key_id",
29370
29540
  "key_id",
29541
+ "reset_epoch",
29542
+ "subject_id",
29371
29543
  "unlock_sent",
29372
29544
  "boot",
29373
29545
  "created_at",
@@ -29385,7 +29557,9 @@
29385
29557
  {
29386
29558
  "type": "string",
29387
29559
  "enum": [
29388
- "machine_gone"
29560
+ "machine_gone",
29561
+ "machine_moved",
29562
+ "no_machine_available"
29389
29563
  ]
29390
29564
  },
29391
29565
  {
@@ -55,6 +55,13 @@ export type TMintedApiKey = {
55
55
  * 6. shows `sk-llm-{id}.{secret_b64url}` once.
56
56
  */
57
57
  export declare const mintApiKey: (dek: Uint8Array, vaultVersion: number) => Promise<TMintedApiKey>;
58
+ /**
59
+ * {@link mintApiKey} with a caller-chosen `(id, secret)` — for a key that must
60
+ * be re-derivable (the Routebox's, from the seed). The DEK wrap and the sealed
61
+ * copy still use random nonces, so the row differs per call but the `sk-llm`
62
+ * string is the same. Never zeroes `apiKeySecret`.
63
+ */
64
+ export declare const mintApiKeyFrom: (dek: Uint8Array, vaultVersion: number, apiKeyId: string, apiKeySecret: Uint8Array) => Promise<TMintedApiKey>;
58
65
  /** The secret columns of an `api_keys` row re-wrapped under a new DEK. */
59
66
  export type TRewrappedApiKey = {
60
67
  readonly dek_for_key: string;
@@ -71,9 +71,17 @@ const newApiKeyId = () => toB64Url(randomBytes(OPENLLM_API_KEY_ID_BYTES));
71
71
  * vault_version }` to `/api/keys`,
72
72
  * 6. shows `sk-llm-{id}.{secret_b64url}` once.
73
73
  */
74
- export const mintApiKey = async (dek, vaultVersion) => {
75
- const apiKeyId = newApiKeyId();
76
- const apiKeySecret = randomBytes(OPENLLM_API_KEY_SECRET_BYTES);
74
+ export const mintApiKey = (dek, vaultVersion) => mintApiKeyFrom(dek, vaultVersion, newApiKeyId(), randomBytes(OPENLLM_API_KEY_SECRET_BYTES));
75
+ /**
76
+ * {@link mintApiKey} with a caller-chosen `(id, secret)` — for a key that must
77
+ * be re-derivable (the Routebox's, from the seed). The DEK wrap and the sealed
78
+ * copy still use random nonces, so the row differs per call but the `sk-llm`
79
+ * string is the same. Never zeroes `apiKeySecret`.
80
+ */
81
+ export const mintApiKeyFrom = async (dek, vaultVersion, apiKeyId, apiKeySecret) => {
82
+ if (apiKeySecret.length !== OPENLLM_API_KEY_SECRET_BYTES) {
83
+ throw new Error("API key secret must be 32 bytes");
84
+ }
77
85
  const wrapKey = await deriveApiWrapKey(apiKeySecret, apiKeyId);
78
86
  try {
79
87
  const nonce = randomBytes(NONCE_BYTES);
@@ -1,3 +1,16 @@
1
- export declare const ROUTEBOX_HOME_HKDF_INFO = "openllm-routebox-home-v1";
1
+ import type { TMintedApiKey } from "./api-key.js";
2
+ export declare const ROUTEBOX_HOME_HKDF_INFO = "openllm-routebox-home-v2";
3
+ export declare const ROUTEBOX_KEY_ID_HKDF_INFO = "openllm-routebox-key-id-v1";
4
+ export declare const ROUTEBOX_KEY_SECRET_HKDF_INFO = "openllm-routebox-key-secret-v1";
2
5
  /** Derive the box's home key; the caller must zero the returned bytes. */
3
- export declare const deriveRouteboxHomeKey: (controlSeed: Uint8Array, keyId: string) => Promise<Uint8Array>;
6
+ export declare const deriveRouteboxHomeKey: (controlSeed: Uint8Array, subjectId: string, epoch: number) => Promise<Uint8Array>;
7
+ /** The box's API key id, in the ordinary base64url key-id encoding. */
8
+ export declare const deriveRouteboxKeyId: (controlSeed: Uint8Array, subjectId: string, epoch: number) => Promise<string>;
9
+ /** The box's API key secret; the caller must zero the returned bytes. */
10
+ export declare const deriveRouteboxKeySecret: (controlSeed: Uint8Array, subjectId: string, epoch: number) => Promise<Uint8Array>;
11
+ /**
12
+ * Mint the box's API key deterministically: a normal `api_keys` row whose id
13
+ * and `sk-llm` string are the same every time for this seed and machine (only
14
+ * the DEK-wrap nonces are random).
15
+ */
16
+ export declare const mintRouteboxApiKey: (dek: Uint8Array, vaultVersion: number, controlSeed: Uint8Array, subjectId: string, epoch: number) => Promise<TMintedApiKey>;
@@ -1,35 +1,79 @@
1
1
  /**
2
- * The Routebox's home key: what opens its encrypted home (LUKS).
2
+ * The Routebox's keys, all derived from the account's device-control seed and
3
+ * the machine's GalaxyGate SUBJECT id (stable for the machine's life, across
4
+ * deployments, resets and re-claims):
3
5
  *
4
- * Derived from the box API key's DEVICE ANCHOR secret — the per-key pair
5
- * secret `HKDF(device-control seed, key id)` (`device-anchor.ts`) that every
6
- * anchored device already holds — under its own label, so the home key and the
7
- * anchor's other uses never coincide. The device-control seed is itself
8
- * `HKDF(vault seed)`, held by an unlocked browser and by nothing else: no API
9
- * key, daemon or server. So the home key is deterministic from the recovery
10
- * phrase, stored nowhere, re-derivable by the owner's browser after every
11
- * reboot, different for every key, and gone with a vault rotation. A box that
12
- * is reset or replaced gets a new key, so a new home key; deleting the key is
13
- * the revocation.
6
+ * - the box's API key id (10 bytes, the normal key-id encoding),
7
+ * - the box's API key secret (32 bytes),
8
+ * - the home key that opens its encrypted home (LUKS).
9
+ *
10
+ * all also depend on the box's reset epoch (see `saltOf`).
11
+ *
12
+ * Each is `HKDF-SHA256(seed, utf8(subject id), <own info>, n)`, so they never
13
+ * coincide. The device-control seed is itself `HKDF(vault seed)`, held by an
14
+ * unlocked browser and by nothing else: no API key, daemon or server. So any
15
+ * deployment, given the same user's phrase, rebuilds the same `sk-llm` and the
16
+ * same home key — the key already on the box keeps working after a takeover.
17
+ * Different subject or seed, different keys; a vault rotation changes the seed
18
+ * and so everything.
14
19
  *
15
20
  * Deliberately NOT re-exported from `vault/index.ts`: the `openllm` binary
16
- * imports that barrel, and a box only ever receives this key. Import it by
21
+ * imports that barrel, and a box only ever receives these keys. Import by
17
22
  * subpath: `@openllmsh/sdk/vault/routebox-key`.
18
23
  */
19
- import { hkdfSha256, zero } from "./crypto.js";
20
- import { deriveDevicePairSecret } from "./device-anchor.js";
24
+ import { OPENLLM_API_KEY_ID_BYTES, OPENLLM_API_KEY_SECRET_BYTES, } from "@openllmsh/sdk/protocol";
25
+ import { mintApiKeyFrom } from "./api-key.js";
26
+ import { hkdfSha256, toB64Url, zero } from "./crypto.js";
21
27
  import { DEVICE_CONTROL_SEED_BYTES } from "./device-control.js";
22
- export const ROUTEBOX_HOME_HKDF_INFO = "openllm-routebox-home-v1";
23
- /** Derive the box's home key; the caller must zero the returned bytes. */
24
- export const deriveRouteboxHomeKey = async (controlSeed, keyId) => {
28
+ export const ROUTEBOX_HOME_HKDF_INFO = "openllm-routebox-home-v2";
29
+ export const ROUTEBOX_KEY_ID_HKDF_INFO = "openllm-routebox-key-id-v1";
30
+ export const ROUTEBOX_KEY_SECRET_HKDF_INFO = "openllm-routebox-key-secret-v1";
31
+ /**
32
+ * The salt: the subject id and the box's reset epoch. A Reset increments the
33
+ * epoch, so it derives a NEW key id, secret and home key (an old `sk-llm` is
34
+ * never re-minted); a takeover reads the epoch from the machine's name and so
35
+ * rebuilds the same ones.
36
+ */
37
+ const saltOf = (subjectId, epoch) => {
38
+ if (!Number.isInteger(epoch) || epoch < 0) {
39
+ throw new Error("Routebox reset epoch must be a non-negative integer");
40
+ }
41
+ return new TextEncoder().encode(`${subjectId}|e${epoch}`);
42
+ };
43
+ const derive = async (controlSeed, subjectId, epoch, info, length) => {
25
44
  if (controlSeed.length !== DEVICE_CONTROL_SEED_BYTES) {
26
45
  throw new Error("invalid device-control seed length");
27
46
  }
28
- const pairSecret = await deriveDevicePairSecret(controlSeed, keyId);
47
+ if (subjectId.length === 0)
48
+ throw new Error("Routebox key needs a subject id");
49
+ return hkdfSha256(controlSeed, saltOf(subjectId, epoch), info, length);
50
+ };
51
+ /** Derive the box's home key; the caller must zero the returned bytes. */
52
+ export const deriveRouteboxHomeKey = (controlSeed, subjectId, epoch) => derive(controlSeed, subjectId, epoch, ROUTEBOX_HOME_HKDF_INFO, 32);
53
+ /** The box's API key id, in the ordinary base64url key-id encoding. */
54
+ export const deriveRouteboxKeyId = async (controlSeed, subjectId, epoch) => {
55
+ const bytes = await derive(controlSeed, subjectId, epoch, ROUTEBOX_KEY_ID_HKDF_INFO, OPENLLM_API_KEY_ID_BYTES);
56
+ try {
57
+ return toB64Url(bytes);
58
+ }
59
+ finally {
60
+ zero(bytes);
61
+ }
62
+ };
63
+ /** The box's API key secret; the caller must zero the returned bytes. */
64
+ export const deriveRouteboxKeySecret = (controlSeed, subjectId, epoch) => derive(controlSeed, subjectId, epoch, ROUTEBOX_KEY_SECRET_HKDF_INFO, OPENLLM_API_KEY_SECRET_BYTES);
65
+ /**
66
+ * Mint the box's API key deterministically: a normal `api_keys` row whose id
67
+ * and `sk-llm` string are the same every time for this seed and machine (only
68
+ * the DEK-wrap nonces are random).
69
+ */
70
+ export const mintRouteboxApiKey = async (dek, vaultVersion, controlSeed, subjectId, epoch) => {
71
+ const id = await deriveRouteboxKeyId(controlSeed, subjectId, epoch);
72
+ const secret = await deriveRouteboxKeySecret(controlSeed, subjectId, epoch);
29
73
  try {
30
- return await hkdfSha256(pairSecret, new Uint8Array(0), ROUTEBOX_HOME_HKDF_INFO, 32);
74
+ return await mintApiKeyFrom(dek, vaultVersion, id, secret);
31
75
  }
32
76
  finally {
33
- zero(pairSecret);
77
+ zero(secret);
34
78
  }
35
79
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openllmsh/sdk",
3
- "version": "2.10.19-alpha.2",
3
+ "version": "2.10.19-alpha.3",
4
4
  "private": false,
5
5
  "description": "The OpenLLM SDK: typed API contracts, wire-format adapters, the device tunnel, client-side vault crypto, the OpenAPI spec and MCP tools.",
6
6
  "keywords": [