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

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.
@@ -30,9 +30,9 @@ export const DeviceAccessPinReport = S.Struct({
30
30
  *
31
31
  * - `enabled`: sessions on — the install/login/loopback trust anchor is
32
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
33
+ * off, and this is not a Routebox. False → agent sessions fail closed
34
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
+ * (flag off / Routebox); offer local enable or re-install with sessions.
36
36
  * - `dpk_proof`: `HMAC-SHA256(pair_secret, "openllm-dpk-proof-v1" ||
37
37
  * key_id || pubkey)`, base64url. Verify with `@openllmsh/sdk/vault`
38
38
  * `verifyDpkProof` BEFORE using `DaemonStatus.pubkey` as `dpk`. Absent when
@@ -67,7 +67,7 @@ export const LocalDeviceControlRequest = S.Struct({
67
67
  * `key_id` is the key this daemon runs on, writes `OPENLLM_DEVICE_ANCHOR` with
68
68
  * the same writer as `openllm daemon anchor`, turns sessions on, and
69
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.
70
+ * only — the anchor is never removed. Enable is refused on a Routebox.
71
71
  * The anchor is never logged or echoed back.
72
72
  */
73
73
  export const DEVICE_ANCHOR_LOCAL_PATH = "/local/device-anchor";
@@ -93,8 +93,8 @@ export const LocalDeviceAnchorRefusal = S.Literals([
93
93
  "malformed_anchor",
94
94
  "key_id_mismatch",
95
95
  "persist_failed",
96
- /** A routing box never enables device sessions. */
97
- "routing_box",
96
+ /** A Routebox never enables device sessions. */
97
+ "routebox",
98
98
  ]);
99
99
  /** `POST /local/device-anchor` response. */
100
100
  export const LocalDeviceAnchorResponse = S.Union([
@@ -581,7 +581,7 @@ 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
- /** Sessions flag off (`OPENLLM_DEVICE_SESSIONS=0`) or a routing box.
584
+ /** Sessions flag off (`OPENLLM_DEVICE_SESSIONS=0`) or a Routebox.
585
585
  * Distinct from `device_not_anchored` (no trust anchor / ineligible pin). */
586
586
  "device_sessions_disabled",
587
587
  ]);
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Where a Routebox 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 Routebox is too small for them). Shared so the two sides
5
+ * can't drift. Plan: docs/plans/routebox.md.
6
+ */
7
+ export declare const ROUTEBOX_MARKER_PATH = "/etc/openllm/routebox";
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Where a Routebox 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 Routebox is too small for them). Shared so the two sides
5
+ * can't drift. Plan: docs/plans/routebox.md.
6
+ */
7
+ export const ROUTEBOX_MARKER_PATH = "/etc/openllm/routebox";
@@ -7,8 +7,8 @@
7
7
  * so connector and CLI ciphertext are not interchangeable. The server is a
8
8
  * mailbox: it stores only the JSON envelope.
9
9
  */
10
- import { aesGcmDecrypt, aesGcmEncrypt, fromB64, hkdfSha256, randomBytes, toB64, zero, } from "./crypto.js";
11
10
  import { generateResumableX25519Keypair, generateX25519Keypair, importX25519PrivateKey, } from "./handoff.js";
11
+ import { decodeCanonicalB64, openX25519, sealX25519 } from "./x25519-seal.js";
12
12
  export const CLI_AUTH_SEAL_DOMAIN = "openllm-cli-auth-seal-v1";
13
13
  const aad = (binding) => new TextEncoder().encode(JSON.stringify([
14
14
  CLI_AUTH_SEAL_DOMAIN,
@@ -16,59 +16,34 @@ const aad = (binding) => new TextEncoder().encode(JSON.stringify([
16
16
  binding.authorizationId,
17
17
  binding.recipientPublicKeyB64,
18
18
  ]));
19
- const decode = (value) => {
20
- if (typeof value !== "string" ||
21
- !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
22
- throw new Error("Invalid sealed envelope encoding");
23
- const bytes = fromB64(value);
24
- if (toB64(bytes) !== value)
25
- throw new Error("Invalid sealed envelope encoding");
26
- return bytes;
27
- };
28
- const deriveKey = async (privateKey, peerB64, epk, recipient) => {
29
- const peer = await crypto.subtle.importKey("spki", decode(peerB64), { name: "X25519" }, false, []);
30
- const shared = new Uint8Array(await crypto.subtle.deriveBits({ name: "X25519", public: peer }, privateKey, 256));
31
- try {
32
- return await hkdfSha256(shared, new Uint8Array(0), JSON.stringify([CLI_AUTH_SEAL_DOMAIN, epk, recipient]), 32);
33
- }
34
- finally {
35
- zero(shared);
36
- }
37
- };
38
19
  /** Caller retains ownership of plaintext; the temporary copy is wiped. */
39
- export const sealCliAuth = async (binding, plaintext) => {
40
- const eph = await generateX25519Keypair();
41
- const key = await deriveKey(eph.privateKey, binding.recipientPublicKeyB64, eph.publicKeyB64, binding.recipientPublicKeyB64);
42
- const copy = new Uint8Array(plaintext);
43
- try {
44
- const nonce = randomBytes(12);
45
- return {
46
- v: 1,
47
- epk: eph.publicKeyB64,
48
- nonce: toB64(nonce),
49
- ct: toB64(await aesGcmEncrypt(key, nonce, copy, aad(binding))),
50
- };
51
- }
52
- finally {
53
- zero(key);
54
- zero(copy);
55
- }
56
- };
20
+ export const sealCliAuth = async (binding, plaintext) => sealX25519({
21
+ domain: CLI_AUTH_SEAL_DOMAIN,
22
+ recipientB64: binding.recipientPublicKeyB64,
23
+ recipientBytes: decodeCanonicalB64(binding.recipientPublicKeyB64),
24
+ format: "spki",
25
+ aad: aad(binding),
26
+ plaintext,
27
+ });
57
28
  /** Caller owns the returned plaintext and must wipe it when finished. */
58
29
  export const openCliAuth = async (binding, sealed, privateKey) => {
59
30
  if (typeof sealed !== "object" || sealed === null || sealed.v !== 1)
60
31
  throw new Error("Invalid sealed envelope");
61
- const nonce = decode(sealed.nonce);
62
- const ct = decode(sealed.ct);
32
+ const nonce = decodeCanonicalB64(sealed.nonce);
33
+ const ct = decodeCanonicalB64(sealed.ct);
63
34
  if (nonce.length !== 12 || ct.length < 16 || typeof sealed.epk !== "string")
64
35
  throw new Error("Invalid sealed envelope");
65
- const key = await deriveKey(privateKey, sealed.epk, sealed.epk, binding.recipientPublicKeyB64);
66
- try {
67
- return await aesGcmDecrypt(key, nonce, ct, aad(binding));
68
- }
69
- finally {
70
- zero(key);
71
- }
36
+ return openX25519({
37
+ domain: CLI_AUTH_SEAL_DOMAIN,
38
+ privateKey,
39
+ recipientB64: binding.recipientPublicKeyB64,
40
+ epkBytes: decodeCanonicalB64(sealed.epk),
41
+ epkB64: sealed.epk,
42
+ format: "spki",
43
+ aad: aad(binding),
44
+ nonce,
45
+ ct,
46
+ });
72
47
  };
73
48
  /** Alias kept for CLI call-site parity with the old `cli-auth-crypto` names. */
74
49
  export const generateCliAuthKeypair = generateX25519Keypair;
@@ -28,7 +28,7 @@ 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). */
31
+ /** Length of the device-control seed (and of the Routebox key's input). */
32
32
  export declare const DEVICE_CONTROL_SEED_BYTES = 32;
33
33
  /**
34
34
  * `HKDF-SHA256(ikm = BIP39 entropy(phrase), salt = DEVICE_CONTROL_HKDF_SALT,
@@ -33,9 +33,8 @@ 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
- /** Length of the device-control seed (and of the routing box key's input). */
36
+ /** Length of the device-control seed (and of the Routebox key's input). */
37
37
  export const DEVICE_CONTROL_SEED_BYTES = 32;
38
- const SEED_BYTES = DEVICE_CONTROL_SEED_BYTES;
39
38
  /**
40
39
  * `HKDF-SHA256(ikm = BIP39 entropy(phrase), salt = DEVICE_CONTROL_HKDF_SALT,
41
40
  * info = DEVICE_CONTROL_HKDF_INFO, 32)` — the Ed25519 private seed.
@@ -57,7 +56,7 @@ export const deriveDeviceControlSeed = async (phrase) => {
57
56
  * BIP39 entropy, `./seed.ts`) — the same key, for callers that hold the seed
58
57
  * bytes rather than the words. Never zeroes its input.
59
58
  */
60
- export const deriveDeviceControlSeedFromVaultSeed = (vaultSeed) => hkdfSha256(vaultSeed, new TextEncoder().encode(DEVICE_CONTROL_HKDF_SALT), DEVICE_CONTROL_HKDF_INFO, SEED_BYTES);
59
+ export const deriveDeviceControlSeedFromVaultSeed = (vaultSeed) => hkdfSha256(vaultSeed, new TextEncoder().encode(DEVICE_CONTROL_HKDF_SALT), DEVICE_CONTROL_HKDF_INFO, DEVICE_CONTROL_SEED_BYTES);
61
60
  /** The control public key as base64(SPKI DER) — the value daemons pin. */
62
61
  export const deviceControlPublicKeySpkiB64 = (seed) => deviceAccessPublicKeySpkiB64(seed);
63
62
  /**
@@ -74,7 +73,7 @@ export const controlKeepOuterKey = (dek, userId) => {
74
73
  if (userId.length === 0) {
75
74
  throw new Error("control keep requires a non-empty userId");
76
75
  }
77
- return hkdfSha256(dek, new TextEncoder().encode(userId), DEVICE_CONTROL_KEEP_HKDF_INFO, SEED_BYTES);
76
+ return hkdfSha256(dek, new TextEncoder().encode(userId), DEVICE_CONTROL_KEEP_HKDF_INFO, DEVICE_CONTROL_SEED_BYTES);
78
77
  };
79
78
  /**
80
79
  * Sign a rotation statement with the OLD control seed, vouching for `new`.
@@ -1,59 +1,32 @@
1
- import { aesGcmDecrypt, aesGcmEncrypt, fromB64, hkdfSha256, randomBytes, toB64, zero, } from "./crypto.js";
2
- import { generateX25519Keypair } from "./handoff.js";
1
+ import { decodeCanonicalB64, openX25519, sealX25519 } from "./x25519-seal.js";
3
2
  const DOMAIN = "openllm-connector-seal-v1";
4
3
  const aad = (binding) => new TextEncoder().encode(JSON.stringify([DOMAIN, binding.clientId, binding.userId, binding.grantId]));
5
- const decode = (value) => {
6
- if (typeof value !== "string" ||
7
- !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
8
- throw new Error("Invalid sealed envelope encoding");
9
- const bytes = fromB64(value);
10
- if (toB64(bytes) !== value)
11
- throw new Error("Invalid sealed envelope encoding");
12
- return bytes;
13
- };
14
- const deriveKey = async (privateKey, peerB64, epk, recipient) => {
15
- const peer = await crypto.subtle.importKey("spki", decode(peerB64), { name: "X25519" }, false, []);
16
- const shared = new Uint8Array(await crypto.subtle.deriveBits({ name: "X25519", public: peer }, privateKey, 256));
17
- try {
18
- // JSON array framing makes the public-key boundaries unambiguous.
19
- return await hkdfSha256(shared, new Uint8Array(0), JSON.stringify([DOMAIN, epk, recipient]), 32);
20
- }
21
- finally {
22
- zero(shared);
23
- }
24
- };
25
4
  /** Caller retains ownership of plaintext; the temporary copy is wiped. */
26
- export const sealToPublicKey = async (binding, plaintext) => {
27
- const eph = await generateX25519Keypair();
28
- const key = await deriveKey(eph.privateKey, binding.recipientPublicKeyB64, eph.publicKeyB64, binding.recipientPublicKeyB64);
29
- const copy = new Uint8Array(plaintext);
30
- try {
31
- const nonce = randomBytes(12);
32
- return {
33
- v: 1,
34
- epk: eph.publicKeyB64,
35
- nonce: toB64(nonce),
36
- ct: toB64(await aesGcmEncrypt(key, nonce, copy, aad(binding))),
37
- };
38
- }
39
- finally {
40
- zero(key);
41
- zero(copy);
42
- }
43
- };
5
+ export const sealToPublicKey = async (binding, plaintext) => sealX25519({
6
+ domain: DOMAIN,
7
+ recipientB64: binding.recipientPublicKeyB64,
8
+ recipientBytes: decodeCanonicalB64(binding.recipientPublicKeyB64),
9
+ format: "spki",
10
+ aad: aad(binding),
11
+ plaintext,
12
+ });
44
13
  /** Caller owns the returned plaintext and must wipe it when finished. */
45
14
  export const openSealed = async (binding, sealed, privateKey) => {
46
15
  if (typeof sealed !== "object" || sealed === null || sealed.v !== 1)
47
16
  throw new Error("Invalid sealed envelope");
48
- const nonce = decode(sealed.nonce);
49
- const ct = decode(sealed.ct);
17
+ const nonce = decodeCanonicalB64(sealed.nonce);
18
+ const ct = decodeCanonicalB64(sealed.ct);
50
19
  if (nonce.length !== 12 || ct.length < 16 || typeof sealed.epk !== "string")
51
20
  throw new Error("Invalid sealed envelope");
52
- const key = await deriveKey(privateKey, sealed.epk, sealed.epk, binding.recipientPublicKeyB64);
53
- try {
54
- return await aesGcmDecrypt(key, nonce, ct, aad(binding));
55
- }
56
- finally {
57
- zero(key);
58
- }
21
+ return openX25519({
22
+ domain: DOMAIN,
23
+ privateKey,
24
+ recipientB64: binding.recipientPublicKeyB64,
25
+ epkBytes: decodeCanonicalB64(sealed.epk),
26
+ epkB64: sealed.epk,
27
+ format: "spki",
28
+ aad: aad(binding),
29
+ nonce,
30
+ ct,
31
+ });
59
32
  };
@@ -0,0 +1,3 @@
1
+ export declare const ROUTEBOX_HOME_HKDF_INFO = "openllm-routebox-home-v1";
2
+ /** Derive the box's home key; the caller must zero the returned bytes. */
3
+ export declare const deriveRouteboxHomeKey: (controlSeed: Uint8Array, keyId: string) => Promise<Uint8Array>;
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The routing box's home key: what opens its encrypted home (LUKS).
2
+ * The Routebox's home key: what opens its encrypted home (LUKS).
3
3
  *
4
4
  * Derived from the box API key's DEVICE ANCHOR secret — the per-key pair
5
5
  * secret `HKDF(device-control seed, key id)` (`device-anchor.ts`) that every
@@ -14,20 +14,20 @@
14
14
  *
15
15
  * Deliberately NOT re-exported from `vault/index.ts`: the `openllm` binary
16
16
  * imports that barrel, and a box only ever receives this key. Import it by
17
- * subpath: `@openllmsh/sdk/vault/routing-box-key`.
17
+ * subpath: `@openllmsh/sdk/vault/routebox-key`.
18
18
  */
19
19
  import { hkdfSha256, zero } from "./crypto.js";
20
20
  import { deriveDevicePairSecret } from "./device-anchor.js";
21
21
  import { DEVICE_CONTROL_SEED_BYTES } from "./device-control.js";
22
- export const ROUTING_BOX_HOME_HKDF_INFO = "openllm-routing-box-home-v1";
22
+ export const ROUTEBOX_HOME_HKDF_INFO = "openllm-routebox-home-v1";
23
23
  /** Derive the box's home key; the caller must zero the returned bytes. */
24
- export const deriveRoutingBoxHomeKey = async (controlSeed, keyId) => {
24
+ export const deriveRouteboxHomeKey = async (controlSeed, keyId) => {
25
25
  if (controlSeed.length !== DEVICE_CONTROL_SEED_BYTES) {
26
26
  throw new Error("invalid device-control seed length");
27
27
  }
28
28
  const pairSecret = await deriveDevicePairSecret(controlSeed, keyId);
29
29
  try {
30
- return await hkdfSha256(pairSecret, new Uint8Array(0), ROUTING_BOX_HOME_HKDF_INFO, 32);
30
+ return await hkdfSha256(pairSecret, new Uint8Array(0), ROUTEBOX_HOME_HKDF_INFO, 32);
31
31
  }
32
32
  finally {
33
33
  zero(pairSecret);
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Seal a routing box's unlock to the one-time token its current boot made.
2
+ * Seal a Routebox's unlock to the one-time token its current boot made.
3
3
  *
4
4
  * The box generates a fresh X25519 keypair on every boot and keeps the
5
5
  * private half in RAM (`/run`, tmpfs). The browser seals to the public half:
@@ -14,13 +14,13 @@
14
14
  *
15
15
  * Deliberately NOT re-exported from `vault/index.ts` (the `openllm` binary
16
16
  * imports that barrel). Import by subpath:
17
- * `@openllmsh/sdk/vault/routing-box-seal`.
17
+ * `@openllmsh/sdk/vault/routebox-seal`.
18
18
  *
19
19
  * The box side mirrors `open_unlock` in
20
- * `packages/api/lib/routing-box/box-agent.ts` (Python).
20
+ * `packages/api/lib/routebox/box-agent.ts` (Python).
21
21
  */
22
- export declare const ROUTING_BOX_SEAL_DOMAIN = "openllm-routing-box-seal-v1";
23
- export type TRoutingBoxSealBinding = {
22
+ export declare const ROUTEBOX_SEAL_DOMAIN = "openllm-routebox-seal-v1";
23
+ export type TRouteboxSealBinding = {
24
24
  readonly userId: string;
25
25
  readonly boxId: string;
26
26
  /** The box's API key; its home key derives from this key's anchor. */
@@ -31,7 +31,7 @@ export type TRoutingBoxSealBinding = {
31
31
  /** The boot's 32-byte challenge, base64. */
32
32
  readonly challengeB64: string;
33
33
  };
34
- export type TRoutingBoxEnvelope = {
34
+ export type TRouteboxEnvelope = {
35
35
  readonly v: 1;
36
36
  /** Ephemeral X25519 public key, base64 of the raw 32 bytes. */
37
37
  readonly epk: string;
@@ -44,13 +44,13 @@ export type TRoutingBoxEnvelope = {
44
44
  * control key, which WebRTC needs). Sent every time, so a box that failed
45
45
  * before installing it recovers on its next boot.
46
46
  */
47
- export type TRoutingBoxUnlock = {
47
+ export type TRouteboxUnlock = {
48
48
  readonly home_key: string;
49
49
  readonly api_key: string;
50
50
  };
51
51
  /** Canonical associated data; the Python side builds the same bytes. */
52
- export declare const routingBoxSealAad: (binding: TRoutingBoxSealBinding) => Uint8Array;
52
+ export declare const routeboxSealAad: (binding: TRouteboxSealBinding) => Uint8Array;
53
53
  /** Seal `unlock` to the boot in `binding`. */
54
- export declare const sealRoutingBoxUnlock: (binding: TRoutingBoxSealBinding, unlock: TRoutingBoxUnlock) => Promise<TRoutingBoxEnvelope>;
54
+ export declare const sealRouteboxUnlock: (binding: TRouteboxSealBinding, unlock: TRouteboxUnlock) => Promise<TRouteboxEnvelope>;
55
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>;
56
+ export declare const openRouteboxUnlock: (binding: TRouteboxSealBinding, envelope: TRouteboxEnvelope, bootPrivateKey: CryptoKey) => Promise<TRouteboxUnlock>;
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Seal a Routebox'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/routebox-seal`.
18
+ *
19
+ * The box side mirrors `open_unlock` in
20
+ * `packages/api/lib/routebox/box-agent.ts` (Python).
21
+ */
22
+ import { fromB64, toB64, zero } from "./crypto.js";
23
+ import { openX25519, sealX25519 } from "./x25519-seal.js";
24
+ export const ROUTEBOX_SEAL_DOMAIN = "openllm-routebox-seal-v1";
25
+ const encoder = new TextEncoder();
26
+ /** Canonical associated data; the Python side builds the same bytes. */
27
+ export const routeboxSealAad = (binding) => encoder.encode(JSON.stringify([
28
+ ROUTEBOX_SEAL_DOMAIN,
29
+ binding.userId,
30
+ binding.boxId,
31
+ binding.keyId,
32
+ binding.bootGeneration,
33
+ binding.bootPubkeyB64,
34
+ binding.challengeB64,
35
+ ]));
36
+ const raw32 = (b64, what) => {
37
+ const bytes = fromB64(b64);
38
+ if (bytes.length !== 32 || toB64(bytes) !== b64) {
39
+ throw new Error(`${what} must be base64 of 32 bytes`);
40
+ }
41
+ return bytes;
42
+ };
43
+ /** Seal `unlock` to the boot in `binding`. */
44
+ export const sealRouteboxUnlock = async (binding, unlock) => {
45
+ raw32(binding.challengeB64, "challenge");
46
+ const plaintext = encoder.encode(JSON.stringify(unlock));
47
+ try {
48
+ return await sealX25519({
49
+ domain: ROUTEBOX_SEAL_DOMAIN,
50
+ recipientB64: binding.bootPubkeyB64,
51
+ recipientBytes: raw32(binding.bootPubkeyB64, "boot public key"),
52
+ format: "raw",
53
+ aad: routeboxSealAad(binding),
54
+ plaintext,
55
+ });
56
+ }
57
+ finally {
58
+ zero(plaintext);
59
+ }
60
+ };
61
+ /** Open an envelope with the boot's private key (tests; the box uses Python). */
62
+ export const openRouteboxUnlock = async (binding, envelope, bootPrivateKey) => {
63
+ if (envelope.v !== 1)
64
+ throw new Error("unknown envelope version");
65
+ const plaintext = await openX25519({
66
+ domain: ROUTEBOX_SEAL_DOMAIN,
67
+ privateKey: bootPrivateKey,
68
+ recipientB64: binding.bootPubkeyB64,
69
+ epkBytes: raw32(envelope.epk, "ephemeral key"),
70
+ epkB64: envelope.epk,
71
+ format: "raw",
72
+ aad: routeboxSealAad(binding),
73
+ nonce: fromB64(envelope.nonce),
74
+ ct: fromB64(envelope.ct),
75
+ });
76
+ try {
77
+ const parsed = JSON.parse(new TextDecoder().decode(plaintext));
78
+ if (typeof parsed !== "object" ||
79
+ parsed === null ||
80
+ !("home_key" in parsed) ||
81
+ !("api_key" in parsed) ||
82
+ typeof parsed.home_key !== "string" ||
83
+ typeof parsed.api_key !== "string") {
84
+ throw new Error("malformed routebox unlock payload");
85
+ }
86
+ return { home_key: parsed.home_key, api_key: parsed.api_key };
87
+ }
88
+ finally {
89
+ zero(plaintext);
90
+ }
91
+ };
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The one ephemeral-X25519 + HKDF-SHA-256 + AES-256-GCM seal behind
3
+ * `public-key-seal.ts`, `cli-auth-seal.ts` and `routebox-seal.ts`.
4
+ *
5
+ * Callers differ only in their domain string, associated data and the
6
+ * encoding of the recipient / ephemeral public key (`spki` DER or `raw`
7
+ * 32 bytes); the key derivation and ciphertext layout are shared, so every
8
+ * wire format stays exactly as each seal documents it.
9
+ */
10
+ export type TX25519KeyFormat = "spki" | "raw";
11
+ export type TX25519Sealed = {
12
+ readonly v: 1;
13
+ readonly epk: string;
14
+ readonly nonce: string;
15
+ readonly ct: string;
16
+ };
17
+ /** The HKDF + ECDH half: both sides derive the same 32-byte AES key. */
18
+ export declare const deriveX25519SealKey: (params: {
19
+ readonly domain: string;
20
+ readonly privateKey: CryptoKey;
21
+ readonly peerKeyBytes: Uint8Array;
22
+ readonly peerFormat: TX25519KeyFormat;
23
+ readonly epkB64: string;
24
+ readonly recipientB64: string;
25
+ }) => Promise<Uint8Array>;
26
+ /** Seal `plaintext` to `recipientB64`; the caller keeps ownership of it. */
27
+ export declare const sealX25519: (params: {
28
+ readonly domain: string;
29
+ readonly recipientB64: string;
30
+ readonly recipientBytes: Uint8Array;
31
+ readonly format: TX25519KeyFormat;
32
+ readonly aad: Uint8Array;
33
+ readonly plaintext: Uint8Array;
34
+ }) => Promise<TX25519Sealed>;
35
+ /** Open an envelope; the caller owns the returned plaintext and wipes it. */
36
+ export declare const openX25519: (params: {
37
+ readonly domain: string;
38
+ readonly privateKey: CryptoKey;
39
+ readonly recipientB64: string;
40
+ readonly epkBytes: Uint8Array;
41
+ readonly epkB64: string;
42
+ readonly format: TX25519KeyFormat;
43
+ readonly aad: Uint8Array;
44
+ readonly nonce: Uint8Array;
45
+ readonly ct: Uint8Array;
46
+ }) => Promise<Uint8Array>;
47
+ /** Strict canonical-base64 decode shared by the SPKI-format seals. */
48
+ export declare const decodeCanonicalB64: (value: unknown) => Uint8Array;
@@ -0,0 +1,78 @@
1
+ /**
2
+ * The one ephemeral-X25519 + HKDF-SHA-256 + AES-256-GCM seal behind
3
+ * `public-key-seal.ts`, `cli-auth-seal.ts` and `routebox-seal.ts`.
4
+ *
5
+ * Callers differ only in their domain string, associated data and the
6
+ * encoding of the recipient / ephemeral public key (`spki` DER or `raw`
7
+ * 32 bytes); the key derivation and ciphertext layout are shared, so every
8
+ * wire format stays exactly as each seal documents it.
9
+ */
10
+ import { aesGcmDecrypt, aesGcmEncrypt, fromB64, hkdfSha256, randomBytes, toB64, zero, } from "./crypto.js";
11
+ /** The HKDF + ECDH half: both sides derive the same 32-byte AES key. */
12
+ export const deriveX25519SealKey = async (params) => {
13
+ const peer = await crypto.subtle.importKey(params.peerFormat, params.peerKeyBytes, { name: "X25519" }, false, []);
14
+ const shared = new Uint8Array(await crypto.subtle.deriveBits({ name: "X25519", public: peer }, params.privateKey, 256));
15
+ try {
16
+ // JSON array framing makes the public-key boundaries unambiguous.
17
+ return await hkdfSha256(shared, new Uint8Array(0), JSON.stringify([params.domain, params.epkB64, params.recipientB64]), 32);
18
+ }
19
+ finally {
20
+ zero(shared);
21
+ }
22
+ };
23
+ /** Seal `plaintext` to `recipientB64`; the caller keeps ownership of it. */
24
+ export const sealX25519 = async (params) => {
25
+ const eph = (await crypto.subtle.generateKey({ name: "X25519" }, false, [
26
+ "deriveBits",
27
+ ]));
28
+ const epk = toB64(new Uint8Array(await crypto.subtle.exportKey(params.format, eph.publicKey)));
29
+ const key = await deriveX25519SealKey({
30
+ domain: params.domain,
31
+ privateKey: eph.privateKey,
32
+ peerKeyBytes: params.recipientBytes,
33
+ peerFormat: params.format,
34
+ epkB64: epk,
35
+ recipientB64: params.recipientB64,
36
+ });
37
+ const copy = new Uint8Array(params.plaintext);
38
+ try {
39
+ const nonce = randomBytes(12);
40
+ return {
41
+ v: 1,
42
+ epk,
43
+ nonce: toB64(nonce),
44
+ ct: toB64(await aesGcmEncrypt(key, nonce, copy, params.aad)),
45
+ };
46
+ }
47
+ finally {
48
+ zero(key);
49
+ zero(copy);
50
+ }
51
+ };
52
+ /** Open an envelope; the caller owns the returned plaintext and wipes it. */
53
+ export const openX25519 = async (params) => {
54
+ const key = await deriveX25519SealKey({
55
+ domain: params.domain,
56
+ privateKey: params.privateKey,
57
+ peerKeyBytes: params.epkBytes,
58
+ peerFormat: params.format,
59
+ epkB64: params.epkB64,
60
+ recipientB64: params.recipientB64,
61
+ });
62
+ try {
63
+ return await aesGcmDecrypt(key, params.nonce, params.ct, params.aad);
64
+ }
65
+ finally {
66
+ zero(key);
67
+ }
68
+ };
69
+ /** Strict canonical-base64 decode shared by the SPKI-format seals. */
70
+ export const decodeCanonicalB64 = (value) => {
71
+ if (typeof value !== "string" ||
72
+ !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
73
+ throw new Error("Invalid sealed envelope encoding");
74
+ const bytes = fromB64(value);
75
+ if (toB64(bytes) !== value)
76
+ throw new Error("Invalid sealed envelope encoding");
77
+ return bytes;
78
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openllmsh/sdk",
3
- "version": "2.10.19-alpha.0",
3
+ "version": "2.10.19-alpha.2",
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": [
@@ -1,7 +0,0 @@
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";
@@ -1,7 +0,0 @@
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";
@@ -1,3 +0,0 @@
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>;