pico-engine 1.9.5 → 1.10.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 (126) hide show
  1. package/README.md +11 -5
  2. package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
  3. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
  4. package/demos/echo/com.example.echo.bootstrap.krl +10 -7
  5. package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
  6. package/demos/json_query/README.md +11 -0
  7. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  8. package/demos/json_query/com.example.json_query.krl +162 -0
  9. package/demos/json_query/try-it.md +5 -0
  10. package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
  11. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
  12. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
  13. package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
  14. package/demos/try-it-order.json +1 -1
  15. package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
  16. package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
  17. package/dist/cli.js +5 -1
  18. package/dist/engineConfig.js +1 -1
  19. package/dist/identity/portableMove.js +5 -1
  20. package/dist/index.js +44 -12
  21. package/dist/internalAccess.js +110 -0
  22. package/dist/oauth/OAuthService.js +172 -10
  23. package/dist/oauth/acg.js +194 -24
  24. package/dist/oauth/cimd.js +381 -0
  25. package/dist/oauth/discovery.js +175 -0
  26. package/dist/runMcp.js +1 -1
  27. package/dist/server.js +197 -48
  28. package/dist/subtreeWrangler.js +8 -5
  29. package/dist/uiChannelPolicies.js +2 -0
  30. package/krl/io.picolabs.pds.krl +109 -21
  31. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  32. package/krl/io.picolabs.wrangler.krl +21 -9
  33. package/mcp/devResources.js +52 -0
  34. package/mcp/devTools.js +40 -9
  35. package/mcp/docs/CLAUDE.md +3 -2
  36. package/mcp/docs/cookbook/README.md +23 -0
  37. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  38. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  39. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  40. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  41. package/mcp/docs/cookbook/collection/README.md +21 -0
  42. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  43. package/mcp/docs/cookbook/echo/README.md +19 -0
  44. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  45. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  46. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  47. package/mcp/docs/cookbook/json_query/README.md +26 -0
  48. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  49. package/mcp/docs/cookbook/kblog/README.md +60 -0
  50. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  51. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  52. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  53. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  54. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  55. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  56. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  57. package/mcp/docs/cookbook/secrets/README.md +25 -0
  58. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  59. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  60. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  61. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  62. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  63. package/mcp/docs/developing/README.md +28 -0
  64. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  65. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  66. package/mcp/docs/developing/converting-time-formats.md +28 -0
  67. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  68. package/mcp/docs/developing/decoding-form-data.md +67 -0
  69. package/mcp/docs/developing/engine-log-files.md +34 -0
  70. package/mcp/docs/developing/event-loop.md +77 -0
  71. package/mcp/docs/developing/events-from-email.md +80 -0
  72. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  73. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  74. package/mcp/docs/developing/misconceptions.md +467 -0
  75. package/mcp/docs/developing/names-and-scope.md +44 -0
  76. package/mcp/docs/developing/postman.md +159 -0
  77. package/mcp/docs/developing/querying-another-pico.md +47 -0
  78. package/mcp/docs/developing/singleton-picos.md +36 -0
  79. package/mcp/docs/developing/tabular-data.md +67 -0
  80. package/mcp/docs/developing/tips.md +251 -0
  81. package/mcp/docs/developing/webhook-signatures.md +56 -0
  82. package/mcp/docs/developing/workflow.md +106 -0
  83. package/mcp/docs/exp/README.md +46 -0
  84. package/mcp/docs/exp/event.md +110 -0
  85. package/mcp/docs/exp/query.md +94 -0
  86. package/mcp/docs/lessons/README.md +59 -0
  87. package/mcp/docs/lessons/events-and-queries.md +247 -0
  88. package/mcp/docs/lessons/gossip.md +28 -0
  89. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  90. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  91. package/mcp/docs/lessons/pico-state.md +267 -0
  92. package/mcp/docs/lessons/pico-views.md +290 -0
  93. package/mcp/docs/lessons/quickstart.md +157 -0
  94. package/mcp/docs/lessons/relationships.md +530 -0
  95. package/mcp/docs/lessons/scatter-gather.md +362 -0
  96. package/mcp/docs/pico-engine.md +7 -5
  97. package/mcp/docs/pico-overview.md +3 -3
  98. package/mcp/docs/wrangler/README.md +47 -0
  99. package/mcp/docs/wrangler/channels.md +235 -0
  100. package/mcp/docs/wrangler/oauth.md +56 -0
  101. package/mcp/docs/wrangler/pds.md +423 -0
  102. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  103. package/mcp/docs/wrangler/relationships.md +297 -0
  104. package/mcp/docs/wrangler/wrangler.md +253 -0
  105. package/mcp/docs/wrangler/xmlui.md +60 -0
  106. package/mcp/engineClient.js +57 -5
  107. package/mcp/mcpScopes.js +118 -0
  108. package/mcp/meshHttp.js +151 -45
  109. package/mcp/runStdio.js +2 -0
  110. package/mcp/subtreeTools.js +184 -0
  111. package/mcp/tryItTools.js +202 -0
  112. package/package.json +14 -8
  113. package/public/pico-engine-ui.js +26 -26
  114. package/src/cli.ts +6 -2
  115. package/src/engineConfig.ts +5 -2
  116. package/src/identity/portableMove.ts +6 -1
  117. package/src/index.ts +469 -430
  118. package/src/internalAccess.ts +127 -0
  119. package/src/oauth/OAuthService.ts +243 -11
  120. package/src/oauth/acg.ts +289 -25
  121. package/src/oauth/cimd.ts +508 -0
  122. package/src/oauth/discovery.ts +233 -0
  123. package/src/runMcp.ts +3 -1
  124. package/src/server.ts +252 -52
  125. package/src/subtreeWrangler.ts +17 -5
  126. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,508 @@
1
+ /**
2
+ * Client ID Metadata Documents (1.10 §2 A4).
3
+ *
4
+ * A client_id that is an https URL is fetched and checked. The document's
5
+ * client_id must equal that URL, and its redirect_uris must contain the
6
+ * request's redirect_uri exactly. Pre-registered app_ clients never come
7
+ * through here.
8
+ */
9
+
10
+ import * as dns from "dns";
11
+ import * as https from "https";
12
+ import * as net from "net";
13
+ import { OAuthError } from "./errors";
14
+
15
+ export const CIMD_MAX_BYTES = 5 * 1024;
16
+ export const CIMD_TIMEOUT_MS = 5000;
17
+ export const CIMD_CACHE_CEILING_MS = 60 * 60 * 1000;
18
+ const MAX_REDIRECTS = 5;
19
+
20
+ const blocked = new net.BlockList();
21
+ blocked.addSubnet("0.0.0.0", 8, "ipv4");
22
+ blocked.addSubnet("10.0.0.0", 8, "ipv4");
23
+ blocked.addSubnet("100.64.0.0", 10, "ipv4");
24
+ blocked.addSubnet("127.0.0.0", 8, "ipv4");
25
+ blocked.addSubnet("169.254.0.0", 16, "ipv4");
26
+ blocked.addSubnet("172.16.0.0", 12, "ipv4");
27
+ blocked.addSubnet("192.0.0.0", 24, "ipv4");
28
+ blocked.addSubnet("192.0.2.0", 24, "ipv4");
29
+ blocked.addSubnet("192.168.0.0", 16, "ipv4");
30
+ blocked.addSubnet("198.18.0.0", 15, "ipv4");
31
+ blocked.addSubnet("198.51.100.0", 24, "ipv4");
32
+ blocked.addSubnet("203.0.113.0", 24, "ipv4");
33
+ blocked.addSubnet("224.0.0.0", 4, "ipv4");
34
+ blocked.addSubnet("240.0.0.0", 4, "ipv4");
35
+ blocked.addSubnet("::", 128, "ipv6");
36
+ blocked.addSubnet("::1", 128, "ipv6");
37
+ blocked.addSubnet("fc00::", 7, "ipv6");
38
+ blocked.addSubnet("fe80::", 10, "ipv6");
39
+ blocked.addSubnet("ff00::", 8, "ipv6");
40
+ blocked.addSubnet("2001:db8::", 32, "ipv6");
41
+
42
+ export interface ClientMetadataDocument {
43
+ clientId: string;
44
+ clientName: string;
45
+ redirectUris: string[];
46
+ clientUri?: string;
47
+ logoUri?: string;
48
+ }
49
+
50
+ export interface ClientMetadataResponse {
51
+ status: number;
52
+ headers: Record<string, string | string[] | undefined>;
53
+ body: Buffer;
54
+ }
55
+
56
+ export interface ClientMetadataDeps {
57
+ request?: (url: string, signal: AbortSignal) => Promise<ClientMetadataResponse>;
58
+ lookup?: (hostname: string) => Promise<string[]>;
59
+ now?: () => number;
60
+ cache?: Map<string, { doc: ClientMetadataDocument; expiresAt: number }>;
61
+ }
62
+
63
+ const defaultCache = new Map<string, { doc: ClientMetadataDocument; expiresAt: number }>();
64
+
65
+ export function isClientMetadataUrl(value: string): boolean {
66
+ let url: URL;
67
+ try {
68
+ url = new URL(value);
69
+ } catch {
70
+ return false;
71
+ }
72
+ return (
73
+ url.protocol === "https:" &&
74
+ !url.username &&
75
+ !url.password &&
76
+ url.hash === "" &&
77
+ url.hostname.length > 0
78
+ );
79
+ }
80
+
81
+ /** An http(s) client_id that is not a usable metadata URL. */
82
+ export function rejectsAsMetadataUrl(value: string): boolean {
83
+ return /^https?:\/\//i.test(value) && !isClientMetadataUrl(value);
84
+ }
85
+
86
+ export function isPrivateAddress(address: string): boolean {
87
+ let ip = address.trim().toLowerCase().replace(/^\[|\]$/g, "").split("%")[0];
88
+ if (ip.startsWith("::ffff:")) {
89
+ const rest = ip.slice("::ffff:".length);
90
+ if (net.isIP(rest) === 4) {
91
+ return isPrivateAddress(rest);
92
+ }
93
+ const mapped = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(rest);
94
+ if (mapped) {
95
+ const hi = parseInt(mapped[1], 16);
96
+ const lo = parseInt(mapped[2], 16);
97
+ ip = `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
98
+ }
99
+ }
100
+ const kind = net.isIP(ip);
101
+ if (kind === 4) {
102
+ return blocked.check(ip, "ipv4");
103
+ }
104
+ if (kind === 6) {
105
+ return blocked.check(ip, "ipv6");
106
+ }
107
+ return true;
108
+ }
109
+
110
+ /** https URL safe to put on the approval page (the browser will fetch it). */
111
+ export function safeDisplayUrl(value: unknown): string | undefined {
112
+ if (typeof value !== "string" || !value.trim()) {
113
+ return undefined;
114
+ }
115
+ let url: URL;
116
+ try {
117
+ url = new URL(value.trim());
118
+ } catch {
119
+ return undefined;
120
+ }
121
+ if (url.protocol !== "https:" || url.username || url.password) {
122
+ return undefined;
123
+ }
124
+ if (isBlockedHostname(url.hostname)) {
125
+ return undefined;
126
+ }
127
+ if (net.isIP(url.hostname) && isPrivateAddress(url.hostname)) {
128
+ return undefined;
129
+ }
130
+ return value.trim();
131
+ }
132
+
133
+ export function cacheTtlMs(
134
+ headers: Record<string, string | string[] | undefined>,
135
+ now: number
136
+ ): number | null {
137
+ const cc = headerValue(headers, "cache-control").toLowerCase();
138
+ const expires = headerValue(headers, "expires");
139
+ if (!cc && !expires) {
140
+ return null;
141
+ }
142
+ if (/\bno-store\b/.test(cc) || /\bno-cache\b/.test(cc)) {
143
+ return null;
144
+ }
145
+ const maxAge = /\bmax-age=(\d+)/.exec(cc);
146
+ if (maxAge) {
147
+ const ms = Number(maxAge[1]) * 1000;
148
+ if (ms <= 0) {
149
+ return null;
150
+ }
151
+ return Math.min(ms, CIMD_CACHE_CEILING_MS);
152
+ }
153
+ if (expires) {
154
+ const at = Date.parse(expires);
155
+ if (!Number.isNaN(at) && at > now) {
156
+ return Math.min(at - now, CIMD_CACHE_CEILING_MS);
157
+ }
158
+ }
159
+ return null;
160
+ }
161
+
162
+ export function parseClientMetadata(
163
+ requestedUrl: string,
164
+ body: Buffer
165
+ ): ClientMetadataDocument {
166
+ if (body.length > CIMD_MAX_BYTES) {
167
+ throw new OAuthError("Client metadata document is too large", "invalid_client", 401);
168
+ }
169
+ let text = body.toString("utf8");
170
+ if (text.charCodeAt(0) === 0xfeff) {
171
+ text = text.slice(1);
172
+ }
173
+ let json: unknown;
174
+ try {
175
+ json = JSON.parse(text);
176
+ } catch {
177
+ throw new OAuthError("Client metadata document is not JSON", "invalid_client", 401);
178
+ }
179
+ if (!json || typeof json !== "object" || Array.isArray(json)) {
180
+ throw new OAuthError("Client metadata document is not an object", "invalid_client", 401);
181
+ }
182
+ const doc = json as Record<string, unknown>;
183
+ if (doc.client_id !== requestedUrl) {
184
+ throw new OAuthError(
185
+ "client_id in the metadata document does not match the URL",
186
+ "invalid_client",
187
+ 401
188
+ );
189
+ }
190
+ if (
191
+ !Array.isArray(doc.redirect_uris) ||
192
+ doc.redirect_uris.some((uri) => typeof uri !== "string")
193
+ ) {
194
+ throw new OAuthError(
195
+ "Client metadata document is missing redirect_uris",
196
+ "invalid_client",
197
+ 401
198
+ );
199
+ }
200
+ const redirectUris = (doc.redirect_uris as string[]).map((uri) => uri.trim()).filter(Boolean);
201
+ if (
202
+ typeof doc.token_endpoint_auth_method === "string" &&
203
+ doc.token_endpoint_auth_method !== "none"
204
+ ) {
205
+ throw new OAuthError(
206
+ "Client metadata document must use token_endpoint_auth_method none",
207
+ "invalid_client",
208
+ 401
209
+ );
210
+ }
211
+ if (
212
+ Array.isArray(doc.grant_types) &&
213
+ !doc.grant_types.includes("authorization_code")
214
+ ) {
215
+ throw new OAuthError(
216
+ "Client metadata document does not allow authorization_code",
217
+ "invalid_client",
218
+ 401
219
+ );
220
+ }
221
+ const host = new URL(requestedUrl).host;
222
+ return {
223
+ clientId: requestedUrl,
224
+ clientName: cleanName(
225
+ typeof doc.client_name === "string" ? doc.client_name : "",
226
+ host
227
+ ),
228
+ redirectUris,
229
+ clientUri: safeDisplayUrl(doc.client_uri),
230
+ logoUri: safeDisplayUrl(doc.logo_uri),
231
+ };
232
+ }
233
+
234
+ export async function loadClientMetadata(
235
+ clientIdUrl: string,
236
+ deps: ClientMetadataDeps = {}
237
+ ): Promise<ClientMetadataDocument> {
238
+ const now = (deps.now || Date.now)();
239
+ const cache = deps.cache || defaultCache;
240
+ const hit = cache.get(clientIdUrl);
241
+ if (hit && hit.expiresAt > now) {
242
+ return hit.doc;
243
+ }
244
+ let response: { headers: Record<string, string | string[] | undefined>; body: Buffer };
245
+ try {
246
+ const signal = AbortSignal.timeout(CIMD_TIMEOUT_MS);
247
+ response = await fetchDocument(clientIdUrl, deps, signal);
248
+ } catch (err) {
249
+ throw asOAuthError(err);
250
+ }
251
+ const doc = parseClientMetadata(clientIdUrl, response.body);
252
+ const ttl = cacheTtlMs(response.headers, now);
253
+ if (ttl && ttl > 0) {
254
+ cache.set(clientIdUrl, { doc, expiresAt: now + ttl });
255
+ } else {
256
+ cache.delete(clientIdUrl);
257
+ }
258
+ return doc;
259
+ }
260
+
261
+ async function fetchDocument(
262
+ startUrl: string,
263
+ deps: ClientMetadataDeps,
264
+ signal: AbortSignal
265
+ ): Promise<{ headers: Record<string, string | string[] | undefined>; body: Buffer }> {
266
+ let current = startUrl;
267
+ const seen = new Set<string>();
268
+ for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
269
+ if (seen.has(current)) {
270
+ throw new OAuthError(
271
+ "Client metadata URL redirected too many times",
272
+ "invalid_client",
273
+ 401
274
+ );
275
+ }
276
+ seen.add(current);
277
+ await assertPublicMetadataUrl(current, deps.lookup);
278
+ const response = await (deps.request || defaultRequest)(current, signal);
279
+ if ([301, 302, 303, 307, 308].includes(response.status)) {
280
+ const location = headerValue(response.headers, "location");
281
+ if (!location) {
282
+ throw new OAuthError("Client metadata could not be fetched", "invalid_client", 401);
283
+ }
284
+ current = new URL(location, current).toString();
285
+ continue;
286
+ }
287
+ if (response.status !== 200) {
288
+ throw new OAuthError("Client metadata could not be fetched", "invalid_client", 401);
289
+ }
290
+ const declared = Number(headerValue(response.headers, "content-length") || "0");
291
+ if (
292
+ (declared > 0 && declared > CIMD_MAX_BYTES) ||
293
+ response.body.length > CIMD_MAX_BYTES
294
+ ) {
295
+ throw new OAuthError(
296
+ "Client metadata document is too large",
297
+ "invalid_client",
298
+ 401
299
+ );
300
+ }
301
+ return { headers: response.headers, body: response.body };
302
+ }
303
+ throw new OAuthError(
304
+ "Client metadata URL redirected too many times",
305
+ "invalid_client",
306
+ 401
307
+ );
308
+ }
309
+
310
+ export async function assertPublicMetadataUrl(
311
+ raw: string,
312
+ lookup: ClientMetadataDeps["lookup"] = defaultLookup
313
+ ): Promise<void> {
314
+ let url: URL;
315
+ try {
316
+ url = new URL(raw);
317
+ } catch {
318
+ throw new OAuthError("Invalid client metadata URL", "invalid_client", 401);
319
+ }
320
+ if (url.protocol !== "https:" || url.username || url.password || url.hash) {
321
+ throw new OAuthError(
322
+ "client_id must be an https URL without a fragment or userinfo",
323
+ "invalid_client",
324
+ 401
325
+ );
326
+ }
327
+ const hostname = url.hostname.replace(/\.$/, "");
328
+ if (isBlockedHostname(hostname)) {
329
+ throw new OAuthError(
330
+ "Client metadata URL resolves to a private address",
331
+ "invalid_client",
332
+ 401
333
+ );
334
+ }
335
+ if (net.isIP(hostname)) {
336
+ if (isPrivateAddress(hostname)) {
337
+ throw new OAuthError(
338
+ "Client metadata URL resolves to a private address",
339
+ "invalid_client",
340
+ 401
341
+ );
342
+ }
343
+ return;
344
+ }
345
+ let addresses: string[];
346
+ try {
347
+ addresses = await lookup(hostname);
348
+ } catch {
349
+ throw new OAuthError(
350
+ "Client metadata URL could not be resolved",
351
+ "invalid_client",
352
+ 401
353
+ );
354
+ }
355
+ if (!addresses.length || addresses.some((address) => isPrivateAddress(address))) {
356
+ throw new OAuthError(
357
+ "Client metadata URL resolves to a private address",
358
+ "invalid_client",
359
+ 401
360
+ );
361
+ }
362
+ }
363
+
364
+ function isBlockedHostname(hostname: string): boolean {
365
+ const host = hostname.toLowerCase().replace(/\.$/, "");
366
+ if (
367
+ !host ||
368
+ host === "localhost" ||
369
+ host.endsWith(".localhost") ||
370
+ host.endsWith(".local") ||
371
+ host.endsWith(".internal")
372
+ ) {
373
+ return true;
374
+ }
375
+ if (!host.includes(".")) {
376
+ return true;
377
+ }
378
+ if (/^\d+$/.test(host) || /^0x[0-9a-f]+$/i.test(host)) {
379
+ return true;
380
+ }
381
+ return false;
382
+ }
383
+
384
+ async function defaultLookup(hostname: string): Promise<string[]> {
385
+ const records = await dns.promises.lookup(hostname, { all: true, verbatim: true });
386
+ return records.map((record) => record.address);
387
+ }
388
+
389
+ function defaultRequest(url: string, signal: AbortSignal): Promise<ClientMetadataResponse> {
390
+ return new Promise((resolve, reject) => {
391
+ if (signal.aborted) {
392
+ reject(Object.assign(new Error("timeout"), { name: "TimeoutError" }));
393
+ return;
394
+ }
395
+ const req = https.request(
396
+ url,
397
+ {
398
+ method: "GET",
399
+ headers: { Accept: "application/json", "User-Agent": "pico-engine" },
400
+ lookup: publicLookup as unknown as https.RequestOptions["lookup"],
401
+ },
402
+ (res) => {
403
+ const chunks: Buffer[] = [];
404
+ let size = 0;
405
+ res.on("data", (chunk: Buffer) => {
406
+ size += chunk.length;
407
+ if (size > CIMD_MAX_BYTES) {
408
+ res.destroy();
409
+ reject(
410
+ new OAuthError(
411
+ "Client metadata document is too large",
412
+ "invalid_client",
413
+ 401
414
+ )
415
+ );
416
+ return;
417
+ }
418
+ chunks.push(chunk);
419
+ });
420
+ res.on("end", () => {
421
+ resolve({
422
+ status: res.statusCode || 0,
423
+ headers: res.headers as ClientMetadataResponse["headers"],
424
+ body: Buffer.concat(chunks),
425
+ });
426
+ });
427
+ res.on("error", reject);
428
+ }
429
+ );
430
+ const abort = () => {
431
+ req.destroy(Object.assign(new Error("timeout"), { name: "TimeoutError" }));
432
+ };
433
+ signal.addEventListener("abort", abort, { once: true });
434
+ req.setTimeout(CIMD_TIMEOUT_MS, abort);
435
+ req.on("error", reject);
436
+ req.end();
437
+ });
438
+ }
439
+
440
+ function publicLookup(hostname: string, options: unknown, callback?: unknown): void {
441
+ let opts = options as { all?: boolean };
442
+ let cb = callback as (
443
+ err: Error | null,
444
+ address: string | dns.LookupAddress[],
445
+ family?: number
446
+ ) => void;
447
+ if (typeof options === "function") {
448
+ cb = options as typeof cb;
449
+ opts = {};
450
+ }
451
+ dns.lookup(hostname, { all: true, verbatim: true }, (err, addresses) => {
452
+ if (err || !addresses.length || addresses.some((item) => isPrivateAddress(item.address))) {
453
+ const error =
454
+ err ||
455
+ Object.assign(new Error("Client metadata URL resolves to a private address"), {
456
+ code: "EPERM",
457
+ });
458
+ cb(error, opts.all ? [] : "", 0);
459
+ return;
460
+ }
461
+ if (opts.all) {
462
+ cb(
463
+ null,
464
+ addresses.map((item) => ({ address: item.address, family: item.family }))
465
+ );
466
+ return;
467
+ }
468
+ cb(null, addresses[0].address, addresses[0].family);
469
+ });
470
+ }
471
+
472
+ function headerValue(
473
+ headers: Record<string, string | string[] | undefined>,
474
+ name: string
475
+ ): string {
476
+ const wanted = name.toLowerCase();
477
+ for (const [key, value] of Object.entries(headers)) {
478
+ if (key.toLowerCase() !== wanted || value === undefined) {
479
+ continue;
480
+ }
481
+ return Array.isArray(value) ? value.join(", ") : value;
482
+ }
483
+ return "";
484
+ }
485
+
486
+ function cleanName(name: string, fallback: string): string {
487
+ const cleaned = name.replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 200);
488
+ return cleaned || fallback;
489
+ }
490
+
491
+ function asOAuthError(err: unknown): OAuthError {
492
+ if (err instanceof OAuthError) {
493
+ return err;
494
+ }
495
+ const name = err instanceof Error ? err.name : "";
496
+ const message = err instanceof Error ? err.message : "";
497
+ if (message.includes("private address")) {
498
+ return new OAuthError(
499
+ "Client metadata URL resolves to a private address",
500
+ "invalid_client",
501
+ 401
502
+ );
503
+ }
504
+ if (name === "AbortError" || name === "TimeoutError" || message === "timeout") {
505
+ return new OAuthError("Client metadata request timed out", "invalid_client", 401);
506
+ }
507
+ return new OAuthError("Client metadata could not be fetched", "invalid_client", 401);
508
+ }