@openllmsh/sdk 0.0.0-stage → 2.10.12-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.
Files changed (245) hide show
  1. package/ARCHITECTURE.md +43 -0
  2. package/LICENSE +202 -0
  3. package/README.md +142 -2
  4. package/assets/openllm-light.svg +18 -0
  5. package/assets/openllm.svg +18 -0
  6. package/client/chat.ts +140 -0
  7. package/client/devices.ts +269 -0
  8. package/client/http.ts +72 -0
  9. package/client/index.ts +129 -0
  10. package/client/relay-mux.ts +547 -0
  11. package/client/types.ts +51 -0
  12. package/client/vault.ts +239 -0
  13. package/connect/chat.ts +58 -0
  14. package/connect/client.ts +240 -0
  15. package/connect/config.ts +47 -0
  16. package/connect/errors.ts +121 -0
  17. package/connect/index.ts +23 -0
  18. package/connect/oauth.ts +265 -0
  19. package/connect/routes.ts +234 -0
  20. package/connect/store.ts +107 -0
  21. package/mcp/handle.ts +24 -0
  22. package/mcp/index.ts +76 -0
  23. package/mcp/server.ts +319 -0
  24. package/mcp/tools/marketplace.ts +439 -0
  25. package/mcp/tools/memory-client.ts +297 -0
  26. package/mcp/tools/memory-config.ts +32 -0
  27. package/mcp/tools/memory.ts +369 -0
  28. package/mcp/tools/model-priority.ts +88 -0
  29. package/mcp/tools/openllm.ts +883 -0
  30. package/mcp/types.ts +28 -0
  31. package/openapi/call.ts +90 -0
  32. package/openapi/index.ts +8 -0
  33. package/openapi/openapi.json +80213 -0
  34. package/openapi/operations.ts +2075 -0
  35. package/package.json +39 -4
  36. package/protocol/CONTRIBUTING.md +21 -0
  37. package/protocol/README.md +134 -0
  38. package/protocol/access.ts +186 -0
  39. package/protocol/agent-prompt-text.ts +32 -0
  40. package/protocol/agent.ts +991 -0
  41. package/protocol/api-key-syntax.ts +105 -0
  42. package/protocol/assets/openllm-light.svg +18 -0
  43. package/protocol/assets/openllm.svg +18 -0
  44. package/protocol/audio.ts +29 -0
  45. package/protocol/auth.ts +142 -0
  46. package/protocol/changelog.ts +155 -0
  47. package/protocol/chat.ts +458 -0
  48. package/protocol/client-registry.ts +356 -0
  49. package/protocol/config.ts +345 -0
  50. package/protocol/control-channel.ts +115 -0
  51. package/protocol/cooldown-reason.ts +78 -0
  52. package/protocol/cost.ts +10 -0
  53. package/protocol/daemon-port.ts +31 -0
  54. package/protocol/daemon.ts +1524 -0
  55. package/protocol/default-chains.ts +66 -0
  56. package/protocol/device-state.ts +85 -0
  57. package/protocol/doctor-report-local.ts +443 -0
  58. package/protocol/doctor-report-policy.ts +119 -0
  59. package/protocol/doctor-report.ts +947 -0
  60. package/protocol/errors.ts +14 -0
  61. package/protocol/execution-selection.ts +141 -0
  62. package/protocol/hop-grant.ts +33 -0
  63. package/protocol/image-edit-parse.ts +263 -0
  64. package/protocol/images.ts +298 -0
  65. package/protocol/index.ts +74 -0
  66. package/protocol/inference-headers.ts +3 -0
  67. package/protocol/keepalive.ts +69 -0
  68. package/protocol/local-auth.ts +300 -0
  69. package/protocol/local-device-control.ts +133 -0
  70. package/protocol/local-provider.ts +288 -0
  71. package/protocol/local-session.ts +118 -0
  72. package/protocol/marketplace.ts +187 -0
  73. package/protocol/media-attempt.ts +81 -0
  74. package/protocol/media-bytes.ts +28 -0
  75. package/protocol/media-default.ts +357 -0
  76. package/protocol/media-dimensions.ts +132 -0
  77. package/protocol/media-input.ts +61 -0
  78. package/protocol/media-model.ts +142 -0
  79. package/protocol/media-option-issue.ts +90 -0
  80. package/protocol/media-types.ts +70 -0
  81. package/protocol/model-match.ts +1051 -0
  82. package/protocol/model-settings.ts +327 -0
  83. package/protocol/models.ts +767 -0
  84. package/protocol/mux.ts +722 -0
  85. package/protocol/plan-surface.ts +59 -0
  86. package/protocol/provider-models.ts +16 -0
  87. package/protocol/provider-status.ts +206 -0
  88. package/protocol/provider-tier.ts +67 -0
  89. package/protocol/provider-usage.ts +263 -0
  90. package/protocol/providers.ts +901 -0
  91. package/protocol/public-usage-index.ts +354 -0
  92. package/protocol/realtime-generated.ts +31 -0
  93. package/protocol/realtime.ts +324 -0
  94. package/protocol/registry-pointer.ts +118 -0
  95. package/protocol/relay.ts +702 -0
  96. package/protocol/replay-session.ts +11 -0
  97. package/protocol/responses.ts +280 -0
  98. package/protocol/semver.ts +182 -0
  99. package/protocol/setup-mode.ts +22 -0
  100. package/protocol/sha256-hex.ts +98 -0
  101. package/protocol/stats.ts +406 -0
  102. package/protocol/streaming.ts +19 -0
  103. package/protocol/subscription-daemon-floors.ts +33 -0
  104. package/protocol/subscription-provider-compat.ts +104 -0
  105. package/protocol/subscription-provider.ts +32 -0
  106. package/protocol/team-grant.ts +17 -0
  107. package/protocol/team-shareable.ts +61 -0
  108. package/protocol/transcription-encoding.ts +76 -0
  109. package/protocol/url-locality-dns.ts +37 -0
  110. package/protocol/url-locality.ts +288 -0
  111. package/protocol/usage-snapshots.ts +9 -0
  112. package/protocol/vendor-cli-install.ts +29 -0
  113. package/protocol/video-job-plan.ts +50 -0
  114. package/protocol/videos.ts +227 -0
  115. package/tsconfig.json +14 -0
  116. package/tunnel/ARCHITECTURE.md +111 -0
  117. package/tunnel/LICENSE +33 -0
  118. package/tunnel/README.md +45 -0
  119. package/tunnel/assets/openllm-light.svg +18 -0
  120. package/tunnel/assets/openllm.svg +18 -0
  121. package/tunnel/channel-envelope.ts +139 -0
  122. package/tunnel/codec.ts +191 -0
  123. package/tunnel/device-anchor.ts +229 -0
  124. package/tunnel/device-control.ts +118 -0
  125. package/tunnel/device-grant.ts +173 -0
  126. package/tunnel/fleet.ts +77 -0
  127. package/tunnel/index.ts +22 -0
  128. package/tunnel/mux.ts +580 -0
  129. package/tunnel/peer-link.ts +390 -0
  130. package/tunnel/rtc-auth.ts +415 -0
  131. package/tunnel/rtc-duplex.ts +187 -0
  132. package/tunnel/rtc-ice.ts +136 -0
  133. package/tunnel/secure.ts +1298 -0
  134. package/tunnel/stream-reset-error.ts +14 -0
  135. package/tunnel/streams.ts +1430 -0
  136. package/tunnel/team-grant.ts +302 -0
  137. package/tunnel/wire-bytes.ts +102 -0
  138. package/vault/ARCHITECTURE.md +470 -0
  139. package/vault/LICENSE +33 -0
  140. package/vault/api-key.ts +190 -0
  141. package/vault/argon2.ts +106 -0
  142. package/vault/cli-auth-seal.ts +157 -0
  143. package/vault/cred-seal.ts +146 -0
  144. package/vault/credential.ts +55 -0
  145. package/vault/crypto.ts +210 -0
  146. package/vault/daemon-attest.ts +229 -0
  147. package/vault/derive.ts +113 -0
  148. package/vault/device-access.ts +87 -0
  149. package/vault/device-anchor.ts +185 -0
  150. package/vault/device-control.ts +174 -0
  151. package/vault/handoff.ts +396 -0
  152. package/vault/index.ts +21 -0
  153. package/vault/passkey.ts +243 -0
  154. package/vault/phrase.ts +65 -0
  155. package/vault/pin.ts +153 -0
  156. package/vault/public-key-seal.ts +131 -0
  157. package/vault/seed.ts +272 -0
  158. package/vault/team.ts +355 -0
  159. package/vault/vault-item.ts +131 -0
  160. package/vault/vault-migrate-digest.ts +29 -0
  161. package/vault/wrapped.ts +77 -0
  162. package/wire/ARCHITECTURE.md +90 -0
  163. package/wire/CONTRIBUTING.md +19 -0
  164. package/wire/LICENSE +33 -0
  165. package/wire/README.md +51 -0
  166. package/wire/adapters/messages/anthropic-map.ts +37 -0
  167. package/wire/adapters/messages/index.ts +7 -0
  168. package/wire/adapters/messages/reasoning-from-items.ts +38 -0
  169. package/wire/adapters/messages/reasoning-signature.ts +243 -0
  170. package/wire/adapters/messages/request.ts +574 -0
  171. package/wire/adapters/messages/response.ts +215 -0
  172. package/wire/adapters/messages/streaming.ts +1027 -0
  173. package/wire/adapters/messages/usage.ts +43 -0
  174. package/wire/adapters/responses/index.ts +3 -0
  175. package/wire/adapters/responses/request.ts +395 -0
  176. package/wire/adapters/responses/response.ts +88 -0
  177. package/wire/adapters/responses/streaming.ts +344 -0
  178. package/wire/assets/openllm-light.svg +18 -0
  179. package/wire/assets/openllm.svg +18 -0
  180. package/wire/features/account-rank.ts +166 -0
  181. package/wire/features/compaction/compact-request.ts +862 -0
  182. package/wire/features/compaction/compaction-text.ts +43 -0
  183. package/wire/features/context-demote.ts +47 -0
  184. package/wire/features/context-overflow-strategy.ts +26 -0
  185. package/wire/features/context-skip.ts +170 -0
  186. package/wire/features/conversation-affinity.ts +144 -0
  187. package/wire/features/max-tokens-backfill.ts +141 -0
  188. package/wire/features/model-caps.ts +53 -0
  189. package/wire/features/model-settings.ts +24 -0
  190. package/wire/features/output-limit-clamp.ts +64 -0
  191. package/wire/features/quota-gate.ts +85 -0
  192. package/wire/index.ts +44 -0
  193. package/wire/lib/attempt-outcome.ts +43 -0
  194. package/wire/lib/canonical/content-part.ts +38 -0
  195. package/wire/lib/canonical/count-tokens-capability.ts +138 -0
  196. package/wire/lib/canonical/encoding-select.ts +82 -0
  197. package/wire/lib/canonical/image-signature.ts +202 -0
  198. package/wire/lib/canonical/image-sse.ts +216 -0
  199. package/wire/lib/canonical/message.ts +43 -0
  200. package/wire/lib/canonical/token-estimate.ts +266 -0
  201. package/wire/lib/encrypted-content.ts +66 -0
  202. package/wire/lib/error-class.ts +154 -0
  203. package/wire/lib/error-envelope.ts +56 -0
  204. package/wire/lib/forwarded-headers.ts +180 -0
  205. package/wire/lib/provider-error-rules.ts +48 -0
  206. package/wire/lib/refusal.ts +38 -0
  207. package/wire/lib/responses-apply-patch.ts +104 -0
  208. package/wire/lib/responses-namespace.ts +53 -0
  209. package/wire/lib/secret-scrub.ts +101 -0
  210. package/wire/lib/streaming/accumulate.ts +221 -0
  211. package/wire/lib/streaming/finish-reason.ts +33 -0
  212. package/wire/lib/streaming/peek.ts +154 -0
  213. package/wire/lib/streaming/provider-decode.ts +259 -0
  214. package/wire/lib/streaming/response-stream.ts +71 -0
  215. package/wire/lib/streaming/sse.ts +699 -0
  216. package/wire/lib/streaming/strip-tool-calls.ts +95 -0
  217. package/wire/lib/streaming/upstream-error.ts +58 -0
  218. package/wire/lib/strip-subagent-isolation.ts +284 -0
  219. package/wire/lib/thinking-signature.ts +156 -0
  220. package/wire/lib/token-ruler/bpe-core.ts +426 -0
  221. package/wire/lib/token-ruler/index.ts +2 -0
  222. package/wire/lib/token-ruler/ruler.ts +79 -0
  223. package/wire/lib/token-ruler/vocab/claude-ranks.ts +16 -0
  224. package/wire/lib/token-ruler/vocab/claude.ts +22 -0
  225. package/wire/lib/token-ruler/vocab/o200k-ranks.ts +18 -0
  226. package/wire/lib/token-ruler/vocab/o200k.ts +19 -0
  227. package/wire/lib/tool-name-map.ts +271 -0
  228. package/wire/lib/tool-schema.ts +353 -0
  229. package/wire/lib/usage-observer.ts +125 -0
  230. package/wire/providers/anthropic/adaptive-thinking.ts +291 -0
  231. package/wire/providers/anthropic/beta-headers.ts +165 -0
  232. package/wire/providers/anthropic/index.ts +10 -0
  233. package/wire/providers/anthropic/request.ts +607 -0
  234. package/wire/providers/anthropic/response.ts +155 -0
  235. package/wire/providers/anthropic/streaming.ts +315 -0
  236. package/wire/providers/anthropic/web-search-domains.ts +49 -0
  237. package/wire/providers/chatgpt/common.ts +136 -0
  238. package/wire/providers/chatgpt/index.ts +9 -0
  239. package/wire/providers/chatgpt/request.ts +959 -0
  240. package/wire/providers/chatgpt/streaming.ts +1007 -0
  241. package/wire/providers/chatgpt/web-search.ts +63 -0
  242. package/wire/providers/grok/web-search.ts +87 -0
  243. package/wire/providers/kimi/web-search.ts +145 -0
  244. package/wire/providers/upstream-deny.ts +355 -0
  245. package/wire/providers/upstream-request.ts +619 -0
@@ -0,0 +1,470 @@
1
+ # `packages/sdk/vault` Architecture
2
+
3
+ > Zero-knowledge crypto — pure bytes-in/bytes-out primitives that run
4
+ > identically in the browser and on the proxy. Depends on nothing
5
+ > app-specific. Provider credentials are client-encrypted at rest; the proxy
6
+ > decrypts them only transiently for an authenticated upstream request.
7
+
8
+ Referenced from the root [`ARCHITECTURE.md`](../../ARCHITECTURE.md).
9
+
10
+ ---
11
+
12
+ ## Modules
13
+
14
+ ```
15
+ vault/
16
+ crypto.ts — WebCrypto AES-256-GCM + HKDF-SHA256 + b64/b64url + zero()
17
+ argon2.ts — Argon2id wrap-key derivation, params registry keyed by version
18
+ wrapped.ts — sealed-blob layout: IV||ct, plus the `v<n>:` KDF stamp
19
+ seed.ts — THE vault secret: seed ↔ phrase, seed → DEK / vault_key_id
20
+ (HKDF), key-tree branch/leaf keys, passkey seed seal
21
+ vault-item.ts— seal/open an item under its branch (and leaf) of the tree;
22
+ `k1:` nonce tag, untagged = legacy root (until the sunset)
23
+ vault-migrate-digest.ts — row digest shared by browser and server for the
24
+ one-time update and rotation
25
+ derive.ts — LEGACY: buildVault / unlockDek (phrase → DEK via wrapped_dek)
26
+ credential.ts— encrypt/decrypt a credential row under the DEK
27
+ api-key.ts — sk-llm parse + HKDF api-wrap-key + dek_for_key un/wrap + mint
28
+ device-access.ts — Ed25519 SPKI encoding + device-grant sign / verify
29
+ device-control.ts— the account device-control key (phrase → Ed25519, never
30
+ from the DEK), rotation sign/verify, control-keep outer key
31
+ daemon-attest.ts — control-signed attestation of a daemon X25519 key (dpk)
32
+ handoff.ts — device handoff: X25519 seal of the SEED to a new device, its
33
+ binding, the anchor check (`vault_key_id`), the 6-digit code
34
+ cli-auth-seal.ts — seal an ordinary sk-llm API key to a CLI caller's ephemeral
35
+ X25519 pubkey (CLI OpenLLM OAuth handover; distinct domain/AAD
36
+ from the connector seal so ciphertexts are not interchangeable)
37
+ passkey.ts — LEGACY WebAuthn-PRF DEK wrap (seed vaults seal the seed: seed.ts)
38
+ phrase.ts · pin.ts (deriveVaultState lives in lib/vault/state.ts)
39
+ team.ts — user-held team key T: seal under DEK, invite wrap, K_mem, memory seal
40
+ index.ts
41
+ ```
42
+
43
+ ## Seed-only vault (current)
44
+
45
+ Design and decisions: [`docs/plans/seed-only-vault.md`](../../docs/plans/seed-only-vault.md).
46
+ The sections after this one describe the LEGACY vault, which stays readable
47
+ only until the sunset (`docs/todo/remove-legacy-vault-migration.md`).
48
+
49
+ - **One secret.** The seed is the 12-word phrase's 16-byte BIP39 entropy
50
+ (`seed.ts`). Everything is derived from it with HKDF, nothing derived is
51
+ stored: the vault root key (DEK), the public `users.vault_key_id` (the
52
+ server's check that a phrase or a handed-off seed is this vault's), and the
53
+ device-control key (`device-control.ts`, unchanged from legacy for the same
54
+ phrase).
55
+ - **Stored only sealed, only under a method.** A PIN (`seed_pin_v1:`, Argon2id,
56
+ this browser) or a passkey (`user_passkeys.sealed_seed`, PRF output → HKDF,
57
+ AAD-bound to the credential and `vault_key_id`, plus a local cache
58
+ `seed_passkey_v1:`). `session.openSeed(seed, method)` is the only way in and
59
+ requires a method; the unlocked session is `session_v4:` under a
60
+ non-extractable IndexedDB key. The phrase is shown again by opening the seed
61
+ with the PIN or passkey (Settings → Vault, `/get-started`), never from a
62
+ stored copy.
63
+ - **Key tree.** Items are sealed under a branch of the root (`credentials`,
64
+ `memory/<integration>`, `chats/<session id>`, `apps`, `teams`, `keys`) with a
65
+ `k1:` nonce tag (`vault-item.ts`). Every API key's `dek_for_key` wraps the
66
+ whole root, so by default every key reads what any other wrote; narrowing
67
+ is opt-in and never changes leaf ids.
68
+ - **One-time update / rotation** (`/api/vault/migrate/*`,
69
+ `lib/vault/migrate.ts`). A legacy vault is re-sealed once from its random
70
+ root to the seed's root (seed = the phrase the user already has) on a
71
+ blocking screen; a seed vault rotates the same way to a NEW seed. Rows are
72
+ paged, re-sealed, verified and staged with the digest of the row they
73
+ replace; the commit swaps all of them in one transaction or refuses
74
+ (`migration_incomplete`). API keys keep their strings (re-wrapped, not
75
+ revoked). The control key is re-published at the new version with its
76
+ device attestations re-signed (rotation also signs `old → new`).
77
+ - **Handoff** carries the seed; the new device checks it against
78
+ `vault_key_id`, then chooses a PIN or passkey before `openSeed`.
79
+
80
+ ## Zero-knowledge vault (legacy)
81
+
82
+ Provider credentials are never persisted in plaintext or sent plaintext
83
+ when saved from the browser. The proxy receives plaintext only after it
84
+ transiently decrypts an authenticated request's credential. The crypto is
85
+ in `packages/sdk/vault` (browser- and proxy-compatible, pure bytes-in/bytes-out):
86
+
87
+ - A **recovery phrase** → `wrap_key` via **Argon2id** (`argon2.ts`,
88
+ salt = `wrap_salt`). The Argon2id parameters are an **append-only
89
+ registry keyed by version**, and every wrapped blob is stamped with the
90
+ version that produced it (`wrapped.ts`, `v<n>:<base64>`). Editing a
91
+ parameter in place would change every derived `wrap_key` and, with no
92
+ server-side escape hatch, permanently lock out every existing vault —
93
+ so re-tuning means adding a version, never changing one. An unstamped
94
+ blob is v1.
95
+ - A random 32-byte **DEK** is AES-GCM-wrapped under `wrap_key` →
96
+ `wrapped_dek`. Only `wrap_salt` + `wrapped_dek` are stored on
97
+ `users`; the phrase and DEK never touch the DB in the clear (the
98
+ phrase is stored only sealed under a passkey's PRF output, see
99
+ "Passkey wraps" below).
100
+ - Credentials are AES-256-GCM encrypted under the DEK in the browser
101
+ before `POST /api/credentials`; the row stores `{ ciphertext, nonce,
102
+ vault_version }`.
103
+
104
+ **API keys carry the DEK, not a hash.** `mintApiKey` (client-side)
105
+ picks `(id, secret)`, derives `api_wrap_key = HKDF(secret, salt=id,
106
+ info="api-key-v1")`, wraps the DEK → `dek_for_key`, and also wraps the
107
+ full `sk-llm-{id}.{secret}` string under the DEK (`secret_ciphertext`)
108
+ so an unlocked dashboard can re-display it. At mint time the server
109
+ receives the public key id and metadata plus only wrapped secret material;
110
+ the token itself is sent in an authenticated request header. On each `/v1/*` request,
111
+ `validateApiKey` looks up the row by id, checks
112
+ `key.vault_version === user.vault_version`, re-derives `api_wrap_key`,
113
+ and AES-GCM-unwraps `dek_for_key` to recover the DEK — an auth-tag
114
+ failure (wrong secret) returns 401. The proxy decrypts the provider
115
+ credential with that DEK, then `zero()`s it in `finally`.
116
+
117
+ ### Device-control key (seedgate trust root)
118
+
119
+ Device grants, daemon attestations and their rotations are signed by ONE
120
+ account **device-control key**, Ed25519, derived in the browser from the
121
+ recovery phrase:
122
+
123
+ ```
124
+ entropy = BIP39 entropy(normalizePhrase(phrase)) // checksum-checked
125
+ seed = HKDF-SHA256(entropy, salt="openllm-device-control-salt-v1",
126
+ info="openllm-device-control-v1", 32)
127
+ ```
128
+
129
+ It is never derived from the DEK and never wrapped for an API key, because the
130
+ server unwraps the DEK from `dek_for_key` on every `sk-llm` request: a key the
131
+ DEK can produce is a key a compromised cloud can sign with. (The previous
132
+ per-key `HKDF(DEK, key_id)` seed was deleted for exactly that reason.) HKDF,
133
+ not Argon2id: the phrase already carries 128 bits, and HKDF keeps every
134
+ server-supplied input (`wrap_salt`, KDF version) out of the key. Callers derive
135
+ only from a phrase they have proven (`unlockDek`, an accepted handoff).
136
+
137
+ The server stores only public material: `users.device_control_pubkey`
138
+ (+ `device_control_version`, the signed `device_control_rotations` chain), each
139
+ provisioned `api_keys.device_access_pubkey` (= the control key; the column
140
+ name is historical), and `daemon_attestations` rows. Each signed message is
141
+ `label || 0x00 || json`:
142
+
143
+ - grant — `openllm-device-grant-v1` (`@openllmsh/sdk/tunnel` `device-grant.ts`);
144
+ - attestation — `openllm-daemon-attest-v1`, `{v, user_id, key_id, dpk, cv, ts}`
145
+ (`daemon-attest.ts`): key_id-bound cache of a proof-verified daemon X25519
146
+ key; any browser verifies it with its OWN derived key before using
147
+ that `dpk` for grants, Noise and the RTC seal;
148
+ - rotation — `openllm-device-control-rotate-v2`, `{v:2, old, new, cv}`, signed
149
+ by `old`, no timestamp (`@openllmsh/sdk/tunnel` `device-control.ts`): stored and
150
+ replayed to daemons that were offline when the phrase rotated.
151
+
152
+ In a browser the seed lives at rest only under the same local unlock as the
153
+ DEK session — the "control keep" (`controlKeepOuterKey(dek, userId)` outside a
154
+ non-extractable per-browser IndexedDB key; `lib/vault/control-keep.ts`). A
155
+ passkey is only an alternative to the PIN for unlocking the vault DEK; it does
156
+ not wrap the control seed. Opening the DEK (PIN or passkey) restores the seed
157
+ from the control keep. The server cannot open the keep. Daemons pin the public
158
+ key from the install-time trust anchor, a signed rotation, or the desktop app
159
+ over loopback — never trust-on-first-use for agent sessions
160
+ (`packages/cli/daemon/src/device-access-verify.ts`).
161
+
162
+ `device-anchor.ts` is the browser half of that anchor: `buildDeviceAnchor` /
163
+ `buildAnchoredApiKey` (`base64url(control raw || HKDF(seed, utf8(key_id),
164
+ "openllm-pair-v1"))`, appended to the key in the command the user copies),
165
+ `verifyDpkProof` (the daemon's `HMAC(pair_secret, "openllm-dpk-proof-v1" ||
166
+ key_id || dpk)` — checked before any `dpk` is trusted), and
167
+ `signDeviceSessionsDisable` (the control-signed remote DISABLE only —
168
+ re-enable writes the anchor again via install / update / login / desktop).
169
+
170
+ ## Vault state machine (legacy)
171
+
172
+ `vault_state` (derived by `deriveVaultState` in `lib/vault/state.ts`) is one of
173
+ `uninitialized → pending_phrase → ready`, plus `reset_pending`. The
174
+ transitions are driven by the `/api/vault/*` handlers (see
175
+ [`packages/api`](../api/ARCHITECTURE.md)), operating on the vault columns
176
+ of `public.users`:
177
+
178
+ - `begin` (uninitialized→pending_phrase): stage `wrap_salt`.
179
+ - `commit` (pending_phrase→ready): save `wrapped_dek`, bump
180
+ `vault_version` 0→1. TOCTOU-guarded (`WHERE wrapped_dek IS NULL`).
181
+ - `abandon` (pending_phrase→uninitialized): clear staging if the phrase
182
+ was lost between steps.
183
+ - `reset/begin` (ready→reset_pending): stage `*_next` columns + optional
184
+ re-encrypted credentials at `vault_version+1`, in one txn. Proxy keeps
185
+ reading the current generation until commit. From `reset_pending` it
186
+ REPLACES the stale staging (dropping that staging's `vault_version+1`
187
+ credentials): a staged phrase only lives in the dialog that made it, so a
188
+ staging found later is one nobody can finish.
189
+ - `reset/commit`: optionally names the staging it means
190
+ (`staged_wrapped_dek`); a mismatch — another tab's `begin` replaced it —
191
+ is a 409 `reset_conflict` that promotes nothing. Otherwise: promote `*_next`, drop old-generation credentials,
192
+ bump `vault_version`, **hard-delete all API keys** (their
193
+ `dek_for_key` wraps the now-stale DEK), and **hard-delete all saved
194
+ memories** (`public.embeddings` rows with `integration = 'memory'` —
195
+ encrypted under the old DEK and never staged/re-encrypted across a
196
+ rotation; see "DEK-encrypted memories" below). It also best-effort
197
+ deletes input-media blobs and their ledger rows because their encrypted
198
+ chat transcripts are now orphaned; generated/library media remains.
199
+ - `reset/abort`: drop `*_next` + the staged `vault_version+1`
200
+ credentials, return to `ready`.
201
+ - `reset/commit` also deletes every passkey wrap (`user_passkeys`) — each
202
+ seals the old DEK. See "Passkey wraps" below.
203
+
204
+ The browser-side DEK session lives in `lib/vault/session.tsx`, over the
205
+ persistence layer in `lib/vault/session-store.ts`. **The DEK is never at
206
+ rest in a readable form.** `localStorage` holds three blobs and no key
207
+ material: the PIN-wrapped DEK (Argon2id), a time-limited unlock
208
+ session wrapped under a **non-extractable `CryptoKey`** kept in
209
+ IndexedDB — the browser will not export those bytes to any caller, so a
210
+ profile-directory dump recovers nothing — and the **phrase keep**
211
+ (`lib/vault/phrase-keep.ts`): the recovery phrase AES-GCM-sealed under
212
+ the DEK, written by `unlock(dek, { phrase })` at the three moments the
213
+ phrase is in memory (creation, a phrase unlock, a rotation commit) and
214
+ read only by Settings → Vault, which unwraps the DEK from the PIN blob
215
+ with the PIN just typed and opens the keep with that — never with the
216
+ live session DEK. The keep grants exactly what the DEK already grants,
217
+ lives on the device alone (the server never sees the ciphertext), and
218
+ follows the PIN blob's lifecycle: it survives `lock()` and dies with
219
+ `forgetDevice()`. It is what let the setup flow drop its three-words-back
220
+ backup quiz. Every failure to open the session wrap (no IndexedDB, no
221
+ WebCrypto, key destroyed) degrades to "no session", i.e. the PIN prompt.
222
+
223
+ The session auto-locks at expiry, zeroes its in-memory DEK on lock,
224
+ forget-device and unmount, and **propagates across tabs**: each teardown
225
+ clears a `localStorage` key and a `storage` listener mirrors the lock,
226
+ the forget, the stale-DEK flag and a fresh unlock into every other open
227
+ tab. `lib/vault/device-access-cache.ts` holds the device-control seed for
228
+ grant signing, cleared on those same lifecycle events. `components/vault/{pin-flow,
229
+ require-unlocked,vault-lock-pill}` gate UI that needs an unlocked vault.
230
+
231
+ ## CLI OpenLLM OAuth seal
232
+
233
+ `cli-auth-seal.ts` seals a plaintext `sk-llm-…` API key to the waiting CLI's
234
+ ephemeral X25519 public key during browser approve
235
+ ([`docs/plan/2026-11-01-cli-install-onboarding.md`](../../docs/plan/2026-11-01-cli-install-onboarding.md)
236
+ §2). Envelope shape matches the connector seal (ephemeral X25519 →
237
+ HKDF-SHA256 → AES-256-GCM), but the HKDF domain and AAD bind
238
+ `openllm-cli-auth-seal-v1` + `userId` + `authorizationId` + recipient pubkey, so
239
+ connector and CLI ciphertext are not interchangeable. The server stores only
240
+ the JSON envelope in `cli_authorizations.sealed_key` and cannot open it. The
241
+ CLI unwraps on claim with its private key; claim retries return the same
242
+ envelope until the original authorization expiry. No OAuth access/refresh
243
+ tokens are sealed or retained — only the ordinary user-owned API key.
244
+
245
+ ## Device handoff (legacy payload)
246
+
247
+ A device with no PIN blob (the desktop app, another browser) can get the vault
248
+ from one of the account's unlocked devices instead of the recovery phrase
249
+ (`handoff.ts`; design, protocol and threat model in
250
+ [`docs/plans/vault-device-handoff.md`](../../docs/plans/vault-device-handoff.md)).
251
+ The new device mints an ephemeral X25519 key and posts its public half; the
252
+ unlocked device, after the user compares a six-digit code derived from the
253
+ server-chosen request id and that key, and pays its own unlock method (PIN or
254
+ passkey), seals `{ dek, phrase }` with `X25519 → HKDF-SHA256(salt = request
255
+ id, info = [user, request, vault_version, both public keys]) → AES-256-GCM`.
256
+ The new device re-derives the DEK from the phrase against `users.wrapped_dek`
257
+ before accepting it (`acceptHandoff`), which is what stops a session-cookie
258
+ holder from handing it a DEK of its own; a payload without a phrase is
259
+ refused, so only devices that keep the phrase are asked to approve. The server
260
+ (`/api/vault/handoff/*`, browser-session only) stores public keys, a token
261
+ hash and ciphertext — nothing that opens.
262
+
263
+ ## Passkey wraps (WebAuthn PRF) (legacy DEK wrap)
264
+
265
+ The third DEK wrapper, beside the phrase and the PIN
266
+ (`docs/plans/passkey-vault-unlock.md`):
267
+
268
+ | Wrapper | Input | KDF | Stored | Unlocks |
269
+ | --- | --- | --- | --- | --- |
270
+ | Phrase | 12 words (~128 bits) | Argon2id | `users.wrapped_dek` | any device |
271
+ | PIN | 4/6 digits | Argon2id | this browser only | the device that set it |
272
+ | Passkey | PRF output (256 bits) | HKDF-SHA256 | `user_passkeys.wrapped_dek` (+ the phrase in `sealed_phrase`) | any device the passkey syncs to |
273
+
274
+ - Per credential a random 32-byte `prf_salt` is evaluated as
275
+ `prf.eval.first`; `wrap_key = HKDF-SHA256(prfOutput, salt = prf_salt,
276
+ info = "openllm-vault-passkey-v1", 32)`; the DEK is AES-256-GCM sealed as
277
+ base64 `IV || ct+tag`, with **AAD = info | credential id | vault_version**
278
+ so a relabelled or swapped row fails its tag instead of yielding a DEK the
279
+ session would stamp with the wrong generation. No Argon2: the input is
280
+ 256 bits from the authenticator, so unlock is instant.
281
+ - **Server-side is safe here, unlike a PIN** (`docs/plans/vault-pin-unlock.md`
282
+ §2): without the authenticator there is no PRF output to guess, so a
283
+ database leak yields ciphertext plus a public salt. The server never
284
+ verifies an assertion and stores no public key — possession of a row grants
285
+ nothing.
286
+ - **A passkey is a full local unlock method.** The session keeps a per-account
287
+ *passkey link* (`lib/vault/passkey-link.ts`: credential id + generation, no
288
+ key material) with the PIN blob's lifecycle (survives `lock()`, dies with
289
+ `forgetDevice()`). The single readiness predicate is `needsLocalUnlock =
290
+ DEK in memory ∧ ¬(PIN blob ∨ passkey link)`, read by `<RequireUnlocked>`,
291
+ the unlock / setup / rotate dialogs, `useVaultReadiness` and the onboarding
292
+ wizard. A passkey-only device therefore needs no PIN: within the
293
+ keep-unlocked window the DEK rehydrates from the non-extractable IndexedDB
294
+ wrap exactly as before; after it, one passkey ceremony re-enters. The link is
295
+ a pointer, not a local copy of the wrap, so revoking a passkey in Settings
296
+ revokes it on every device at once (the cost: a passkey unlock needs the
297
+ network, which reading `vault_state` already does).
298
+ - **Onboarding commits on arrival; the unlock method comes after.** The
299
+ getting-ready screen (`<StepGettingReady>`) commits the staged vault with NO
300
+ local unlock method (`useCreateVault.commit`) and lets the user in
301
+ (`docs/plans/onboarding-deferred-unlock.md`). The commit files a *secure
302
+ deferral* record on that device (`lib/vault/secure-deferral.ts`, timestamps
303
+ only), and `isSecureDeferred` (the record ∧ no method) decides three things:
304
+ the session holds it OPEN (`HELD_OPEN_UNTIL_TS`: no auto-lock, survives
305
+ reloads), so the DEK never lapses into "only the phrase gets you back in";
306
+ `<RequireUnlocked>` and `useVaultReadiness` serve it; and the UI's Lock asks
307
+ for a method first (`useLockVault`), then locks once one is set. The first
308
+ method clears the record and re-stamps the chosen window; so do `lock()`,
309
+ `forgetDevice()` and any unlock under another vault generation (a reset or
310
+ rotation elsewhere), and a record that cannot be stored grants nothing. The
311
+ three gates read one predicate, `canServeVault`. Any other device with no method (a phrase or
312
+ handoff unlock) keeps its normal window, locks normally, and still meets
313
+ `set` mode at the gate. `<UnlockMethodPrompt>` (app shell) asks — banner, then a
314
+ modal that cannot be dismissed on a second visit or after three days. The
315
+ dashboard's `<VaultSetupDialog>` still commits on the PIN or passkey
316
+ (`save` / `savePasskey`), ceremony BEFORE `/api/vault/commit`.
317
+ - **Phrase reveal** (Settings → Vault) pays the device's own method: the PIN
318
+ unwraps the PIN blob, or a passkey ceremony unwraps a private DEK from the
319
+ passkey wrap (or opens the passkey's own sealed copy, below); the reveal
320
+ never reads the live session DEK.
321
+ - **The phrase rides on the passkey too** (`user_passkeys.sealed_phrase`,
322
+ `docs/plans/vault-phrase-sync.md`): `sealPhraseWithPrf` seals it under
323
+ `HKDF(prfOutput, salt = prf_salt, info = "openllm-vault-passkey-phrase-v1")`
324
+ with the same AAD shape, so any device the passkey syncs to can show the
325
+ words after a ceremony, without a local keep. **Never under the DEK**: the
326
+ server holds the DEK transiently on every `sk-llm` request
327
+ (`dek_for_key`), and the phrase is more than the DEK — it derives the
328
+ device-control seed the server must never reach.
329
+ - **Filed only where the flow proved the person:** vault creation and the
330
+ rotation re-file (the phrase was just minted; rotation's confirm step pays
331
+ the method); adding a passkey on a PIN device, which now REQUIRES the PIN
332
+ (`TPasskeyEnrollProof` — the keep is opened with the DEK unwrapped from
333
+ the PIN blob, not the session's); adding a first method on a device with
334
+ none; and a passkey unlock backfilling an empty row **through the passkey
335
+ this device is already linked to**. Never on `link()`, never through
336
+ another passkey of the account, never on a second passkey added to a
337
+ passkey-only device. The add/link paths open the local keep with a DEK
338
+ the session already holds (`withDek`), which is why each is gated above.
339
+ - The backfill PATCH is fill-only and generation-fenced (`sealed_phrase IS
340
+ NULL AND vault_version = :v`), so a tab with a stale list can't replace a
341
+ fresher copy. A re-enroll without the field clears the old copy.
342
+ - **A passkey can reach the device-control seed.** Reading the copy never
343
+ installs the phrase locally, but whoever can open it can read the words and
344
+ type them into "Verify this browser". So every passkey that holds a copy
345
+ is as strong as the phrase itself; the gates above exist for that reason.
346
+ Not a backup: losing every device and the passkey loses this copy too.
347
+ - Rotation: `reset/commit` deletes every `user_passkeys` row. The rotate
348
+ flow (`lib/hooks/use-vault-rotation.ts`) keeps THIS device's method across
349
+ the switch without asking for a new one: it mints the new DEK when the
350
+ dialog opens, and its confirm step — the device's PIN or passkey — proves
351
+ the method AND seals the new DEK under it (`wrapDekWithPin`, or
352
+ `usePasskeyRewrap`: one assertion, wrap bound to `vault_version+1`). After
353
+ the commit the PIN blob is installed with `unlock`, or the passkey wrap is
354
+ re-filed (an upsert by credential id) and linked. Passkeys on other devices
355
+ need turning on again. A device with neither is let in and asked later
356
+ (`deferLocalUnlock`). `rp.id` is the production apex (`openllm.sh`, shared by `www` and
357
+ `dev`); `localhost` and preview hosts mint their own credentials.
358
+ - Residual risk, accepted: onboarding defers the phrase backup, so a user
359
+ who deletes their only passkey from the OS keychain before saving the
360
+ phrase (or adding a PIN) must reset the vault — the same class of risk as a
361
+ forgotten PIN today, and narrower, because the passkey syncs. Deferring the
362
+ unlock method adds one more: an unsecured device that loses its browser
363
+ data (or is forgotten) before a method is chosen has only the phrase,
364
+ which the user has not saved yet — a reset. The held-open session means a
365
+ lapse never causes it, and the forced prompt bounds how long it can last.
366
+ Separately, an unsecured device stays unlocked with no time bound until a
367
+ method exists; at rest the DEK is still ciphertext under the
368
+ non-extractable IndexedDB key, so this widens who can use an unattended
369
+ browser, not what is on disk.
370
+
371
+ ## DEK-encrypted memories
372
+
373
+ Saved memories (OpenLLM Memory rows in `public.embeddings`)
374
+ are AES-256-GCM encrypted **at rest** under the same DEK, reusing
375
+ `encryptCredential` / `decryptCredential`: `content` holds base64
376
+ ciphertext, `content_nonce` the base64 nonce, `vault_version` the DEK
377
+ generation (`content_nonce IS NULL` ⇒ legacy plaintext row, lazily
378
+ encrypted by a background sweep on the next DEK-bearing request).
379
+ Because every `sk-llm` key from the same phrase wraps the same DEK, a
380
+ memory saved through key A is readable through key B for free.
381
+
382
+ **This is at-rest encryption, not zero-knowledge** — weaker than the
383
+ credential story above, equal to the `/v1/*` trust level:
384
+
385
+ - Memory plaintext transits the server (and Bedrock, for embedding)
386
+ inside a request window opened by a valid key; the DEK is `zero()`d
387
+ in the dispatcher's `finally`.
388
+ - **The embedding vector stays plaintext** — pgvector similarity search
389
+ cannot run over ciphertext. A 1024-d vector leaks semantic content
390
+ (embedding-inversion attacks reconstruct approximate text): anyone
391
+ with DB access learns *what a memory is about*, not its wording.
392
+ - Session-cookie reads (the dashboard) carry no DEK server-side; the
393
+ API returns ciphertext + `encrypted: true` and the browser decrypts
394
+ with the unlocked vault session.
395
+ - Rotation wipes memories rather than re-encrypting them: re-encrypt
396
+ would need old and new DEK live server-side simultaneously (or an
397
+ unbounded browser round-trip). Wipe matches the rotation's existing
398
+ blast radius ("all API keys revoked").
399
+
400
+ ## Team key graph
401
+
402
+ User-held team encryption (`team.ts`; `docs/plan/2026-10-26-teams.md` §9).
403
+ OpenLLM never sees T in plaintext. The graph is one-way: team material cannot
404
+ open personal rows.
405
+
406
+ ```
407
+ personal DEK ──seal──► team_members.sealed_team_key (T)
408
+ invite secret ─HKDF(auth info)──► auth (base64url) ──sha256──► token_hash
409
+ invite secret ─HKDF(wrap info)──► wrap key ──seal──► team_invites.wrapped_team_key (T)
410
+ T ─HKDF──► K_mem ──seal──► embeddings.content (team rows)
411
+ T ─HKDF──► K_cred ──seal──► team share credential (inner layer)
412
+ ▲
413
+ server K_srv wraps that as outer layer
414
+ (HMAC-SHA256 of host signing secret;
415
+ packages/api/lib/team-cred-wrap.ts)
416
+ ```
417
+
418
+ - **Create (browser, vault unlocked):** `generateTeamKey()` → seal T under the
419
+ owner's DEK (`sealTeamKey`) → persist `sealed_team_key`. Invite links carry
420
+ a fragment secret that **never leaves the browser**. From it the browser
421
+ derives two independent HKDF outputs with distinct info labels:
422
+ `auth = deriveTeamInviteAuth(secret, invite_id)` (info
423
+ `openllm-team-invite-auth-v1`, posted as the request `auth` field; server
424
+ stores only `sha256(auth)` as `token_hash`) and
425
+ `wrap = deriveTeamInviteWrapKey(secret, invite_id)` (info
426
+ `openllm-team-invite-v1`, used only to build
427
+ `wrapped_team_key = wrapTeamKeyForInvite(secret, invite_id, T)`). The create
428
+ response is id-only — the client builds `/join#<id>.<secret>` itself.
429
+ - **Join (vault unlocked):** browser derives `auth` again for preview/join
430
+ POSTs, then `unwrapTeamKeyFromInvite` (wrap key stays local) →
431
+ `sealTeamKey` under the joiner's DEK. Joining without an unlocked vault
432
+ cannot seal a copy. From everything the server sees or stores
433
+ (`invite_id`, `auth`, `token_hash`, `wrapped_team_key`, `key_version`)
434
+ unwrapping T fails.
435
+ - **Request / memory path:** DEK → `openTeamKey` → T → `deriveTeamMemKey` →
436
+ `K_mem`. Team-row encrypt/decrypt (`encryptTeamMemory` /
437
+ `decryptTeamMemory`) accept **only** `K_mem`, never the personal DEK.
438
+ - **API-key share path (inner layer):** DEK → `openTeamKey` → T →
439
+ `deriveTeamCredKey` → `K_cred`. The supplier's browser decrypts its own
440
+ credential blob under the personal DEK, then re-encrypts under `K_cred`
441
+ with AAD binding `(team_id, share_id, provider, key_version)` via
442
+ `encryptTeamCredential`. The server wraps that packed inner ciphertext
443
+ under per-share `K_srv` before storage (`team_shares.payload_ciphertext`).
444
+ At request time the member opens T the same way; the server removes the
445
+ outer layer; `K_cred` removes the inner. Neither layer alone opens the
446
+ credential. `NEON_AUTH_COOKIE_SECRET` absent → sharing fails closed
447
+ (`team_credential_unavailable`).
448
+ - **Domain separation:** invite auth info `openllm-team-invite-auth-v1`;
449
+ invite wrap info `openllm-team-invite-v1`; memory info
450
+ `openllm-team-mem-v1`; credential info `openllm-team-cred-v1`. Auth ≠ wrap
451
+ key ≠ `K_mem` ≠ `K_cred` ≠ DEK ≠ `K_srv`. Personal credentials, personal
452
+ memory, and `api_keys.dek_for_key` / `secret_ciphertext` stay under the
453
+ personal DEK (or the API-key wrap key); T / `K_mem` / `K_cred` / invite
454
+ wrap fail GCM auth on them. Each team's T is independent — T₁ cannot open
455
+ T₂'s sealed copy, memories, or credential shares. A former member with T
456
+ but without the server outer layer gets nothing.
457
+ - **Vault reset:** clears this account's `sealed_team_key` copies only. Team
458
+ ciphertext and other members' seals remain. Re-join (or re-seal from an
459
+ unlocked device that still holds T) restores access.
460
+ - **Zeroing:** callers `zero()` T, `K_mem`, and `K_cred` after use (same
461
+ hygiene as the personal DEK).
462
+
463
+ Isolation is enforced by `tests/vault/team-key-isolation.test.ts` and
464
+ `tests/vault/team-invite-auth-wrap.test.ts` against the real primitives (no
465
+ crypto stubs).
466
+
467
+ ## Layering rules
468
+
469
+ - `packages/sdk/vault` depends on nothing app-specific. Pure bytes-in/bytes-out
470
+ primitives run identically in the browser and on the proxy.
package/vault/LICENSE ADDED
@@ -0,0 +1,33 @@
1
+ Business Source License 1.1
2
+
3
+ Licensor: OpenLLM, INC
4
+ Licensed Work: OpenLLM Vault
5
+ The Licensed Work is (c) 2026 OpenLLM, INC.
6
+ Additional Use Grant: You may use the Licensed Work for internal business purposes, personal use, development, testing, evaluation, non-production deployments, and self-hosted production deployments that are not offered to third parties as a hosted, managed, or paid service that competes with OpenLLM or any substantially similar AI model gateway, proxy, credential-management, routing, memory, indexing, or inference orchestration product or service. In addition, further uses may be listed and defined at https://github.com/openllmsh/license-grants.
7
+ Change Date: The earlier of the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work, or a date specified at https://github.com/openllmsh/license-grants.
8
+ Change License: MIT License
9
+
10
+ Terms
11
+
12
+ The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above, permitting limited production use.
13
+
14
+ Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the Change License, and the rights granted in the paragraph above terminate.
15
+
16
+ If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase a commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
17
+
18
+ All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work and the Change Date may vary for each version of the Licensed Work released by Licensor.
19
+
20
+ You must conspicuously display this License on each original or modified copy of the Licensed Work. If you receive the Licensed Work in original or modified form from any third party, you must retain all copyright, patent, trademark, and attribution notices contained in the Licensed Work.
21
+
22
+ Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
23
+
24
+ This License does not grant you any right in any trademark or logo of Licensor or its affiliates.
25
+
26
+ TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
27
+
28
+ Business Source License 1.1 Parameters
29
+
30
+ Licensor: OpenLLM, INC
31
+ Licensed Work: OpenLLM Vault
32
+ Change Date: The earlier of the fourth anniversary of first publication, or a date specified at https://github.com/openllmsh/license-grants.
33
+ Change License: MIT License