@openllmsh/sdk 2.10.18 → 2.10.19-alpha.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.
@@ -921,6 +921,86 @@ export const API_OPERATIONS = [
921
921
  "queryParams": [],
922
922
  "hasBody": false
923
923
  },
924
+ {
925
+ "id": "routingBoxes.get",
926
+ "method": "get",
927
+ "path": "/routing-boxes",
928
+ "summary": "",
929
+ "tags": [
930
+ "routingBoxes"
931
+ ],
932
+ "pathParams": [],
933
+ "queryParams": [],
934
+ "hasBody": false
935
+ },
936
+ {
937
+ "id": "routingBoxes.create",
938
+ "method": "post",
939
+ "path": "/routing-boxes",
940
+ "summary": "",
941
+ "tags": [
942
+ "routingBoxes"
943
+ ],
944
+ "pathParams": [],
945
+ "queryParams": [],
946
+ "hasBody": false
947
+ },
948
+ {
949
+ "id": "routingBoxes.remove",
950
+ "method": "delete",
951
+ "path": "/routing-boxes/{id}",
952
+ "summary": "",
953
+ "tags": [
954
+ "routingBoxes"
955
+ ],
956
+ "pathParams": [
957
+ "id"
958
+ ],
959
+ "queryParams": [],
960
+ "hasBody": false
961
+ },
962
+ {
963
+ "id": "routingBoxes.reset",
964
+ "method": "post",
965
+ "path": "/routing-boxes/{id}/reset",
966
+ "summary": "",
967
+ "tags": [
968
+ "routingBoxes"
969
+ ],
970
+ "pathParams": [
971
+ "id"
972
+ ],
973
+ "queryParams": [],
974
+ "hasBody": false
975
+ },
976
+ {
977
+ "id": "routingBoxes.restart",
978
+ "method": "post",
979
+ "path": "/routing-boxes/{id}/restart",
980
+ "summary": "",
981
+ "tags": [
982
+ "routingBoxes"
983
+ ],
984
+ "pathParams": [
985
+ "id"
986
+ ],
987
+ "queryParams": [],
988
+ "hasBody": false
989
+ },
990
+ {
991
+ "id": "routingBoxes.unlock",
992
+ "method": "post",
993
+ "path": "/routing-boxes/{id}/unlock",
994
+ "summary": "",
995
+ "tags": [
996
+ "routingBoxes"
997
+ ],
998
+ "pathParams": [
999
+ "id"
1000
+ ],
1001
+ "queryParams": [],
1002
+ "hasBody": true
1003
+ },
924
1004
  {
925
1005
  "id": "sessions.list",
926
1006
  "method": "get",
@@ -1624,17 +1624,17 @@ export declare const DaemonStatus: S.Struct<{
1624
1624
  /** The device-control pin this daemon verifies grants against: `fp` is the
1625
1625
  * key's fingerprint (`keyFingerprint` in `@openllmsh/sdk/tunnel`), `via` the
1626
1626
  * path that set it. Whether it is agent-eligible is reported once, in
1627
- * `device_sessions.anchored`. Absent when unpinned or on older daemons. */
1627
+ * `device_sessions.enabled`. Absent when unpinned or on older daemons. */
1628
1628
  readonly device_access_pin: S.optional<S.Struct<{
1629
1629
  readonly fp: S.String;
1630
1630
  readonly kind: S.Literals<readonly ["control", "legacy"]>;
1631
1631
  readonly via: S.optional<S.Literals<readonly ["anchor", "tofu", "local", "rotation"]>>;
1632
1632
  }>>;
1633
1633
  /** Device sessions readiness + the dpk proof (`DeviceSessionsReport`).
1634
- * `anchored` == sessions on (env-file trust anchor present). Absent on
1635
- * daemons too old to anchor — treat as not anchored. */
1634
+ * `enabled` == sessions on (anchor present, sessions flag not off, not a
1635
+ * routing box). Absent on daemons too old to report it — treat as off. */
1636
1636
  readonly device_sessions: S.optional<S.Struct<{
1637
- readonly anchored: S.Boolean;
1637
+ readonly enabled: S.Boolean;
1638
1638
  readonly dpk_proof: S.optional<S.String>;
1639
1639
  }>>;
1640
1640
  /** The loopback port this daemon's `/v1/*` + `/whoami` surface listens on
@@ -566,8 +566,9 @@ const SetAutoUpdatePayload = S.Struct({ enabled: S.Boolean });
566
566
  /** Disable device sessions remotely: `statement` is the base64 envelope of
567
567
  * `{ v: 1, key_id, ts, nonce, sig }` signed by the account control key
568
568
  * (`@openllmsh/sdk/vault` `signDeviceSessionsDisable`). Disable-only — there is no
569
- * remote enable. The daemon verifies against its ANCHORED pin and blanks
570
- * `OPENLLM_DEVICE_ANCHOR`; the cloud only relays and cannot forge one. */
569
+ * remote enable. The daemon verifies against its ANCHORED pin and sets
570
+ * `OPENLLM_DEVICE_SESSIONS=0` (the trust anchor stays); the cloud only
571
+ * relays and cannot forge one. */
571
572
  const SetDeviceSessionsPayload = S.Struct({
572
573
  statement: S.String.check(S.isMinLength(1), S.isMaxLength(1024), S.isPattern(/^[A-Za-z0-9+/]+={0,2}$/)),
573
574
  });
@@ -1094,11 +1095,11 @@ export const DaemonStatus = S.Struct({
1094
1095
  /** The device-control pin this daemon verifies grants against: `fp` is the
1095
1096
  * key's fingerprint (`keyFingerprint` in `@openllmsh/sdk/tunnel`), `via` the
1096
1097
  * path that set it. Whether it is agent-eligible is reported once, in
1097
- * `device_sessions.anchored`. Absent when unpinned or on older daemons. */
1098
+ * `device_sessions.enabled`. Absent when unpinned or on older daemons. */
1098
1099
  device_access_pin: S.optional(DeviceAccessPinReport),
1099
1100
  /** Device sessions readiness + the dpk proof (`DeviceSessionsReport`).
1100
- * `anchored` == sessions on (env-file trust anchor present). Absent on
1101
- * daemons too old to anchor — treat as not anchored. */
1101
+ * `enabled` == sessions on (anchor present, sessions flag not off, not a
1102
+ * routing box). Absent on daemons too old to report it — treat as off. */
1102
1103
  device_sessions: S.optional(DeviceSessionsReport),
1103
1104
  /** The loopback port this daemon's `/v1/*` + `/whoami` surface listens on
1104
1105
  * (`OPENLLM_DAEMON_PORT`, default 8787). Reported in `daemon_status_json`
@@ -56,6 +56,7 @@ export * from "./registry-pointer.js";
56
56
  export * from "./relay.js";
57
57
  export * from "./replay-session.js";
58
58
  export * from "./responses.js";
59
+ export * from "./routing-box.js";
59
60
  export * from "./semver.js";
60
61
  export * from "./setup-mode.js";
61
62
  export * from "./stats.js";
@@ -56,6 +56,7 @@ export * from "./registry-pointer.js";
56
56
  export * from "./relay.js";
57
57
  export * from "./replay-session.js";
58
58
  export * from "./responses.js";
59
+ export * from "./routing-box.js";
59
60
  export * from "./semver.js";
60
61
  export * from "./setup-mode.js";
61
62
  export * from "./stats.js";
@@ -11,8 +11,8 @@
11
11
  * browser to attest with its control key;
12
12
  * - `POST /local/device-control` → pin the account control public key
13
13
  * directly (`via: "local"`, an anchored pin).
14
- * - `POST /local/device-anchor` → install or remove the device trust anchor
15
- * (sessions on == anchor present).
14
+ * - `POST /local/device-anchor` → install the device trust anchor, or set the
15
+ * device-sessions on/off flag (the anchor is never removed).
16
16
  */
17
17
  import { Schema as S } from "effect";
18
18
  export declare const IDENTITY_LOCAL_PATH = "/local/identity";
@@ -29,17 +29,19 @@ export type TDeviceAccessPinReport = S.Schema.Type<typeof DeviceAccessPinReport>
29
29
  * `DaemonStatus.device_sessions` — whether this device can host agent sessions
30
30
  * and the daemon's proof of its X25519 key.
31
31
  *
32
- * - `anchored`: the pin descends from a local trust root (install / login /
33
- * desktop loopback anchor). True == device sessions are on. False → agent
34
- * sessions fail closed with `device_not_anchored`; offer "Set up device
35
- * sessions".
32
+ * - `enabled`: sessions on — the install/login/loopback trust anchor is
33
+ * present (agent-eligible pin), the `OPENLLM_DEVICE_SESSIONS` flag is not
34
+ * off, and this is not a routing box. False → agent sessions fail closed
35
+ * with `device_not_anchored` (no anchor) or `device_sessions_disabled`
36
+ * (flag off / routing box); offer local enable or re-install with sessions.
36
37
  * - `dpk_proof`: `HMAC-SHA256(pair_secret, "openllm-dpk-proof-v1" ||
37
38
  * key_id || pubkey)`, base64url. Verify with `@openllmsh/sdk/vault`
38
39
  * `verifyDpkProof` BEFORE using `DaemonStatus.pubkey` as `dpk`. Absent when
39
- * the daemon holds no anchor for the key it runs on.
40
+ * the daemon holds no anchor for the key it runs on. The proof follows the
41
+ * anchor alone — the sessions flag does not affect it.
40
42
  */
41
43
  export declare const DeviceSessionsReport: S.Struct<{
42
- readonly anchored: S.Boolean;
44
+ readonly enabled: S.Boolean;
43
45
  readonly dpk_proof: S.optional<S.String>;
44
46
  }>;
45
47
  export type TDeviceSessionsReport = S.Schema.Type<typeof DeviceSessionsReport>;
@@ -56,7 +58,7 @@ export declare const LocalIdentityResponse: S.Struct<{
56
58
  }>>;
57
59
  /** Same as `DaemonStatus.device_sessions`. Absent on older daemons. */
58
60
  readonly device_sessions: S.optional<S.Struct<{
59
- readonly anchored: S.Boolean;
61
+ readonly enabled: S.Boolean;
60
62
  readonly dpk_proof: S.optional<S.String>;
61
63
  }>>;
62
64
  }>;
@@ -70,16 +72,18 @@ export declare const LocalDeviceControlRequest: S.Struct<{
70
72
  }>;
71
73
  export type TLocalDeviceControlRequest = S.Schema.Type<typeof LocalDeviceControlRequest>;
72
74
  /**
73
- * `POST /local/device-anchor` — install or remove this machine's trust anchor
74
- * over loopback (the desktop app's Device sessions toggle). Same admission as
75
- * `/local/device-control`. Install refuses unless `key_id` is the key this
76
- * daemon runs on, writes `OPENLLM_DEVICE_ANCHOR` with the same writer as
77
- * `openllm daemon anchor`, and re-derives its pin. Remove blanks that line.
78
- * The anchor is never logged or echoed back. Sessions on == anchor present.
75
+ * `POST /local/device-anchor` — install this machine's trust anchor, or flip
76
+ * the device-sessions flag, over loopback (the desktop app's Device sessions
77
+ * toggle). Same admission as `/local/device-control`. Install refuses unless
78
+ * `key_id` is the key this daemon runs on, writes `OPENLLM_DEVICE_ANCHOR` with
79
+ * the same writer as `openllm daemon anchor`, turns sessions on, and
80
+ * re-derives its pin. `{ sessions: true|false }` sets `OPENLLM_DEVICE_SESSIONS`
81
+ * only — the anchor is never removed. Enable is refused on a routing box.
82
+ * The anchor is never logged or echoed back.
79
83
  */
80
84
  export declare const DEVICE_ANCHOR_LOCAL_PATH = "/local/device-anchor";
81
85
  export declare const DEVICE_ANCHOR_LOCAL_MAX_BODY_BYTES = 512;
82
- /** `POST /local/device-anchor` body — install or remove. */
86
+ /** `POST /local/device-anchor` body — install the anchor, or set sessions. */
83
87
  export declare const LocalDeviceAnchorRequest: S.Union<readonly [S.Struct<{
84
88
  /** The API key id the anchor was derived for (`sk-llm-<key_id>.…`). */
85
89
  readonly key_id: S.String;
@@ -87,22 +91,22 @@ export declare const LocalDeviceAnchorRequest: S.Union<readonly [S.Struct<{
87
91
  readonly anchor: S.String;
88
92
  }>, S.Struct<{
89
93
  readonly key_id: S.String;
90
- /** Blank `OPENLLM_DEVICE_ANCHOR` — sessions off. */
91
- readonly remove: S.Literal<true>;
94
+ /** Flip `OPENLLM_DEVICE_SESSIONS` — the anchor stays. */
95
+ readonly sessions: S.Boolean;
92
96
  }>]>;
93
97
  export type TLocalDeviceAnchorRequest = S.Schema.Type<typeof LocalDeviceAnchorRequest>;
94
98
  /** Why `POST /local/device-anchor` refused. */
95
- export declare const LocalDeviceAnchorRefusal: S.Literals<readonly ["invalid_body", "body_too_large", "malformed_anchor", "key_id_mismatch", "persist_failed"]>;
99
+ export declare const LocalDeviceAnchorRefusal: S.Literals<readonly ["invalid_body", "body_too_large", "malformed_anchor", "key_id_mismatch", "persist_failed", "routing_box"]>;
96
100
  export type TLocalDeviceAnchorRefusal = S.Schema.Type<typeof LocalDeviceAnchorRefusal>;
97
101
  /** `POST /local/device-anchor` response. */
98
102
  export declare const LocalDeviceAnchorResponse: S.Union<readonly [S.Struct<{
99
103
  readonly ok: S.Literal<true>;
100
104
  readonly device_sessions: S.Struct<{
101
- readonly anchored: S.Boolean;
105
+ readonly enabled: S.Boolean;
102
106
  readonly dpk_proof: S.optional<S.String>;
103
107
  }>;
104
108
  }>, S.Struct<{
105
109
  readonly ok: S.Literal<false>;
106
- readonly error: S.Literals<readonly ["invalid_body", "body_too_large", "malformed_anchor", "key_id_mismatch", "persist_failed"]>;
110
+ readonly error: S.Literals<readonly ["invalid_body", "body_too_large", "malformed_anchor", "key_id_mismatch", "persist_failed", "routing_box"]>;
107
111
  }>]>;
108
112
  export type TLocalDeviceAnchorResponse = S.Schema.Type<typeof LocalDeviceAnchorResponse>;
@@ -11,8 +11,8 @@
11
11
  * browser to attest with its control key;
12
12
  * - `POST /local/device-control` → pin the account control public key
13
13
  * directly (`via: "local"`, an anchored pin).
14
- * - `POST /local/device-anchor` → install or remove the device trust anchor
15
- * (sessions on == anchor present).
14
+ * - `POST /local/device-anchor` → install the device trust anchor, or set the
15
+ * device-sessions on/off flag (the anchor is never removed).
16
16
  */
17
17
  import { Schema as S } from "effect";
18
18
  export const IDENTITY_LOCAL_PATH = "/local/identity";
@@ -28,17 +28,19 @@ export const DeviceAccessPinReport = S.Struct({
28
28
  * `DaemonStatus.device_sessions` — whether this device can host agent sessions
29
29
  * and the daemon's proof of its X25519 key.
30
30
  *
31
- * - `anchored`: the pin descends from a local trust root (install / login /
32
- * desktop loopback anchor). True == device sessions are on. False → agent
33
- * sessions fail closed with `device_not_anchored`; offer "Set up device
34
- * sessions".
31
+ * - `enabled`: sessions on — the install/login/loopback trust anchor is
32
+ * present (agent-eligible pin), the `OPENLLM_DEVICE_SESSIONS` flag is not
33
+ * off, and this is not a routing box. False → agent sessions fail closed
34
+ * with `device_not_anchored` (no anchor) or `device_sessions_disabled`
35
+ * (flag off / routing box); offer local enable or re-install with sessions.
35
36
  * - `dpk_proof`: `HMAC-SHA256(pair_secret, "openllm-dpk-proof-v1" ||
36
37
  * key_id || pubkey)`, base64url. Verify with `@openllmsh/sdk/vault`
37
38
  * `verifyDpkProof` BEFORE using `DaemonStatus.pubkey` as `dpk`. Absent when
38
- * the daemon holds no anchor for the key it runs on.
39
+ * the daemon holds no anchor for the key it runs on. The proof follows the
40
+ * anchor alone — the sessions flag does not affect it.
39
41
  */
40
42
  export const DeviceSessionsReport = S.Struct({
41
- anchored: S.Boolean,
43
+ enabled: S.Boolean,
42
44
  dpk_proof: S.optional(S.String.check(S.isMaxLength(64))),
43
45
  });
44
46
  /** `GET /local/identity` response. */
@@ -59,16 +61,18 @@ export const LocalDeviceControlRequest = S.Struct({
59
61
  version: S.optional(S.NullOr(S.Number.check(S.isInt(), S.isGreaterThanOrEqualTo(1)))),
60
62
  });
61
63
  /**
62
- * `POST /local/device-anchor` — install or remove this machine's trust anchor
63
- * over loopback (the desktop app's Device sessions toggle). Same admission as
64
- * `/local/device-control`. Install refuses unless `key_id` is the key this
65
- * daemon runs on, writes `OPENLLM_DEVICE_ANCHOR` with the same writer as
66
- * `openllm daemon anchor`, and re-derives its pin. Remove blanks that line.
67
- * The anchor is never logged or echoed back. Sessions on == anchor present.
64
+ * `POST /local/device-anchor` — install this machine's trust anchor, or flip
65
+ * the device-sessions flag, over loopback (the desktop app's Device sessions
66
+ * toggle). Same admission as `/local/device-control`. Install refuses unless
67
+ * `key_id` is the key this daemon runs on, writes `OPENLLM_DEVICE_ANCHOR` with
68
+ * the same writer as `openllm daemon anchor`, turns sessions on, and
69
+ * re-derives its pin. `{ sessions: true|false }` sets `OPENLLM_DEVICE_SESSIONS`
70
+ * only — the anchor is never removed. Enable is refused on a routing box.
71
+ * The anchor is never logged or echoed back.
68
72
  */
69
73
  export const DEVICE_ANCHOR_LOCAL_PATH = "/local/device-anchor";
70
74
  export const DEVICE_ANCHOR_LOCAL_MAX_BODY_BYTES = 512;
71
- /** `POST /local/device-anchor` body — install or remove. */
75
+ /** `POST /local/device-anchor` body — install the anchor, or set sessions. */
72
76
  export const LocalDeviceAnchorRequest = S.Union([
73
77
  S.Struct({
74
78
  /** The API key id the anchor was derived for (`sk-llm-<key_id>.…`). */
@@ -78,8 +82,8 @@ export const LocalDeviceAnchorRequest = S.Union([
78
82
  }),
79
83
  S.Struct({
80
84
  key_id: S.String.check(S.isMinLength(1), S.isMaxLength(64)),
81
- /** Blank `OPENLLM_DEVICE_ANCHOR` — sessions off. */
82
- remove: S.Literal(true),
85
+ /** Flip `OPENLLM_DEVICE_SESSIONS` — the anchor stays. */
86
+ sessions: S.Boolean,
83
87
  }),
84
88
  ]);
85
89
  /** Why `POST /local/device-anchor` refused. */
@@ -89,6 +93,8 @@ export const LocalDeviceAnchorRefusal = S.Literals([
89
93
  "malformed_anchor",
90
94
  "key_id_mismatch",
91
95
  "persist_failed",
96
+ /** A routing box never enables device sessions. */
97
+ "routing_box",
92
98
  ]);
93
99
  /** `POST /local/device-anchor` response. */
94
100
  export const LocalDeviceAnchorResponse = S.Union([
@@ -581,9 +581,8 @@ export const StreamResetCode = S.Literals([
581
581
  * no install anchor): agent sessions fail closed. Fix with "Set up device
582
582
  * sessions" (`openllm login sk-llm-<key>.<anchor>`). */
583
583
  "device_not_anchored",
584
- /** Retired: older daemons emitted this when a separate enabled flag was off.
585
- * Current daemons only emit `device_not_anchored` (sessions on == anchor).
586
- * Kept in the closed vocabulary so old peers still decode. */
584
+ /** Sessions flag off (`OPENLLM_DEVICE_SESSIONS=0`) or a routing box.
585
+ * Distinct from `device_not_anchored` (no trust anchor / ineligible pin). */
587
586
  "device_sessions_disabled",
588
587
  ]);
589
588
  /** JSON payload of a mux RESET frame. */
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Where a routing box marks itself. The box's user-data writes this file;
3
+ * the daemon reads it to keep auto-update always on and to refuse device
4
+ * sessions (a routing box is too small for them). Shared so the two sides
5
+ * can't drift. Plan: docs/plans/routing-sandbox.md.
6
+ */
7
+ export declare const ROUTING_BOX_MARKER_PATH = "/etc/openllm/routing-box";
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Where a routing box marks itself. The box's user-data writes this file;
3
+ * the daemon reads it to keep auto-update always on and to refuse device
4
+ * sessions (a routing box is too small for them). Shared so the two sides
5
+ * can't drift. Plan: docs/plans/routing-sandbox.md.
6
+ */
7
+ export const ROUTING_BOX_MARKER_PATH = "/etc/openllm/routing-box";
@@ -28,6 +28,8 @@ export declare const DEVICE_CONTROL_HKDF_INFO = "openllm-device-control-v1";
28
28
  export declare const DEVICE_CONTROL_HKDF_SALT = "openllm-device-control-salt-v1";
29
29
  /** HKDF info for the at-rest "control keep" outer wrap (under the DEK). */
30
30
  export declare const DEVICE_CONTROL_KEEP_HKDF_INFO = "openllm-device-control-keep-v1";
31
+ /** Length of the device-control seed (and of the routing box key's input). */
32
+ export declare const DEVICE_CONTROL_SEED_BYTES = 32;
31
33
  /**
32
34
  * `HKDF-SHA256(ikm = BIP39 entropy(phrase), salt = DEVICE_CONTROL_HKDF_SALT,
33
35
  * info = DEVICE_CONTROL_HKDF_INFO, 32)` — the Ed25519 private seed.
@@ -33,7 +33,9 @@ export const DEVICE_CONTROL_HKDF_INFO = "openllm-device-control-v1";
33
33
  export const DEVICE_CONTROL_HKDF_SALT = "openllm-device-control-salt-v1";
34
34
  /** HKDF info for the at-rest "control keep" outer wrap (under the DEK). */
35
35
  export const DEVICE_CONTROL_KEEP_HKDF_INFO = "openllm-device-control-keep-v1";
36
- const SEED_BYTES = 32;
36
+ /** Length of the device-control seed (and of the routing box key's input). */
37
+ export const DEVICE_CONTROL_SEED_BYTES = 32;
38
+ const SEED_BYTES = DEVICE_CONTROL_SEED_BYTES;
37
39
  /**
38
40
  * `HKDF-SHA256(ikm = BIP39 entropy(phrase), salt = DEVICE_CONTROL_HKDF_SALT,
39
41
  * info = DEVICE_CONTROL_HKDF_INFO, 32)` — the Ed25519 private seed.
@@ -0,0 +1,3 @@
1
+ export declare const ROUTING_BOX_HOME_HKDF_INFO = "openllm-routing-box-home-v1";
2
+ /** Derive the box's home key; the caller must zero the returned bytes. */
3
+ export declare const deriveRoutingBoxHomeKey: (controlSeed: Uint8Array, keyId: string) => Promise<Uint8Array>;
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The routing box's home key: what opens its encrypted home (LUKS).
3
+ *
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.
14
+ *
15
+ * 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
17
+ * subpath: `@openllmsh/sdk/vault/routing-box-key`.
18
+ */
19
+ import { hkdfSha256, zero } from "./crypto.js";
20
+ import { deriveDevicePairSecret } from "./device-anchor.js";
21
+ import { DEVICE_CONTROL_SEED_BYTES } from "./device-control.js";
22
+ export const ROUTING_BOX_HOME_HKDF_INFO = "openllm-routing-box-home-v1";
23
+ /** Derive the box's home key; the caller must zero the returned bytes. */
24
+ export const deriveRoutingBoxHomeKey = async (controlSeed, keyId) => {
25
+ if (controlSeed.length !== DEVICE_CONTROL_SEED_BYTES) {
26
+ throw new Error("invalid device-control seed length");
27
+ }
28
+ const pairSecret = await deriveDevicePairSecret(controlSeed, keyId);
29
+ try {
30
+ return await hkdfSha256(pairSecret, new Uint8Array(0), ROUTING_BOX_HOME_HKDF_INFO, 32);
31
+ }
32
+ finally {
33
+ zero(pairSecret);
34
+ }
35
+ };
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Seal a routing box's unlock to the one-time token its current boot made.
3
+ *
4
+ * The box generates a fresh X25519 keypair on every boot and keeps the
5
+ * private half in RAM (`/run`, tmpfs). The browser seals to the public half:
6
+ * an ephemeral X25519 exchange, HKDF-SHA-256 and AES-256-GCM, the same
7
+ * construction as `public-key-seal.ts`, so the box can open it with Python's
8
+ * `cryptography` (cloud-init's own dependency) and no OpenLLM binary change.
9
+ *
10
+ * The associated data binds the envelope to the user, box, the box's API key
11
+ * id, boot generation, boot public key and challenge, so an envelope sealed for one
12
+ * boot can't be replayed into another, and the server, which only stores and
13
+ * forwards the ciphertext, can't redirect it.
14
+ *
15
+ * Deliberately NOT re-exported from `vault/index.ts` (the `openllm` binary
16
+ * imports that barrel). Import by subpath:
17
+ * `@openllmsh/sdk/vault/routing-box-seal`.
18
+ *
19
+ * The box side mirrors `open_unlock` in
20
+ * `packages/api/lib/routing-box/box-agent.ts` (Python).
21
+ */
22
+ export declare const ROUTING_BOX_SEAL_DOMAIN = "openllm-routing-box-seal-v1";
23
+ export type TRoutingBoxSealBinding = {
24
+ readonly userId: string;
25
+ readonly boxId: string;
26
+ /** The box's API key; its home key derives from this key's anchor. */
27
+ readonly keyId: string;
28
+ readonly bootGeneration: number;
29
+ /** The boot's X25519 public key, base64 of the raw 32 bytes. */
30
+ readonly bootPubkeyB64: string;
31
+ /** The boot's 32-byte challenge, base64. */
32
+ readonly challengeB64: string;
33
+ };
34
+ export type TRoutingBoxEnvelope = {
35
+ readonly v: 1;
36
+ /** Ephemeral X25519 public key, base64 of the raw 32 bytes. */
37
+ readonly epk: string;
38
+ readonly nonce: string;
39
+ readonly ct: string;
40
+ };
41
+ /**
42
+ * What the box receives on every boot: `home_key` opens its encrypted home,
43
+ * and `api_key` is the box's ANCHORED `sk-llm` key (so its daemon pins the
44
+ * control key, which WebRTC needs). Sent every time, so a box that failed
45
+ * before installing it recovers on its next boot.
46
+ */
47
+ export type TRoutingBoxUnlock = {
48
+ readonly home_key: string;
49
+ readonly api_key: string;
50
+ };
51
+ /** Canonical associated data; the Python side builds the same bytes. */
52
+ export declare const routingBoxSealAad: (binding: TRoutingBoxSealBinding) => Uint8Array;
53
+ /** Seal `unlock` to the boot in `binding`. */
54
+ export declare const sealRoutingBoxUnlock: (binding: TRoutingBoxSealBinding, unlock: TRoutingBoxUnlock) => Promise<TRoutingBoxEnvelope>;
55
+ /** Open an envelope with the boot's private key (tests; the box uses Python). */
56
+ export declare const openRoutingBoxUnlock: (binding: TRoutingBoxSealBinding, envelope: TRoutingBoxEnvelope, bootPrivateKey: CryptoKey) => Promise<TRoutingBoxUnlock>;
@@ -0,0 +1,93 @@
1
+ /**
2
+ * Seal a routing box's unlock to the one-time token its current boot made.
3
+ *
4
+ * The box generates a fresh X25519 keypair on every boot and keeps the
5
+ * private half in RAM (`/run`, tmpfs). The browser seals to the public half:
6
+ * an ephemeral X25519 exchange, HKDF-SHA-256 and AES-256-GCM, the same
7
+ * construction as `public-key-seal.ts`, so the box can open it with Python's
8
+ * `cryptography` (cloud-init's own dependency) and no OpenLLM binary change.
9
+ *
10
+ * The associated data binds the envelope to the user, box, the box's API key
11
+ * id, boot generation, boot public key and challenge, so an envelope sealed for one
12
+ * boot can't be replayed into another, and the server, which only stores and
13
+ * forwards the ciphertext, can't redirect it.
14
+ *
15
+ * Deliberately NOT re-exported from `vault/index.ts` (the `openllm` binary
16
+ * imports that barrel). Import by subpath:
17
+ * `@openllmsh/sdk/vault/routing-box-seal`.
18
+ *
19
+ * The box side mirrors `open_unlock` in
20
+ * `packages/api/lib/routing-box/box-agent.ts` (Python).
21
+ */
22
+ import { aesGcmDecrypt, aesGcmEncrypt, fromB64, hkdfSha256, randomBytes, toB64, zero, } from "./crypto.js";
23
+ export const ROUTING_BOX_SEAL_DOMAIN = "openllm-routing-box-seal-v1";
24
+ const encoder = new TextEncoder();
25
+ /** Canonical associated data; the Python side builds the same bytes. */
26
+ export const routingBoxSealAad = (binding) => encoder.encode(JSON.stringify([
27
+ ROUTING_BOX_SEAL_DOMAIN,
28
+ binding.userId,
29
+ binding.boxId,
30
+ binding.keyId,
31
+ binding.bootGeneration,
32
+ binding.bootPubkeyB64,
33
+ binding.challengeB64,
34
+ ]));
35
+ const raw32 = (b64, what) => {
36
+ const bytes = fromB64(b64);
37
+ if (bytes.length !== 32 || toB64(bytes) !== b64) {
38
+ throw new Error(`${what} must be base64 of 32 bytes`);
39
+ }
40
+ return bytes;
41
+ };
42
+ const deriveKey = async (privateKey, peerRaw, epkB64, recipientB64) => {
43
+ const peer = await crypto.subtle.importKey("raw", peerRaw, { name: "X25519" }, false, []);
44
+ const shared = new Uint8Array(await crypto.subtle.deriveBits({ name: "X25519", public: peer }, privateKey, 256));
45
+ try {
46
+ return await hkdfSha256(shared, new Uint8Array(0), JSON.stringify([ROUTING_BOX_SEAL_DOMAIN, epkB64, recipientB64]), 32);
47
+ }
48
+ finally {
49
+ zero(shared);
50
+ }
51
+ };
52
+ /** Seal `unlock` to the boot in `binding`. */
53
+ export const sealRoutingBoxUnlock = async (binding, unlock) => {
54
+ raw32(binding.challengeB64, "challenge");
55
+ const recipient = raw32(binding.bootPubkeyB64, "boot public key");
56
+ const eph = (await crypto.subtle.generateKey({ name: "X25519" }, true, [
57
+ "deriveBits",
58
+ ]));
59
+ const epkB64 = toB64(new Uint8Array(await crypto.subtle.exportKey("raw", eph.publicKey)));
60
+ const key = await deriveKey(eph.privateKey, recipient, epkB64, binding.bootPubkeyB64);
61
+ const plaintext = encoder.encode(JSON.stringify(unlock));
62
+ try {
63
+ const nonce = randomBytes(12);
64
+ return {
65
+ v: 1,
66
+ epk: epkB64,
67
+ nonce: toB64(nonce),
68
+ ct: toB64(await aesGcmEncrypt(key, nonce, plaintext, routingBoxSealAad(binding))),
69
+ };
70
+ }
71
+ finally {
72
+ zero(key);
73
+ zero(plaintext);
74
+ }
75
+ };
76
+ /** Open an envelope with the boot's private key (tests; the box uses Python). */
77
+ export const openRoutingBoxUnlock = async (binding, envelope, bootPrivateKey) => {
78
+ if (envelope.v !== 1)
79
+ throw new Error("unknown envelope version");
80
+ const key = await deriveKey(bootPrivateKey, raw32(envelope.epk, "ephemeral key"), envelope.epk, binding.bootPubkeyB64);
81
+ try {
82
+ const plaintext = await aesGcmDecrypt(key, fromB64(envelope.nonce), fromB64(envelope.ct), routingBoxSealAad(binding));
83
+ try {
84
+ return JSON.parse(new TextDecoder().decode(plaintext));
85
+ }
86
+ finally {
87
+ zero(plaintext);
88
+ }
89
+ }
90
+ finally {
91
+ zero(key);
92
+ }
93
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openllmsh/sdk",
3
- "version": "2.10.18",
3
+ "version": "2.10.19-alpha.0",
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": [