@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,76 @@
1
+ import type { TDefaultChainRankable } from "./default-chains";
2
+ import { orderDefaultChainMembers } from "./default-chains";
3
+ import type { TMediaAudioInputFormat } from "./media-default";
4
+ import { inspectMediaAudioInputFormat } from "./media-default";
5
+ import type { TExtendedModel } from "./models";
6
+ import { MEDIA_DEFAULT_CLASS } from "./models";
7
+
8
+ export type TTranscriptionEncoding = "wav16k" | "wav_generic" | "raw";
9
+
10
+ /**
11
+ * Choose how to encode a recording for catalog-declared
12
+ * `audio_support.input_formats`.
13
+ *
14
+ * - `wav_pcm16_16khz_mono` → exact mono 16kHz PCM16 WAV conversion.
15
+ * - Any other declared set (e.g. `webm_opus` only) → forward raw bytes.
16
+ * - No declared formats → historical generic WAV.
17
+ */
18
+ export const chooseTranscriptionEncoding = (
19
+ inputFormats: ReadonlyArray<string> | undefined,
20
+ ): TTranscriptionEncoding => {
21
+ if (inputFormats === undefined) return "wav_generic";
22
+ if (inputFormats.includes("wav_pcm16_16khz_mono")) return "wav16k";
23
+ return "raw";
24
+ };
25
+
26
+ const recorderFormat = (recorderMime: string): TMediaAudioInputFormat =>
27
+ inspectMediaAudioInputFormat({ contentType: recorderMime });
28
+
29
+ /**
30
+ * Whether this model's declared formats can consume a browser recording
31
+ * of `recorderMime` — convert paths are always compatible; raw paths
32
+ * require a positive format match.
33
+ */
34
+ export const transcriptionCompatibleWithRecorder = (
35
+ inputFormats: ReadonlyArray<string> | undefined,
36
+ recorderMime: string,
37
+ ): boolean => {
38
+ const encoding = chooseTranscriptionEncoding(inputFormats);
39
+ if (encoding === "wav16k" || encoding === "wav_generic") return true;
40
+ const proven = recorderFormat(recorderMime);
41
+ if (proven === "unknown") return false;
42
+ return inputFormats?.includes(proven) ?? false;
43
+ };
44
+
45
+ export type TTranscriptionSelectable = TDefaultChainRankable &
46
+ Pick<TExtendedModel, "audio_support">;
47
+
48
+ /**
49
+ * Catalog-ranked transcription pick for the browser mic: same
50
+ * `deriveMediaDefaultModels` order, then first hop compatible with the
51
+ * recorder MIME (raw vs convert).
52
+ */
53
+ export const pickRankedTranscriptionModel = <
54
+ T extends TTranscriptionSelectable,
55
+ >(
56
+ cards: ReadonlyArray<T>,
57
+ recorderMime: string,
58
+ ): T | null => {
59
+ const ordered = orderDefaultChainMembers(
60
+ cards,
61
+ undefined,
62
+ MEDIA_DEFAULT_CLASS,
63
+ "transcription",
64
+ );
65
+ for (const card of ordered) {
66
+ if (
67
+ transcriptionCompatibleWithRecorder(
68
+ card.audio_support?.input_formats,
69
+ recorderMime,
70
+ )
71
+ ) {
72
+ return card;
73
+ }
74
+ }
75
+ return null;
76
+ };
@@ -0,0 +1,37 @@
1
+ import {
2
+ isForbiddenResolvedAddress,
3
+ preflightRemoteEndpoint,
4
+ } from "./url-locality";
5
+
6
+ /**
7
+ * Resolve a syntactically non-local URL and accept it only when every DNS
8
+ * answer is globally routable. Node-only: it imports `node:dns/promises`, so it
9
+ * lives outside the package index (`@openllmsh/sdk/protocol/url-locality-dns`) to
10
+ * keep edge/browser bundles that import the protocol root free of `node:dns`.
11
+ *
12
+ * This validation must be invoked directly before each hosted fetch. Standard
13
+ * Fetch (undici / Bun) does not expose a portable DNS-pin primitive that
14
+ * connects to the resolved address while preserving Host + TLS SNI, so the
15
+ * established defence is: preflight DNS here, then `redirect: "manual"` with
16
+ * revalidation of every Location before the next hop. A true
17
+ * connect-to-resolved-IP path would require a custom dispatcher and is out of
18
+ * scope for the portable fetch surface this codebase targets.
19
+ */
20
+ export const isSafeRemoteEndpoint = async (url: string): Promise<boolean> => {
21
+ const preflight = preflightRemoteEndpoint(url);
22
+ if ("safe" in preflight) return preflight.safe;
23
+ try {
24
+ const dns = await import("node:dns/promises");
25
+ const answers = await dns.lookup(preflight.resolve, {
26
+ all: true,
27
+ verbatim: true,
28
+ });
29
+ return (
30
+ answers.length > 0 &&
31
+ answers.every((answer) => !isForbiddenResolvedAddress(answer.address))
32
+ );
33
+ } catch {
34
+ // A failed lookup cannot establish that an upstream is safe: fail closed.
35
+ return false;
36
+ }
37
+ };
@@ -0,0 +1,288 @@
1
+ /**
2
+ * Classifiers and validation for custom upstream URLs.
3
+ *
4
+ * `isLocalEndpoint` is intentionally a pure, synchronous classifier: browser
5
+ * routing and daemon-local code need to answer whether a literal URL names the
6
+ * local network without doing DNS. Hosted code must use
7
+ * `isSafeRemoteEndpoint` immediately before connecting; it resolves public
8
+ * names and rejects answers in non-public address space.
9
+ */
10
+
11
+ /** `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`. */
12
+ const isRfc1918 = (o: ReadonlyArray<number>): boolean => {
13
+ const [a, b] = o as [number, number, number, number];
14
+ if (a === 10) return true;
15
+ if (a === 172 && b >= 16 && b <= 31) return true;
16
+ if (a === 192 && b === 168) return true;
17
+ return false;
18
+ };
19
+
20
+ const parseIpv4 = (host: string): ReadonlyArray<number> | null => {
21
+ const parts = host.split(".");
22
+ if (parts.length !== 4) return null;
23
+ const octets: Array<number> = [];
24
+ for (const part of parts) {
25
+ if (!/^\d{1,3}$/.test(part)) return null;
26
+ const n = Number(part);
27
+ if (n > 255) return null;
28
+ octets.push(n);
29
+ }
30
+ return octets;
31
+ };
32
+
33
+ /**
34
+ * Remove trailing slashes and an optional trailing `/v1` segment.
35
+ */
36
+ const normalizeHostRoot = (raw: string): string => {
37
+ const hostRoot = raw.replace(/\/+$/, "");
38
+ return hostRoot.replace(/\/v1$/, "");
39
+ };
40
+
41
+ /**
42
+ * Same as `normalizeHostRoot`, plus optional `/v1beta` stripping for image
43
+ * endpoints that may use Google-compatible discovery paths.
44
+ */
45
+ const normalizeHostRootForImage = (raw: string): string =>
46
+ raw
47
+ .replace(/\/+$/, "")
48
+ .replace(/\/v1beta$/, "")
49
+ .replace(/\/v1$/, "");
50
+
51
+ /**
52
+ * Options for custom base URL normalization.
53
+ */
54
+ type TNormalizeBaseUrlOptions = {
55
+ readonly trimWhitespace?: boolean;
56
+ };
57
+
58
+ /**
59
+ * Normalize a user-pasted custom base URL for OpenAI-style custom endpoints.
60
+ */
61
+ export const normalizeBaseUrl = (
62
+ raw: string,
63
+ options: TNormalizeBaseUrlOptions = {},
64
+ ): string => {
65
+ const normalized = options.trimWhitespace === true ? raw.trim() : raw;
66
+ return normalizeHostRoot(normalized);
67
+ };
68
+
69
+ /**
70
+ * Normalize a user-pasted custom base URL for image-style custom endpoints.
71
+ */
72
+ export const normalizeImageBaseUrl = (
73
+ raw: string,
74
+ options: TNormalizeBaseUrlOptions = {},
75
+ ): string => {
76
+ const normalized = options.trimWhitespace === true ? raw.trim() : raw;
77
+ return normalizeHostRootForImage(normalized);
78
+ };
79
+
80
+ /**
81
+ * WHATWG URL keeps IPv6 brackets in `hostname`. Lower-case it and remove the
82
+ * single root-label dot that denotes the same DNS name (`localhost.`).
83
+ */
84
+ const normalizeHost = (raw: string): string => {
85
+ const lower = raw.trim().toLowerCase();
86
+ const bare =
87
+ lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
88
+ return bare.endsWith(".") ? bare.slice(0, -1) : bare;
89
+ };
90
+
91
+ const isLocalIpv4 = (o: ReadonlyArray<number>): boolean => {
92
+ const [a, b] = o as [number, number, number, number];
93
+ if (a === 127) return true;
94
+ if (a === 0) return true;
95
+ if (a === 169 && b === 254) return true;
96
+ return isRfc1918(o);
97
+ };
98
+
99
+ const isForbiddenIpv4 = (o: ReadonlyArray<number>): boolean => {
100
+ const [a, b, c] = o as [number, number, number, number];
101
+ if (isLocalIpv4(o)) return true;
102
+ // Carrier-grade NAT, benchmark, documentation, multicast, and reserved
103
+ // ranges are not public Internet targets and must not be SSRF destinations.
104
+ // Match the reserved blocks exactly — do not over-block neighbouring
105
+ // public space under the same /16 (e.g. 192.0.1.0/24 is public, only
106
+ // 192.0.0.0/24 and 192.0.2.0/24 are reserved; likewise 198.51.100.0/24,
107
+ // not 198.51.0.0/16).
108
+ if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT
109
+ if (a === 192 && b === 0 && c === 0) return true; // 192.0.0.0/24 IETF Protocol Assignments
110
+ if (a === 192 && b === 0 && c === 2) return true; // 192.0.2.0/24 TEST-NET-1
111
+ if (a === 192 && b === 88 && c === 99) return true; // 192.88.99.0/24 6to4 anycast (deprecated)
112
+ if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 benchmark
113
+ if (a === 198 && b === 51 && c === 100) return true; // 198.51.100.0/24 TEST-NET-2
114
+ if (a === 203 && b === 0 && c === 113) return true; // 203.0.113.0/24 TEST-NET-3
115
+ return a >= 224; // multicast + reserved
116
+ };
117
+
118
+ const isLocalIpv6 = (host: string): boolean => {
119
+ const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(host);
120
+ if (mapped !== null) {
121
+ const embedded = parseIpv4(mapped[1] as string);
122
+ return embedded !== null && isLocalIpv4(embedded);
123
+ }
124
+ const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
125
+ if (mappedHex !== null) {
126
+ const hi = Number.parseInt(mappedHex[1] as string, 16);
127
+ const lo = Number.parseInt(mappedHex[2] as string, 16);
128
+ return isLocalIpv4([hi >> 8, hi & 0xff, lo >> 8, lo & 0xff]);
129
+ }
130
+ if (host === "::1" || host === "::") return true;
131
+ if (/^fe[89ab][0-9a-f]:/.test(host)) return true;
132
+ if (/^f[cd][0-9a-f]{0,2}:/.test(host)) return true;
133
+ return false;
134
+ };
135
+
136
+ /**
137
+ * Expand a textual IPv6 address (no brackets, no dotted v4 tail) into 8
138
+ * hextets. Returns null when the form is unparseable.
139
+ */
140
+ const parseIpv6Hextets = (host: string): ReadonlyArray<number> | null => {
141
+ if (host.includes(".")) return null;
142
+ const sides = host.split("::");
143
+ if (sides.length > 2) return null;
144
+ const parseSide = (side: string): Array<number> | null => {
145
+ if (side.length === 0) return [];
146
+ const parts = side.split(":");
147
+ const out: Array<number> = [];
148
+ for (const part of parts) {
149
+ if (!/^[0-9a-f]{1,4}$/.test(part)) return null;
150
+ out.push(Number.parseInt(part, 16));
151
+ }
152
+ return out;
153
+ };
154
+ if (sides.length === 1) {
155
+ const all = parseSide(sides[0] as string);
156
+ return all !== null && all.length === 8 ? all : null;
157
+ }
158
+ const left = parseSide(sides[0] as string);
159
+ const right = parseSide(sides[1] as string);
160
+ if (left === null || right === null) return null;
161
+ const fill = 8 - left.length - right.length;
162
+ if (fill < 1) return null;
163
+ return [...left, ...Array.from({ length: fill }, () => 0), ...right];
164
+ };
165
+
166
+ const ipv4FromHextetPair = (hi: number, lo: number): ReadonlyArray<number> => [
167
+ hi >> 8,
168
+ hi & 0xff,
169
+ lo >> 8,
170
+ lo & 0xff,
171
+ ];
172
+
173
+ const isForbiddenIpv6 = (host: string): boolean => {
174
+ if (isLocalIpv6(host)) return true;
175
+ // IPv4-mapped dotted form (::ffff:a.b.c.d) — apply the v4 policy to the
176
+ // embedded address (CGNAT / docs / multicast, not only RFC1918).
177
+ const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(host);
178
+ if (mapped !== null) {
179
+ const embedded = parseIpv4(mapped[1] as string);
180
+ return embedded !== null && isForbiddenIpv4(embedded);
181
+ }
182
+ const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
183
+ if (mappedHex !== null) {
184
+ const hi = Number.parseInt(mappedHex[1] as string, 16);
185
+ const lo = Number.parseInt(mappedHex[2] as string, 16);
186
+ return isForbiddenIpv4(ipv4FromHextetPair(hi, lo));
187
+ }
188
+ // IPv4-compatible addresses are obsolete, but still permit a textual v4
189
+ // tail in some resolvers. Treat them conservatively.
190
+ if (/^::(?:[0-9a-f]{1,4}:)?[0-9a-f]+:[0-9a-f]+$/.test(host)) return true;
191
+ // IPv6 documentation space (2001:db8::/32) is reserved.
192
+ if (host.startsWith("2001:db8:")) return true;
193
+ // 6to4 (2002::/16) is a deprecated transition mechanism — never a safe
194
+ // hosted SSRF target even when the embedded v4 looks public.
195
+ if (host.startsWith("2002:")) return true;
196
+
197
+ const hextets = parseIpv6Hextets(host);
198
+ if (hextets === null) {
199
+ // Fail closed on multicast / NAT64 textual prefixes we couldn't expand.
200
+ if (/^ff[0-9a-f]{0,2}:/.test(host)) return true;
201
+ if (host.startsWith("64:ff9b:")) return true;
202
+ return false;
203
+ }
204
+ const first = hextets[0] as number;
205
+ // Multicast ff00::/8.
206
+ if ((first & 0xff00) === 0xff00) return true;
207
+ // NAT64 well-known prefix 64:ff9b::/96 — last 32 bits are the embedded v4.
208
+ if (
209
+ first === 0x64 &&
210
+ hextets[1] === 0xff9b &&
211
+ hextets[2] === 0 &&
212
+ hextets[3] === 0 &&
213
+ hextets[4] === 0 &&
214
+ hextets[5] === 0
215
+ ) {
216
+ return isForbiddenIpv4(
217
+ ipv4FromHextetPair(hextets[6] as number, hextets[7] as number),
218
+ );
219
+ }
220
+ return false;
221
+ };
222
+
223
+ /** True when `host` names local/private/link-local network space. */
224
+ export const isLocalHostname = (rawHost: string): boolean => {
225
+ const host = normalizeHost(rawHost);
226
+ if (host.length === 0) return true;
227
+ if (host === "localhost" || host.endsWith(".localhost")) return true;
228
+ if (host === "local" || host.endsWith(".local")) return true;
229
+ const v4 = parseIpv4(host);
230
+ if (v4 !== null) return isLocalIpv4(v4);
231
+ if (host.includes(":")) return isLocalIpv6(host);
232
+ return false;
233
+ };
234
+
235
+ /**
236
+ * True when `url` is unparseable, or its literal host is loopback / private /
237
+ * link-local / mDNS. This intentionally does not resolve DNS.
238
+ */
239
+ export const isLocalEndpoint = (url: string): boolean => {
240
+ let parsed: URL;
241
+ try {
242
+ parsed = new URL(url);
243
+ } catch {
244
+ return true;
245
+ }
246
+ return isLocalHostname(parsed.hostname);
247
+ };
248
+
249
+ export const isForbiddenResolvedAddress = (address: string): boolean => {
250
+ const normalized = normalizeHost(address);
251
+ const v4 = parseIpv4(normalized);
252
+ if (v4 !== null) return isForbiddenIpv4(v4);
253
+ return normalized.includes(":") ? isForbiddenIpv6(normalized) : true;
254
+ };
255
+
256
+ /**
257
+ * The DNS-free half of `isSafeRemoteEndpoint` (in `url-locality-dns.ts`):
258
+ * a verdict when the URL alone decides it, otherwise the hostname to resolve.
259
+ * Kept here so this module stays importable from edge/browser bundles.
260
+ */
261
+ export const preflightRemoteEndpoint = (
262
+ url: string,
263
+ ): { readonly safe: boolean } | { readonly resolve: string } => {
264
+ let parsed: URL;
265
+ try {
266
+ parsed = new URL(url);
267
+ } catch {
268
+ return { safe: false };
269
+ }
270
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
271
+ return { safe: false };
272
+ }
273
+ if (parsed.username.length > 0 || parsed.password.length > 0) {
274
+ return { safe: false };
275
+ }
276
+ if (isLocalHostname(parsed.hostname)) return { safe: false };
277
+ const literal = normalizeHost(parsed.hostname);
278
+ if (parseIpv4(literal) !== null || literal.includes(":")) {
279
+ return { safe: !isForbiddenResolvedAddress(literal) };
280
+ }
281
+ return { resolve: literal };
282
+ };
283
+
284
+ /** Error code every refusal path returns, so clients can branch on it. */
285
+ export const LOCAL_ENDPOINT_ERROR_CODE = "local_endpoint_requires_daemon";
286
+
287
+ export const localEndpointMessage = (url: string): string =>
288
+ `"${url}" points at a local or private network address. The hosted gateway runs on Vercel — its localhost is not your machine, so it can never reach this endpoint. Local models (Ollama, LM Studio, llama.cpp) are served by the OpenLLM daemon running on your own machine; register and use them with the daemon running and the request never leaves the box.`;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Shared quota-observation retention bound. The calibration estimator reads a
3
+ * 45-day window; keeping 60 days leaves debugging slack while bounding history.
4
+ * Every writer, sweeper, and reader uses this same horizon so a delayed cached
5
+ * observation cannot outlive or re-enter calibration through another path.
6
+ */
7
+ export const USAGE_SNAPSHOT_RETENTION_DAYS = 60;
8
+ export const USAGE_SNAPSHOT_RETENTION_MS =
9
+ USAGE_SNAPSHOT_RETENTION_DAYS * 24 * 60 * 60 * 1000;
@@ -0,0 +1,29 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ /** A successful installer still needs a subsequent CLI presence probe. */
4
+ export const VENDOR_CLI_DETECTION_GRACE_MS = 2 * 60_000;
5
+ /** Old persisted progress is not evidence that an installer is still running. */
6
+ export const VENDOR_CLI_INSTALL_STALE_MS = 30 * 60_000;
7
+ /**
8
+ * Browser vs device clock lead tolerated for install timestamps. A small
9
+ * positive skew must not drop an active job to "missing" (and surface a
10
+ * duplicate install command); larger leads stay invalid.
11
+ */
12
+ export const VENDOR_CLI_INSTALL_CLOCK_SKEW_MS = 60_000;
13
+
14
+ /** Metadata for vendor installers started by OpenLLM, not external installs. */
15
+ export const VendorCliInstall = S.Struct({
16
+ attempt_id: S.String.check(S.isMinLength(1), S.isMaxLength(128)),
17
+ stage: S.Literals([
18
+ "installing",
19
+ "awaiting_detection",
20
+ "failed",
21
+ "interrupted",
22
+ ]),
23
+ started_at_ms: S.Int.check(S.isGreaterThanOrEqualTo(0)),
24
+ updated_at_ms: S.Int.check(S.isGreaterThanOrEqualTo(0)),
25
+ reason: S.optional(
26
+ S.Literals(["installer_failed", "interrupted", "detection_timeout"]),
27
+ ),
28
+ });
29
+ export type TVendorCliInstall = S.Schema.Type<typeof VendorCliInstall>;
@@ -0,0 +1,50 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ /**
4
+ * Metadata-only signed plan for an existing video job (poll/content/cancel).
5
+ * Carries the job id's signed fields only — never the prompt, never aliases,
6
+ * never cooldown/default derivation. The cloud verifies `sig` before planning.
7
+ */
8
+ export const VIDEO_JOB_PLAN_QUERY_KEY = "video_job";
9
+ export const VIDEO_JOB_PLAN_JSON_MAX_BYTES = 1024;
10
+
11
+ export const VideoJobPlanRequest = S.Struct({
12
+ model: S.String.check(S.isMinLength(1), S.isMaxLength(128)),
13
+ provider: S.String.check(S.isMinLength(1), S.isMaxLength(64)),
14
+ upstream_id: S.String.check(S.isMinLength(1), S.isMaxLength(256)),
15
+ created_at: S.Number,
16
+ sig: S.String.check(S.isPattern(/^[a-f0-9]{64}$/)),
17
+ });
18
+ export type TVideoJobPlanRequest = S.Schema.Type<typeof VideoJobPlanRequest>;
19
+
20
+ const decodeRequest = S.decodeUnknownResult(VideoJobPlanRequest);
21
+
22
+ const utf8ByteLength = (value: string): number =>
23
+ new TextEncoder().encode(value).byteLength;
24
+
25
+ export const encodeVideoJobPlanQuery = (
26
+ request: TVideoJobPlanRequest,
27
+ ): string | null => {
28
+ const decoded = decodeRequest(request);
29
+ if (decoded._tag === "Failure") return null;
30
+ const json = JSON.stringify(decoded.success);
31
+ if (utf8ByteLength(json) > VIDEO_JOB_PLAN_JSON_MAX_BYTES) return null;
32
+ return `${VIDEO_JOB_PLAN_QUERY_KEY}=${encodeURIComponent(json)}`;
33
+ };
34
+
35
+ export const decodeVideoJobPlanQuery = (
36
+ params: URLSearchParams,
37
+ ): TVideoJobPlanRequest | null => {
38
+ const raw = params.get(VIDEO_JOB_PLAN_QUERY_KEY);
39
+ if (raw === null || raw.length === 0) return null;
40
+ if (utf8ByteLength(raw) > VIDEO_JOB_PLAN_JSON_MAX_BYTES) return null;
41
+ let parsed: unknown;
42
+ try {
43
+ parsed = JSON.parse(raw);
44
+ } catch {
45
+ return null;
46
+ }
47
+ const decoded = decodeRequest(parsed);
48
+ if (decoded._tag === "Failure") return null;
49
+ return decoded.success;
50
+ };