@bsv/overlay-express 2.6.0 → 2.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/LICENSES/Open-BSV-License-4-standard-pre-2026.txt +28 -0
  2. package/README.md +81 -13
  3. package/THIRD_PARTY_NOTICES.md +49 -0
  4. package/dist/cjs/package.json +4 -2
  5. package/dist/cjs/src/ArcadeProvider.d.ts +5 -1
  6. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -1
  7. package/dist/cjs/src/ArcadeProvider.js +159 -18
  8. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  9. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts +1 -4
  10. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  11. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -1
  12. package/dist/cjs/src/BanAwareLookupWrapper.d.ts.map +1 -1
  13. package/dist/cjs/src/BanAwareLookupWrapper.js +2 -1
  14. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -1
  15. package/dist/cjs/src/BanAwareTopicManager.d.ts.map +1 -1
  16. package/dist/cjs/src/BanAwareTopicManager.js +3 -2
  17. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -1
  18. package/dist/cjs/src/BanService.d.ts +2 -0
  19. package/dist/cjs/src/BanService.d.ts.map +1 -1
  20. package/dist/cjs/src/BanService.js +52 -9
  21. package/dist/cjs/src/BanService.js.map +1 -1
  22. package/dist/cjs/src/ChaintracksProvider.d.ts +4 -0
  23. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -1
  24. package/dist/cjs/src/ChaintracksProvider.js +64 -9
  25. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  26. package/dist/cjs/src/JanitorService.d.ts +3 -0
  27. package/dist/cjs/src/JanitorService.d.ts.map +1 -1
  28. package/dist/cjs/src/JanitorService.js +80 -33
  29. package/dist/cjs/src/JanitorService.js.map +1 -1
  30. package/dist/cjs/src/OutboundSecurity.d.ts +19 -0
  31. package/dist/cjs/src/OutboundSecurity.d.ts.map +1 -0
  32. package/dist/cjs/src/OutboundSecurity.js +199 -0
  33. package/dist/cjs/src/OutboundSecurity.js.map +1 -0
  34. package/dist/cjs/src/OverlayExpress.d.ts +9 -1
  35. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -1
  36. package/dist/cjs/src/OverlayExpress.js +717 -153
  37. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  38. package/dist/cjs/src/OverlayMonitor.d.ts +10 -1
  39. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -1
  40. package/dist/cjs/src/OverlayMonitor.js +173 -72
  41. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  42. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -1
  43. package/dist/cjs/src/ProviderChainBroadcaster.js +28 -1
  44. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  45. package/dist/cjs/src/ReorgStream.d.ts +13 -9
  46. package/dist/cjs/src/ReorgStream.d.ts.map +1 -1
  47. package/dist/cjs/src/ReorgStream.js +193 -73
  48. package/dist/cjs/src/ReorgStream.js.map +1 -1
  49. package/dist/cjs/src/makeUserInterface.d.ts +2 -0
  50. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -1
  51. package/dist/cjs/src/makeUserInterface.js +316 -118
  52. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  53. package/dist/esm/src/ArcadeProvider.js +164 -19
  54. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  55. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  56. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  57. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  58. package/dist/esm/src/BanAwareTopicManager.js +4 -3
  59. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  60. package/dist/esm/src/BanService.js +51 -9
  61. package/dist/esm/src/BanService.js.map +1 -1
  62. package/dist/esm/src/ChaintracksProvider.js +63 -9
  63. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  64. package/dist/esm/src/JanitorService.js +78 -29
  65. package/dist/esm/src/JanitorService.js.map +1 -1
  66. package/dist/esm/src/OutboundSecurity.js +183 -0
  67. package/dist/esm/src/OutboundSecurity.js.map +1 -0
  68. package/dist/esm/src/OverlayExpress.js +708 -121
  69. package/dist/esm/src/OverlayExpress.js.map +1 -1
  70. package/dist/esm/src/OverlayMonitor.js +166 -67
  71. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  72. package/dist/esm/src/ProviderChainBroadcaster.js +28 -1
  73. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  74. package/dist/esm/src/ReorgStream.js +189 -66
  75. package/dist/esm/src/ReorgStream.js.map +1 -1
  76. package/dist/esm/src/makeUserInterface.js +316 -118
  77. package/dist/esm/src/makeUserInterface.js.map +1 -1
  78. package/dist/types/src/ArcadeProvider.d.ts +5 -1
  79. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  80. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +1 -4
  81. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  82. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  83. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  84. package/dist/types/src/BanService.d.ts +2 -0
  85. package/dist/types/src/BanService.d.ts.map +1 -1
  86. package/dist/types/src/ChaintracksProvider.d.ts +4 -0
  87. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  88. package/dist/types/src/JanitorService.d.ts +3 -0
  89. package/dist/types/src/JanitorService.d.ts.map +1 -1
  90. package/dist/types/src/OutboundSecurity.d.ts +19 -0
  91. package/dist/types/src/OutboundSecurity.d.ts.map +1 -0
  92. package/dist/types/src/OverlayExpress.d.ts +9 -1
  93. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  94. package/dist/types/src/OverlayMonitor.d.ts +10 -1
  95. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  96. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  97. package/dist/types/src/ReorgStream.d.ts +13 -9
  98. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  99. package/dist/types/src/makeUserInterface.d.ts +2 -0
  100. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  101. package/package.json +9 -7
@@ -1,41 +1,9 @@
1
1
  "use strict";
2
- var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
- if (k2 === undefined) k2 = k;
4
- var desc = Object.getOwnPropertyDescriptor(m, k);
5
- if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
- desc = { enumerable: true, get: function() { return m[k]; } };
7
- }
8
- Object.defineProperty(o, k2, desc);
9
- }) : (function(o, m, k, k2) {
10
- if (k2 === undefined) k2 = k;
11
- o[k2] = m[k];
12
- }));
13
- var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
- Object.defineProperty(o, "default", { enumerable: true, value: v });
15
- }) : function(o, v) {
16
- o["default"] = v;
17
- });
18
- var __importStar = (this && this.__importStar) || (function () {
19
- var ownKeys = function(o) {
20
- ownKeys = Object.getOwnPropertyNames || function (o) {
21
- var ar = [];
22
- for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
- return ar;
24
- };
25
- return ownKeys(o);
26
- };
27
- return function (mod) {
28
- if (mod && mod.__esModule) return mod;
29
- var result = {};
30
- if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
- __setModuleDefault(result, mod);
32
- return result;
33
- };
34
- })();
35
2
  var __importDefault = (this && this.__importDefault) || function (mod) {
36
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
37
4
  };
38
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
+ const utils_1 = require("@bsv/sdk/primitives/utils");
39
7
  const express_1 = __importDefault(require("express"));
40
8
  const body_parser_1 = __importDefault(require("body-parser"));
41
9
  const overlay_1 = require("@bsv/overlay");
@@ -43,7 +11,7 @@ const sdk_1 = require("@bsv/sdk");
43
11
  const knex_1 = __importDefault(require("knex"));
44
12
  const mongodb_1 = require("mongodb");
45
13
  const makeUserInterface_js_1 = __importDefault(require("./makeUserInterface.js"));
46
- const DiscoveryServices = __importStar(require("@bsv/overlay-discovery-services"));
14
+ const overlay_discovery_services_1 = require("@bsv/overlay-discovery-services");
47
15
  const chalk_1 = __importDefault(require("chalk"));
48
16
  const uuid_1 = require("uuid");
49
17
  const node_crypto_1 = require("node:crypto");
@@ -59,6 +27,7 @@ const auth_express_middleware_1 = require("@bsv/auth-express-middleware");
59
27
  const ArcadeProvider_js_1 = require("./ArcadeProvider.js");
60
28
  const ProviderChainBroadcaster_js_1 = require("./ProviderChainBroadcaster.js");
61
29
  const ChaintracksProvider_js_1 = require("./ChaintracksProvider.js");
30
+ const OutboundSecurity_js_1 = require("./OutboundSecurity.js");
62
31
  const edgePolicy_js_1 = require("./security/edgePolicy.js");
63
32
  /**
64
33
  * In-memory migration source for Knex migrations.
@@ -95,12 +64,30 @@ class InMemoryMigrationSource {
95
64
  return await Promise.resolve(migration);
96
65
  }
97
66
  }
67
+ const MAX_HEALTH_TIMEOUT_MS = 60000;
68
+ const MAX_HEALTH_CHECKS = 128;
69
+ const MAX_HEALTH_NAME_BYTES = 128;
70
+ const MAX_HEALTH_MESSAGE_BYTES = 1024;
71
+ const MAX_HEALTH_REPORT_DATA_BYTES = 1024 * 1024;
72
+ const MIN_SHARED_SECRET_BYTES = 32;
73
+ const MAX_SHARED_SECRET_BYTES = 16 * 1024;
74
+ const MAX_BLOCK_HEADER_RESPONSE_BYTES = 64 * 1024;
75
+ const BLOCK_HEADER_REQUEST_TIMEOUT_MS = 30000;
76
+ const MAX_CONFIGURED_BODY_BYTES = 512 * 1024 * 1024;
77
+ const MAX_CONFIGURED_ORIGINS = 128;
98
78
  class PublicRequestError extends Error {
99
79
  constructor(message) {
100
80
  super(message);
101
81
  this.name = 'PublicRequestError';
102
82
  }
103
83
  }
84
+ class UnsupportedBasmCapabilityError extends PublicRequestError {
85
+ constructor() {
86
+ super('BASM capability is not supported by this Overlay engine');
87
+ this.code = 'BASM_UNSUPPORTED';
88
+ this.name = 'UnsupportedBasmCapabilityError';
89
+ }
90
+ }
104
91
  function publicErrorMessage(error, fallback = 'Request could not be processed') {
105
92
  return error instanceof PublicRequestError ? error.message : fallback;
106
93
  }
@@ -109,6 +96,89 @@ function secretMatches(provided, expected) {
109
96
  const expectedDigest = (0, node_crypto_1.createHash)('sha256').update(expected, 'utf8').digest();
110
97
  return (0, node_crypto_1.timingSafeEqual)(providedDigest, expectedDigest);
111
98
  }
99
+ function assertSharedSecret(value, label) {
100
+ if (typeof value !== 'string' || value !== value.trim()) {
101
+ throw new TypeError(`${label} must not contain leading or trailing whitespace`);
102
+ }
103
+ const byteLength = new TextEncoder().encode(value).byteLength;
104
+ if (byteLength < MIN_SHARED_SECRET_BYTES || byteLength > MAX_SHARED_SECRET_BYTES) {
105
+ throw new TypeError(`${label} must contain between ${MIN_SHARED_SECRET_BYTES} and ${MAX_SHARED_SECRET_BYTES} UTF-8 bytes`);
106
+ }
107
+ if (Array.from(value).some(character => {
108
+ var _a;
109
+ const codePoint = (_a = character.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
110
+ return codePoint <= 0x1f || codePoint === 0x7f;
111
+ })) {
112
+ throw new TypeError(`${label} must not contain control characters`);
113
+ }
114
+ }
115
+ function assertConfigurationObject(value, label) {
116
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
117
+ throw new TypeError(`${label} must be an object`);
118
+ }
119
+ }
120
+ function assertBooleanOption(value, label) {
121
+ if (typeof value !== 'boolean')
122
+ throw new TypeError(`${label} must be a boolean`);
123
+ }
124
+ function assertSingleLineString(value, label, maxBytes, allowEmpty = true) {
125
+ (0, OutboundSecurity_js_1.assertBoundedString)(value, label, maxBytes, allowEmpty);
126
+ if (Array.from(value).some(character => {
127
+ var _a;
128
+ const codePoint = (_a = character.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
129
+ return codePoint <= 0x1f || codePoint === 0x7f;
130
+ })) {
131
+ throw new TypeError(`${label} must not contain control characters`);
132
+ }
133
+ }
134
+ function assertIntegerOption(value, label, minimum, maximum, allowUnlimited = false) {
135
+ if (!Number.isSafeInteger(value) ||
136
+ (value < minimum && !(allowUnlimited && value === -1)) ||
137
+ value > maximum) {
138
+ const unlimited = allowUnlimited ? ' or -1' : '';
139
+ throw new TypeError(`${label} must be an integer between ${minimum} and ${maximum}${unlimited}`);
140
+ }
141
+ }
142
+ function normalizeConfiguredOrigin(value) {
143
+ assertSingleLineString(value, 'Allowed origin', 2048, false);
144
+ let parsed;
145
+ try {
146
+ parsed = new URL(value);
147
+ }
148
+ catch {
149
+ throw new TypeError('Allowed origins must be valid HTTP(S) origins');
150
+ }
151
+ if ((parsed.protocol !== 'https:' && parsed.protocol !== 'http:') ||
152
+ parsed.username !== '' ||
153
+ parsed.password !== '' ||
154
+ parsed.pathname !== '/' ||
155
+ parsed.search !== '' ||
156
+ parsed.hash !== '' ||
157
+ parsed.origin === 'null') {
158
+ throw new TypeError('Allowed origins must not contain credentials, paths, queries, or fragments');
159
+ }
160
+ return parsed.origin;
161
+ }
162
+ function normalizeAdvertisableFQDN(value) {
163
+ assertSingleLineString(value, 'Advertisable FQDN', 2048, false);
164
+ let parsed;
165
+ try {
166
+ parsed = new URL(value.includes('://') ? value : `https://${value}`);
167
+ }
168
+ catch {
169
+ throw new TypeError('Advertisable FQDN must be a valid HTTPS host');
170
+ }
171
+ if (parsed.protocol !== 'https:' ||
172
+ parsed.username !== '' ||
173
+ parsed.password !== '' ||
174
+ parsed.pathname !== '/' ||
175
+ parsed.search !== '' ||
176
+ parsed.hash !== '' ||
177
+ parsed.hostname === '') {
178
+ throw new TypeError('Advertisable FQDN must be an HTTPS host without credentials or a path');
179
+ }
180
+ return parsed.host;
181
+ }
112
182
  function parseTopicsHeader(header) {
113
183
  const value = header.trim();
114
184
  let parsed;
@@ -124,6 +194,19 @@ function parseTopicsHeader(header) {
124
194
  }
125
195
  return parsed;
126
196
  }
197
+ function assertRegistryName(value, label) {
198
+ (0, OutboundSecurity_js_1.assertBoundedString)(value, label, 256, false);
199
+ if (value === '__proto__' ||
200
+ value === 'prototype' ||
201
+ value === 'constructor' ||
202
+ Array.from(value).some(character => {
203
+ var _a;
204
+ const codePoint = (_a = character.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
205
+ return codePoint <= 0x1f || codePoint === 0x7f;
206
+ })) {
207
+ throw new TypeError(`${label} is invalid`);
208
+ }
209
+ }
127
210
  /**
128
211
  * OverlayExpress class provides an Express-based server for hosting Overlay Services.
129
212
  * It allows configuration of various components like databases, topic managers, and lookup services.
@@ -154,9 +237,9 @@ class OverlayExpress {
154
237
  // (We keep a property for it, so we can pass it to Engine)
155
238
  this.chainTracker = new sdk_1.WhatsOnChain('main');
156
239
  // Configured Topic Managers
157
- this.managers = {};
240
+ this.managers = Object.create(null);
158
241
  // Configured Lookup Services
159
- this.services = {};
242
+ this.services = Object.create(null);
160
243
  // Enable GASP Sync
161
244
  // (We allow an on/off toggle, but also can do advanced custom sync config below)
162
245
  this.enableGASPSync = true;
@@ -172,6 +255,7 @@ class OverlayExpress {
172
255
  // How often (ms) to refresh proofs for old unproven rows and then evict rows
173
256
  // that still have no proof. Set to 0 to disable background maintenance.
174
257
  this.unprovenMaintenanceIntervalMs = 0;
258
+ this.reorgStreamAllowPrivateHosts = false;
175
259
  // Depth (in blocks from the tip) for the reorg revalidation sweep.
176
260
  this.reorgScanDepth = 3;
177
261
  // ARC API Key
@@ -184,6 +268,7 @@ class OverlayExpress {
184
268
  this.arcadeApiKey = undefined;
185
269
  this.arcadeDeploymentId = undefined;
186
270
  this.arcadeChaintracksApiPrefix = '/chaintracks/v2';
271
+ this.arcadeAllowPrivateHosts = false;
187
272
  // Verbose request logging
188
273
  this.verboseRequestLogging = false;
189
274
  // Web UI configuration
@@ -202,7 +287,7 @@ class OverlayExpress {
202
287
  };
203
288
  // Health endpoint configuration
204
289
  this.healthConfig = {
205
- includeDetails: true,
290
+ includeDetails: false,
206
291
  timeoutMs: 5000
207
292
  };
208
293
  // Extra application-specific health checks
@@ -222,9 +307,12 @@ class OverlayExpress {
222
307
  maxRequestsPerSocket: 1000
223
308
  },
224
309
  securityHeaders: {
225
- contentSecurityPolicy: "default-src 'none'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: https://bsvblockchain.org; connect-src 'self' https:; font-src 'self' https://cdn.jsdelivr.net; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
310
+ contentSecurityPolicy: "default-src 'none'; script-src 'none'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: https:; connect-src 'self' https:; font-src 'self' https://cdn.jsdelivr.net; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
226
311
  }
227
312
  };
313
+ if (adminToken !== undefined)
314
+ assertSharedSecret(adminToken, 'The administrative Bearer token');
315
+ this.advertisableFQDN = normalizeAdvertisableFQDN(advertisableFQDN);
228
316
  this.app = (0, express_1.default)();
229
317
  this.logger.log(chalk_1.default.green.bold(`${name} constructed`));
230
318
  this.adminToken = adminToken !== null && adminToken !== void 0 ? adminToken : (0, uuid_1.v4)(); // generate random if not provided
@@ -240,6 +328,7 @@ class OverlayExpress {
240
328
  * @param port - The port number
241
329
  */
242
330
  configurePort(port) {
331
+ assertIntegerOption(port, 'Server port', 1, 65535);
243
332
  this.port = port;
244
333
  this.logger.log(chalk_1.default.blue(`Server port set to ${port}`));
245
334
  }
@@ -262,20 +351,64 @@ class OverlayExpress {
262
351
  * - maxReportResults: Maximum retained result details; -1 retains all
263
352
  */
264
353
  configureJanitor(config) {
265
- this.janitorConfig = {
266
- ...this.janitorConfig,
267
- ...config
268
- };
354
+ assertConfigurationObject(config, 'Janitor configuration');
355
+ const next = { ...this.janitorConfig };
356
+ if (config.requestTimeoutMs !== undefined) {
357
+ assertIntegerOption(config.requestTimeoutMs, 'Janitor requestTimeoutMs', 1, 300000);
358
+ next.requestTimeoutMs = config.requestTimeoutMs;
359
+ }
360
+ if (config.hostDownRevokeScore !== undefined) {
361
+ assertIntegerOption(config.hostDownRevokeScore, 'Janitor hostDownRevokeScore', 1, 1000);
362
+ next.hostDownRevokeScore = config.hostDownRevokeScore;
363
+ }
364
+ if (config.autoBanOnRemoval !== undefined) {
365
+ assertBooleanOption(config.autoBanOnRemoval, 'Janitor autoBanOnRemoval');
366
+ next.autoBanOnRemoval = config.autoBanOnRemoval;
367
+ }
368
+ if (config.allowPrivateHosts !== undefined) {
369
+ assertBooleanOption(config.allowPrivateHosts, 'Janitor allowPrivateHosts');
370
+ next.allowPrivateHosts = config.allowPrivateHosts;
371
+ }
372
+ if (config.batchSize !== undefined) {
373
+ assertIntegerOption(config.batchSize, 'Janitor batchSize', 1, 100000, true);
374
+ next.batchSize = config.batchSize;
375
+ }
376
+ if (config.maxReportResults !== undefined) {
377
+ assertIntegerOption(config.maxReportResults, 'Janitor maxReportResults', 1, 1000000, true);
378
+ next.maxReportResults = config.maxReportResults;
379
+ }
380
+ this.janitorConfig = next;
269
381
  this.logger.log(chalk_1.default.blue('Janitor service has been configured.'));
270
382
  }
271
383
  /**
272
384
  * Configures health-report behavior.
273
385
  */
274
386
  configureHealth(config) {
275
- this.healthConfig = {
276
- ...this.healthConfig,
277
- ...config
278
- };
387
+ if (typeof config !== 'object' || config === null || Array.isArray(config)) {
388
+ throw new TypeError('Health configuration must be an object');
389
+ }
390
+ const next = { ...this.healthConfig };
391
+ if (Object.prototype.hasOwnProperty.call(config, 'includeDetails')) {
392
+ if (typeof config.includeDetails !== 'boolean') {
393
+ throw new TypeError('Health includeDetails must be a boolean');
394
+ }
395
+ next.includeDetails = config.includeDetails;
396
+ }
397
+ if (Object.prototype.hasOwnProperty.call(config, 'timeoutMs')) {
398
+ if (!Number.isSafeInteger(config.timeoutMs) ||
399
+ config.timeoutMs < 1 ||
400
+ config.timeoutMs > MAX_HEALTH_TIMEOUT_MS) {
401
+ throw new TypeError(`Health timeoutMs must be an integer from 1 to ${MAX_HEALTH_TIMEOUT_MS}`);
402
+ }
403
+ next.timeoutMs = config.timeoutMs;
404
+ }
405
+ if (Object.prototype.hasOwnProperty.call(config, 'contextProvider')) {
406
+ if (config.contextProvider !== undefined && typeof config.contextProvider !== 'function') {
407
+ throw new TypeError('Health contextProvider must be a function');
408
+ }
409
+ next.contextProvider = config.contextProvider;
410
+ }
411
+ this.healthConfig = next;
279
412
  this.logger.log(chalk_1.default.blue('Health reporting has been configured.'));
280
413
  }
281
414
  /**
@@ -284,33 +417,144 @@ class OverlayExpress {
284
417
  * OVERLAY_CORS_MODE=allowlist to restrict browser callers.
285
418
  */
286
419
  configureEdgePolicy(config) {
287
- const { http, securityHeaders: headerConfig, ...topLevel } = config;
288
- const definedTopLevel = Object.fromEntries(Object.entries(topLevel).filter(([, value]) => value !== undefined));
289
- const definedHttp = Object.fromEntries(Object.entries(http !== null && http !== void 0 ? http : {}).filter(([, value]) => value !== undefined));
290
- const definedHeaders = Object.fromEntries(Object.entries(headerConfig !== null && headerConfig !== void 0 ? headerConfig : {}).filter(([, value]) => value !== undefined));
291
- this.edgePolicyConfig = {
420
+ assertConfigurationObject(config, 'HTTP edge policy');
421
+ const next = {
292
422
  ...this.edgePolicyConfig,
293
- ...definedTopLevel,
294
- http: {
295
- ...this.edgePolicyConfig.http,
296
- ...definedHttp
297
- },
298
- securityHeaders: {
299
- ...this.edgePolicyConfig.securityHeaders,
300
- ...definedHeaders
301
- }
423
+ allowedOrigins: this.edgePolicyConfig.allowedOrigins === undefined
424
+ ? undefined
425
+ : [...this.edgePolicyConfig.allowedOrigins],
426
+ http: { ...this.edgePolicyConfig.http },
427
+ securityHeaders: { ...this.edgePolicyConfig.securityHeaders }
302
428
  };
429
+ if (config.environmentPrefix !== undefined) {
430
+ if (typeof config.environmentPrefix !== 'string' ||
431
+ !/^[A-Z][A-Z0-9_]{0,63}$/.test(config.environmentPrefix)) {
432
+ throw new TypeError('HTTP edge environmentPrefix is invalid');
433
+ }
434
+ next.environmentPrefix = config.environmentPrefix;
435
+ }
436
+ if (config.allowedOrigins !== undefined) {
437
+ if (!Array.isArray(config.allowedOrigins) ||
438
+ config.allowedOrigins.length > MAX_CONFIGURED_ORIGINS) {
439
+ throw new TypeError(`allowedOrigins must contain at most ${MAX_CONFIGURED_ORIGINS} origins`);
440
+ }
441
+ next.allowedOrigins = [...new Set(config.allowedOrigins.map(normalizeConfiguredOrigin))];
442
+ }
443
+ if (config.jsonBodyLimitBytes !== undefined) {
444
+ assertIntegerOption(config.jsonBodyLimitBytes, 'JSON body limit', 1, MAX_CONFIGURED_BODY_BYTES, true);
445
+ next.jsonBodyLimitBytes = config.jsonBodyLimitBytes;
446
+ }
447
+ if (config.binaryBodyLimitBytes !== undefined) {
448
+ assertIntegerOption(config.binaryBodyLimitBytes, 'Binary body limit', 1, MAX_CONFIGURED_BODY_BYTES, true);
449
+ next.binaryBodyLimitBytes = config.binaryBodyLimitBytes;
450
+ }
451
+ if (config.maxConcurrentRequests !== undefined) {
452
+ assertIntegerOption(config.maxConcurrentRequests, 'Maximum concurrent requests', 1, 100000, true);
453
+ next.maxConcurrentRequests = config.maxConcurrentRequests;
454
+ }
455
+ if (config.http !== undefined) {
456
+ assertConfigurationObject(config.http, 'HTTP server policy');
457
+ const httpBounds = [
458
+ ['requestTimeoutMs', 3600000, false],
459
+ ['headersTimeoutMs', 3600000, false],
460
+ ['keepAliveTimeoutMs', 3600000, false],
461
+ ['socketTimeoutMs', 3600000, false],
462
+ ['maxRequestsPerSocket', 1000000, false],
463
+ ['maxConnections', 1000000, true]
464
+ ];
465
+ for (const [key, maximum, allowUnlimited] of httpBounds) {
466
+ const value = config.http[key];
467
+ if (value === undefined)
468
+ continue;
469
+ assertIntegerOption(value, `HTTP ${key}`, 1, maximum, allowUnlimited);
470
+ next.http[key] = value;
471
+ }
472
+ if (next.http.headersTimeoutMs > next.http.requestTimeoutMs) {
473
+ throw new TypeError('HTTP headersTimeoutMs cannot exceed requestTimeoutMs');
474
+ }
475
+ if (next.http.keepAliveTimeoutMs > next.http.requestTimeoutMs) {
476
+ throw new TypeError('HTTP keepAliveTimeoutMs cannot exceed requestTimeoutMs');
477
+ }
478
+ }
479
+ if (config.securityHeaders !== undefined) {
480
+ assertConfigurationObject(config.securityHeaders, 'Security headers policy');
481
+ const headers = config.securityHeaders;
482
+ if (Object.prototype.hasOwnProperty.call(headers, 'environmentPrefix')) {
483
+ throw new TypeError('Security headers must use the top-level environmentPrefix');
484
+ }
485
+ for (const key of ['contentSecurityPolicy', 'permissionsPolicy']) {
486
+ const value = headers[key];
487
+ if (value === undefined)
488
+ continue;
489
+ if (value !== false)
490
+ assertSingleLineString(value, `Security header ${key}`, 16 * 1024);
491
+ next.securityHeaders[key] = value;
492
+ }
493
+ const enumeratedHeaders = {
494
+ crossOriginResourcePolicy: ['same-origin', 'same-site', 'cross-origin'],
495
+ crossOriginOpenerPolicy: ['same-origin', 'same-origin-allow-popups', 'unsafe-none'],
496
+ frameOptions: ['DENY', 'SAMEORIGIN']
497
+ };
498
+ for (const key of Object.keys(enumeratedHeaders)) {
499
+ const value = headers[key];
500
+ if (value === undefined)
501
+ continue;
502
+ if (value !== false && !enumeratedHeaders[key].includes(value)) {
503
+ throw new TypeError(`Security header ${key} is invalid`);
504
+ }
505
+ ;
506
+ next.securityHeaders[key] = value;
507
+ }
508
+ if (headers.strictTransportSecurity !== undefined) {
509
+ assertBooleanOption(headers.strictTransportSecurity, 'Strict-Transport-Security setting');
510
+ next.securityHeaders.strictTransportSecurity = headers.strictTransportSecurity;
511
+ }
512
+ }
513
+ this.edgePolicyConfig = next;
303
514
  this.logger.log(chalk_1.default.blue('HTTP edge policy has been configured.'));
304
515
  }
305
516
  /**
306
517
  * Registers an application-specific health check.
307
518
  */
308
519
  registerHealthCheck(definition) {
520
+ var _a, _b;
521
+ if (typeof definition !== 'object' || definition === null || Array.isArray(definition)) {
522
+ throw new TypeError('Health check definition must be an object');
523
+ }
524
+ if (typeof definition.name !== 'string' ||
525
+ definition.name.length === 0 ||
526
+ new TextEncoder().encode(definition.name).byteLength > MAX_HEALTH_NAME_BYTES ||
527
+ Array.from(definition.name).some(character => {
528
+ var _a;
529
+ const codePoint = (_a = character.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
530
+ return codePoint <= 0x1f || codePoint === 0x7f;
531
+ })) {
532
+ throw new TypeError('Health check name is invalid');
533
+ }
534
+ if (['process', 'engine', 'knex', 'mongo'].includes(definition.name)) {
535
+ throw new TypeError('Health check name is reserved');
536
+ }
537
+ if (definition.scope !== undefined &&
538
+ definition.scope !== 'live' &&
539
+ definition.scope !== 'ready') {
540
+ throw new TypeError('Health check scope is invalid');
541
+ }
542
+ if (definition.critical !== undefined && typeof definition.critical !== 'boolean') {
543
+ throw new TypeError('Health check critical must be a boolean');
544
+ }
545
+ if (typeof definition.handler !== 'function') {
546
+ throw new TypeError('Health check handler must be a function');
547
+ }
548
+ if (!this.healthChecks.some(check => check.name === definition.name) &&
549
+ this.healthChecks.length >= MAX_HEALTH_CHECKS) {
550
+ throw new RangeError(`Cannot register more than ${MAX_HEALTH_CHECKS} health checks`);
551
+ }
309
552
  this.healthChecks = this.healthChecks.filter(check => check.name !== definition.name);
310
553
  this.healthChecks.push({
311
- scope: 'ready',
312
- critical: false,
313
- ...definition
554
+ name: definition.name,
555
+ scope: (_a = definition.scope) !== null && _a !== void 0 ? _a : 'ready',
556
+ critical: (_b = definition.critical) !== null && _b !== void 0 ? _b : false,
557
+ handler: definition.handler
314
558
  });
315
559
  this.logger.log(chalk_1.default.blue(`Registered health check ${definition.name}`));
316
560
  }
@@ -322,6 +566,9 @@ class OverlayExpress {
322
566
  * @param identityKey - The hex-encoded public key of the admin
323
567
  */
324
568
  configureAdminIdentityKey(identityKey) {
569
+ if (typeof identityKey !== 'string' || !/^(?:02|03)[0-9a-fA-F]{64}$/.test(identityKey)) {
570
+ throw new TypeError('Admin identity key must be a compressed secp256k1 public key');
571
+ }
325
572
  this.adminIdentityKey = identityKey;
326
573
  this.logger.log(chalk_1.default.blue('Admin identity key has been configured.'));
327
574
  }
@@ -339,6 +586,9 @@ class OverlayExpress {
339
586
  * @param logger - A logger object (e.g., console)
340
587
  */
341
588
  configureLogger(logger) {
589
+ if (typeof logger !== 'object' || logger === null || typeof logger.log !== 'function') {
590
+ throw new TypeError('Logger must provide a log function');
591
+ }
342
592
  this.logger = logger;
343
593
  this.logger.log(chalk_1.default.blue('Logger has been configured.'));
344
594
  }
@@ -349,6 +599,9 @@ class OverlayExpress {
349
599
  * @param network - The network ('main', 'test', or 'ttn')
350
600
  */
351
601
  configureNetwork(network) {
602
+ if (network !== 'main' && network !== 'test' && network !== 'ttn') {
603
+ throw new TypeError('Network must be main, test, or ttn');
604
+ }
352
605
  this.network = network;
353
606
  this.chainTracker =
354
607
  network === 'ttn'
@@ -375,6 +628,13 @@ class OverlayExpress {
375
628
  }
376
629
  chainTracker = new sdk_1.WhatsOnChain(this.network);
377
630
  }
631
+ if (chainTracker !== 'scripts only' &&
632
+ (typeof chainTracker !== 'object' ||
633
+ chainTracker === null ||
634
+ typeof chainTracker.isValidRootForHeight !== 'function' ||
635
+ typeof chainTracker.currentHeight !== 'function')) {
636
+ throw new TypeError('ChainTracker must implement root validation and currentHeight');
637
+ }
378
638
  this.chainTracker = chainTracker;
379
639
  this.logger.log(chalk_1.default.blue('ChainTracker has been configured.'));
380
640
  }
@@ -383,6 +643,7 @@ class OverlayExpress {
383
643
  * @param apiKey - The ARC API key
384
644
  */
385
645
  configureArcApiKey(apiKey) {
646
+ assertSingleLineString(apiKey, 'ARC API key', MAX_SHARED_SECRET_BYTES);
386
647
  this.arcApiKey = apiKey;
387
648
  this.logger.log(chalk_1.default.blue('ARC API key has been configured.'));
388
649
  }
@@ -391,6 +652,7 @@ class OverlayExpress {
391
652
  * @param token - The token ARC should present when posting callback notifications.
392
653
  */
393
654
  configureArcCallbackToken(token) {
655
+ assertSharedSecret(token, 'The ARC callback token');
394
656
  this.arcCallbackToken = token;
395
657
  this.logger.log(chalk_1.default.blue('ARC callback token has been configured.'));
396
658
  }
@@ -398,9 +660,34 @@ class OverlayExpress {
398
660
  * Configures Arcade for first-choice transaction propagation and proof lookup.
399
661
  */
400
662
  configureArcade(url, config = {}) {
663
+ var _a;
664
+ assertConfigurationObject(config, 'Arcade configuration');
665
+ if (config.allowPrivateHosts !== undefined) {
666
+ assertBooleanOption(config.allowPrivateHosts, 'Arcade allowPrivateHosts');
667
+ }
668
+ const allowPrivateHosts = (_a = config.allowPrivateHosts) !== null && _a !== void 0 ? _a : false;
669
+ (0, OutboundSecurity_js_1.secureServiceFetch)(url, undefined, allowPrivateHosts);
670
+ if (config.apiKey !== undefined) {
671
+ assertSingleLineString(config.apiKey, 'Arcade API key', MAX_SHARED_SECRET_BYTES);
672
+ }
673
+ if (config.deploymentId !== undefined) {
674
+ assertSingleLineString(config.deploymentId, 'Arcade deployment ID', 1024);
675
+ }
676
+ if (config.chaintracksApiPrefix !== undefined) {
677
+ assertSingleLineString(config.chaintracksApiPrefix, 'Arcade Chaintracks API prefix', 2048);
678
+ // Reuse the provider's URL-path parser even when Chaintracks is configured later.
679
+ const chaintracksStreamUrl = new ChaintracksProvider_js_1.ChaintracksProvider(url, {
680
+ apiPrefix: config.chaintracksApiPrefix,
681
+ allowPrivateHosts
682
+ }).reorgStreamUrl();
683
+ if (!chaintracksStreamUrl.endsWith('/reorg/stream')) {
684
+ throw new TypeError('Chaintracks API prefix must be a URL path');
685
+ }
686
+ }
401
687
  this.arcadeUrl = url;
402
688
  this.arcadeApiKey = config.apiKey;
403
689
  this.arcadeDeploymentId = config.deploymentId;
690
+ this.arcadeAllowPrivateHosts = allowPrivateHosts;
404
691
  if (config.chaintracksApiPrefix !== undefined) {
405
692
  this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix;
406
693
  }
@@ -412,8 +699,21 @@ class OverlayExpress {
412
699
  */
413
700
  configureChaintracks(url, config = {}) {
414
701
  var _a;
702
+ assertConfigurationObject(config, 'Chaintracks configuration');
703
+ if (config.reorgStream !== undefined) {
704
+ assertBooleanOption(config.reorgStream, 'Chaintracks reorgStream');
705
+ }
706
+ if (config.allowPrivateHosts !== undefined) {
707
+ assertBooleanOption(config.allowPrivateHosts, 'Chaintracks allowPrivateHosts');
708
+ }
709
+ if (config.scanDepth !== undefined) {
710
+ assertIntegerOption(config.scanDepth, 'Chaintracks scanDepth', 1, 100000);
711
+ }
415
712
  const apiPrefix = (_a = config.apiPrefix) !== null && _a !== void 0 ? _a : '/chaintracks/v2';
416
- const client = new ChaintracksProvider_js_1.ChaintracksProvider(url, { apiPrefix });
713
+ const client = new ChaintracksProvider_js_1.ChaintracksProvider(url, {
714
+ apiPrefix,
715
+ allowPrivateHosts: config.allowPrivateHosts
716
+ });
417
717
  this.configureChainTracker(client);
418
718
  this.configureTopicAnchorHeaderResolver(async (blockHeight) => {
419
719
  const header = await client.findHeaderForHeight(blockHeight);
@@ -426,7 +726,7 @@ class OverlayExpress {
426
726
  };
427
727
  });
428
728
  if (config.reorgStream !== false) {
429
- this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth);
729
+ this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth, config.allowPrivateHosts);
430
730
  }
431
731
  this.logger.log(chalk_1.default.blue('go-chaintracks provider has been configured.'));
432
732
  }
@@ -436,6 +736,7 @@ class OverlayExpress {
436
736
  * @param enable - true to enable, false to disable
437
737
  */
438
738
  configureEnableGASPSync(enable) {
739
+ assertBooleanOption(enable, 'GASP synchronization setting');
439
740
  this.enableGASPSync = enable;
440
741
  this.logger.log(chalk_1.default.blue(`GASP synchronization ${enable ? 'enabled' : 'disabled'}.`));
441
742
  }
@@ -444,6 +745,7 @@ class OverlayExpress {
444
745
  * BASM is opt-in because it requires direct proofs and block hash resolution.
445
746
  */
446
747
  configureEnableBASMSync(enable) {
748
+ assertBooleanOption(enable, 'BASM synchronization setting');
447
749
  this.enableBASMSync = enable;
448
750
  this.logger.log(chalk_1.default.blue(`BASM synchronization ${enable ? 'enabled' : 'disabled'}.`));
449
751
  }
@@ -451,6 +753,9 @@ class OverlayExpress {
451
753
  * Configures the block header resolver used to derive BASM block hashes.
452
754
  */
453
755
  configureTopicAnchorHeaderResolver(resolver) {
756
+ if (typeof resolver !== 'function') {
757
+ throw new TypeError('Topic anchor header resolver must be a function');
758
+ }
454
759
  this.topicAnchorHeaderResolver = resolver;
455
760
  this.logger.log(chalk_1.default.blue('BASM topic anchor header resolver has been configured.'));
456
761
  }
@@ -460,11 +765,14 @@ class OverlayExpress {
460
765
  * @param url - The reorg stream URL, e.g. `https://arcade.example/v2/reorg/stream`.
461
766
  * @param scanDepth - Optional revalidation-sweep depth in blocks (default 3).
462
767
  */
463
- configureReorgStream(url, scanDepth) {
464
- this.reorgStreamUrl = url;
768
+ configureReorgStream(url, scanDepth, allowPrivateHosts = false) {
769
+ assertBooleanOption(allowPrivateHosts, 'Reorg stream allowPrivateHosts');
465
770
  if (scanDepth !== undefined) {
771
+ assertIntegerOption(scanDepth, 'Reorg scanDepth', 1, 100000);
466
772
  this.reorgScanDepth = scanDepth;
467
773
  }
774
+ this.reorgStreamUrl = (0, OutboundSecurity_js_1.secureServiceFetch)(url, undefined, allowPrivateHosts).baseUrl;
775
+ this.reorgStreamAllowPrivateHosts = allowPrivateHosts;
468
776
  this.logger.log(chalk_1.default.blue('BASM reorg stream has been configured.'));
469
777
  }
470
778
  /**
@@ -472,6 +780,11 @@ class OverlayExpress {
472
780
  */
473
781
  configureUnprovenEviction(config) {
474
782
  if (config.thresholdBlocks !== undefined) {
783
+ if (!Number.isSafeInteger(config.thresholdBlocks) ||
784
+ config.thresholdBlocks < 1 ||
785
+ config.thresholdBlocks > 10000000) {
786
+ throw new TypeError('thresholdBlocks must be an integer between 1 and 10000000');
787
+ }
475
788
  this.unprovenEvictionBlocks = config.thresholdBlocks;
476
789
  }
477
790
  this.logger.log(chalk_1.default.blue('Unproven transaction eviction has been configured.'));
@@ -482,10 +795,15 @@ class OverlayExpress {
482
795
  */
483
796
  configureUnprovenMaintenance(config) {
484
797
  if (config.intervalMs !== undefined) {
798
+ if (!Number.isSafeInteger(config.intervalMs) ||
799
+ config.intervalMs < 0 ||
800
+ config.intervalMs > 0x7fffffff) {
801
+ throw new TypeError('intervalMs must be an integer between 0 and 2147483647');
802
+ }
485
803
  this.unprovenMaintenanceIntervalMs = config.intervalMs;
486
804
  }
487
805
  if (config.thresholdBlocks !== undefined) {
488
- this.unprovenEvictionBlocks = config.thresholdBlocks;
806
+ this.configureUnprovenEviction({ thresholdBlocks: config.thresholdBlocks });
489
807
  }
490
808
  this.logger.log(chalk_1.default.blue('Unproven transaction maintenance has been configured.'));
491
809
  }
@@ -494,6 +812,9 @@ class OverlayExpress {
494
812
  * follow the chain tip. Set to 0 to disable periodic polling.
495
813
  */
496
814
  configureBASMBlockPollInterval(intervalMs) {
815
+ if (!Number.isSafeInteger(intervalMs) || intervalMs < 0 || intervalMs > 0x7fffffff) {
816
+ throw new TypeError('intervalMs must be an integer between 0 and 2147483647');
817
+ }
497
818
  this.basmBlockPollIntervalMs = intervalMs;
498
819
  this.logger.log(chalk_1.default.blue(`BASM block poll interval set to ${intervalMs}ms.`));
499
820
  }
@@ -502,6 +823,7 @@ class OverlayExpress {
502
823
  * @param enable - true to enable, false to disable
503
824
  */
504
825
  configureVerboseRequestLogging(enable) {
826
+ assertBooleanOption(enable, 'Verbose request logging setting');
505
827
  this.verboseRequestLogging = enable;
506
828
  this.logger.log(chalk_1.default.blue(`Verbose request logging ${enable ? 'enabled' : 'disabled'}.`));
507
829
  }
@@ -541,6 +863,7 @@ class OverlayExpress {
541
863
  * @param manager - An instance of TopicManager
542
864
  */
543
865
  configureTopicManager(name, manager) {
866
+ assertRegistryName(name, 'Topic manager name');
544
867
  this.managers[name] = manager;
545
868
  this.logger.log(chalk_1.default.blue(`Configured topic manager ${name}`));
546
869
  }
@@ -550,6 +873,7 @@ class OverlayExpress {
550
873
  * @param service - An instance of LookupService
551
874
  */
552
875
  configureLookupService(name, service) {
876
+ assertRegistryName(name, 'Lookup service name');
553
877
  this.services[name] = service;
554
878
  this.logger.log(chalk_1.default.blue(`Configured lookup service ${name}`));
555
879
  }
@@ -559,6 +883,7 @@ class OverlayExpress {
559
883
  * @param serviceFactory - A factory function that creates a LookupService instance using Knex
560
884
  */
561
885
  configureLookupServiceWithKnex(name, serviceFactory) {
886
+ assertRegistryName(name, 'Lookup service name');
562
887
  const knex = this.ensureKnex();
563
888
  const factoryResult = serviceFactory(knex);
564
889
  this.services[name] = factoryResult.service;
@@ -571,6 +896,7 @@ class OverlayExpress {
571
896
  * @param serviceFactory - A factory function that creates a LookupService instance using MongoDB
572
897
  */
573
898
  configureLookupServiceWithMongo(name, serviceFactory) {
899
+ assertRegistryName(name, 'Lookup service name');
574
900
  const mongoDb = this.ensureMongo();
575
901
  this.services[name] = serviceFactory(mongoDb);
576
902
  this.logger.log(chalk_1.default.blue(`Configured lookup service ${name} with MongoDB`));
@@ -590,9 +916,65 @@ class OverlayExpress {
590
916
  * in the `configureEngine()` method below.
591
917
  */
592
918
  configureEngineParams(params) {
919
+ var _a;
920
+ assertConfigurationObject(params, 'Engine configuration');
921
+ for (const key of [
922
+ 'logTime',
923
+ 'throwOnBroadcastFailure',
924
+ 'suppressDefaultSyncAdvertisements',
925
+ 'enableBASMSync',
926
+ 'reorgStreamAllowPrivateHosts'
927
+ ]) {
928
+ const value = params[key];
929
+ if (value !== undefined)
930
+ assertBooleanOption(value, `Engine ${key}`);
931
+ }
932
+ if (params.logPrefix !== undefined) {
933
+ assertSingleLineString(params.logPrefix, 'Engine logPrefix', 1024);
934
+ }
935
+ if (params.topicAnchorHeaderResolver !== undefined &&
936
+ typeof params.topicAnchorHeaderResolver !== 'function') {
937
+ throw new TypeError('Engine topicAnchorHeaderResolver must be a function');
938
+ }
939
+ if (params.chainTracker !== undefined && params.chainTracker !== 'scripts only') {
940
+ if (typeof params.chainTracker !== 'object' ||
941
+ params.chainTracker === null ||
942
+ typeof params.chainTracker.isValidRootForHeight !== 'function' ||
943
+ typeof params.chainTracker.currentHeight !== 'function') {
944
+ throw new TypeError('Engine chainTracker must implement root validation and currentHeight');
945
+ }
946
+ }
947
+ if (params.reorgScanDepth !== undefined) {
948
+ assertIntegerOption(params.reorgScanDepth, 'Engine reorgScanDepth', 1, 100000);
949
+ }
950
+ if (params.unprovenMaintenanceIntervalMs !== undefined) {
951
+ assertIntegerOption(params.unprovenMaintenanceIntervalMs, 'Engine unprovenMaintenanceIntervalMs', 0, 0x7fffffff);
952
+ }
953
+ if (params.unprovenEvictionBlocks !== undefined) {
954
+ assertIntegerOption(params.unprovenEvictionBlocks, 'Engine unprovenEvictionBlocks', 1, 10000000);
955
+ }
956
+ if (params.maxLookupResults !== undefined) {
957
+ assertIntegerOption(params.maxLookupResults, 'Engine maxLookupResults', 1, Number.MAX_SAFE_INTEGER, true);
958
+ }
959
+ if (params.reorgStreamUrl !== undefined) {
960
+ assertSingleLineString(params.reorgStreamUrl, 'Engine reorgStreamUrl', 2048, false);
961
+ (0, OutboundSecurity_js_1.secureServiceFetch)(params.reorgStreamUrl, undefined, (_a = params.reorgStreamAllowPrivateHosts) !== null && _a !== void 0 ? _a : false);
962
+ }
963
+ for (const key of ['shipTrackers', 'slapTrackers']) {
964
+ const trackers = params[key];
965
+ if (trackers !== undefined && !Array.isArray(trackers)) {
966
+ throw new TypeError(`Engine ${key} must be an array`);
967
+ }
968
+ }
593
969
  this.engineConfig = {
594
970
  ...this.engineConfig,
595
- ...params
971
+ ...params,
972
+ shipTrackers: params.shipTrackers === undefined
973
+ ? this.engineConfig.shipTrackers
974
+ : [...params.shipTrackers],
975
+ slapTrackers: params.slapTrackers === undefined
976
+ ? this.engineConfig.slapTrackers
977
+ : [...params.slapTrackers]
596
978
  };
597
979
  this.logger.log(chalk_1.default.blue('Advanced Engine configuration params have been updated.'));
598
980
  }
@@ -617,22 +999,22 @@ class OverlayExpress {
617
999
  }), 1000000);
618
1000
  if (autoConfigureShipSlap) {
619
1001
  const mongoDb = this.ensureMongo();
620
- const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb);
621
- const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb);
1002
+ const shipStorage = new overlay_discovery_services_1.SHIPStorage(mongoDb);
1003
+ const slapStorage = new overlay_discovery_services_1.SLAPStorage(mongoDb);
622
1004
  // Run the one-time discovery migration before the engine can accept
623
1005
  // traffic, so a failed unique-index build is a visible startup failure.
624
1006
  await shipStorage.ensureIndexes();
625
1007
  await slapStorage.ensureIndexes();
626
- this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
627
- this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
1008
+ this.configureTopicManager('tm_ship', new overlay_discovery_services_1.SHIPTopicManager());
1009
+ this.configureTopicManager('tm_slap', new overlay_discovery_services_1.SLAPTopicManager());
628
1010
  const shipStorageForLookup = this.banService === undefined
629
1011
  ? shipStorage
630
1012
  : new BanAwareDiscoveryStorage_js_1.BanAwareSHIPStorage(shipStorage, this.banService, this.logger);
631
1013
  const slapStorageForLookup = this.banService === undefined
632
1014
  ? slapStorage
633
1015
  : new BanAwareDiscoveryStorage_js_1.BanAwareSLAPStorage(slapStorage, this.banService, this.logger);
634
- this.services.ls_ship = new ResourceBoundedLookupWrapper_js_1.ResourceBoundedLookupWrapper(new DiscoveryServices.SHIPLookupService(shipStorageForLookup), maxLookupResults);
635
- this.services.ls_slap = new ResourceBoundedLookupWrapper_js_1.ResourceBoundedLookupWrapper(new DiscoveryServices.SLAPLookupService(slapStorageForLookup), maxLookupResults);
1016
+ this.services.ls_ship = new ResourceBoundedLookupWrapper_js_1.ResourceBoundedLookupWrapper(new overlay_discovery_services_1.SHIPLookupService(shipStorageForLookup), maxLookupResults);
1017
+ this.services.ls_slap = new ResourceBoundedLookupWrapper_js_1.ResourceBoundedLookupWrapper(new overlay_discovery_services_1.SLAPLookupService(slapStorageForLookup), maxLookupResults);
636
1018
  this.logger.log(chalk_1.default.blue('Configured lookup service ls_ship with MongoDB'));
637
1019
  this.logger.log(chalk_1.default.blue('Configured lookup service ls_slap with MongoDB'));
638
1020
  }
@@ -672,7 +1054,7 @@ class OverlayExpress {
672
1054
  if (this.enableGASPSync) {
673
1055
  return (_a = this.engineConfig.syncConfiguration) !== null && _a !== void 0 ? _a : {};
674
1056
  }
675
- const syncConfig = {};
1057
+ const syncConfig = Object.create(null);
676
1058
  for (const name of Object.keys(this.managers)) {
677
1059
  syncConfig[name] = false;
678
1060
  }
@@ -687,7 +1069,8 @@ class OverlayExpress {
687
1069
  apiKey: this.arcadeApiKey,
688
1070
  callbackUrl,
689
1071
  callbackToken: this.arcCallbackToken,
690
- deploymentId: this.arcadeDeploymentId
1072
+ deploymentId: this.arcadeDeploymentId,
1073
+ allowPrivateHosts: this.arcadeAllowPrivateHosts
691
1074
  });
692
1075
  providers.push({
693
1076
  name: 'Arcade',
@@ -723,7 +1106,8 @@ class OverlayExpress {
723
1106
  apiKey: this.arcadeApiKey,
724
1107
  callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
725
1108
  callbackToken: this.arcCallbackToken,
726
- deploymentId: this.arcadeDeploymentId
1109
+ deploymentId: this.arcadeDeploymentId,
1110
+ allowPrivateHosts: this.arcadeAllowPrivateHosts
727
1111
  });
728
1112
  return this.arcadeProvider;
729
1113
  }
@@ -744,7 +1128,7 @@ class OverlayExpress {
744
1128
  throw new Error(`Arcade proof for ${txid} did not include a block height`);
745
1129
  }
746
1130
  const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight);
747
- if (!valid) {
1131
+ if (valid !== true) {
748
1132
  throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`);
749
1133
  }
750
1134
  return {
@@ -771,17 +1155,21 @@ class OverlayExpress {
771
1155
  if (this.network === 'ttn')
772
1156
  return undefined;
773
1157
  return async (blockHeight) => {
774
- const response = await fetch(`https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
1158
+ var _a;
1159
+ (0, OutboundSecurity_js_1.assertNonnegativeSafeInteger)(blockHeight, 'WhatsOnChain block height');
1160
+ const response = await (0, OutboundSecurity_js_1.fetchWithDeadline)(fetch, `https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
775
1161
  method: 'GET',
776
1162
  headers: { Accept: 'application/json' }
777
- });
1163
+ }, BLOCK_HEADER_REQUEST_TIMEOUT_MS);
778
1164
  if (!response.ok) {
1165
+ await ((_a = response.body) === null || _a === void 0 ? void 0 : _a.cancel());
779
1166
  throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`);
780
1167
  }
781
- const header = (await response.json());
782
- if (typeof header.hash !== 'string') {
783
- throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`);
784
- }
1168
+ const header = await (0, OutboundSecurity_js_1.readBoundedJson)(response, MAX_BLOCK_HEADER_RESPONSE_BYTES, 'WhatsOnChain header response', BLOCK_HEADER_REQUEST_TIMEOUT_MS);
1169
+ if (!(0, OutboundSecurity_js_1.isRecord)(header))
1170
+ throw new TypeError('WhatsOnChain returned an invalid block header');
1171
+ (0, OutboundSecurity_js_1.assertHash)(header.hash, 'WhatsOnChain block hash');
1172
+ (0, OutboundSecurity_js_1.assertHash)(header.merkleroot, 'WhatsOnChain Merkle root');
785
1173
  return {
786
1174
  blockHeight,
787
1175
  blockHash: header.hash,
@@ -810,7 +1198,7 @@ class OverlayExpress {
810
1198
  ? 'https://staging-storage.babbage.systems'
811
1199
  : 'https://storage.babbage.systems';
812
1200
  try {
813
- return new DiscoveryServices.WalletAdvertiser(this.network, this.privateKey, storageBase, `https://${this.advertisableFQDN}`);
1201
+ return new overlay_discovery_services_1.WalletAdvertiser(this.network, this.privateKey, storageBase, `https://${this.advertisableFQDN}`);
814
1202
  }
815
1203
  catch (e) {
816
1204
  this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled. Reason: ${e}`);
@@ -899,14 +1287,20 @@ class OverlayExpress {
899
1287
  /** Parse outpoint string, ban it, and evict it from all lookup services. */
900
1288
  async handleBanOutpoint(res, engine, value, reason) {
901
1289
  const dotIndex = value.lastIndexOf('.');
902
- if (dotIndex === -1) {
1290
+ if (dotIndex !== 64 || !/^(0|[1-9]\d*)$/.test(value.substring(dotIndex + 1))) {
903
1291
  return res
904
1292
  .status(400)
905
1293
  .json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
906
1294
  }
907
1295
  const txid = value.substring(0, dotIndex);
908
- const outputIndex = Number.parseInt(value.substring(dotIndex + 1));
909
- if (Number.isNaN(outputIndex)) {
1296
+ const outputIndex = Number(value.substring(dotIndex + 1));
1297
+ try {
1298
+ (0, OutboundSecurity_js_1.assertHash)(txid, 'Outpoint txid');
1299
+ (0, OutboundSecurity_js_1.assertNonnegativeSafeInteger)(outputIndex, 'Outpoint outputIndex');
1300
+ if (outputIndex > 0xffffffff)
1301
+ throw new TypeError('Outpoint outputIndex is too large');
1302
+ }
1303
+ catch {
910
1304
  return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' });
911
1305
  }
912
1306
  await this.banService.banOutpoint(txid, outputIndex, reason);
@@ -919,7 +1313,9 @@ class OverlayExpress {
919
1313
  /** Evict an output from a specific service or all services (silent per-service errors). */
920
1314
  async evictFromServices(engine, txid, outputIndex, service) {
921
1315
  if (typeof service === 'string') {
922
- const svc = engine.lookupServices[service];
1316
+ const svc = Object.prototype.hasOwnProperty.call(engine.lookupServices, service)
1317
+ ? engine.lookupServices[service]
1318
+ : undefined;
923
1319
  if (svc !== undefined)
924
1320
  await svc.outputEvicted(txid, outputIndex);
925
1321
  return;
@@ -958,18 +1354,29 @@ class OverlayExpress {
958
1354
  let timeout;
959
1355
  try {
960
1356
  const result = ((_a = (await Promise.race([
961
- Promise.resolve(definition.handler()),
1357
+ Promise.resolve().then(async () => await definition.handler()),
962
1358
  new Promise((_, reject) => {
963
1359
  timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
964
1360
  })
965
1361
  ]))) !== null && _a !== void 0 ? _a : {});
1362
+ if (typeof result !== 'object' ||
1363
+ result === null ||
1364
+ (result.status !== undefined && !['ok', 'degraded', 'error'].includes(result.status)) ||
1365
+ (result.message !== undefined &&
1366
+ (typeof result.message !== 'string' ||
1367
+ new TextEncoder().encode(result.message).byteLength > MAX_HEALTH_MESSAGE_BYTES))) {
1368
+ throw new TypeError('Health check returned an invalid result');
1369
+ }
1370
+ const details = result.details === undefined
1371
+ ? undefined
1372
+ : this.cloneBoundedHealthData(result.details, 'Health check details');
966
1373
  return {
967
1374
  name: definition.name,
968
1375
  scope: definition.scope,
969
1376
  critical: definition.critical,
970
1377
  status: (_b = result.status) !== null && _b !== void 0 ? _b : 'ok',
971
1378
  message: result.message,
972
- details: result.details,
1379
+ details,
973
1380
  durationMs: Date.now() - startedAt
974
1381
  };
975
1382
  }
@@ -993,6 +1400,24 @@ class OverlayExpress {
993
1400
  clearTimeout(timeout);
994
1401
  }
995
1402
  }
1403
+ cloneBoundedHealthData(value, label) {
1404
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
1405
+ throw new TypeError(`${label} must be an object`);
1406
+ }
1407
+ let serialized;
1408
+ try {
1409
+ serialized = JSON.stringify(value);
1410
+ }
1411
+ catch {
1412
+ throw new TypeError(`${label} must be JSON serializable`);
1413
+ }
1414
+ if (serialized === undefined)
1415
+ throw new TypeError(`${label} must be JSON serializable`);
1416
+ if (Buffer.byteLength(serialized, 'utf8') > MAX_HEALTH_REPORT_DATA_BYTES) {
1417
+ throw new RangeError(`${label} exceeds ${MAX_HEALTH_REPORT_DATA_BYTES} bytes`);
1418
+ }
1419
+ return JSON.parse(serialized);
1420
+ }
996
1421
  async collectHealthReport(mode) {
997
1422
  var _a;
998
1423
  var _b, _c;
@@ -1088,9 +1513,28 @@ class OverlayExpress {
1088
1513
  else if (checks.some(check => check.status !== 'ok')) {
1089
1514
  status = 'degraded';
1090
1515
  }
1091
- const context = typeof this.healthConfig.contextProvider === 'function'
1092
- ? await this.healthConfig.contextProvider()
1093
- : undefined;
1516
+ let context;
1517
+ if (mode === 'full' &&
1518
+ this.healthConfig.includeDetails &&
1519
+ typeof this.healthConfig.contextProvider === 'function') {
1520
+ let timeout;
1521
+ try {
1522
+ const suppliedContext = await Promise.race([
1523
+ Promise.resolve().then(async () => { var _a, _b; return await ((_b = (_a = this.healthConfig).contextProvider) === null || _b === void 0 ? void 0 : _b.call(_a)); }),
1524
+ new Promise((_, reject) => {
1525
+ timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
1526
+ })
1527
+ ]);
1528
+ context =
1529
+ suppliedContext === undefined
1530
+ ? undefined
1531
+ : this.cloneBoundedHealthData(suppliedContext, 'Health context');
1532
+ }
1533
+ finally {
1534
+ if (timeout !== undefined)
1535
+ clearTimeout(timeout);
1536
+ }
1537
+ }
1094
1538
  const report = {
1095
1539
  status,
1096
1540
  live,
@@ -1145,16 +1589,15 @@ class OverlayExpress {
1145
1589
  if (typeof headerToken === 'string' && headerToken.startsWith('Bearer ')) {
1146
1590
  return headerToken.slice('Bearer '.length);
1147
1591
  }
1148
- return headerToken;
1592
+ return undefined;
1149
1593
  }
1150
1594
  arcCallbackAuthorized(req) {
1151
1595
  if (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0) {
1152
- return true;
1596
+ return false;
1153
1597
  }
1154
1598
  const callbackHeader = req.headers['x-callback-token'];
1155
1599
  const callbackToken = Array.isArray(callbackHeader) ? callbackHeader[0] : callbackHeader;
1156
- return (this.arcCallbackRequestToken(req) === this.arcCallbackToken ||
1157
- callbackToken === this.arcCallbackToken);
1600
+ return [this.arcCallbackRequestToken(req), callbackToken].some(candidate => typeof candidate === 'string' && secretMatches(candidate, this.arcCallbackToken));
1158
1601
  }
1159
1602
  async processArcIngest(engine, req, res) {
1160
1603
  if (!this.arcCallbackAuthorized(req)) {
@@ -1237,6 +1680,12 @@ class OverlayExpress {
1237
1680
  async start() {
1238
1681
  const engine = this.ensureEngine();
1239
1682
  const knex = this.ensureKnex();
1683
+ const hasConfiguredArcProvider = (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1684
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0);
1685
+ if (hasConfiguredArcProvider &&
1686
+ (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0)) {
1687
+ throw new Error('ARC/Arcade is configured without an ARC callback token; configureArcCallbackToken is required');
1688
+ }
1240
1689
  this.startTime = new Date();
1241
1690
  const edgePolicy = this.edgePolicyConfig;
1242
1691
  const resourceProfile = (0, edgePolicy_js_1.readResourceProfile)(edgePolicy.environmentPrefix);
@@ -1260,13 +1709,23 @@ class OverlayExpress {
1260
1709
  throw new TypeError('OVERLAY_ADMIN_LIST_DEFAULT_LIMIT cannot exceed OVERLAY_ADMIN_LIST_MAX_LIMIT');
1261
1710
  }
1262
1711
  const parseAdminPage = (rawPageValue, rawLimitValue) => {
1263
- const rawPage = Number.parseInt(typeof rawPageValue === 'string' ? rawPageValue : '', 10);
1264
- const requestedPage = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1712
+ const rawPageText = typeof rawPageValue === 'string' ? rawPageValue.trim() : '';
1713
+ if (rawPageText.length > 0 && !/^[1-9]\d*$/.test(rawPageText)) {
1714
+ throw new TypeError('page must be a positive integer');
1715
+ }
1716
+ const requestedPage = rawPageText.length === 0 ? 1 : Number(rawPageText);
1717
+ if (!Number.isSafeInteger(requestedPage)) {
1718
+ throw new TypeError('page must be a positive safe integer');
1719
+ }
1265
1720
  const rawLimitText = typeof rawLimitValue === 'string' ? rawLimitValue.trim().toLowerCase() : '';
1266
- const parsedLimit = rawLimitText === '-1' || rawLimitText === 'unlimited'
1267
- ? -1
1268
- : Number.parseInt(rawLimitText, 10);
1269
- const requestedLimit = rawLimitText.length === 0 || Number.isNaN(parsedLimit) ? adminListDefaultLimit : parsedLimit;
1721
+ if (rawLimitText.length > 0 &&
1722
+ rawLimitText !== '-1' &&
1723
+ rawLimitText !== 'unlimited' &&
1724
+ !/^[1-9]\d*$/.test(rawLimitText)) {
1725
+ throw new TypeError('limit must be a positive integer, -1, or unlimited');
1726
+ }
1727
+ const parsedLimit = rawLimitText === '-1' || rawLimitText === 'unlimited' ? -1 : Number(rawLimitText);
1728
+ const requestedLimit = rawLimitText.length === 0 ? adminListDefaultLimit : parsedLimit;
1270
1729
  if (requestedLimit !== -1 && (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1)) {
1271
1730
  throw new TypeError('limit must be a positive integer, -1, or unlimited');
1272
1731
  }
@@ -1282,11 +1741,30 @@ class OverlayExpress {
1282
1741
  }
1283
1742
  return { page, limit, skip };
1284
1743
  };
1744
+ const parseAdminSearch = (rawSearchValue) => {
1745
+ var _a;
1746
+ if (rawSearchValue === undefined)
1747
+ return undefined;
1748
+ (0, OutboundSecurity_js_1.assertBoundedString)(rawSearchValue, 'search', 256);
1749
+ const search = rawSearchValue.trim();
1750
+ if (search.length === 0)
1751
+ return undefined;
1752
+ for (const character of search) {
1753
+ const codePoint = (_a = character.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
1754
+ if (codePoint <= 0x1f || codePoint === 0x7f) {
1755
+ throw new TypeError('search must not contain control characters');
1756
+ }
1757
+ }
1758
+ // Search is literal. Treating authenticated operator input as a MongoDB
1759
+ // regular expression still enables catastrophic backtracking and broad
1760
+ // accidental scans when an admin token or browser is compromised.
1761
+ return search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
1762
+ };
1285
1763
  this.app.disable('x-powered-by');
1286
1764
  this.app.use(edgePolicy_js_1.initialDoubleSlashCompatibility);
1287
1765
  this.app.use((0, edgePolicy_js_1.securityHeaders)({
1288
- environmentPrefix: edgePolicy.environmentPrefix,
1289
- ...edgePolicy.securityHeaders
1766
+ ...edgePolicy.securityHeaders,
1767
+ environmentPrefix: edgePolicy.environmentPrefix
1290
1768
  }));
1291
1769
  this.app.use((0, edgePolicy_js_1.corsPolicy)({
1292
1770
  environmentPrefix: edgePolicy.environmentPrefix,
@@ -1311,15 +1789,19 @@ class OverlayExpress {
1311
1789
  }
1312
1790
  // Serve a static documentation site or user interface
1313
1791
  this.app.get('/', (req, res) => {
1792
+ const scriptNonce = (0, node_crypto_1.randomBytes)(18).toString('base64');
1314
1793
  res.set('content-type', 'text/html');
1794
+ res.set('Content-Security-Policy', `default-src 'none'; script-src 'nonce-${scriptNonce}' 'strict-dynamic'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: https:; connect-src 'self' https:; font-src 'self' https://cdn.jsdelivr.net; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`);
1315
1795
  res.send((0, makeUserInterface_js_1.default)({
1316
1796
  ...this.webUIConfig,
1317
- adminIdentityKey: this.adminIdentityKey
1797
+ adminIdentityKey: this.adminIdentityKey,
1798
+ scriptNonce
1318
1799
  }));
1319
1800
  });
1320
1801
  // Serve health check endpoints
1321
1802
  this.app.get('/health/live', (_, res) => {
1322
- ;
1803
+ res.set('Cache-Control', 'no-store, max-age=0');
1804
+ res.set('Pragma', 'no-cache');
1323
1805
  (async () => {
1324
1806
  const report = await this.collectHealthReport('live');
1325
1807
  return res.status(report.live ? 200 : 503).json(report);
@@ -1333,7 +1815,8 @@ class OverlayExpress {
1333
1815
  });
1334
1816
  // Compatibility alias used by Kubernetes probes and existing deployments.
1335
1817
  this.app.get('/healthz', (_, res) => {
1336
- ;
1818
+ res.set('Cache-Control', 'no-store, max-age=0');
1819
+ res.set('Pragma', 'no-cache');
1337
1820
  (async () => {
1338
1821
  const report = await this.collectHealthReport('live');
1339
1822
  return res.status(report.live ? 200 : 503).json(report);
@@ -1343,7 +1826,8 @@ class OverlayExpress {
1343
1826
  });
1344
1827
  });
1345
1828
  this.app.get('/health/ready', (_, res) => {
1346
- ;
1829
+ res.set('Cache-Control', 'no-store, max-age=0');
1830
+ res.set('Pragma', 'no-cache');
1347
1831
  (async () => {
1348
1832
  const report = await this.collectHealthReport('ready');
1349
1833
  return res.status(report.ready ? 200 : 503).json(report);
@@ -1356,7 +1840,8 @@ class OverlayExpress {
1356
1840
  });
1357
1841
  });
1358
1842
  this.app.get('/health', (_, res) => {
1359
- ;
1843
+ res.set('Cache-Control', 'no-store, max-age=0');
1844
+ res.set('Pragma', 'no-cache');
1360
1845
  (async () => {
1361
1846
  const report = await this.collectHealthReport('full');
1362
1847
  return res.status(report.ready ? 200 : 503).json(report);
@@ -1473,8 +1958,8 @@ class OverlayExpress {
1473
1958
  let offChainValues;
1474
1959
  let beef = Array.from(body);
1475
1960
  if (includesOffChain) {
1476
- const r = new sdk_1.Utils.Reader(beef);
1477
- const l = r.readVarIntNum();
1961
+ const r = new utils_1.Reader(beef);
1962
+ const l = r.readVarIntNumStrict(false);
1478
1963
  beef = r.read(l);
1479
1964
  offChainValues = r.read();
1480
1965
  }
@@ -1530,7 +2015,7 @@ class OverlayExpress {
1530
2015
  const beef = new sdk_1.Beef();
1531
2016
  const outputs = result.outputs;
1532
2017
  // Serialize in the format expected by LookupResolver
1533
- const writer = new sdk_1.Utils.Writer();
2018
+ const writer = new utils_1.Writer();
1534
2019
  // Write number of outpoints
1535
2020
  writer.writeVarIntNum(outputs.length);
1536
2021
  // Write each outpoint data
@@ -1570,8 +2055,10 @@ class OverlayExpress {
1570
2055
  });
1571
2056
  });
1572
2057
  // ARC/Arcade ingest route (only if a provider is configured)
1573
- if ((typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1574
- (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)) {
2058
+ const hasArcProvider = (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
2059
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0);
2060
+ const hasArcCallbackToken = typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0;
2061
+ if (hasArcProvider && hasArcCallbackToken) {
1575
2062
  this.app.post('/arc-ingest', (req, res) => {
1576
2063
  ;
1577
2064
  (async () => {
@@ -1593,7 +2080,7 @@ class OverlayExpress {
1593
2080
  });
1594
2081
  });
1595
2082
  }
1596
- else {
2083
+ else if (!hasArcProvider) {
1597
2084
  this.logger.warn(chalk_1.default.yellow('Disabling ARC/Arcade ingest because no provider was configured.'));
1598
2085
  }
1599
2086
  // GASP sync routes if enabled
@@ -1607,7 +2094,7 @@ class OverlayExpress {
1607
2094
  return res.status(200).json(response);
1608
2095
  }
1609
2096
  catch (error) {
1610
- console.error(chalk_1.default.red('Error in /requestSyncResponse:'), error);
2097
+ this.logger.error(chalk_1.default.red(`Error in /requestSyncResponse: error=${(0, overlay_1.serializeErrorForLog)(error)}`));
1611
2098
  return res.status(400).json({
1612
2099
  status: 'error',
1613
2100
  message: publicErrorMessage(error)
@@ -1625,11 +2112,15 @@ class OverlayExpress {
1625
2112
  (async () => {
1626
2113
  try {
1627
2114
  const { graphID, txid, outputIndex } = req.body;
1628
- const response = await engine.provideForeignGASPNode(graphID, txid, outputIndex);
2115
+ const header = req.headers['x-bsv-topic'];
2116
+ if (typeof header !== 'string' || header.length === 0) {
2117
+ throw new PublicRequestError('Missing x-bsv-topic header');
2118
+ }
2119
+ const response = await engine.provideForeignGASPNode(graphID, txid, outputIndex, header);
1629
2120
  return res.status(200).json(response);
1630
2121
  }
1631
2122
  catch (error) {
1632
- console.error(chalk_1.default.red('Error in /requestForeignGASPNode:'), error);
2123
+ this.logger.error(chalk_1.default.red(`Error in /requestForeignGASPNode: error=${(0, overlay_1.serializeErrorForLog)(error)}`));
1633
2124
  return res.status(400).json({
1634
2125
  status: 'error',
1635
2126
  message: publicErrorMessage(error)
@@ -1671,6 +2162,13 @@ class OverlayExpress {
1671
2162
  }
1672
2163
  catch (error) {
1673
2164
  console.error(chalk_1.default.red(`Error in ${path}:`), error);
2165
+ if (error instanceof Error && 'code' in error && error.code === 'BASM_UNSUPPORTED') {
2166
+ return res.status(400).json({
2167
+ status: 'error',
2168
+ message: 'BASM capability is not supported by this Overlay engine',
2169
+ code: error.code
2170
+ });
2171
+ }
1674
2172
  return res.status(400).json({
1675
2173
  status: 'error',
1676
2174
  message: publicErrorMessage(error)
@@ -1681,38 +2179,90 @@ class OverlayExpress {
1681
2179
  });
1682
2180
  });
1683
2181
  };
1684
- const requireTxids = (value) => {
1685
- if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1686
- throw new PublicRequestError('txids must be an array of strings');
2182
+ const requireBasmCapability = (capability) => {
2183
+ if (typeof engine[capability] !== 'function') {
2184
+ throw new UnsupportedBasmCapabilityError();
2185
+ }
2186
+ };
2187
+ const requireBasmHeight = (value, field) => {
2188
+ if ((typeof value !== 'number' && typeof value !== 'string') ||
2189
+ (typeof value === 'string' && value.trim().length === 0)) {
2190
+ throw new PublicRequestError(`${field} must be a nonnegative safe integer`);
2191
+ }
2192
+ const height = Number(value);
2193
+ if (!Number.isSafeInteger(height) || height < 0) {
2194
+ throw new PublicRequestError(`${field} must be a nonnegative safe integer`);
2195
+ }
2196
+ return height;
2197
+ };
2198
+ const requireBlockHash = (value) => {
2199
+ if (value === undefined)
2200
+ return undefined;
2201
+ if (typeof value !== 'string' || !/^[0-9a-fA-F]{64}$/.test(value)) {
2202
+ throw new PublicRequestError('blockHash must be a 32-byte hexadecimal string');
2203
+ }
2204
+ return value.toLowerCase();
2205
+ };
2206
+ const requireTxids = (value, requireAtLeastOne = true) => {
2207
+ if (!Array.isArray(value) || (requireAtLeastOne && value.length === 0)) {
2208
+ throw new PublicRequestError('txids must be a non-empty array');
1687
2209
  }
1688
2210
  if (maxBasmTxids !== -1 && value.length > maxBasmTxids) {
1689
2211
  throw new PublicRequestError(`txids must contain at most ${maxBasmTxids} entries`);
1690
2212
  }
1691
- return value;
2213
+ const seen = new Set();
2214
+ const txids = [];
2215
+ for (const txid of value) {
2216
+ if (typeof txid !== 'string' || !/^[0-9a-fA-F]{64}$/.test(txid)) {
2217
+ throw new PublicRequestError('txids must contain 32-byte hexadecimal transaction IDs');
2218
+ }
2219
+ const normalized = txid.toLowerCase();
2220
+ if (seen.has(normalized)) {
2221
+ throw new PublicRequestError('txids must not contain duplicates');
2222
+ }
2223
+ seen.add(normalized);
2224
+ txids.push(normalized);
2225
+ }
2226
+ return txids;
1692
2227
  };
1693
- registerJsonRoute('/requestTopicAnchorTip', async (req) => await basmEngine.provideTopicAnchorTip(readBasmTopic(req)));
2228
+ registerJsonRoute('/requestTopicAnchorTip', async (req) => {
2229
+ requireBasmCapability('provideTopicAnchorTip');
2230
+ return await basmEngine.provideTopicAnchorTip(readBasmTopic(req));
2231
+ });
1694
2232
  registerJsonRoute('/requestTopicAnchorRange', async (req) => {
1695
2233
  const { fromHeight, toHeight } = req.body;
1696
- const from = Number(fromHeight);
1697
- const to = Number(toHeight);
1698
- if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to < from) {
2234
+ const from = requireBasmHeight(fromHeight, 'fromHeight');
2235
+ const to = requireBasmHeight(toHeight, 'toHeight');
2236
+ if (to < from) {
1699
2237
  throw new PublicRequestError('fromHeight and toHeight must define a valid ascending range');
1700
2238
  }
1701
2239
  if (maxBasmAnchorRange !== -1 && to - from + 1 > maxBasmAnchorRange) {
1702
2240
  throw new PublicRequestError(`topic anchor range must contain at most ${maxBasmAnchorRange} blocks`);
1703
2241
  }
2242
+ requireBasmCapability('provideTopicAnchorRange');
1704
2243
  return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), from, to);
1705
2244
  });
1706
2245
  registerJsonRoute('/requestAdmittedList', async (req) => {
1707
2246
  const { blockHeight, blockHash } = req.body;
1708
- return await basmEngine.provideAdmittedList(readBasmTopic(req), Number(blockHeight), typeof blockHash === 'string' ? blockHash : undefined);
2247
+ const height = requireBasmHeight(blockHeight, 'blockHeight');
2248
+ const hash = requireBlockHash(blockHash);
2249
+ requireBasmCapability('provideAdmittedList');
2250
+ return await basmEngine.provideAdmittedList(readBasmTopic(req), height, hash);
1709
2251
  });
1710
2252
  registerJsonRoute('/requestCompoundMerklePath', async (req) => {
1711
2253
  const topic = readBasmTopic(req);
1712
2254
  const { blockHeight, txids } = req.body;
1713
- return await basmEngine.provideCompoundMerklePath(topic, Number(blockHeight), requireTxids(txids));
2255
+ const height = requireBasmHeight(blockHeight, 'blockHeight');
2256
+ const requestedTxids = requireTxids(txids);
2257
+ requireBasmCapability('provideCompoundMerklePath');
2258
+ return await basmEngine.provideCompoundMerklePath(topic, height, requestedTxids);
2259
+ });
2260
+ registerJsonRoute('/requestRawTransactions', async (req) => {
2261
+ const topic = readBasmTopic(req);
2262
+ const txids = requireTxids(req.body.txids, false);
2263
+ requireBasmCapability('provideRawTransactions');
2264
+ return await basmEngine.provideRawTransactions(txids, topic);
1714
2265
  });
1715
- registerJsonRoute('/requestRawTransactions', async (req) => await basmEngine.provideRawTransactions(requireTxids(req.body.txids)));
1716
2266
  /**
1717
2267
  * ============== ADMIN ROUTES ==============
1718
2268
  * These routes expose advanced engine operations.
@@ -1740,6 +2290,10 @@ class OverlayExpress {
1740
2290
  * 2. BSV mutual auth - if req.auth.identityKey matches the admin identity key
1741
2291
  */
1742
2292
  const checkAdminAuth = (req, res, next) => {
2293
+ // Administrative responses contain sensitive operational state and must
2294
+ // never survive logout in browser, proxy, or shared-cache storage.
2295
+ res.setHeader('Cache-Control', 'no-store, max-age=0');
2296
+ res.setHeader('Pragma', 'no-cache');
1743
2297
  // Method 1: BSV mutual authentication (identity key match)
1744
2298
  const authReq = req;
1745
2299
  if (typeof this.adminIdentityKey === 'string' &&
@@ -1833,7 +2387,7 @@ class OverlayExpress {
1833
2387
  try {
1834
2388
  const db = this.ensureMongo();
1835
2389
  const collection = db.collection('shipRecords');
1836
- const search = typeof req.query.search === 'string' ? req.query.search : undefined;
2390
+ const search = parseAdminSearch(req.query.search);
1837
2391
  const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1838
2392
  const query = {};
1839
2393
  if (typeof search === 'string' && search.length > 0) {
@@ -1883,7 +2437,7 @@ class OverlayExpress {
1883
2437
  try {
1884
2438
  const db = this.ensureMongo();
1885
2439
  const collection = db.collection('slapRecords');
1886
- const search = typeof req.query.search === 'string' ? req.query.search : undefined;
2440
+ const search = parseAdminSearch(req.query.search);
1887
2441
  const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1888
2442
  const query = {};
1889
2443
  if (typeof search === 'string' && search.length > 0) {
@@ -2055,18 +2609,28 @@ class OverlayExpress {
2055
2609
  (async () => {
2056
2610
  try {
2057
2611
  const { txid, outputIndex, service, ban, banDomain: shouldBanDomain } = req.body;
2058
- if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
2612
+ try {
2613
+ (0, OutboundSecurity_js_1.assertHash)(txid, 'txid');
2614
+ (0, OutboundSecurity_js_1.assertNonnegativeSafeInteger)(outputIndex, 'outputIndex');
2615
+ if (outputIndex > 0xffffffff)
2616
+ throw new TypeError('outputIndex is too large');
2617
+ }
2618
+ catch {
2059
2619
  return res.status(400).json({
2060
2620
  status: 'error',
2061
- message: 'txid (string) and outputIndex (number) are required'
2621
+ message: 'txid and outputIndex must form a valid outpoint'
2062
2622
  });
2063
2623
  }
2624
+ if (service !== undefined && typeof service !== 'string') {
2625
+ return res.status(400).json({ status: 'error', message: 'service must be a string' });
2626
+ }
2064
2627
  // Look up domain before eviction if needed for banning
2065
2628
  let removedDomain;
2066
2629
  if (shouldBanDomain === true || ban === true) {
2067
2630
  removedDomain = await this.lookupDomainForOutpoint(txid, outputIndex);
2068
2631
  }
2069
- await this.evictFromServices(engine, txid, outputIndex, service);
2632
+ // Persist requested bans before eviction so a concurrent GASP sync
2633
+ // cannot re-admit the output during the administrative operation.
2070
2634
  if (ban === true && this.banService !== undefined) {
2071
2635
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain);
2072
2636
  }
@@ -2075,6 +2639,7 @@ class OverlayExpress {
2075
2639
  this.banService !== undefined) {
2076
2640
  await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal');
2077
2641
  }
2642
+ await this.evictFromServices(engine, txid, outputIndex, service);
2078
2643
  const banMsg = ban === true ? ' Outpoint banned.' : '';
2079
2644
  const domainMsg = shouldBanDomain === true && typeof removedDomain === 'string'
2080
2645
  ? ` Domain "${removedDomain}" banned.`
@@ -2201,22 +2766,20 @@ class OverlayExpress {
2201
2766
  this.app.post('/admin/evictOutpoint', checkAdminAuth, (req, res) => {
2202
2767
  ;
2203
2768
  (async () => {
2769
+ var _a;
2204
2770
  try {
2205
- if (typeof req.body.service === 'string') {
2206
- const service = engine.lookupServices[req.body.service];
2207
- await service.outputEvicted(req.body.txid, req.body.outputIndex);
2208
- }
2209
- else {
2210
- const services = Object.values(engine.lookupServices);
2211
- for (const service of services) {
2212
- try {
2213
- await service.outputEvicted(req.body.txid, req.body.outputIndex);
2214
- }
2215
- catch {
2216
- continue;
2217
- }
2771
+ const { txid, outputIndex, service } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
2772
+ (0, OutboundSecurity_js_1.assertHash)(txid, 'txid');
2773
+ (0, OutboundSecurity_js_1.assertNonnegativeSafeInteger)(outputIndex, 'outputIndex');
2774
+ if (outputIndex > 0xffffffff)
2775
+ throw new TypeError('outputIndex is too large');
2776
+ if (service !== undefined) {
2777
+ (0, OutboundSecurity_js_1.assertBoundedString)(service, 'service', 256, false);
2778
+ if (!Object.prototype.hasOwnProperty.call(engine.lookupServices, service)) {
2779
+ throw new TypeError('service must name a configured lookup service');
2218
2780
  }
2219
2781
  }
2782
+ await this.evictFromServices(engine, txid, outputIndex, service);
2220
2783
  return res.status(200).json({ status: 'success', message: 'Outpoint evicted' });
2221
2784
  }
2222
2785
  catch (error) {
@@ -2336,7 +2899,7 @@ class OverlayExpress {
2336
2899
  async runStartupSync() {
2337
2900
  var _a, _b;
2338
2901
  // The legacy Ninja advertiser has a setLookupEngine method.
2339
- if (((_a = this.engine) === null || _a === void 0 ? void 0 : _a.advertiser) instanceof DiscoveryServices.WalletAdvertiser) {
2902
+ if (((_a = this.engine) === null || _a === void 0 ? void 0 : _a.advertiser) instanceof overlay_discovery_services_1.WalletAdvertiser) {
2340
2903
  this.logger.log(chalk_1.default.cyan(`${this.name} will now advertise with SHIP and SLAP as appropriate at FQDN: ${this.advertisableFQDN}`));
2341
2904
  await this.engine.advertiser.init();
2342
2905
  }
@@ -2408,7 +2971,7 @@ class OverlayExpress {
2408
2971
  }
2409
2972
  /** Real-time reorg reconciliation via the go-chaintracks (Arcade) reorg SSE. */
2410
2973
  startBASMReorgStream() {
2411
- var _a, _b;
2974
+ var _a, _b, _c;
2412
2975
  const reorgStreamUrl = (_a = this.engineConfig.reorgStreamUrl) !== null && _a !== void 0 ? _a : this.reorgStreamUrl;
2413
2976
  const reorgScanDepth = (_b = this.engineConfig.reorgScanDepth) !== null && _b !== void 0 ? _b : this.reorgScanDepth;
2414
2977
  if (reorgStreamUrl === undefined || reorgStreamUrl === '') {
@@ -2423,7 +2986,8 @@ class OverlayExpress {
2423
2986
  onConnect: async () => {
2424
2987
  await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.revalidateRecentAnchors(reorgScanDepth));
2425
2988
  },
2426
- logger: this.logger
2989
+ logger: this.logger,
2990
+ allowPrivateHosts: (_c = this.engineConfig.reorgStreamAllowPrivateHosts) !== null && _c !== void 0 ? _c : this.reorgStreamAllowPrivateHosts
2427
2991
  });
2428
2992
  this.reorgAdapter.start();
2429
2993
  this.logger.log(chalk_1.default.green(`BASM reorg stream listening at ${reorgStreamUrl}`));