@bsv/overlay-express 2.6.1 → 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 (99) hide show
  1. package/README.md +76 -12
  2. package/dist/cjs/package.json +1 -1
  3. package/dist/cjs/src/ArcadeProvider.d.ts +5 -1
  4. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -1
  5. package/dist/cjs/src/ArcadeProvider.js +159 -18
  6. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  7. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts +1 -4
  8. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  9. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -1
  10. package/dist/cjs/src/BanAwareLookupWrapper.d.ts.map +1 -1
  11. package/dist/cjs/src/BanAwareLookupWrapper.js +2 -1
  12. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -1
  13. package/dist/cjs/src/BanAwareTopicManager.d.ts.map +1 -1
  14. package/dist/cjs/src/BanAwareTopicManager.js +3 -2
  15. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -1
  16. package/dist/cjs/src/BanService.d.ts +2 -0
  17. package/dist/cjs/src/BanService.d.ts.map +1 -1
  18. package/dist/cjs/src/BanService.js +52 -9
  19. package/dist/cjs/src/BanService.js.map +1 -1
  20. package/dist/cjs/src/ChaintracksProvider.d.ts +4 -0
  21. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -1
  22. package/dist/cjs/src/ChaintracksProvider.js +64 -9
  23. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  24. package/dist/cjs/src/JanitorService.d.ts +3 -0
  25. package/dist/cjs/src/JanitorService.d.ts.map +1 -1
  26. package/dist/cjs/src/JanitorService.js +80 -33
  27. package/dist/cjs/src/JanitorService.js.map +1 -1
  28. package/dist/cjs/src/OutboundSecurity.d.ts +19 -0
  29. package/dist/cjs/src/OutboundSecurity.d.ts.map +1 -0
  30. package/dist/cjs/src/OutboundSecurity.js +199 -0
  31. package/dist/cjs/src/OutboundSecurity.js.map +1 -0
  32. package/dist/cjs/src/OverlayExpress.d.ts +9 -1
  33. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -1
  34. package/dist/cjs/src/OverlayExpress.js +717 -153
  35. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  36. package/dist/cjs/src/OverlayMonitor.d.ts +10 -1
  37. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -1
  38. package/dist/cjs/src/OverlayMonitor.js +173 -72
  39. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  40. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -1
  41. package/dist/cjs/src/ProviderChainBroadcaster.js +28 -1
  42. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  43. package/dist/cjs/src/ReorgStream.d.ts +13 -9
  44. package/dist/cjs/src/ReorgStream.d.ts.map +1 -1
  45. package/dist/cjs/src/ReorgStream.js +193 -73
  46. package/dist/cjs/src/ReorgStream.js.map +1 -1
  47. package/dist/cjs/src/makeUserInterface.d.ts +2 -0
  48. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -1
  49. package/dist/cjs/src/makeUserInterface.js +316 -118
  50. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  51. package/dist/esm/src/ArcadeProvider.js +164 -19
  52. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  53. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  54. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  55. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  56. package/dist/esm/src/BanAwareTopicManager.js +4 -3
  57. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  58. package/dist/esm/src/BanService.js +51 -9
  59. package/dist/esm/src/BanService.js.map +1 -1
  60. package/dist/esm/src/ChaintracksProvider.js +63 -9
  61. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  62. package/dist/esm/src/JanitorService.js +78 -29
  63. package/dist/esm/src/JanitorService.js.map +1 -1
  64. package/dist/esm/src/OutboundSecurity.js +183 -0
  65. package/dist/esm/src/OutboundSecurity.js.map +1 -0
  66. package/dist/esm/src/OverlayExpress.js +708 -121
  67. package/dist/esm/src/OverlayExpress.js.map +1 -1
  68. package/dist/esm/src/OverlayMonitor.js +166 -67
  69. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  70. package/dist/esm/src/ProviderChainBroadcaster.js +28 -1
  71. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  72. package/dist/esm/src/ReorgStream.js +189 -66
  73. package/dist/esm/src/ReorgStream.js.map +1 -1
  74. package/dist/esm/src/makeUserInterface.js +316 -118
  75. package/dist/esm/src/makeUserInterface.js.map +1 -1
  76. package/dist/types/src/ArcadeProvider.d.ts +5 -1
  77. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  78. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +1 -4
  79. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  80. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  81. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  82. package/dist/types/src/BanService.d.ts +2 -0
  83. package/dist/types/src/BanService.d.ts.map +1 -1
  84. package/dist/types/src/ChaintracksProvider.d.ts +4 -0
  85. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  86. package/dist/types/src/JanitorService.d.ts +3 -0
  87. package/dist/types/src/JanitorService.d.ts.map +1 -1
  88. package/dist/types/src/OutboundSecurity.d.ts +19 -0
  89. package/dist/types/src/OutboundSecurity.d.ts.map +1 -0
  90. package/dist/types/src/OverlayExpress.d.ts +9 -1
  91. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  92. package/dist/types/src/OverlayMonitor.d.ts +10 -1
  93. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  94. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  95. package/dist/types/src/ReorgStream.d.ts +13 -9
  96. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  97. package/dist/types/src/makeUserInterface.d.ts +2 -0
  98. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  99. package/package.json +6 -6
@@ -1,14 +1,15 @@
1
+ import { Reader, Writer } from '@bsv/sdk/primitives/utils';
1
2
  import express from 'express';
2
3
  import bodyParser from 'body-parser';
3
4
  import { Engine, KnexStorage, KnexStorageMigrations, serializeErrorForLog, serializeLogValue } from '@bsv/overlay';
4
- import { ARC, MerklePath, WhatsOnChain, HTTPSOverlayBroadcastFacilitator, DEFAULT_TESTNET_SLAP_TRACKERS, DEFAULT_TTN_SLAP_TRACKERS, DEFAULT_SLAP_TRACKERS, Utils, Beef, Transaction, PrivateKey, KeyDeriver } from '@bsv/sdk';
5
+ import { ARC, MerklePath, WhatsOnChain, HTTPSOverlayBroadcastFacilitator, DEFAULT_TESTNET_SLAP_TRACKERS, DEFAULT_TTN_SLAP_TRACKERS, DEFAULT_SLAP_TRACKERS, Beef, Transaction, PrivateKey, KeyDeriver } from '@bsv/sdk';
5
6
  import Knex from 'knex';
6
7
  import { MongoClient } from 'mongodb';
7
8
  import makeUserInterface from './makeUserInterface.js';
8
- import * as DiscoveryServices from '@bsv/overlay-discovery-services';
9
+ import { SHIPLookupService, SHIPStorage, SHIPTopicManager, SLAPLookupService, SLAPStorage, SLAPTopicManager, WalletAdvertiser } from '@bsv/overlay-discovery-services';
9
10
  import chalk from 'chalk';
10
11
  import { v4 as uuidv4 } from 'uuid';
11
- import { createHash, timingSafeEqual } from 'node:crypto';
12
+ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
12
13
  import { JanitorService } from './JanitorService.js';
13
14
  import { BanService } from './BanService.js';
14
15
  import { BanAwareLookupWrapper } from './BanAwareLookupWrapper.js';
@@ -21,6 +22,7 @@ import { createAuthMiddleware } from '@bsv/auth-express-middleware';
21
22
  import { ArcadeProvider, isTerminalArcStatus } from './ArcadeProvider.js';
22
23
  import { ProviderChainBroadcaster } from './ProviderChainBroadcaster.js';
23
24
  import { ChaintracksProvider } from './ChaintracksProvider.js';
25
+ import { assertBoundedString, assertHash, assertNonnegativeSafeInteger, fetchWithDeadline, isRecord, readBoundedJson, secureServiceFetch } from './OutboundSecurity.js';
24
26
  import { bodyParserErrorHandler, concurrencyLimit, configureHttpServer, corsPolicy, initialDoubleSlashCompatibility, profileValue, readBodyLimitBytes, readResourceLimit, readResourceProfile, responseSizeLimit, securityHeaders } from './security/edgePolicy.js';
25
27
  /**
26
28
  * In-memory migration source for Knex migrations.
@@ -58,12 +60,30 @@ class InMemoryMigrationSource {
58
60
  return await Promise.resolve(migration);
59
61
  }
60
62
  }
63
+ const MAX_HEALTH_TIMEOUT_MS = 60_000;
64
+ const MAX_HEALTH_CHECKS = 128;
65
+ const MAX_HEALTH_NAME_BYTES = 128;
66
+ const MAX_HEALTH_MESSAGE_BYTES = 1024;
67
+ const MAX_HEALTH_REPORT_DATA_BYTES = 1024 * 1024;
68
+ const MIN_SHARED_SECRET_BYTES = 32;
69
+ const MAX_SHARED_SECRET_BYTES = 16 * 1024;
70
+ const MAX_BLOCK_HEADER_RESPONSE_BYTES = 64 * 1024;
71
+ const BLOCK_HEADER_REQUEST_TIMEOUT_MS = 30_000;
72
+ const MAX_CONFIGURED_BODY_BYTES = 512 * 1024 * 1024;
73
+ const MAX_CONFIGURED_ORIGINS = 128;
61
74
  class PublicRequestError extends Error {
62
75
  constructor(message) {
63
76
  super(message);
64
77
  this.name = 'PublicRequestError';
65
78
  }
66
79
  }
80
+ class UnsupportedBasmCapabilityError extends PublicRequestError {
81
+ code = 'BASM_UNSUPPORTED';
82
+ constructor() {
83
+ super('BASM capability is not supported by this Overlay engine');
84
+ this.name = 'UnsupportedBasmCapabilityError';
85
+ }
86
+ }
67
87
  function publicErrorMessage(error, fallback = 'Request could not be processed') {
68
88
  return error instanceof PublicRequestError ? error.message : fallback;
69
89
  }
@@ -72,6 +92,87 @@ function secretMatches(provided, expected) {
72
92
  const expectedDigest = createHash('sha256').update(expected, 'utf8').digest();
73
93
  return timingSafeEqual(providedDigest, expectedDigest);
74
94
  }
95
+ function assertSharedSecret(value, label) {
96
+ if (typeof value !== 'string' || value !== value.trim()) {
97
+ throw new TypeError(`${label} must not contain leading or trailing whitespace`);
98
+ }
99
+ const byteLength = new TextEncoder().encode(value).byteLength;
100
+ if (byteLength < MIN_SHARED_SECRET_BYTES || byteLength > MAX_SHARED_SECRET_BYTES) {
101
+ throw new TypeError(`${label} must contain between ${MIN_SHARED_SECRET_BYTES} and ${MAX_SHARED_SECRET_BYTES} UTF-8 bytes`);
102
+ }
103
+ if (Array.from(value).some(character => {
104
+ const codePoint = character.codePointAt(0) ?? 0;
105
+ return codePoint <= 0x1f || codePoint === 0x7f;
106
+ })) {
107
+ throw new TypeError(`${label} must not contain control characters`);
108
+ }
109
+ }
110
+ function assertConfigurationObject(value, label) {
111
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
112
+ throw new TypeError(`${label} must be an object`);
113
+ }
114
+ }
115
+ function assertBooleanOption(value, label) {
116
+ if (typeof value !== 'boolean')
117
+ throw new TypeError(`${label} must be a boolean`);
118
+ }
119
+ function assertSingleLineString(value, label, maxBytes, allowEmpty = true) {
120
+ assertBoundedString(value, label, maxBytes, allowEmpty);
121
+ if (Array.from(value).some(character => {
122
+ const codePoint = character.codePointAt(0) ?? 0;
123
+ return codePoint <= 0x1f || codePoint === 0x7f;
124
+ })) {
125
+ throw new TypeError(`${label} must not contain control characters`);
126
+ }
127
+ }
128
+ function assertIntegerOption(value, label, minimum, maximum, allowUnlimited = false) {
129
+ if (!Number.isSafeInteger(value) ||
130
+ (value < minimum && !(allowUnlimited && value === -1)) ||
131
+ value > maximum) {
132
+ const unlimited = allowUnlimited ? ' or -1' : '';
133
+ throw new TypeError(`${label} must be an integer between ${minimum} and ${maximum}${unlimited}`);
134
+ }
135
+ }
136
+ function normalizeConfiguredOrigin(value) {
137
+ assertSingleLineString(value, 'Allowed origin', 2048, false);
138
+ let parsed;
139
+ try {
140
+ parsed = new URL(value);
141
+ }
142
+ catch {
143
+ throw new TypeError('Allowed origins must be valid HTTP(S) origins');
144
+ }
145
+ if ((parsed.protocol !== 'https:' && parsed.protocol !== 'http:') ||
146
+ parsed.username !== '' ||
147
+ parsed.password !== '' ||
148
+ parsed.pathname !== '/' ||
149
+ parsed.search !== '' ||
150
+ parsed.hash !== '' ||
151
+ parsed.origin === 'null') {
152
+ throw new TypeError('Allowed origins must not contain credentials, paths, queries, or fragments');
153
+ }
154
+ return parsed.origin;
155
+ }
156
+ function normalizeAdvertisableFQDN(value) {
157
+ assertSingleLineString(value, 'Advertisable FQDN', 2048, false);
158
+ let parsed;
159
+ try {
160
+ parsed = new URL(value.includes('://') ? value : `https://${value}`);
161
+ }
162
+ catch {
163
+ throw new TypeError('Advertisable FQDN must be a valid HTTPS host');
164
+ }
165
+ if (parsed.protocol !== 'https:' ||
166
+ parsed.username !== '' ||
167
+ parsed.password !== '' ||
168
+ parsed.pathname !== '/' ||
169
+ parsed.search !== '' ||
170
+ parsed.hash !== '' ||
171
+ parsed.hostname === '') {
172
+ throw new TypeError('Advertisable FQDN must be an HTTPS host without credentials or a path');
173
+ }
174
+ return parsed.host;
175
+ }
75
176
  function parseTopicsHeader(header) {
76
177
  const value = header.trim();
77
178
  let parsed;
@@ -87,6 +188,18 @@ function parseTopicsHeader(header) {
87
188
  }
88
189
  return parsed;
89
190
  }
191
+ function assertRegistryName(value, label) {
192
+ assertBoundedString(value, label, 256, false);
193
+ if (value === '__proto__' ||
194
+ value === 'prototype' ||
195
+ value === 'constructor' ||
196
+ Array.from(value).some(character => {
197
+ const codePoint = character.codePointAt(0) ?? 0;
198
+ return codePoint <= 0x1f || codePoint === 0x7f;
199
+ })) {
200
+ throw new TypeError(`${label} is invalid`);
201
+ }
202
+ }
90
203
  /**
91
204
  * OverlayExpress class provides an Express-based server for hosting Overlay Services.
92
205
  * It allows configuration of various components like databases, topic managers, and lookup services.
@@ -118,9 +231,9 @@ export default class OverlayExpress {
118
231
  // The Overlay Engine
119
232
  engine;
120
233
  // Configured Topic Managers
121
- managers = {};
234
+ managers = Object.create(null);
122
235
  // Configured Lookup Services
123
- services = {};
236
+ services = Object.create(null);
124
237
  // Enable GASP Sync
125
238
  // (We allow an on/off toggle, but also can do advanced custom sync config below)
126
239
  enableGASPSync = true;
@@ -143,6 +256,7 @@ export default class OverlayExpress {
143
256
  // When set, reorgs are reconciled in real time; the block poll also runs a
144
257
  // revalidation sweep as a fallback / reconnect catch-up.
145
258
  reorgStreamUrl;
259
+ reorgStreamAllowPrivateHosts = false;
146
260
  // Depth (in blocks from the tip) for the reorg revalidation sweep.
147
261
  reorgScanDepth = 3;
148
262
  // Handle for the reorg SSE adapter.
@@ -159,6 +273,7 @@ export default class OverlayExpress {
159
273
  arcadeApiKey = undefined;
160
274
  arcadeDeploymentId = undefined;
161
275
  arcadeChaintracksApiPrefix = '/chaintracks/v2';
276
+ arcadeAllowPrivateHosts = false;
162
277
  arcadeProvider;
163
278
  // Verbose request logging
164
279
  verboseRequestLogging = false;
@@ -191,7 +306,7 @@ export default class OverlayExpress {
191
306
  startTime;
192
307
  // Health endpoint configuration
193
308
  healthConfig = {
194
- includeDetails: true,
309
+ includeDetails: false,
195
310
  timeoutMs: 5000
196
311
  };
197
312
  // Extra application-specific health checks
@@ -215,7 +330,7 @@ export default class OverlayExpress {
215
330
  maxRequestsPerSocket: 1_000
216
331
  },
217
332
  securityHeaders: {
218
- 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'"
333
+ 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'"
219
334
  }
220
335
  };
221
336
  /**
@@ -230,6 +345,9 @@ export default class OverlayExpress {
230
345
  this.name = name;
231
346
  this.privateKey = privateKey;
232
347
  this.advertisableFQDN = advertisableFQDN;
348
+ if (adminToken !== undefined)
349
+ assertSharedSecret(adminToken, 'The administrative Bearer token');
350
+ this.advertisableFQDN = normalizeAdvertisableFQDN(advertisableFQDN);
233
351
  this.app = express();
234
352
  this.logger.log(chalk.green.bold(`${name} constructed`));
235
353
  this.adminToken = adminToken ?? uuidv4(); // generate random if not provided
@@ -245,6 +363,7 @@ export default class OverlayExpress {
245
363
  * @param port - The port number
246
364
  */
247
365
  configurePort(port) {
366
+ assertIntegerOption(port, 'Server port', 1, 65_535);
248
367
  this.port = port;
249
368
  this.logger.log(chalk.blue(`Server port set to ${port}`));
250
369
  }
@@ -267,20 +386,64 @@ export default class OverlayExpress {
267
386
  * - maxReportResults: Maximum retained result details; -1 retains all
268
387
  */
269
388
  configureJanitor(config) {
270
- this.janitorConfig = {
271
- ...this.janitorConfig,
272
- ...config
273
- };
389
+ assertConfigurationObject(config, 'Janitor configuration');
390
+ const next = { ...this.janitorConfig };
391
+ if (config.requestTimeoutMs !== undefined) {
392
+ assertIntegerOption(config.requestTimeoutMs, 'Janitor requestTimeoutMs', 1, 300_000);
393
+ next.requestTimeoutMs = config.requestTimeoutMs;
394
+ }
395
+ if (config.hostDownRevokeScore !== undefined) {
396
+ assertIntegerOption(config.hostDownRevokeScore, 'Janitor hostDownRevokeScore', 1, 1000);
397
+ next.hostDownRevokeScore = config.hostDownRevokeScore;
398
+ }
399
+ if (config.autoBanOnRemoval !== undefined) {
400
+ assertBooleanOption(config.autoBanOnRemoval, 'Janitor autoBanOnRemoval');
401
+ next.autoBanOnRemoval = config.autoBanOnRemoval;
402
+ }
403
+ if (config.allowPrivateHosts !== undefined) {
404
+ assertBooleanOption(config.allowPrivateHosts, 'Janitor allowPrivateHosts');
405
+ next.allowPrivateHosts = config.allowPrivateHosts;
406
+ }
407
+ if (config.batchSize !== undefined) {
408
+ assertIntegerOption(config.batchSize, 'Janitor batchSize', 1, 100_000, true);
409
+ next.batchSize = config.batchSize;
410
+ }
411
+ if (config.maxReportResults !== undefined) {
412
+ assertIntegerOption(config.maxReportResults, 'Janitor maxReportResults', 1, 1_000_000, true);
413
+ next.maxReportResults = config.maxReportResults;
414
+ }
415
+ this.janitorConfig = next;
274
416
  this.logger.log(chalk.blue('Janitor service has been configured.'));
275
417
  }
276
418
  /**
277
419
  * Configures health-report behavior.
278
420
  */
279
421
  configureHealth(config) {
280
- this.healthConfig = {
281
- ...this.healthConfig,
282
- ...config
283
- };
422
+ if (typeof config !== 'object' || config === null || Array.isArray(config)) {
423
+ throw new TypeError('Health configuration must be an object');
424
+ }
425
+ const next = { ...this.healthConfig };
426
+ if (Object.prototype.hasOwnProperty.call(config, 'includeDetails')) {
427
+ if (typeof config.includeDetails !== 'boolean') {
428
+ throw new TypeError('Health includeDetails must be a boolean');
429
+ }
430
+ next.includeDetails = config.includeDetails;
431
+ }
432
+ if (Object.prototype.hasOwnProperty.call(config, 'timeoutMs')) {
433
+ if (!Number.isSafeInteger(config.timeoutMs) ||
434
+ config.timeoutMs < 1 ||
435
+ config.timeoutMs > MAX_HEALTH_TIMEOUT_MS) {
436
+ throw new TypeError(`Health timeoutMs must be an integer from 1 to ${MAX_HEALTH_TIMEOUT_MS}`);
437
+ }
438
+ next.timeoutMs = config.timeoutMs;
439
+ }
440
+ if (Object.prototype.hasOwnProperty.call(config, 'contextProvider')) {
441
+ if (config.contextProvider !== undefined && typeof config.contextProvider !== 'function') {
442
+ throw new TypeError('Health contextProvider must be a function');
443
+ }
444
+ next.contextProvider = config.contextProvider;
445
+ }
446
+ this.healthConfig = next;
284
447
  this.logger.log(chalk.blue('Health reporting has been configured.'));
285
448
  }
286
449
  /**
@@ -289,33 +452,142 @@ export default class OverlayExpress {
289
452
  * OVERLAY_CORS_MODE=allowlist to restrict browser callers.
290
453
  */
291
454
  configureEdgePolicy(config) {
292
- const { http, securityHeaders: headerConfig, ...topLevel } = config;
293
- const definedTopLevel = Object.fromEntries(Object.entries(topLevel).filter(([, value]) => value !== undefined));
294
- const definedHttp = Object.fromEntries(Object.entries(http ?? {}).filter(([, value]) => value !== undefined));
295
- const definedHeaders = Object.fromEntries(Object.entries(headerConfig ?? {}).filter(([, value]) => value !== undefined));
296
- this.edgePolicyConfig = {
455
+ assertConfigurationObject(config, 'HTTP edge policy');
456
+ const next = {
297
457
  ...this.edgePolicyConfig,
298
- ...definedTopLevel,
299
- http: {
300
- ...this.edgePolicyConfig.http,
301
- ...definedHttp
302
- },
303
- securityHeaders: {
304
- ...this.edgePolicyConfig.securityHeaders,
305
- ...definedHeaders
306
- }
458
+ allowedOrigins: this.edgePolicyConfig.allowedOrigins === undefined
459
+ ? undefined
460
+ : [...this.edgePolicyConfig.allowedOrigins],
461
+ http: { ...this.edgePolicyConfig.http },
462
+ securityHeaders: { ...this.edgePolicyConfig.securityHeaders }
307
463
  };
464
+ if (config.environmentPrefix !== undefined) {
465
+ if (typeof config.environmentPrefix !== 'string' ||
466
+ !/^[A-Z][A-Z0-9_]{0,63}$/.test(config.environmentPrefix)) {
467
+ throw new TypeError('HTTP edge environmentPrefix is invalid');
468
+ }
469
+ next.environmentPrefix = config.environmentPrefix;
470
+ }
471
+ if (config.allowedOrigins !== undefined) {
472
+ if (!Array.isArray(config.allowedOrigins) ||
473
+ config.allowedOrigins.length > MAX_CONFIGURED_ORIGINS) {
474
+ throw new TypeError(`allowedOrigins must contain at most ${MAX_CONFIGURED_ORIGINS} origins`);
475
+ }
476
+ next.allowedOrigins = [...new Set(config.allowedOrigins.map(normalizeConfiguredOrigin))];
477
+ }
478
+ if (config.jsonBodyLimitBytes !== undefined) {
479
+ assertIntegerOption(config.jsonBodyLimitBytes, 'JSON body limit', 1, MAX_CONFIGURED_BODY_BYTES, true);
480
+ next.jsonBodyLimitBytes = config.jsonBodyLimitBytes;
481
+ }
482
+ if (config.binaryBodyLimitBytes !== undefined) {
483
+ assertIntegerOption(config.binaryBodyLimitBytes, 'Binary body limit', 1, MAX_CONFIGURED_BODY_BYTES, true);
484
+ next.binaryBodyLimitBytes = config.binaryBodyLimitBytes;
485
+ }
486
+ if (config.maxConcurrentRequests !== undefined) {
487
+ assertIntegerOption(config.maxConcurrentRequests, 'Maximum concurrent requests', 1, 100_000, true);
488
+ next.maxConcurrentRequests = config.maxConcurrentRequests;
489
+ }
490
+ if (config.http !== undefined) {
491
+ assertConfigurationObject(config.http, 'HTTP server policy');
492
+ const httpBounds = [
493
+ ['requestTimeoutMs', 3_600_000, false],
494
+ ['headersTimeoutMs', 3_600_000, false],
495
+ ['keepAliveTimeoutMs', 3_600_000, false],
496
+ ['socketTimeoutMs', 3_600_000, false],
497
+ ['maxRequestsPerSocket', 1_000_000, false],
498
+ ['maxConnections', 1_000_000, true]
499
+ ];
500
+ for (const [key, maximum, allowUnlimited] of httpBounds) {
501
+ const value = config.http[key];
502
+ if (value === undefined)
503
+ continue;
504
+ assertIntegerOption(value, `HTTP ${key}`, 1, maximum, allowUnlimited);
505
+ next.http[key] = value;
506
+ }
507
+ if (next.http.headersTimeoutMs > next.http.requestTimeoutMs) {
508
+ throw new TypeError('HTTP headersTimeoutMs cannot exceed requestTimeoutMs');
509
+ }
510
+ if (next.http.keepAliveTimeoutMs > next.http.requestTimeoutMs) {
511
+ throw new TypeError('HTTP keepAliveTimeoutMs cannot exceed requestTimeoutMs');
512
+ }
513
+ }
514
+ if (config.securityHeaders !== undefined) {
515
+ assertConfigurationObject(config.securityHeaders, 'Security headers policy');
516
+ const headers = config.securityHeaders;
517
+ if (Object.prototype.hasOwnProperty.call(headers, 'environmentPrefix')) {
518
+ throw new TypeError('Security headers must use the top-level environmentPrefix');
519
+ }
520
+ for (const key of ['contentSecurityPolicy', 'permissionsPolicy']) {
521
+ const value = headers[key];
522
+ if (value === undefined)
523
+ continue;
524
+ if (value !== false)
525
+ assertSingleLineString(value, `Security header ${key}`, 16 * 1024);
526
+ next.securityHeaders[key] = value;
527
+ }
528
+ const enumeratedHeaders = {
529
+ crossOriginResourcePolicy: ['same-origin', 'same-site', 'cross-origin'],
530
+ crossOriginOpenerPolicy: ['same-origin', 'same-origin-allow-popups', 'unsafe-none'],
531
+ frameOptions: ['DENY', 'SAMEORIGIN']
532
+ };
533
+ for (const key of Object.keys(enumeratedHeaders)) {
534
+ const value = headers[key];
535
+ if (value === undefined)
536
+ continue;
537
+ if (value !== false && !enumeratedHeaders[key].includes(value)) {
538
+ throw new TypeError(`Security header ${key} is invalid`);
539
+ }
540
+ ;
541
+ next.securityHeaders[key] = value;
542
+ }
543
+ if (headers.strictTransportSecurity !== undefined) {
544
+ assertBooleanOption(headers.strictTransportSecurity, 'Strict-Transport-Security setting');
545
+ next.securityHeaders.strictTransportSecurity = headers.strictTransportSecurity;
546
+ }
547
+ }
548
+ this.edgePolicyConfig = next;
308
549
  this.logger.log(chalk.blue('HTTP edge policy has been configured.'));
309
550
  }
310
551
  /**
311
552
  * Registers an application-specific health check.
312
553
  */
313
554
  registerHealthCheck(definition) {
555
+ if (typeof definition !== 'object' || definition === null || Array.isArray(definition)) {
556
+ throw new TypeError('Health check definition must be an object');
557
+ }
558
+ if (typeof definition.name !== 'string' ||
559
+ definition.name.length === 0 ||
560
+ new TextEncoder().encode(definition.name).byteLength > MAX_HEALTH_NAME_BYTES ||
561
+ Array.from(definition.name).some(character => {
562
+ const codePoint = character.codePointAt(0) ?? 0;
563
+ return codePoint <= 0x1f || codePoint === 0x7f;
564
+ })) {
565
+ throw new TypeError('Health check name is invalid');
566
+ }
567
+ if (['process', 'engine', 'knex', 'mongo'].includes(definition.name)) {
568
+ throw new TypeError('Health check name is reserved');
569
+ }
570
+ if (definition.scope !== undefined &&
571
+ definition.scope !== 'live' &&
572
+ definition.scope !== 'ready') {
573
+ throw new TypeError('Health check scope is invalid');
574
+ }
575
+ if (definition.critical !== undefined && typeof definition.critical !== 'boolean') {
576
+ throw new TypeError('Health check critical must be a boolean');
577
+ }
578
+ if (typeof definition.handler !== 'function') {
579
+ throw new TypeError('Health check handler must be a function');
580
+ }
581
+ if (!this.healthChecks.some(check => check.name === definition.name) &&
582
+ this.healthChecks.length >= MAX_HEALTH_CHECKS) {
583
+ throw new RangeError(`Cannot register more than ${MAX_HEALTH_CHECKS} health checks`);
584
+ }
314
585
  this.healthChecks = this.healthChecks.filter(check => check.name !== definition.name);
315
586
  this.healthChecks.push({
316
- scope: 'ready',
317
- critical: false,
318
- ...definition
587
+ name: definition.name,
588
+ scope: definition.scope ?? 'ready',
589
+ critical: definition.critical ?? false,
590
+ handler: definition.handler
319
591
  });
320
592
  this.logger.log(chalk.blue(`Registered health check ${definition.name}`));
321
593
  }
@@ -327,6 +599,9 @@ export default class OverlayExpress {
327
599
  * @param identityKey - The hex-encoded public key of the admin
328
600
  */
329
601
  configureAdminIdentityKey(identityKey) {
602
+ if (typeof identityKey !== 'string' || !/^(?:02|03)[0-9a-fA-F]{64}$/.test(identityKey)) {
603
+ throw new TypeError('Admin identity key must be a compressed secp256k1 public key');
604
+ }
330
605
  this.adminIdentityKey = identityKey;
331
606
  this.logger.log(chalk.blue('Admin identity key has been configured.'));
332
607
  }
@@ -344,6 +619,9 @@ export default class OverlayExpress {
344
619
  * @param logger - A logger object (e.g., console)
345
620
  */
346
621
  configureLogger(logger) {
622
+ if (typeof logger !== 'object' || logger === null || typeof logger.log !== 'function') {
623
+ throw new TypeError('Logger must provide a log function');
624
+ }
347
625
  this.logger = logger;
348
626
  this.logger.log(chalk.blue('Logger has been configured.'));
349
627
  }
@@ -354,6 +632,9 @@ export default class OverlayExpress {
354
632
  * @param network - The network ('main', 'test', or 'ttn')
355
633
  */
356
634
  configureNetwork(network) {
635
+ if (network !== 'main' && network !== 'test' && network !== 'ttn') {
636
+ throw new TypeError('Network must be main, test, or ttn');
637
+ }
357
638
  this.network = network;
358
639
  this.chainTracker =
359
640
  network === 'ttn'
@@ -380,6 +661,13 @@ export default class OverlayExpress {
380
661
  }
381
662
  chainTracker = new WhatsOnChain(this.network);
382
663
  }
664
+ if (chainTracker !== 'scripts only' &&
665
+ (typeof chainTracker !== 'object' ||
666
+ chainTracker === null ||
667
+ typeof chainTracker.isValidRootForHeight !== 'function' ||
668
+ typeof chainTracker.currentHeight !== 'function')) {
669
+ throw new TypeError('ChainTracker must implement root validation and currentHeight');
670
+ }
383
671
  this.chainTracker = chainTracker;
384
672
  this.logger.log(chalk.blue('ChainTracker has been configured.'));
385
673
  }
@@ -388,6 +676,7 @@ export default class OverlayExpress {
388
676
  * @param apiKey - The ARC API key
389
677
  */
390
678
  configureArcApiKey(apiKey) {
679
+ assertSingleLineString(apiKey, 'ARC API key', MAX_SHARED_SECRET_BYTES);
391
680
  this.arcApiKey = apiKey;
392
681
  this.logger.log(chalk.blue('ARC API key has been configured.'));
393
682
  }
@@ -396,6 +685,7 @@ export default class OverlayExpress {
396
685
  * @param token - The token ARC should present when posting callback notifications.
397
686
  */
398
687
  configureArcCallbackToken(token) {
688
+ assertSharedSecret(token, 'The ARC callback token');
399
689
  this.arcCallbackToken = token;
400
690
  this.logger.log(chalk.blue('ARC callback token has been configured.'));
401
691
  }
@@ -403,9 +693,33 @@ export default class OverlayExpress {
403
693
  * Configures Arcade for first-choice transaction propagation and proof lookup.
404
694
  */
405
695
  configureArcade(url, config = {}) {
696
+ assertConfigurationObject(config, 'Arcade configuration');
697
+ if (config.allowPrivateHosts !== undefined) {
698
+ assertBooleanOption(config.allowPrivateHosts, 'Arcade allowPrivateHosts');
699
+ }
700
+ const allowPrivateHosts = config.allowPrivateHosts ?? false;
701
+ secureServiceFetch(url, undefined, allowPrivateHosts);
702
+ if (config.apiKey !== undefined) {
703
+ assertSingleLineString(config.apiKey, 'Arcade API key', MAX_SHARED_SECRET_BYTES);
704
+ }
705
+ if (config.deploymentId !== undefined) {
706
+ assertSingleLineString(config.deploymentId, 'Arcade deployment ID', 1024);
707
+ }
708
+ if (config.chaintracksApiPrefix !== undefined) {
709
+ assertSingleLineString(config.chaintracksApiPrefix, 'Arcade Chaintracks API prefix', 2048);
710
+ // Reuse the provider's URL-path parser even when Chaintracks is configured later.
711
+ const chaintracksStreamUrl = new ChaintracksProvider(url, {
712
+ apiPrefix: config.chaintracksApiPrefix,
713
+ allowPrivateHosts
714
+ }).reorgStreamUrl();
715
+ if (!chaintracksStreamUrl.endsWith('/reorg/stream')) {
716
+ throw new TypeError('Chaintracks API prefix must be a URL path');
717
+ }
718
+ }
406
719
  this.arcadeUrl = url;
407
720
  this.arcadeApiKey = config.apiKey;
408
721
  this.arcadeDeploymentId = config.deploymentId;
722
+ this.arcadeAllowPrivateHosts = allowPrivateHosts;
409
723
  if (config.chaintracksApiPrefix !== undefined) {
410
724
  this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix;
411
725
  }
@@ -416,8 +730,21 @@ export default class OverlayExpress {
416
730
  * BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
417
731
  */
418
732
  configureChaintracks(url, config = {}) {
733
+ assertConfigurationObject(config, 'Chaintracks configuration');
734
+ if (config.reorgStream !== undefined) {
735
+ assertBooleanOption(config.reorgStream, 'Chaintracks reorgStream');
736
+ }
737
+ if (config.allowPrivateHosts !== undefined) {
738
+ assertBooleanOption(config.allowPrivateHosts, 'Chaintracks allowPrivateHosts');
739
+ }
740
+ if (config.scanDepth !== undefined) {
741
+ assertIntegerOption(config.scanDepth, 'Chaintracks scanDepth', 1, 100_000);
742
+ }
419
743
  const apiPrefix = config.apiPrefix ?? '/chaintracks/v2';
420
- const client = new ChaintracksProvider(url, { apiPrefix });
744
+ const client = new ChaintracksProvider(url, {
745
+ apiPrefix,
746
+ allowPrivateHosts: config.allowPrivateHosts
747
+ });
421
748
  this.configureChainTracker(client);
422
749
  this.configureTopicAnchorHeaderResolver(async (blockHeight) => {
423
750
  const header = await client.findHeaderForHeight(blockHeight);
@@ -430,7 +757,7 @@ export default class OverlayExpress {
430
757
  };
431
758
  });
432
759
  if (config.reorgStream !== false) {
433
- this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth);
760
+ this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth, config.allowPrivateHosts);
434
761
  }
435
762
  this.logger.log(chalk.blue('go-chaintracks provider has been configured.'));
436
763
  }
@@ -440,6 +767,7 @@ export default class OverlayExpress {
440
767
  * @param enable - true to enable, false to disable
441
768
  */
442
769
  configureEnableGASPSync(enable) {
770
+ assertBooleanOption(enable, 'GASP synchronization setting');
443
771
  this.enableGASPSync = enable;
444
772
  this.logger.log(chalk.blue(`GASP synchronization ${enable ? 'enabled' : 'disabled'}.`));
445
773
  }
@@ -448,6 +776,7 @@ export default class OverlayExpress {
448
776
  * BASM is opt-in because it requires direct proofs and block hash resolution.
449
777
  */
450
778
  configureEnableBASMSync(enable) {
779
+ assertBooleanOption(enable, 'BASM synchronization setting');
451
780
  this.enableBASMSync = enable;
452
781
  this.logger.log(chalk.blue(`BASM synchronization ${enable ? 'enabled' : 'disabled'}.`));
453
782
  }
@@ -455,6 +784,9 @@ export default class OverlayExpress {
455
784
  * Configures the block header resolver used to derive BASM block hashes.
456
785
  */
457
786
  configureTopicAnchorHeaderResolver(resolver) {
787
+ if (typeof resolver !== 'function') {
788
+ throw new TypeError('Topic anchor header resolver must be a function');
789
+ }
458
790
  this.topicAnchorHeaderResolver = resolver;
459
791
  this.logger.log(chalk.blue('BASM topic anchor header resolver has been configured.'));
460
792
  }
@@ -464,11 +796,14 @@ export default class OverlayExpress {
464
796
  * @param url - The reorg stream URL, e.g. `https://arcade.example/v2/reorg/stream`.
465
797
  * @param scanDepth - Optional revalidation-sweep depth in blocks (default 3).
466
798
  */
467
- configureReorgStream(url, scanDepth) {
468
- this.reorgStreamUrl = url;
799
+ configureReorgStream(url, scanDepth, allowPrivateHosts = false) {
800
+ assertBooleanOption(allowPrivateHosts, 'Reorg stream allowPrivateHosts');
469
801
  if (scanDepth !== undefined) {
802
+ assertIntegerOption(scanDepth, 'Reorg scanDepth', 1, 100_000);
470
803
  this.reorgScanDepth = scanDepth;
471
804
  }
805
+ this.reorgStreamUrl = secureServiceFetch(url, undefined, allowPrivateHosts).baseUrl;
806
+ this.reorgStreamAllowPrivateHosts = allowPrivateHosts;
472
807
  this.logger.log(chalk.blue('BASM reorg stream has been configured.'));
473
808
  }
474
809
  /**
@@ -476,6 +811,11 @@ export default class OverlayExpress {
476
811
  */
477
812
  configureUnprovenEviction(config) {
478
813
  if (config.thresholdBlocks !== undefined) {
814
+ if (!Number.isSafeInteger(config.thresholdBlocks) ||
815
+ config.thresholdBlocks < 1 ||
816
+ config.thresholdBlocks > 10_000_000) {
817
+ throw new TypeError('thresholdBlocks must be an integer between 1 and 10000000');
818
+ }
479
819
  this.unprovenEvictionBlocks = config.thresholdBlocks;
480
820
  }
481
821
  this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'));
@@ -486,10 +826,15 @@ export default class OverlayExpress {
486
826
  */
487
827
  configureUnprovenMaintenance(config) {
488
828
  if (config.intervalMs !== undefined) {
829
+ if (!Number.isSafeInteger(config.intervalMs) ||
830
+ config.intervalMs < 0 ||
831
+ config.intervalMs > 0x7fffffff) {
832
+ throw new TypeError('intervalMs must be an integer between 0 and 2147483647');
833
+ }
489
834
  this.unprovenMaintenanceIntervalMs = config.intervalMs;
490
835
  }
491
836
  if (config.thresholdBlocks !== undefined) {
492
- this.unprovenEvictionBlocks = config.thresholdBlocks;
837
+ this.configureUnprovenEviction({ thresholdBlocks: config.thresholdBlocks });
493
838
  }
494
839
  this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'));
495
840
  }
@@ -498,6 +843,9 @@ export default class OverlayExpress {
498
843
  * follow the chain tip. Set to 0 to disable periodic polling.
499
844
  */
500
845
  configureBASMBlockPollInterval(intervalMs) {
846
+ if (!Number.isSafeInteger(intervalMs) || intervalMs < 0 || intervalMs > 0x7fffffff) {
847
+ throw new TypeError('intervalMs must be an integer between 0 and 2147483647');
848
+ }
501
849
  this.basmBlockPollIntervalMs = intervalMs;
502
850
  this.logger.log(chalk.blue(`BASM block poll interval set to ${intervalMs}ms.`));
503
851
  }
@@ -506,6 +854,7 @@ export default class OverlayExpress {
506
854
  * @param enable - true to enable, false to disable
507
855
  */
508
856
  configureVerboseRequestLogging(enable) {
857
+ assertBooleanOption(enable, 'Verbose request logging setting');
509
858
  this.verboseRequestLogging = enable;
510
859
  this.logger.log(chalk.blue(`Verbose request logging ${enable ? 'enabled' : 'disabled'}.`));
511
860
  }
@@ -545,6 +894,7 @@ export default class OverlayExpress {
545
894
  * @param manager - An instance of TopicManager
546
895
  */
547
896
  configureTopicManager(name, manager) {
897
+ assertRegistryName(name, 'Topic manager name');
548
898
  this.managers[name] = manager;
549
899
  this.logger.log(chalk.blue(`Configured topic manager ${name}`));
550
900
  }
@@ -554,6 +904,7 @@ export default class OverlayExpress {
554
904
  * @param service - An instance of LookupService
555
905
  */
556
906
  configureLookupService(name, service) {
907
+ assertRegistryName(name, 'Lookup service name');
557
908
  this.services[name] = service;
558
909
  this.logger.log(chalk.blue(`Configured lookup service ${name}`));
559
910
  }
@@ -563,6 +914,7 @@ export default class OverlayExpress {
563
914
  * @param serviceFactory - A factory function that creates a LookupService instance using Knex
564
915
  */
565
916
  configureLookupServiceWithKnex(name, serviceFactory) {
917
+ assertRegistryName(name, 'Lookup service name');
566
918
  const knex = this.ensureKnex();
567
919
  const factoryResult = serviceFactory(knex);
568
920
  this.services[name] = factoryResult.service;
@@ -575,6 +927,7 @@ export default class OverlayExpress {
575
927
  * @param serviceFactory - A factory function that creates a LookupService instance using MongoDB
576
928
  */
577
929
  configureLookupServiceWithMongo(name, serviceFactory) {
930
+ assertRegistryName(name, 'Lookup service name');
578
931
  const mongoDb = this.ensureMongo();
579
932
  this.services[name] = serviceFactory(mongoDb);
580
933
  this.logger.log(chalk.blue(`Configured lookup service ${name} with MongoDB`));
@@ -594,9 +947,64 @@ export default class OverlayExpress {
594
947
  * in the `configureEngine()` method below.
595
948
  */
596
949
  configureEngineParams(params) {
950
+ assertConfigurationObject(params, 'Engine configuration');
951
+ for (const key of [
952
+ 'logTime',
953
+ 'throwOnBroadcastFailure',
954
+ 'suppressDefaultSyncAdvertisements',
955
+ 'enableBASMSync',
956
+ 'reorgStreamAllowPrivateHosts'
957
+ ]) {
958
+ const value = params[key];
959
+ if (value !== undefined)
960
+ assertBooleanOption(value, `Engine ${key}`);
961
+ }
962
+ if (params.logPrefix !== undefined) {
963
+ assertSingleLineString(params.logPrefix, 'Engine logPrefix', 1024);
964
+ }
965
+ if (params.topicAnchorHeaderResolver !== undefined &&
966
+ typeof params.topicAnchorHeaderResolver !== 'function') {
967
+ throw new TypeError('Engine topicAnchorHeaderResolver must be a function');
968
+ }
969
+ if (params.chainTracker !== undefined && params.chainTracker !== 'scripts only') {
970
+ if (typeof params.chainTracker !== 'object' ||
971
+ params.chainTracker === null ||
972
+ typeof params.chainTracker.isValidRootForHeight !== 'function' ||
973
+ typeof params.chainTracker.currentHeight !== 'function') {
974
+ throw new TypeError('Engine chainTracker must implement root validation and currentHeight');
975
+ }
976
+ }
977
+ if (params.reorgScanDepth !== undefined) {
978
+ assertIntegerOption(params.reorgScanDepth, 'Engine reorgScanDepth', 1, 100_000);
979
+ }
980
+ if (params.unprovenMaintenanceIntervalMs !== undefined) {
981
+ assertIntegerOption(params.unprovenMaintenanceIntervalMs, 'Engine unprovenMaintenanceIntervalMs', 0, 0x7fffffff);
982
+ }
983
+ if (params.unprovenEvictionBlocks !== undefined) {
984
+ assertIntegerOption(params.unprovenEvictionBlocks, 'Engine unprovenEvictionBlocks', 1, 10_000_000);
985
+ }
986
+ if (params.maxLookupResults !== undefined) {
987
+ assertIntegerOption(params.maxLookupResults, 'Engine maxLookupResults', 1, Number.MAX_SAFE_INTEGER, true);
988
+ }
989
+ if (params.reorgStreamUrl !== undefined) {
990
+ assertSingleLineString(params.reorgStreamUrl, 'Engine reorgStreamUrl', 2048, false);
991
+ secureServiceFetch(params.reorgStreamUrl, undefined, params.reorgStreamAllowPrivateHosts ?? false);
992
+ }
993
+ for (const key of ['shipTrackers', 'slapTrackers']) {
994
+ const trackers = params[key];
995
+ if (trackers !== undefined && !Array.isArray(trackers)) {
996
+ throw new TypeError(`Engine ${key} must be an array`);
997
+ }
998
+ }
597
999
  this.engineConfig = {
598
1000
  ...this.engineConfig,
599
- ...params
1001
+ ...params,
1002
+ shipTrackers: params.shipTrackers === undefined
1003
+ ? this.engineConfig.shipTrackers
1004
+ : [...params.shipTrackers],
1005
+ slapTrackers: params.slapTrackers === undefined
1006
+ ? this.engineConfig.slapTrackers
1007
+ : [...params.slapTrackers]
600
1008
  };
601
1009
  this.logger.log(chalk.blue('Advanced Engine configuration params have been updated.'));
602
1010
  }
@@ -621,22 +1029,22 @@ export default class OverlayExpress {
621
1029
  }), 1_000_000);
622
1030
  if (autoConfigureShipSlap) {
623
1031
  const mongoDb = this.ensureMongo();
624
- const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb);
625
- const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb);
1032
+ const shipStorage = new SHIPStorage(mongoDb);
1033
+ const slapStorage = new SLAPStorage(mongoDb);
626
1034
  // Run the one-time discovery migration before the engine can accept
627
1035
  // traffic, so a failed unique-index build is a visible startup failure.
628
1036
  await shipStorage.ensureIndexes();
629
1037
  await slapStorage.ensureIndexes();
630
- this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
631
- this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
1038
+ this.configureTopicManager('tm_ship', new SHIPTopicManager());
1039
+ this.configureTopicManager('tm_slap', new SLAPTopicManager());
632
1040
  const shipStorageForLookup = this.banService === undefined
633
1041
  ? shipStorage
634
1042
  : new BanAwareSHIPStorage(shipStorage, this.banService, this.logger);
635
1043
  const slapStorageForLookup = this.banService === undefined
636
1044
  ? slapStorage
637
1045
  : new BanAwareSLAPStorage(slapStorage, this.banService, this.logger);
638
- this.services.ls_ship = new ResourceBoundedLookupWrapper(new DiscoveryServices.SHIPLookupService(shipStorageForLookup), maxLookupResults);
639
- this.services.ls_slap = new ResourceBoundedLookupWrapper(new DiscoveryServices.SLAPLookupService(slapStorageForLookup), maxLookupResults);
1046
+ this.services.ls_ship = new ResourceBoundedLookupWrapper(new SHIPLookupService(shipStorageForLookup), maxLookupResults);
1047
+ this.services.ls_slap = new ResourceBoundedLookupWrapper(new SLAPLookupService(slapStorageForLookup), maxLookupResults);
640
1048
  this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'));
641
1049
  this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'));
642
1050
  }
@@ -675,7 +1083,7 @@ export default class OverlayExpress {
675
1083
  if (this.enableGASPSync) {
676
1084
  return this.engineConfig.syncConfiguration ?? {};
677
1085
  }
678
- const syncConfig = {};
1086
+ const syncConfig = Object.create(null);
679
1087
  for (const name of Object.keys(this.managers)) {
680
1088
  syncConfig[name] = false;
681
1089
  }
@@ -690,7 +1098,8 @@ export default class OverlayExpress {
690
1098
  apiKey: this.arcadeApiKey,
691
1099
  callbackUrl,
692
1100
  callbackToken: this.arcCallbackToken,
693
- deploymentId: this.arcadeDeploymentId
1101
+ deploymentId: this.arcadeDeploymentId,
1102
+ allowPrivateHosts: this.arcadeAllowPrivateHosts
694
1103
  });
695
1104
  providers.push({
696
1105
  name: 'Arcade',
@@ -726,7 +1135,8 @@ export default class OverlayExpress {
726
1135
  apiKey: this.arcadeApiKey,
727
1136
  callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
728
1137
  callbackToken: this.arcCallbackToken,
729
- deploymentId: this.arcadeDeploymentId
1138
+ deploymentId: this.arcadeDeploymentId,
1139
+ allowPrivateHosts: this.arcadeAllowPrivateHosts
730
1140
  });
731
1141
  return this.arcadeProvider;
732
1142
  }
@@ -746,7 +1156,7 @@ export default class OverlayExpress {
746
1156
  throw new Error(`Arcade proof for ${txid} did not include a block height`);
747
1157
  }
748
1158
  const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight);
749
- if (!valid) {
1159
+ if (valid !== true) {
750
1160
  throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`);
751
1161
  }
752
1162
  return {
@@ -772,17 +1182,20 @@ export default class OverlayExpress {
772
1182
  if (this.network === 'ttn')
773
1183
  return undefined;
774
1184
  return async (blockHeight) => {
775
- const response = await fetch(`https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
1185
+ assertNonnegativeSafeInteger(blockHeight, 'WhatsOnChain block height');
1186
+ const response = await fetchWithDeadline(fetch, `https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
776
1187
  method: 'GET',
777
1188
  headers: { Accept: 'application/json' }
778
- });
1189
+ }, BLOCK_HEADER_REQUEST_TIMEOUT_MS);
779
1190
  if (!response.ok) {
1191
+ await response.body?.cancel();
780
1192
  throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`);
781
1193
  }
782
- const header = (await response.json());
783
- if (typeof header.hash !== 'string') {
784
- throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`);
785
- }
1194
+ const header = await readBoundedJson(response, MAX_BLOCK_HEADER_RESPONSE_BYTES, 'WhatsOnChain header response', BLOCK_HEADER_REQUEST_TIMEOUT_MS);
1195
+ if (!isRecord(header))
1196
+ throw new TypeError('WhatsOnChain returned an invalid block header');
1197
+ assertHash(header.hash, 'WhatsOnChain block hash');
1198
+ assertHash(header.merkleroot, 'WhatsOnChain Merkle root');
786
1199
  return {
787
1200
  blockHeight,
788
1201
  blockHash: header.hash,
@@ -811,7 +1224,7 @@ export default class OverlayExpress {
811
1224
  ? 'https://staging-storage.babbage.systems'
812
1225
  : 'https://storage.babbage.systems';
813
1226
  try {
814
- return new DiscoveryServices.WalletAdvertiser(this.network, this.privateKey, storageBase, `https://${this.advertisableFQDN}`);
1227
+ return new WalletAdvertiser(this.network, this.privateKey, storageBase, `https://${this.advertisableFQDN}`);
815
1228
  }
816
1229
  catch (e) {
817
1230
  this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled. Reason: ${e}`);
@@ -900,14 +1313,20 @@ export default class OverlayExpress {
900
1313
  /** Parse outpoint string, ban it, and evict it from all lookup services. */
901
1314
  async handleBanOutpoint(res, engine, value, reason) {
902
1315
  const dotIndex = value.lastIndexOf('.');
903
- if (dotIndex === -1) {
1316
+ if (dotIndex !== 64 || !/^(0|[1-9]\d*)$/.test(value.substring(dotIndex + 1))) {
904
1317
  return res
905
1318
  .status(400)
906
1319
  .json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
907
1320
  }
908
1321
  const txid = value.substring(0, dotIndex);
909
- const outputIndex = Number.parseInt(value.substring(dotIndex + 1));
910
- if (Number.isNaN(outputIndex)) {
1322
+ const outputIndex = Number(value.substring(dotIndex + 1));
1323
+ try {
1324
+ assertHash(txid, 'Outpoint txid');
1325
+ assertNonnegativeSafeInteger(outputIndex, 'Outpoint outputIndex');
1326
+ if (outputIndex > 0xffffffff)
1327
+ throw new TypeError('Outpoint outputIndex is too large');
1328
+ }
1329
+ catch {
911
1330
  return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' });
912
1331
  }
913
1332
  await this.banService.banOutpoint(txid, outputIndex, reason);
@@ -920,7 +1339,9 @@ export default class OverlayExpress {
920
1339
  /** Evict an output from a specific service or all services (silent per-service errors). */
921
1340
  async evictFromServices(engine, txid, outputIndex, service) {
922
1341
  if (typeof service === 'string') {
923
- const svc = engine.lookupServices[service];
1342
+ const svc = Object.prototype.hasOwnProperty.call(engine.lookupServices, service)
1343
+ ? engine.lookupServices[service]
1344
+ : undefined;
924
1345
  if (svc !== undefined)
925
1346
  await svc.outputEvicted(txid, outputIndex);
926
1347
  return;
@@ -957,18 +1378,29 @@ export default class OverlayExpress {
957
1378
  let timeout;
958
1379
  try {
959
1380
  const result = ((await Promise.race([
960
- Promise.resolve(definition.handler()),
1381
+ Promise.resolve().then(async () => await definition.handler()),
961
1382
  new Promise((_, reject) => {
962
1383
  timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
963
1384
  })
964
1385
  ])) ?? {});
1386
+ if (typeof result !== 'object' ||
1387
+ result === null ||
1388
+ (result.status !== undefined && !['ok', 'degraded', 'error'].includes(result.status)) ||
1389
+ (result.message !== undefined &&
1390
+ (typeof result.message !== 'string' ||
1391
+ new TextEncoder().encode(result.message).byteLength > MAX_HEALTH_MESSAGE_BYTES))) {
1392
+ throw new TypeError('Health check returned an invalid result');
1393
+ }
1394
+ const details = result.details === undefined
1395
+ ? undefined
1396
+ : this.cloneBoundedHealthData(result.details, 'Health check details');
965
1397
  return {
966
1398
  name: definition.name,
967
1399
  scope: definition.scope,
968
1400
  critical: definition.critical,
969
1401
  status: result.status ?? 'ok',
970
1402
  message: result.message,
971
- details: result.details,
1403
+ details,
972
1404
  durationMs: Date.now() - startedAt
973
1405
  };
974
1406
  }
@@ -992,6 +1424,24 @@ export default class OverlayExpress {
992
1424
  clearTimeout(timeout);
993
1425
  }
994
1426
  }
1427
+ cloneBoundedHealthData(value, label) {
1428
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
1429
+ throw new TypeError(`${label} must be an object`);
1430
+ }
1431
+ let serialized;
1432
+ try {
1433
+ serialized = JSON.stringify(value);
1434
+ }
1435
+ catch {
1436
+ throw new TypeError(`${label} must be JSON serializable`);
1437
+ }
1438
+ if (serialized === undefined)
1439
+ throw new TypeError(`${label} must be JSON serializable`);
1440
+ if (Buffer.byteLength(serialized, 'utf8') > MAX_HEALTH_REPORT_DATA_BYTES) {
1441
+ throw new RangeError(`${label} exceeds ${MAX_HEALTH_REPORT_DATA_BYTES} bytes`);
1442
+ }
1443
+ return JSON.parse(serialized);
1444
+ }
995
1445
  async collectHealthReport(mode) {
996
1446
  const definitions = [
997
1447
  {
@@ -1083,9 +1533,28 @@ export default class OverlayExpress {
1083
1533
  else if (checks.some(check => check.status !== 'ok')) {
1084
1534
  status = 'degraded';
1085
1535
  }
1086
- const context = typeof this.healthConfig.contextProvider === 'function'
1087
- ? await this.healthConfig.contextProvider()
1088
- : undefined;
1536
+ let context;
1537
+ if (mode === 'full' &&
1538
+ this.healthConfig.includeDetails &&
1539
+ typeof this.healthConfig.contextProvider === 'function') {
1540
+ let timeout;
1541
+ try {
1542
+ const suppliedContext = await Promise.race([
1543
+ Promise.resolve().then(async () => await this.healthConfig.contextProvider?.()),
1544
+ new Promise((_, reject) => {
1545
+ timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
1546
+ })
1547
+ ]);
1548
+ context =
1549
+ suppliedContext === undefined
1550
+ ? undefined
1551
+ : this.cloneBoundedHealthData(suppliedContext, 'Health context');
1552
+ }
1553
+ finally {
1554
+ if (timeout !== undefined)
1555
+ clearTimeout(timeout);
1556
+ }
1557
+ }
1089
1558
  const report = {
1090
1559
  status,
1091
1560
  live,
@@ -1140,16 +1609,15 @@ export default class OverlayExpress {
1140
1609
  if (typeof headerToken === 'string' && headerToken.startsWith('Bearer ')) {
1141
1610
  return headerToken.slice('Bearer '.length);
1142
1611
  }
1143
- return headerToken;
1612
+ return undefined;
1144
1613
  }
1145
1614
  arcCallbackAuthorized(req) {
1146
1615
  if (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0) {
1147
- return true;
1616
+ return false;
1148
1617
  }
1149
1618
  const callbackHeader = req.headers['x-callback-token'];
1150
1619
  const callbackToken = Array.isArray(callbackHeader) ? callbackHeader[0] : callbackHeader;
1151
- return (this.arcCallbackRequestToken(req) === this.arcCallbackToken ||
1152
- callbackToken === this.arcCallbackToken);
1620
+ return [this.arcCallbackRequestToken(req), callbackToken].some(candidate => typeof candidate === 'string' && secretMatches(candidate, this.arcCallbackToken));
1153
1621
  }
1154
1622
  async processArcIngest(engine, req, res) {
1155
1623
  if (!this.arcCallbackAuthorized(req)) {
@@ -1232,6 +1700,12 @@ export default class OverlayExpress {
1232
1700
  async start() {
1233
1701
  const engine = this.ensureEngine();
1234
1702
  const knex = this.ensureKnex();
1703
+ const hasConfiguredArcProvider = (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1704
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0);
1705
+ if (hasConfiguredArcProvider &&
1706
+ (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0)) {
1707
+ throw new Error('ARC/Arcade is configured without an ARC callback token; configureArcCallbackToken is required');
1708
+ }
1235
1709
  this.startTime = new Date();
1236
1710
  const edgePolicy = this.edgePolicyConfig;
1237
1711
  const resourceProfile = readResourceProfile(edgePolicy.environmentPrefix);
@@ -1255,13 +1729,23 @@ export default class OverlayExpress {
1255
1729
  throw new TypeError('OVERLAY_ADMIN_LIST_DEFAULT_LIMIT cannot exceed OVERLAY_ADMIN_LIST_MAX_LIMIT');
1256
1730
  }
1257
1731
  const parseAdminPage = (rawPageValue, rawLimitValue) => {
1258
- const rawPage = Number.parseInt(typeof rawPageValue === 'string' ? rawPageValue : '', 10);
1259
- const requestedPage = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1732
+ const rawPageText = typeof rawPageValue === 'string' ? rawPageValue.trim() : '';
1733
+ if (rawPageText.length > 0 && !/^[1-9]\d*$/.test(rawPageText)) {
1734
+ throw new TypeError('page must be a positive integer');
1735
+ }
1736
+ const requestedPage = rawPageText.length === 0 ? 1 : Number(rawPageText);
1737
+ if (!Number.isSafeInteger(requestedPage)) {
1738
+ throw new TypeError('page must be a positive safe integer');
1739
+ }
1260
1740
  const rawLimitText = typeof rawLimitValue === 'string' ? rawLimitValue.trim().toLowerCase() : '';
1261
- const parsedLimit = rawLimitText === '-1' || rawLimitText === 'unlimited'
1262
- ? -1
1263
- : Number.parseInt(rawLimitText, 10);
1264
- const requestedLimit = rawLimitText.length === 0 || Number.isNaN(parsedLimit) ? adminListDefaultLimit : parsedLimit;
1741
+ if (rawLimitText.length > 0 &&
1742
+ rawLimitText !== '-1' &&
1743
+ rawLimitText !== 'unlimited' &&
1744
+ !/^[1-9]\d*$/.test(rawLimitText)) {
1745
+ throw new TypeError('limit must be a positive integer, -1, or unlimited');
1746
+ }
1747
+ const parsedLimit = rawLimitText === '-1' || rawLimitText === 'unlimited' ? -1 : Number(rawLimitText);
1748
+ const requestedLimit = rawLimitText.length === 0 ? adminListDefaultLimit : parsedLimit;
1265
1749
  if (requestedLimit !== -1 && (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1)) {
1266
1750
  throw new TypeError('limit must be a positive integer, -1, or unlimited');
1267
1751
  }
@@ -1277,11 +1761,29 @@ export default class OverlayExpress {
1277
1761
  }
1278
1762
  return { page, limit, skip };
1279
1763
  };
1764
+ const parseAdminSearch = (rawSearchValue) => {
1765
+ if (rawSearchValue === undefined)
1766
+ return undefined;
1767
+ assertBoundedString(rawSearchValue, 'search', 256);
1768
+ const search = rawSearchValue.trim();
1769
+ if (search.length === 0)
1770
+ return undefined;
1771
+ for (const character of search) {
1772
+ const codePoint = character.codePointAt(0) ?? 0;
1773
+ if (codePoint <= 0x1f || codePoint === 0x7f) {
1774
+ throw new TypeError('search must not contain control characters');
1775
+ }
1776
+ }
1777
+ // Search is literal. Treating authenticated operator input as a MongoDB
1778
+ // regular expression still enables catastrophic backtracking and broad
1779
+ // accidental scans when an admin token or browser is compromised.
1780
+ return search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
1781
+ };
1280
1782
  this.app.disable('x-powered-by');
1281
1783
  this.app.use(initialDoubleSlashCompatibility);
1282
1784
  this.app.use(securityHeaders({
1283
- environmentPrefix: edgePolicy.environmentPrefix,
1284
- ...edgePolicy.securityHeaders
1785
+ ...edgePolicy.securityHeaders,
1786
+ environmentPrefix: edgePolicy.environmentPrefix
1285
1787
  }));
1286
1788
  this.app.use(corsPolicy({
1287
1789
  environmentPrefix: edgePolicy.environmentPrefix,
@@ -1306,15 +1808,19 @@ export default class OverlayExpress {
1306
1808
  }
1307
1809
  // Serve a static documentation site or user interface
1308
1810
  this.app.get('/', (req, res) => {
1811
+ const scriptNonce = randomBytes(18).toString('base64');
1309
1812
  res.set('content-type', 'text/html');
1813
+ 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'`);
1310
1814
  res.send(makeUserInterface({
1311
1815
  ...this.webUIConfig,
1312
- adminIdentityKey: this.adminIdentityKey
1816
+ adminIdentityKey: this.adminIdentityKey,
1817
+ scriptNonce
1313
1818
  }));
1314
1819
  });
1315
1820
  // Serve health check endpoints
1316
1821
  this.app.get('/health/live', (_, res) => {
1317
- ;
1822
+ res.set('Cache-Control', 'no-store, max-age=0');
1823
+ res.set('Pragma', 'no-cache');
1318
1824
  (async () => {
1319
1825
  const report = await this.collectHealthReport('live');
1320
1826
  return res.status(report.live ? 200 : 503).json(report);
@@ -1328,7 +1834,8 @@ export default class OverlayExpress {
1328
1834
  });
1329
1835
  // Compatibility alias used by Kubernetes probes and existing deployments.
1330
1836
  this.app.get('/healthz', (_, res) => {
1331
- ;
1837
+ res.set('Cache-Control', 'no-store, max-age=0');
1838
+ res.set('Pragma', 'no-cache');
1332
1839
  (async () => {
1333
1840
  const report = await this.collectHealthReport('live');
1334
1841
  return res.status(report.live ? 200 : 503).json(report);
@@ -1338,7 +1845,8 @@ export default class OverlayExpress {
1338
1845
  });
1339
1846
  });
1340
1847
  this.app.get('/health/ready', (_, res) => {
1341
- ;
1848
+ res.set('Cache-Control', 'no-store, max-age=0');
1849
+ res.set('Pragma', 'no-cache');
1342
1850
  (async () => {
1343
1851
  const report = await this.collectHealthReport('ready');
1344
1852
  return res.status(report.ready ? 200 : 503).json(report);
@@ -1351,7 +1859,8 @@ export default class OverlayExpress {
1351
1859
  });
1352
1860
  });
1353
1861
  this.app.get('/health', (_, res) => {
1354
- ;
1862
+ res.set('Cache-Control', 'no-store, max-age=0');
1863
+ res.set('Pragma', 'no-cache');
1355
1864
  (async () => {
1356
1865
  const report = await this.collectHealthReport('full');
1357
1866
  return res.status(report.ready ? 200 : 503).json(report);
@@ -1468,8 +1977,8 @@ export default class OverlayExpress {
1468
1977
  let offChainValues;
1469
1978
  let beef = Array.from(body);
1470
1979
  if (includesOffChain) {
1471
- const r = new Utils.Reader(beef);
1472
- const l = r.readVarIntNum();
1980
+ const r = new Reader(beef);
1981
+ const l = r.readVarIntNumStrict(false);
1473
1982
  beef = r.read(l);
1474
1983
  offChainValues = r.read();
1475
1984
  }
@@ -1525,7 +2034,7 @@ export default class OverlayExpress {
1525
2034
  const beef = new Beef();
1526
2035
  const outputs = result.outputs;
1527
2036
  // Serialize in the format expected by LookupResolver
1528
- const writer = new Utils.Writer();
2037
+ const writer = new Writer();
1529
2038
  // Write number of outpoints
1530
2039
  writer.writeVarIntNum(outputs.length);
1531
2040
  // Write each outpoint data
@@ -1565,8 +2074,10 @@ export default class OverlayExpress {
1565
2074
  });
1566
2075
  });
1567
2076
  // ARC/Arcade ingest route (only if a provider is configured)
1568
- if ((typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1569
- (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)) {
2077
+ const hasArcProvider = (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
2078
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0);
2079
+ const hasArcCallbackToken = typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0;
2080
+ if (hasArcProvider && hasArcCallbackToken) {
1570
2081
  this.app.post('/arc-ingest', (req, res) => {
1571
2082
  ;
1572
2083
  (async () => {
@@ -1588,7 +2099,7 @@ export default class OverlayExpress {
1588
2099
  });
1589
2100
  });
1590
2101
  }
1591
- else {
2102
+ else if (!hasArcProvider) {
1592
2103
  this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'));
1593
2104
  }
1594
2105
  // GASP sync routes if enabled
@@ -1602,7 +2113,7 @@ export default class OverlayExpress {
1602
2113
  return res.status(200).json(response);
1603
2114
  }
1604
2115
  catch (error) {
1605
- console.error(chalk.red('Error in /requestSyncResponse:'), error);
2116
+ this.logger.error(chalk.red(`Error in /requestSyncResponse: error=${serializeErrorForLog(error)}`));
1606
2117
  return res.status(400).json({
1607
2118
  status: 'error',
1608
2119
  message: publicErrorMessage(error)
@@ -1620,11 +2131,15 @@ export default class OverlayExpress {
1620
2131
  (async () => {
1621
2132
  try {
1622
2133
  const { graphID, txid, outputIndex } = req.body;
1623
- const response = await engine.provideForeignGASPNode(graphID, txid, outputIndex);
2134
+ const header = req.headers['x-bsv-topic'];
2135
+ if (typeof header !== 'string' || header.length === 0) {
2136
+ throw new PublicRequestError('Missing x-bsv-topic header');
2137
+ }
2138
+ const response = await engine.provideForeignGASPNode(graphID, txid, outputIndex, header);
1624
2139
  return res.status(200).json(response);
1625
2140
  }
1626
2141
  catch (error) {
1627
- console.error(chalk.red('Error in /requestForeignGASPNode:'), error);
2142
+ this.logger.error(chalk.red(`Error in /requestForeignGASPNode: error=${serializeErrorForLog(error)}`));
1628
2143
  return res.status(400).json({
1629
2144
  status: 'error',
1630
2145
  message: publicErrorMessage(error)
@@ -1666,6 +2181,13 @@ export default class OverlayExpress {
1666
2181
  }
1667
2182
  catch (error) {
1668
2183
  console.error(chalk.red(`Error in ${path}:`), error);
2184
+ if (error instanceof Error && 'code' in error && error.code === 'BASM_UNSUPPORTED') {
2185
+ return res.status(400).json({
2186
+ status: 'error',
2187
+ message: 'BASM capability is not supported by this Overlay engine',
2188
+ code: error.code
2189
+ });
2190
+ }
1669
2191
  return res.status(400).json({
1670
2192
  status: 'error',
1671
2193
  message: publicErrorMessage(error)
@@ -1676,38 +2198,90 @@ export default class OverlayExpress {
1676
2198
  });
1677
2199
  });
1678
2200
  };
1679
- const requireTxids = (value) => {
1680
- if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1681
- throw new PublicRequestError('txids must be an array of strings');
2201
+ const requireBasmCapability = (capability) => {
2202
+ if (typeof engine[capability] !== 'function') {
2203
+ throw new UnsupportedBasmCapabilityError();
2204
+ }
2205
+ };
2206
+ const requireBasmHeight = (value, field) => {
2207
+ if ((typeof value !== 'number' && typeof value !== 'string') ||
2208
+ (typeof value === 'string' && value.trim().length === 0)) {
2209
+ throw new PublicRequestError(`${field} must be a nonnegative safe integer`);
2210
+ }
2211
+ const height = Number(value);
2212
+ if (!Number.isSafeInteger(height) || height < 0) {
2213
+ throw new PublicRequestError(`${field} must be a nonnegative safe integer`);
2214
+ }
2215
+ return height;
2216
+ };
2217
+ const requireBlockHash = (value) => {
2218
+ if (value === undefined)
2219
+ return undefined;
2220
+ if (typeof value !== 'string' || !/^[0-9a-fA-F]{64}$/.test(value)) {
2221
+ throw new PublicRequestError('blockHash must be a 32-byte hexadecimal string');
2222
+ }
2223
+ return value.toLowerCase();
2224
+ };
2225
+ const requireTxids = (value, requireAtLeastOne = true) => {
2226
+ if (!Array.isArray(value) || (requireAtLeastOne && value.length === 0)) {
2227
+ throw new PublicRequestError('txids must be a non-empty array');
1682
2228
  }
1683
2229
  if (maxBasmTxids !== -1 && value.length > maxBasmTxids) {
1684
2230
  throw new PublicRequestError(`txids must contain at most ${maxBasmTxids} entries`);
1685
2231
  }
1686
- return value;
2232
+ const seen = new Set();
2233
+ const txids = [];
2234
+ for (const txid of value) {
2235
+ if (typeof txid !== 'string' || !/^[0-9a-fA-F]{64}$/.test(txid)) {
2236
+ throw new PublicRequestError('txids must contain 32-byte hexadecimal transaction IDs');
2237
+ }
2238
+ const normalized = txid.toLowerCase();
2239
+ if (seen.has(normalized)) {
2240
+ throw new PublicRequestError('txids must not contain duplicates');
2241
+ }
2242
+ seen.add(normalized);
2243
+ txids.push(normalized);
2244
+ }
2245
+ return txids;
1687
2246
  };
1688
- registerJsonRoute('/requestTopicAnchorTip', async (req) => await basmEngine.provideTopicAnchorTip(readBasmTopic(req)));
2247
+ registerJsonRoute('/requestTopicAnchorTip', async (req) => {
2248
+ requireBasmCapability('provideTopicAnchorTip');
2249
+ return await basmEngine.provideTopicAnchorTip(readBasmTopic(req));
2250
+ });
1689
2251
  registerJsonRoute('/requestTopicAnchorRange', async (req) => {
1690
2252
  const { fromHeight, toHeight } = req.body;
1691
- const from = Number(fromHeight);
1692
- const to = Number(toHeight);
1693
- if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to < from) {
2253
+ const from = requireBasmHeight(fromHeight, 'fromHeight');
2254
+ const to = requireBasmHeight(toHeight, 'toHeight');
2255
+ if (to < from) {
1694
2256
  throw new PublicRequestError('fromHeight and toHeight must define a valid ascending range');
1695
2257
  }
1696
2258
  if (maxBasmAnchorRange !== -1 && to - from + 1 > maxBasmAnchorRange) {
1697
2259
  throw new PublicRequestError(`topic anchor range must contain at most ${maxBasmAnchorRange} blocks`);
1698
2260
  }
2261
+ requireBasmCapability('provideTopicAnchorRange');
1699
2262
  return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), from, to);
1700
2263
  });
1701
2264
  registerJsonRoute('/requestAdmittedList', async (req) => {
1702
2265
  const { blockHeight, blockHash } = req.body;
1703
- return await basmEngine.provideAdmittedList(readBasmTopic(req), Number(blockHeight), typeof blockHash === 'string' ? blockHash : undefined);
2266
+ const height = requireBasmHeight(blockHeight, 'blockHeight');
2267
+ const hash = requireBlockHash(blockHash);
2268
+ requireBasmCapability('provideAdmittedList');
2269
+ return await basmEngine.provideAdmittedList(readBasmTopic(req), height, hash);
1704
2270
  });
1705
2271
  registerJsonRoute('/requestCompoundMerklePath', async (req) => {
1706
2272
  const topic = readBasmTopic(req);
1707
2273
  const { blockHeight, txids } = req.body;
1708
- return await basmEngine.provideCompoundMerklePath(topic, Number(blockHeight), requireTxids(txids));
2274
+ const height = requireBasmHeight(blockHeight, 'blockHeight');
2275
+ const requestedTxids = requireTxids(txids);
2276
+ requireBasmCapability('provideCompoundMerklePath');
2277
+ return await basmEngine.provideCompoundMerklePath(topic, height, requestedTxids);
2278
+ });
2279
+ registerJsonRoute('/requestRawTransactions', async (req) => {
2280
+ const topic = readBasmTopic(req);
2281
+ const txids = requireTxids(req.body.txids, false);
2282
+ requireBasmCapability('provideRawTransactions');
2283
+ return await basmEngine.provideRawTransactions(txids, topic);
1709
2284
  });
1710
- registerJsonRoute('/requestRawTransactions', async (req) => await basmEngine.provideRawTransactions(requireTxids(req.body.txids)));
1711
2285
  /**
1712
2286
  * ============== ADMIN ROUTES ==============
1713
2287
  * These routes expose advanced engine operations.
@@ -1735,6 +2309,10 @@ export default class OverlayExpress {
1735
2309
  * 2. BSV mutual auth - if req.auth.identityKey matches the admin identity key
1736
2310
  */
1737
2311
  const checkAdminAuth = (req, res, next) => {
2312
+ // Administrative responses contain sensitive operational state and must
2313
+ // never survive logout in browser, proxy, or shared-cache storage.
2314
+ res.setHeader('Cache-Control', 'no-store, max-age=0');
2315
+ res.setHeader('Pragma', 'no-cache');
1738
2316
  // Method 1: BSV mutual authentication (identity key match)
1739
2317
  const authReq = req;
1740
2318
  if (typeof this.adminIdentityKey === 'string' &&
@@ -1825,7 +2403,7 @@ export default class OverlayExpress {
1825
2403
  try {
1826
2404
  const db = this.ensureMongo();
1827
2405
  const collection = db.collection('shipRecords');
1828
- const search = typeof req.query.search === 'string' ? req.query.search : undefined;
2406
+ const search = parseAdminSearch(req.query.search);
1829
2407
  const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1830
2408
  const query = {};
1831
2409
  if (typeof search === 'string' && search.length > 0) {
@@ -1875,7 +2453,7 @@ export default class OverlayExpress {
1875
2453
  try {
1876
2454
  const db = this.ensureMongo();
1877
2455
  const collection = db.collection('slapRecords');
1878
- const search = typeof req.query.search === 'string' ? req.query.search : undefined;
2456
+ const search = parseAdminSearch(req.query.search);
1879
2457
  const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1880
2458
  const query = {};
1881
2459
  if (typeof search === 'string' && search.length > 0) {
@@ -2046,18 +2624,28 @@ export default class OverlayExpress {
2046
2624
  (async () => {
2047
2625
  try {
2048
2626
  const { txid, outputIndex, service, ban, banDomain: shouldBanDomain } = req.body;
2049
- if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
2627
+ try {
2628
+ assertHash(txid, 'txid');
2629
+ assertNonnegativeSafeInteger(outputIndex, 'outputIndex');
2630
+ if (outputIndex > 0xffffffff)
2631
+ throw new TypeError('outputIndex is too large');
2632
+ }
2633
+ catch {
2050
2634
  return res.status(400).json({
2051
2635
  status: 'error',
2052
- message: 'txid (string) and outputIndex (number) are required'
2636
+ message: 'txid and outputIndex must form a valid outpoint'
2053
2637
  });
2054
2638
  }
2639
+ if (service !== undefined && typeof service !== 'string') {
2640
+ return res.status(400).json({ status: 'error', message: 'service must be a string' });
2641
+ }
2055
2642
  // Look up domain before eviction if needed for banning
2056
2643
  let removedDomain;
2057
2644
  if (shouldBanDomain === true || ban === true) {
2058
2645
  removedDomain = await this.lookupDomainForOutpoint(txid, outputIndex);
2059
2646
  }
2060
- await this.evictFromServices(engine, txid, outputIndex, service);
2647
+ // Persist requested bans before eviction so a concurrent GASP sync
2648
+ // cannot re-admit the output during the administrative operation.
2061
2649
  if (ban === true && this.banService !== undefined) {
2062
2650
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain);
2063
2651
  }
@@ -2066,6 +2654,7 @@ export default class OverlayExpress {
2066
2654
  this.banService !== undefined) {
2067
2655
  await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal');
2068
2656
  }
2657
+ await this.evictFromServices(engine, txid, outputIndex, service);
2069
2658
  const banMsg = ban === true ? ' Outpoint banned.' : '';
2070
2659
  const domainMsg = shouldBanDomain === true && typeof removedDomain === 'string'
2071
2660
  ? ` Domain "${removedDomain}" banned.`
@@ -2190,21 +2779,18 @@ export default class OverlayExpress {
2190
2779
  ;
2191
2780
  (async () => {
2192
2781
  try {
2193
- if (typeof req.body.service === 'string') {
2194
- const service = engine.lookupServices[req.body.service];
2195
- await service.outputEvicted(req.body.txid, req.body.outputIndex);
2196
- }
2197
- else {
2198
- const services = Object.values(engine.lookupServices);
2199
- for (const service of services) {
2200
- try {
2201
- await service.outputEvicted(req.body.txid, req.body.outputIndex);
2202
- }
2203
- catch {
2204
- continue;
2205
- }
2782
+ const { txid, outputIndex, service } = req.body ?? {};
2783
+ assertHash(txid, 'txid');
2784
+ assertNonnegativeSafeInteger(outputIndex, 'outputIndex');
2785
+ if (outputIndex > 0xffffffff)
2786
+ throw new TypeError('outputIndex is too large');
2787
+ if (service !== undefined) {
2788
+ assertBoundedString(service, 'service', 256, false);
2789
+ if (!Object.prototype.hasOwnProperty.call(engine.lookupServices, service)) {
2790
+ throw new TypeError('service must name a configured lookup service');
2206
2791
  }
2207
2792
  }
2793
+ await this.evictFromServices(engine, txid, outputIndex, service);
2208
2794
  return res.status(200).json({ status: 'success', message: 'Outpoint evicted' });
2209
2795
  }
2210
2796
  catch (error) {
@@ -2320,7 +2906,7 @@ export default class OverlayExpress {
2320
2906
  */
2321
2907
  async runStartupSync() {
2322
2908
  // The legacy Ninja advertiser has a setLookupEngine method.
2323
- if (this.engine?.advertiser instanceof DiscoveryServices.WalletAdvertiser) {
2909
+ if (this.engine?.advertiser instanceof WalletAdvertiser) {
2324
2910
  this.logger.log(chalk.cyan(`${this.name} will now advertise with SHIP and SLAP as appropriate at FQDN: ${this.advertisableFQDN}`));
2325
2911
  await this.engine.advertiser.init();
2326
2912
  }
@@ -2403,7 +2989,8 @@ export default class OverlayExpress {
2403
2989
  onConnect: async () => {
2404
2990
  await basmEngine?.revalidateRecentAnchors(reorgScanDepth);
2405
2991
  },
2406
- logger: this.logger
2992
+ logger: this.logger,
2993
+ allowPrivateHosts: this.engineConfig.reorgStreamAllowPrivateHosts ?? this.reorgStreamAllowPrivateHosts
2407
2994
  });
2408
2995
  this.reorgAdapter.start();
2409
2996
  this.logger.log(chalk.green(`BASM reorg stream listening at ${reorgStreamUrl}`));