@bsv/overlay-express 2.4.2 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/LICENSE.txt +57 -27
  2. package/README.md +141 -56
  3. package/dist/cjs/mod.d.ts +11 -0
  4. package/dist/cjs/mod.d.ts.map +1 -0
  5. package/dist/cjs/mod.js.map +1 -1
  6. package/dist/cjs/package.json +26 -13
  7. package/dist/cjs/src/ArcadeProvider.d.ts +37 -0
  8. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -0
  9. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  10. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts +36 -0
  11. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  12. package/dist/cjs/src/BanAwareDiscoveryStorage.js +5 -4
  13. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -1
  14. package/dist/cjs/src/BanAwareLookupWrapper.d.ts +31 -0
  15. package/dist/cjs/src/BanAwareLookupWrapper.d.ts.map +1 -0
  16. package/dist/cjs/src/BanAwareLookupWrapper.js +3 -2
  17. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -1
  18. package/dist/cjs/src/BanAwareTopicManager.d.ts +28 -0
  19. package/dist/cjs/src/BanAwareTopicManager.d.ts.map +1 -0
  20. package/dist/cjs/src/BanAwareTopicManager.js +3 -2
  21. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -1
  22. package/dist/cjs/src/BanService.d.ts +79 -0
  23. package/dist/cjs/src/BanService.d.ts.map +1 -0
  24. package/dist/cjs/src/BanService.js +18 -5
  25. package/dist/cjs/src/BanService.js.map +1 -1
  26. package/dist/cjs/src/ChaintracksProvider.d.ts +29 -0
  27. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -0
  28. package/dist/cjs/src/ChaintracksProvider.js +1 -1
  29. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  30. package/dist/cjs/src/JanitorService.d.ts +135 -0
  31. package/dist/cjs/src/JanitorService.d.ts.map +1 -0
  32. package/dist/cjs/src/JanitorService.js +168 -48
  33. package/dist/cjs/src/JanitorService.js.map +1 -1
  34. package/dist/cjs/src/OverlayExpress.d.ts +472 -0
  35. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -0
  36. package/dist/cjs/src/OverlayExpress.js +483 -193
  37. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  38. package/dist/cjs/src/OverlayMonitor.d.ts +197 -0
  39. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -0
  40. package/dist/cjs/src/OverlayMonitor.js +6 -4
  41. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  42. package/dist/cjs/src/ProviderChainBroadcaster.d.ts +18 -0
  43. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -0
  44. package/dist/cjs/src/ProviderChainBroadcaster.js +7 -3
  45. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  46. package/dist/cjs/src/ReorgStream.d.ts +74 -0
  47. package/dist/cjs/src/ReorgStream.d.ts.map +1 -0
  48. package/dist/cjs/src/ReorgStream.js +14 -6
  49. package/dist/cjs/src/ReorgStream.js.map +1 -1
  50. package/dist/cjs/src/ResourceBoundedLookupWrapper.d.ts +26 -0
  51. package/dist/cjs/src/ResourceBoundedLookupWrapper.d.ts.map +1 -0
  52. package/dist/cjs/src/ResourceBoundedLookupWrapper.js +70 -0
  53. package/dist/cjs/src/ResourceBoundedLookupWrapper.js.map +1 -0
  54. package/dist/cjs/src/generalGuide.md.d.ts +3 -0
  55. package/dist/cjs/src/generalGuide.md.d.ts.map +1 -0
  56. package/dist/cjs/src/generalGuide.md.js.map +1 -1
  57. package/dist/cjs/src/makeUserInterface.d.ts +22 -0
  58. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -0
  59. package/dist/cjs/src/makeUserInterface.js +4 -4
  60. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  61. package/dist/cjs/src/security/edgePolicy.d.ts +84 -0
  62. package/dist/cjs/src/security/edgePolicy.d.ts.map +1 -0
  63. package/dist/cjs/src/security/edgePolicy.js +533 -0
  64. package/dist/cjs/src/security/edgePolicy.js.map +1 -0
  65. package/dist/esm/mod.js.map +1 -1
  66. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  67. package/dist/esm/src/BanAwareDiscoveryStorage.js +5 -4
  68. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  69. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  70. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  71. package/dist/esm/src/BanAwareTopicManager.js +3 -2
  72. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  73. package/dist/esm/src/BanService.js +18 -5
  74. package/dist/esm/src/BanService.js.map +1 -1
  75. package/dist/esm/src/ChaintracksProvider.js +1 -1
  76. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  77. package/dist/esm/src/JanitorService.js +146 -19
  78. package/dist/esm/src/JanitorService.js.map +1 -1
  79. package/dist/esm/src/OverlayExpress.js +465 -176
  80. package/dist/esm/src/OverlayExpress.js.map +1 -1
  81. package/dist/esm/src/ProviderChainBroadcaster.js +7 -3
  82. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  83. package/dist/esm/src/ReorgStream.js +14 -6
  84. package/dist/esm/src/ReorgStream.js.map +1 -1
  85. package/dist/esm/src/ResourceBoundedLookupWrapper.js +70 -0
  86. package/dist/esm/src/ResourceBoundedLookupWrapper.js.map +1 -0
  87. package/dist/esm/src/makeUserInterface.js +3 -4
  88. package/dist/esm/src/makeUserInterface.js.map +1 -1
  89. package/dist/esm/src/security/edgePolicy.js +522 -0
  90. package/dist/esm/src/security/edgePolicy.js.map +1 -0
  91. package/dist/types/mod.d.ts +1 -1
  92. package/dist/types/mod.d.ts.map +1 -1
  93. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  94. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  95. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  96. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  97. package/dist/types/src/BanService.d.ts +2 -4
  98. package/dist/types/src/BanService.d.ts.map +1 -1
  99. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  100. package/dist/types/src/JanitorService.d.ts +21 -1
  101. package/dist/types/src/JanitorService.d.ts.map +1 -1
  102. package/dist/types/src/OverlayExpress.d.ts +54 -2
  103. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  104. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  105. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  106. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  107. package/dist/types/src/ResourceBoundedLookupWrapper.d.ts +26 -0
  108. package/dist/types/src/ResourceBoundedLookupWrapper.d.ts.map +1 -0
  109. package/dist/types/src/generalGuide.md.d.ts +1 -1
  110. package/dist/types/src/generalGuide.md.d.ts.map +1 -1
  111. package/dist/types/src/makeUserInterface.d.ts +1 -2
  112. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  113. package/dist/types/src/security/edgePolicy.d.ts +84 -0
  114. package/dist/types/src/security/edgePolicy.d.ts.map +1 -0
  115. package/package.json +47 -25
  116. package/dist/cjs/tsconfig.cjs.tsbuildinfo +0 -1
  117. package/dist/esm/tsconfig.esm.tsbuildinfo +0 -1
  118. package/dist/types/tsconfig.types.tsbuildinfo +0 -1
  119. package/mod.ts +0 -47
  120. package/src/ArcadeProvider.ts +0 -232
  121. package/src/BanAwareDiscoveryStorage.ts +0 -91
  122. package/src/BanAwareLookupWrapper.ts +0 -95
  123. package/src/BanAwareTopicManager.ts +0 -87
  124. package/src/BanService.ts +0 -154
  125. package/src/ChaintracksProvider.ts +0 -79
  126. package/src/JanitorService.ts +0 -423
  127. package/src/OverlayExpress.ts +0 -2479
  128. package/src/OverlayMonitor.ts +0 -817
  129. package/src/ProviderChainBroadcaster.ts +0 -108
  130. package/src/ReorgStream.ts +0 -221
  131. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +0 -131
  132. package/src/__tests__/BanAwareLookupWrapper.test.ts +0 -255
  133. package/src/__tests__/BanAwareTopicManager.test.ts +0 -132
  134. package/src/__tests__/BanService.test.ts +0 -310
  135. package/src/__tests__/InMemoryMigrationSource.test.ts +0 -11
  136. package/src/__tests__/JanitorService.test.ts +0 -941
  137. package/src/__tests__/OverlayExpress.test.ts +0 -1300
  138. package/src/__tests__/OverlayMonitor.test.ts +0 -255
  139. package/src/__tests__/OverlayProviders.live.test.ts +0 -43
  140. package/src/__tests__/OverlayProviders.test.ts +0 -123
  141. package/src/__tests__/README.md +0 -105
  142. package/src/__tests__/ReorgStream.test.ts +0 -66
  143. package/src/__tests__/makeUserInterface.test.ts +0 -193
  144. package/src/__tests__/setup.ts +0 -36
  145. package/src/auth-express-middleware.d.ts +0 -16
  146. package/src/generalGuide.md.ts +0 -74
  147. package/src/makeUserInterface.ts +0 -1224
@@ -1,17 +1,18 @@
1
1
  import express from 'express';
2
2
  import bodyParser from 'body-parser';
3
- import { Engine, KnexStorage, KnexStorageMigrations } from '@bsv/overlay';
3
+ import { Engine, KnexStorage, KnexStorageMigrations, serializeErrorForLog, serializeLogValue } from '@bsv/overlay';
4
4
  import { ARC, MerklePath, WhatsOnChain, HTTPSOverlayBroadcastFacilitator, DEFAULT_TESTNET_SLAP_TRACKERS, DEFAULT_SLAP_TRACKERS, Utils, Beef, Transaction, PrivateKey, KeyDeriver } from '@bsv/sdk';
5
5
  import Knex from 'knex';
6
6
  import { MongoClient } from 'mongodb';
7
7
  import makeUserInterface from './makeUserInterface.js';
8
8
  import * as DiscoveryServices from '@bsv/overlay-discovery-services';
9
9
  import chalk from 'chalk';
10
- import util from 'node:util';
11
10
  import { v4 as uuidv4 } from 'uuid';
11
+ import { createHash, timingSafeEqual } from 'node:crypto';
12
12
  import { JanitorService } from './JanitorService.js';
13
13
  import { BanService } from './BanService.js';
14
14
  import { BanAwareLookupWrapper } from './BanAwareLookupWrapper.js';
15
+ import { ResourceBoundedLookupWrapper } from './ResourceBoundedLookupWrapper.js';
15
16
  import { BanAwareTopicManager } from './BanAwareTopicManager.js';
16
17
  import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoveryStorage.js';
17
18
  import { ReorgSseAdapter } from './ReorgStream.js';
@@ -20,6 +21,7 @@ import { createAuthMiddleware } from '@bsv/auth-express-middleware';
20
21
  import { ArcadeProvider, isTerminalArcStatus } from './ArcadeProvider.js';
21
22
  import { ProviderChainBroadcaster } from './ProviderChainBroadcaster.js';
22
23
  import { ChaintracksProvider } from './ChaintracksProvider.js';
24
+ import { bodyParserErrorHandler, concurrencyLimit, configureHttpServer, corsPolicy, initialDoubleSlashCompatibility, profileValue, readBodyLimitBytes, readResourceLimit, readResourceProfile, responseSizeLimit, securityHeaders } from './security/edgePolicy.js';
23
25
  /**
24
26
  * In-memory migration source for Knex migrations.
25
27
  * Allows running migrations defined in code rather than files.
@@ -34,7 +36,7 @@ class InMemoryMigrationSource {
34
36
  * @param loadExtensions - Array of file extensions to filter by (not used here)
35
37
  * @returns Promise resolving to the array of migrations
36
38
  */
37
- async getMigrations(loadExtensions) {
39
+ async getMigrations(_loadExtensions) {
38
40
  return this.migrations;
39
41
  }
40
42
  /**
@@ -43,7 +45,9 @@ class InMemoryMigrationSource {
43
45
  * @returns The name of the migration
44
46
  */
45
47
  getMigrationName(migration) {
46
- return typeof migration.name === 'string' ? migration.name : `Migration at index ${this.migrations.indexOf(migration)}`;
48
+ return typeof migration.name === 'string'
49
+ ? migration.name
50
+ : `Migration at index ${this.migrations.indexOf(migration)}`;
47
51
  }
48
52
  /**
49
53
  * Gets the migration object.
@@ -54,13 +58,32 @@ class InMemoryMigrationSource {
54
58
  return await Promise.resolve(migration);
55
59
  }
56
60
  }
61
+ class PublicRequestError extends Error {
62
+ constructor(message) {
63
+ super(message);
64
+ this.name = 'PublicRequestError';
65
+ }
66
+ }
67
+ function publicErrorMessage(error, fallback = 'Request could not be processed') {
68
+ return error instanceof PublicRequestError ? error.message : fallback;
69
+ }
70
+ function secretMatches(provided, expected) {
71
+ const providedDigest = createHash('sha256').update(provided, 'utf8').digest();
72
+ const expectedDigest = createHash('sha256').update(expected, 'utf8').digest();
73
+ return timingSafeEqual(providedDigest, expectedDigest);
74
+ }
57
75
  function parseTopicsHeader(header) {
58
76
  const value = header.trim();
59
- const parsed = value.startsWith('[')
60
- ? JSON.parse(value)
61
- : value.split(',').map(topic => topic.trim());
62
- if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
63
- throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array');
77
+ let parsed;
78
+ try {
79
+ parsed = value.startsWith('[') ? JSON.parse(value) : value.split(',').map(topic => topic.trim());
80
+ }
81
+ catch {
82
+ throw new PublicRequestError('Invalid x-topics header: expected a comma-separated list or JSON string array');
83
+ }
84
+ if (!Array.isArray(parsed) ||
85
+ parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
86
+ throw new PublicRequestError('Invalid x-topics header: expected a comma-separated list or JSON string array');
64
87
  }
65
88
  return parsed;
66
89
  }
@@ -151,7 +174,10 @@ export default class OverlayExpress {
151
174
  janitorConfig = {
152
175
  requestTimeoutMs: 10000, // 10 seconds
153
176
  hostDownRevokeScore: 3,
154
- autoBanOnRemoval: true
177
+ autoBanOnRemoval: true,
178
+ allowPrivateHosts: false,
179
+ batchSize: undefined,
180
+ maxReportResults: undefined
155
181
  };
156
182
  // Ban service for persistent domain/outpoint blocking
157
183
  banService;
@@ -159,6 +185,8 @@ export default class OverlayExpress {
159
185
  adminIdentityKey;
160
186
  // Server-side wallet (WalletInterface) used for BSV mutual authentication
161
187
  serverWallet;
188
+ // Optional shared store for BSV mutual-auth sessions.
189
+ authSessionManager;
162
190
  // Server start time for uptime tracking
163
191
  startTime;
164
192
  // Health endpoint configuration
@@ -170,6 +198,26 @@ export default class OverlayExpress {
170
198
  healthChecks = [];
171
199
  // Lifecycle marker for readiness/liveness reporting
172
200
  isListening = false;
201
+ // Active HTTP server, retained so timeout policy is observable and the
202
+ // process can add graceful-close handling without replacing app.listen().
203
+ server;
204
+ closePromise;
205
+ edgePolicyConfig = {
206
+ environmentPrefix: 'OVERLAY',
207
+ jsonBodyLimitBytes: 8 * 1024 * 1024,
208
+ binaryBodyLimitBytes: 64 * 1024 * 1024,
209
+ maxConcurrentRequests: 200,
210
+ http: {
211
+ requestTimeoutMs: 2 * 60 * 1000,
212
+ headersTimeoutMs: 15_000,
213
+ keepAliveTimeoutMs: 5_000,
214
+ socketTimeoutMs: 2 * 60 * 1000,
215
+ maxRequestsPerSocket: 1_000
216
+ },
217
+ 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'"
219
+ }
220
+ };
173
221
  /**
174
222
  * Constructs an instance of OverlayExpress.
175
223
  * @param name - The name of the service
@@ -214,6 +262,9 @@ export default class OverlayExpress {
214
262
  * - requestTimeoutMs: Timeout for health check requests (default: 10000ms)
215
263
  * - hostDownRevokeScore: Number of consecutive failures before deleting output (default: 3)
216
264
  * - autoBanOnRemoval: Whether to auto-ban domains when removed by janitor (default: true)
265
+ * - allowPrivateHosts: Permit private/HTTP targets for isolated local development (default: false)
266
+ * - batchSize: Mongo scan batch size; -1 uses the driver default
267
+ * - maxReportResults: Maximum retained result details; -1 retains all
217
268
  */
218
269
  configureJanitor(config) {
219
270
  this.janitorConfig = {
@@ -232,6 +283,30 @@ export default class OverlayExpress {
232
283
  };
233
284
  this.logger.log(chalk.blue('Health reporting has been configured.'));
234
285
  }
286
+ /**
287
+ * Configures explicit browser origins and bounded request/resource policy.
288
+ * Public cross-origin access is the default; pass allowedOrigins or set
289
+ * OVERLAY_CORS_MODE=allowlist to restrict browser callers.
290
+ */
291
+ 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 = {
297
+ ...this.edgePolicyConfig,
298
+ ...definedTopLevel,
299
+ http: {
300
+ ...this.edgePolicyConfig.http,
301
+ ...definedHttp
302
+ },
303
+ securityHeaders: {
304
+ ...this.edgePolicyConfig.securityHeaders,
305
+ ...definedHeaders
306
+ }
307
+ };
308
+ this.logger.log(chalk.blue('HTTP edge policy has been configured.'));
309
+ }
235
310
  /**
236
311
  * Registers an application-specific health check.
237
312
  */
@@ -255,6 +330,15 @@ export default class OverlayExpress {
255
330
  this.adminIdentityKey = identityKey;
256
331
  this.logger.log(chalk.blue('Admin identity key has been configured.'));
257
332
  }
333
+ /**
334
+ * Configures BRC-103 session storage for the administrative mutual-auth
335
+ * middleware. Horizontally scaled services should supply a shared
336
+ * AsyncSessionManager rather than use the default process-local store.
337
+ */
338
+ configureAuthSessionManager(sessionManager) {
339
+ this.authSessionManager = sessionManager;
340
+ this.logger.log(chalk.blue('BSV authentication session manager has been configured.'));
341
+ }
258
342
  /**
259
343
  * Configures the logger to be used by the server.
260
344
  * @param logger - A logger object (e.g., console)
@@ -512,6 +596,12 @@ export default class OverlayExpress {
512
596
  */
513
597
  async configureEngine(autoConfigureShipSlap = true) {
514
598
  const knex = this.ensureKnex();
599
+ const maxLookupResults = this.engineConfig.maxLookupResults ??
600
+ readResourceLimit(this.edgePolicyConfig.environmentPrefix, 'MAX_LOOKUP_RESULTS', profileValue(readResourceProfile(this.edgePolicyConfig.environmentPrefix), {
601
+ small: 500,
602
+ standard: 1000,
603
+ highThroughput: 5000
604
+ }), 1_000_000);
515
605
  if (autoConfigureShipSlap) {
516
606
  const mongoDb = this.ensureMongo();
517
607
  const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb);
@@ -528,8 +618,8 @@ export default class OverlayExpress {
528
618
  const slapStorageForLookup = this.banService === undefined
529
619
  ? slapStorage
530
620
  : new BanAwareSLAPStorage(slapStorage, this.banService, this.logger);
531
- this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup);
532
- this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup);
621
+ this.services.ls_ship = new ResourceBoundedLookupWrapper(new DiscoveryServices.SHIPLookupService(shipStorageForLookup), maxLookupResults);
622
+ this.services.ls_slap = new ResourceBoundedLookupWrapper(new DiscoveryServices.SLAPLookupService(slapStorageForLookup), maxLookupResults);
533
623
  this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'));
534
624
  this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'));
535
625
  }
@@ -542,7 +632,7 @@ export default class OverlayExpress {
542
632
  const EngineWithBASM = Engine;
543
633
  this.engine = new EngineWithBASM(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
544
634
  ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
545
- : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? true, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks);
635
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? true, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks, maxLookupResults);
546
636
  this.initServerWallet();
547
637
  this.logger.log(chalk.green('Engine has been configured.'));
548
638
  }
@@ -672,7 +762,7 @@ export default class OverlayExpress {
672
762
  if (!response.ok) {
673
763
  throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`);
674
764
  }
675
- const header = await response.json();
765
+ const header = (await response.json());
676
766
  if (typeof header.hash !== 'string') {
677
767
  throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`);
678
768
  }
@@ -754,13 +844,20 @@ export default class OverlayExpress {
754
844
  */
755
845
  createJanitor() {
756
846
  const mongoDb = this.ensureMongo();
847
+ const prefix = this.edgePolicyConfig.environmentPrefix;
848
+ const profile = readResourceProfile(prefix);
757
849
  return new JanitorService({
758
850
  mongoDb,
759
851
  logger: this.logger,
760
852
  requestTimeoutMs: this.janitorConfig.requestTimeoutMs,
761
853
  hostDownRevokeScore: this.janitorConfig.hostDownRevokeScore,
762
854
  banService: this.banService,
763
- autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval
855
+ autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval,
856
+ allowPrivateHosts: this.janitorConfig.allowPrivateHosts,
857
+ batchSize: this.janitorConfig.batchSize ??
858
+ readResourceLimit(prefix, 'JANITOR_BATCH_SIZE', profileValue(profile, { small: 100, standard: 250, highThroughput: 1000 }), 100_000),
859
+ maxReportResults: this.janitorConfig.maxReportResults ??
860
+ readResourceLimit(prefix, 'JANITOR_MAX_REPORT_RESULTS', profileValue(profile, { small: 500, standard: 1000, highThroughput: 5000 }), 1_000_000)
764
861
  });
765
862
  }
766
863
  /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
@@ -780,7 +877,9 @@ export default class OverlayExpress {
780
877
  async handleBanOutpoint(res, engine, value, reason) {
781
878
  const dotIndex = value.lastIndexOf('.');
782
879
  if (dotIndex === -1) {
783
- return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
880
+ return res
881
+ .status(400)
882
+ .json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
784
883
  }
785
884
  const txid = value.substring(0, dotIndex);
786
885
  const outputIndex = Number.parseInt(value.substring(dotIndex + 1));
@@ -806,7 +905,9 @@ export default class OverlayExpress {
806
905
  try {
807
906
  await svc.outputEvicted(txid, outputIndex);
808
907
  }
809
- catch { /* best-effort */ }
908
+ catch {
909
+ /* best-effort */
910
+ }
810
911
  }
811
912
  }
812
913
  /** Look up the domain of an outpoint from SHIP or SLAP records. */
@@ -829,11 +930,12 @@ export default class OverlayExpress {
829
930
  }
830
931
  async runHealthCheck(definition) {
831
932
  const startedAt = Date.now();
933
+ let timeout;
832
934
  try {
833
935
  const result = ((await Promise.race([
834
936
  Promise.resolve(definition.handler()),
835
937
  new Promise((_, reject) => {
836
- setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
938
+ timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
837
939
  })
838
940
  ])) ?? {});
839
941
  return {
@@ -847,15 +949,24 @@ export default class OverlayExpress {
847
949
  };
848
950
  }
849
951
  catch (error) {
952
+ this.logger.error({
953
+ operation: 'overlay.health_check',
954
+ check: definition.name,
955
+ error
956
+ });
850
957
  return {
851
958
  name: definition.name,
852
959
  scope: definition.scope,
853
960
  critical: definition.critical,
854
961
  status: 'error',
855
- message: error instanceof Error ? error.message : 'Unknown health-check error',
962
+ message: 'Health check failed',
856
963
  durationMs: Date.now() - startedAt
857
964
  };
858
965
  }
966
+ finally {
967
+ if (timeout !== undefined)
968
+ clearTimeout(timeout);
969
+ }
859
970
  }
860
971
  async collectHealthReport(mode) {
861
972
  const definitions = [
@@ -930,7 +1041,7 @@ export default class OverlayExpress {
930
1041
  handler: check.handler
931
1042
  });
932
1043
  }
933
- const filteredDefinitions = definitions.filter((definition) => {
1044
+ const filteredDefinitions = definitions.filter(definition => {
934
1045
  if (mode === 'full') {
935
1046
  return true;
936
1047
  }
@@ -967,7 +1078,11 @@ export default class OverlayExpress {
967
1078
  },
968
1079
  checks: this.healthConfig.includeDetails
969
1080
  ? checks
970
- : checks.map(({ details, ...check }) => check),
1081
+ : checks.map(check => {
1082
+ const publicCheck = { ...check };
1083
+ delete publicCheck.details;
1084
+ return publicCheck;
1085
+ }),
971
1086
  context
972
1087
  };
973
1088
  return report;
@@ -975,20 +1090,83 @@ export default class OverlayExpress {
975
1090
  /**
976
1091
  * Renders a request or response body for verbose logging, truncating overly long payloads.
977
1092
  */
978
- formatBodyForLog(body, tooLongLabel, okPrefix) {
979
- let bodyString;
980
- if (typeof body === 'object') {
981
- bodyString = JSON.stringify(body, null, 2);
1093
+ formatBodyForLog(body, okPrefix) {
1094
+ if (Buffer.isBuffer(body)) {
1095
+ return chalk.green(`${okPrefix} binary body (${serializeLogValue(body.byteLength)} bytes)`);
982
1096
  }
983
- else if (Buffer.isBuffer(body)) {
984
- bodyString = body.toString('utf8');
1097
+ if (typeof body === 'string') {
1098
+ return chalk.green(`${okPrefix} string body (${serializeLogValue(Buffer.byteLength(body, 'utf8'))} bytes)`);
985
1099
  }
986
- else {
987
- bodyString = String(body);
1100
+ if (body != null && typeof body === 'object') {
1101
+ const keys = Array.isArray(body) ? body.length : Object.keys(body).length;
1102
+ return chalk.green(`${okPrefix} structured body (${serializeLogValue(keys)} top-level item(s))`);
988
1103
  }
989
- return bodyString.length > 280
990
- ? chalk.yellow(`(${tooLongLabel}, length: ${String(bodyString.length)} characters)`)
991
- : chalk.green(`${okPrefix}\n${bodyString}`);
1104
+ return chalk.green(`${okPrefix} type=${serializeLogValue(typeof body)}`);
1105
+ }
1106
+ redactHeadersForLog(headers) {
1107
+ const sensitiveHeader = /authorization|cookie|token|secret|payment|signature|nonce/i;
1108
+ return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
1109
+ name,
1110
+ sensitiveHeader.test(name) ? '[REDACTED]' : value
1111
+ ]));
1112
+ }
1113
+ arcCallbackRequestToken(req) {
1114
+ const authorization = req.headers.authorization;
1115
+ const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1116
+ if (typeof headerToken === 'string' && headerToken.startsWith('Bearer ')) {
1117
+ return headerToken.slice('Bearer '.length);
1118
+ }
1119
+ return headerToken;
1120
+ }
1121
+ arcCallbackAuthorized(req) {
1122
+ if (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0) {
1123
+ return true;
1124
+ }
1125
+ const callbackHeader = req.headers['x-callback-token'];
1126
+ const callbackToken = Array.isArray(callbackHeader) ? callbackHeader[0] : callbackHeader;
1127
+ return (this.arcCallbackRequestToken(req) === this.arcCallbackToken ||
1128
+ callbackToken === this.arcCallbackToken);
1129
+ }
1130
+ async processArcIngest(engine, req, res) {
1131
+ if (!this.arcCallbackAuthorized(req)) {
1132
+ return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1133
+ }
1134
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1135
+ if (typeof txid !== 'string' || txid === '') {
1136
+ throw new PublicRequestError('Provider callback is missing txid');
1137
+ }
1138
+ if (isTerminalArcStatus(txStatus, extraInfo)) {
1139
+ const report = await engine.evictAppliedTransaction(txid, {
1140
+ topic: typeof topic === 'string' ? topic : undefined,
1141
+ reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1142
+ });
1143
+ this.logger.warn({
1144
+ operation: 'overlay.provider_callback',
1145
+ outcome: 'terminal_evicted',
1146
+ txid,
1147
+ txStatus,
1148
+ competingTxs,
1149
+ report
1150
+ });
1151
+ return res.status(200).json({
1152
+ status: 'success',
1153
+ message: 'Terminal transaction status processed',
1154
+ data: { ...report, txStatus, competingTxs }
1155
+ });
1156
+ }
1157
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1158
+ return res
1159
+ .status(202)
1160
+ .json({ status: 'success', message: 'Transaction status received without proof' });
1161
+ }
1162
+ await engine.handleNewMerkleProof(txid, MerklePath.fromHex(merklePathHex), blockHeight);
1163
+ this.logger.log({
1164
+ operation: 'overlay.provider_callback',
1165
+ outcome: 'proof_ingested',
1166
+ txid,
1167
+ blockHeight
1168
+ });
1169
+ return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
992
1170
  }
993
1171
  /**
994
1172
  * Installs middleware that verbosely logs incoming requests and outgoing responses.
@@ -997,13 +1175,11 @@ export default class OverlayExpress {
997
1175
  this.app.use((req, res, next) => {
998
1176
  const startTime = Date.now();
999
1177
  // Log incoming request details
1000
- this.logger.log(chalk.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
1001
- // Pretty-print headers
1002
- this.logger.log(chalk.cyan('Headers:'));
1003
- this.logger.log(util.inspect(req.headers, { colors: true, depth: null }));
1178
+ this.logger.log(chalk.magenta.bold(`Incoming Request: method=${serializeLogValue(req.method)} url=${serializeLogValue(req.originalUrl)}`));
1179
+ this.logger.log(chalk.cyan(`Headers: ${serializeLogValue(this.redactHeadersForLog(req.headers))}`));
1004
1180
  // Handle request body
1005
1181
  if (req.body != null && Object.keys(req.body).length > 0) {
1006
- this.logger.log(this.formatBodyForLog(req.body, 'Body too long to display', 'Request Body:'));
1182
+ this.logger.log(this.formatBodyForLog(req.body, 'Request Body:'));
1007
1183
  }
1008
1184
  // Intercept the res.send method to log responses
1009
1185
  const originalSend = res.send;
@@ -1015,12 +1191,11 @@ export default class OverlayExpress {
1015
1191
  // Log outgoing response details after the response is finished
1016
1192
  res.on('finish', () => {
1017
1193
  const duration = Date.now() - startTime;
1018
- this.logger.log(chalk.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
1019
- this.logger.log(chalk.cyan('Response Headers:'));
1020
- this.logger.log(util.inspect(res.getHeaders(), { colors: true, depth: null }));
1194
+ this.logger.log(chalk.magenta.bold(`Outgoing Response: method=${serializeLogValue(req.method)} url=${serializeLogValue(req.originalUrl)} status=${serializeLogValue(res.statusCode)} durationMs=${serializeLogValue(duration)}`));
1195
+ this.logger.log(chalk.cyan(`Response Headers: ${serializeLogValue(this.redactHeadersForLog(res.getHeaders()))}`));
1021
1196
  // Handle response body
1022
1197
  if (responseBody != null) {
1023
- this.logger.log(this.formatBodyForLog(responseBody, 'Response body too long to display', 'Response Body:'));
1198
+ this.logger.log(this.formatBodyForLog(responseBody, 'Response Body:'));
1024
1199
  }
1025
1200
  });
1026
1201
  next();
@@ -1034,25 +1209,77 @@ export default class OverlayExpress {
1034
1209
  const engine = this.ensureEngine();
1035
1210
  const knex = this.ensureKnex();
1036
1211
  this.startTime = new Date();
1037
- this.app.use(bodyParser.json({ limit: '1gb', type: 'application/json' }));
1038
- this.app.use(bodyParser.raw({ limit: '1gb', type: 'application/octet-stream' }));
1039
- if (this.verboseRequestLogging) {
1040
- this.setupVerboseRequestLogging();
1212
+ const edgePolicy = this.edgePolicyConfig;
1213
+ const resourceProfile = readResourceProfile(edgePolicy.environmentPrefix);
1214
+ const maxResponseBytes = readResourceLimit(edgePolicy.environmentPrefix, 'MAX_RESPONSE_BYTES', profileValue(resourceProfile, {
1215
+ small: 4 * 1024 * 1024,
1216
+ standard: 8 * 1024 * 1024,
1217
+ highThroughput: 32 * 1024 * 1024
1218
+ }), 512 * 1024 * 1024);
1219
+ const maxBasmTxids = readResourceLimit(edgePolicy.environmentPrefix, 'MAX_BASM_TXIDS', profileValue(resourceProfile, { small: 500, standard: 1000, highThroughput: 5000 }), 1_000_000);
1220
+ const maxBasmAnchorRange = readResourceLimit(edgePolicy.environmentPrefix, 'MAX_BASM_ANCHOR_RANGE', profileValue(resourceProfile, { small: 500, standard: 1000, highThroughput: 5000 }), 1_000_000);
1221
+ const adminListDefaultLimit = readResourceLimit(edgePolicy.environmentPrefix, 'ADMIN_LIST_DEFAULT_LIMIT', profileValue(resourceProfile, { small: 25, standard: 50, highThroughput: 100 }), 1_000_000);
1222
+ const adminListMaxLimit = readResourceLimit(edgePolicy.environmentPrefix, 'ADMIN_LIST_MAX_LIMIT', profileValue(resourceProfile, { small: 100, standard: 200, highThroughput: 1000 }), 1_000_000);
1223
+ const adminListMaxOffset = readResourceLimit(edgePolicy.environmentPrefix, 'ADMIN_LIST_MAX_OFFSET', profileValue(resourceProfile, {
1224
+ small: 10_000,
1225
+ standard: 100_000,
1226
+ highThroughput: 1_000_000
1227
+ }), 100_000_000);
1228
+ if (adminListDefaultLimit !== -1 &&
1229
+ adminListMaxLimit !== -1 &&
1230
+ adminListDefaultLimit > adminListMaxLimit) {
1231
+ throw new TypeError('OVERLAY_ADMIN_LIST_DEFAULT_LIMIT cannot exceed OVERLAY_ADMIN_LIST_MAX_LIMIT');
1041
1232
  }
1042
- // Enable CORS
1043
- this.app.use((req, res, next) => {
1044
- res.header('Access-Control-Allow-Origin', '*');
1045
- res.header('Access-Control-Allow-Headers', '*');
1046
- res.header('Access-Control-Allow-Methods', '*');
1047
- res.header('Access-Control-Expose-Headers', '*');
1048
- res.header('Access-Control-Allow-Private-Network', 'true');
1049
- if (req.method === 'OPTIONS') {
1050
- res.sendStatus(200);
1233
+ const parseAdminPage = (rawPageValue, rawLimitValue) => {
1234
+ const rawPage = Number.parseInt(typeof rawPageValue === 'string' ? rawPageValue : '', 10);
1235
+ const requestedPage = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1236
+ const rawLimitText = typeof rawLimitValue === 'string' ? rawLimitValue.trim().toLowerCase() : '';
1237
+ const parsedLimit = rawLimitText === '-1' || rawLimitText === 'unlimited'
1238
+ ? -1
1239
+ : Number.parseInt(rawLimitText, 10);
1240
+ const requestedLimit = rawLimitText.length === 0 || Number.isNaN(parsedLimit) ? adminListDefaultLimit : parsedLimit;
1241
+ if (requestedLimit !== -1 && (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1)) {
1242
+ throw new TypeError('limit must be a positive integer, -1, or unlimited');
1051
1243
  }
1052
- else {
1053
- next();
1244
+ let limit = requestedLimit;
1245
+ if (adminListMaxLimit !== -1) {
1246
+ limit =
1247
+ requestedLimit === -1 ? adminListMaxLimit : Math.min(requestedLimit, adminListMaxLimit);
1054
1248
  }
1055
- });
1249
+ const page = limit === -1 ? 1 : requestedPage;
1250
+ const skip = limit === -1 ? 0 : (page - 1) * limit;
1251
+ if (!Number.isSafeInteger(skip) || (adminListMaxOffset !== -1 && skip > adminListMaxOffset)) {
1252
+ throw new TypeError('requested page exceeds the configured maximum offset');
1253
+ }
1254
+ return { page, limit, skip };
1255
+ };
1256
+ this.app.disable('x-powered-by');
1257
+ this.app.use(initialDoubleSlashCompatibility);
1258
+ this.app.use(securityHeaders({
1259
+ environmentPrefix: edgePolicy.environmentPrefix,
1260
+ ...edgePolicy.securityHeaders
1261
+ }));
1262
+ this.app.use(corsPolicy({
1263
+ environmentPrefix: edgePolicy.environmentPrefix,
1264
+ allowedOrigins: edgePolicy.allowedOrigins,
1265
+ methods: ['GET', 'POST', 'OPTIONS']
1266
+ }));
1267
+ this.app.use(concurrencyLimit(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests === 200
1268
+ ? profileValue(resourceProfile, { small: 8, standard: 24, highThroughput: 96 })
1269
+ : edgePolicy.maxConcurrentRequests));
1270
+ this.app.use(bodyParser.json({
1271
+ limit: readBodyLimitBytes(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes),
1272
+ type: 'application/json'
1273
+ }));
1274
+ this.app.use(bodyParser.raw({
1275
+ limit: readBodyLimitBytes(`${edgePolicy.environmentPrefix}_BINARY`, edgePolicy.binaryBodyLimitBytes),
1276
+ type: 'application/octet-stream'
1277
+ }));
1278
+ this.app.use(bodyParserErrorHandler);
1279
+ this.app.use(responseSizeLimit(edgePolicy.environmentPrefix, maxResponseBytes));
1280
+ if (this.verboseRequestLogging) {
1281
+ this.setupVerboseRequestLogging();
1282
+ }
1056
1283
  // Serve a static documentation site or user interface
1057
1284
  this.app.get('/', (req, res) => {
1058
1285
  res.set('content-type', 'text/html');
@@ -1067,22 +1294,35 @@ export default class OverlayExpress {
1067
1294
  (async () => {
1068
1295
  const report = await this.collectHealthReport('live');
1069
1296
  return res.status(report.live ? 200 : 503).json(report);
1070
- })().catch((error) => {
1297
+ })().catch(error => {
1298
+ this.logger.error({ operation: 'overlay.health_live', error });
1071
1299
  res.status(500).json({
1072
1300
  status: 'error',
1073
- message: error instanceof Error ? error.message : 'Unexpected error'
1301
+ message: 'Health report unavailable'
1074
1302
  });
1075
1303
  });
1076
1304
  });
1305
+ // Compatibility alias used by Kubernetes probes and existing deployments.
1306
+ this.app.get('/healthz', (_, res) => {
1307
+ ;
1308
+ (async () => {
1309
+ const report = await this.collectHealthReport('live');
1310
+ return res.status(report.live ? 200 : 503).json(report);
1311
+ })().catch(error => {
1312
+ this.logger.error({ operation: 'overlay.healthz', error });
1313
+ res.status(500).json({ status: 'error', message: 'Health report unavailable' });
1314
+ });
1315
+ });
1077
1316
  this.app.get('/health/ready', (_, res) => {
1078
1317
  ;
1079
1318
  (async () => {
1080
1319
  const report = await this.collectHealthReport('ready');
1081
1320
  return res.status(report.ready ? 200 : 503).json(report);
1082
- })().catch((error) => {
1321
+ })().catch(error => {
1322
+ this.logger.error({ operation: 'overlay.health_ready', error });
1083
1323
  res.status(500).json({
1084
1324
  status: 'error',
1085
- message: error instanceof Error ? error.message : 'Unexpected error'
1325
+ message: 'Health report unavailable'
1086
1326
  });
1087
1327
  });
1088
1328
  });
@@ -1091,10 +1331,11 @@ export default class OverlayExpress {
1091
1331
  (async () => {
1092
1332
  const report = await this.collectHealthReport('full');
1093
1333
  return res.status(report.ready ? 200 : 503).json(report);
1094
- })().catch((error) => {
1334
+ })().catch(error => {
1335
+ this.logger.error({ operation: 'overlay.health_full', error });
1095
1336
  res.status(500).json({
1096
1337
  status: 'error',
1097
- message: error instanceof Error ? error.message : 'Unexpected error'
1338
+ message: 'Health report unavailable'
1098
1339
  });
1099
1340
  });
1100
1341
  });
@@ -1109,7 +1350,7 @@ export default class OverlayExpress {
1109
1350
  catch (error) {
1110
1351
  return res.status(400).json({
1111
1352
  status: 'error',
1112
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1353
+ message: publicErrorMessage(error)
1113
1354
  });
1114
1355
  }
1115
1356
  })().catch(() => {
@@ -1129,7 +1370,7 @@ export default class OverlayExpress {
1129
1370
  catch (error) {
1130
1371
  return res.status(400).json({
1131
1372
  status: 'error',
1132
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1373
+ message: publicErrorMessage(error)
1133
1374
  });
1134
1375
  }
1135
1376
  })().catch(() => {
@@ -1152,7 +1393,7 @@ export default class OverlayExpress {
1152
1393
  catch (error) {
1153
1394
  return res.status(400).json({
1154
1395
  status: 'error',
1155
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1396
+ message: publicErrorMessage(error)
1156
1397
  });
1157
1398
  }
1158
1399
  })().catch(() => {
@@ -1174,7 +1415,7 @@ export default class OverlayExpress {
1174
1415
  catch (error) {
1175
1416
  return res.status(400).json({
1176
1417
  status: 'error',
1177
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1418
+ message: publicErrorMessage(error)
1178
1419
  });
1179
1420
  }
1180
1421
  })().catch(() => {
@@ -1193,12 +1434,12 @@ export default class OverlayExpress {
1193
1434
  const topicsHeader = req.headers['x-topics'];
1194
1435
  const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true';
1195
1436
  if (typeof topicsHeader !== 'string') {
1196
- throw new TypeError('Missing x-topics header');
1437
+ throw new PublicRequestError('Missing x-topics header');
1197
1438
  }
1198
1439
  const topics = parseTopicsHeader(topicsHeader);
1199
1440
  const body = req.body;
1200
1441
  if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
1201
- throw new TypeError('Missing or empty BEEF body');
1442
+ throw new PublicRequestError('Missing or empty BEEF body');
1202
1443
  }
1203
1444
  let offChainValues;
1204
1445
  let beef = Array.from(body);
@@ -1224,10 +1465,10 @@ export default class OverlayExpress {
1224
1465
  }
1225
1466
  }
1226
1467
  catch (error) {
1227
- console.error(chalk.red('Error in /submit:'), error);
1468
+ this.logger.error(chalk.red(`Error in /submit: error=${serializeErrorForLog(error)}`));
1228
1469
  return res.status(400).json({
1229
1470
  status: 'error',
1230
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1471
+ message: publicErrorMessage(error)
1231
1472
  });
1232
1473
  }
1233
1474
  })().catch(() => {
@@ -1271,7 +1512,7 @@ export default class OverlayExpress {
1271
1512
  // Write outputIndex
1272
1513
  writer.writeVarIntNum(output.outputIndex);
1273
1514
  // Write context length and data
1274
- if ((output.context != null) && output.context.length > 0) {
1515
+ if (output.context != null && output.context.length > 0) {
1275
1516
  writer.writeVarIntNum(output.context.length);
1276
1517
  writer.write(output.context);
1277
1518
  }
@@ -1286,10 +1527,10 @@ export default class OverlayExpress {
1286
1527
  return res.status(200).send(Buffer.from(writer.toArray()));
1287
1528
  }
1288
1529
  catch (error) {
1289
- console.error(chalk.red('Error in /lookup:'), error);
1530
+ this.logger.error(chalk.red(`Error in /lookup: error=${serializeErrorForLog(error)}`));
1290
1531
  return res.status(400).json({
1291
1532
  status: 'error',
1292
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1533
+ message: publicErrorMessage(error)
1293
1534
  });
1294
1535
  }
1295
1536
  })().catch(() => {
@@ -1306,63 +1547,13 @@ export default class OverlayExpress {
1306
1547
  ;
1307
1548
  (async () => {
1308
1549
  try {
1309
- if (typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0) {
1310
- const authorization = req.headers.authorization;
1311
- const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1312
- const xCallbackToken = req.headers['x-callback-token'];
1313
- const callbackToken = Array.isArray(xCallbackToken) ? xCallbackToken[0] : xCallbackToken;
1314
- const bearerToken = typeof headerToken === 'string' && headerToken.startsWith('Bearer ')
1315
- ? headerToken.slice('Bearer '.length)
1316
- : headerToken;
1317
- if (bearerToken !== this.arcCallbackToken && callbackToken !== this.arcCallbackToken) {
1318
- return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1319
- }
1320
- }
1321
- const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1322
- if (typeof txid !== 'string' || txid === '') {
1323
- throw new TypeError('Provider callback is missing txid');
1324
- }
1325
- if (isTerminalArcStatus(txStatus, extraInfo)) {
1326
- const report = await engine.evictAppliedTransaction(txid, {
1327
- topic: typeof topic === 'string' ? topic : undefined,
1328
- reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1329
- });
1330
- this.logger.warn({
1331
- operation: 'overlay.provider_callback',
1332
- outcome: 'terminal_evicted',
1333
- txid,
1334
- txStatus,
1335
- competingTxs,
1336
- report
1337
- });
1338
- return res.status(200).json({
1339
- status: 'success',
1340
- message: 'Terminal transaction status processed',
1341
- data: {
1342
- ...report,
1343
- txStatus,
1344
- competingTxs
1345
- }
1346
- });
1347
- }
1348
- if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1349
- return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' });
1350
- }
1351
- const merklePath = MerklePath.fromHex(merklePathHex);
1352
- await engine.handleNewMerkleProof(txid, merklePath, blockHeight);
1353
- this.logger.log({
1354
- operation: 'overlay.provider_callback',
1355
- outcome: 'proof_ingested',
1356
- txid,
1357
- blockHeight
1358
- });
1359
- return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
1550
+ return await this.processArcIngest(engine, req, res);
1360
1551
  }
1361
1552
  catch (error) {
1362
- console.error(chalk.red('Error in /arc-ingest:'), error);
1553
+ this.logger.error(chalk.red(`Error in /arc-ingest: error=${serializeErrorForLog(error)}`));
1363
1554
  return res.status(400).json({
1364
1555
  status: 'error',
1365
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1556
+ message: publicErrorMessage(error)
1366
1557
  });
1367
1558
  }
1368
1559
  })().catch(() => {
@@ -1390,7 +1581,7 @@ export default class OverlayExpress {
1390
1581
  console.error(chalk.red('Error in /requestSyncResponse:'), error);
1391
1582
  return res.status(400).json({
1392
1583
  status: 'error',
1393
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1584
+ message: publicErrorMessage(error)
1394
1585
  });
1395
1586
  }
1396
1587
  })().catch(() => {
@@ -1412,7 +1603,7 @@ export default class OverlayExpress {
1412
1603
  console.error(chalk.red('Error in /requestForeignGASPNode:'), error);
1413
1604
  return res.status(400).json({
1414
1605
  status: 'error',
1415
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1606
+ message: publicErrorMessage(error)
1416
1607
  });
1417
1608
  }
1418
1609
  })().catch(() => {
@@ -1431,7 +1622,7 @@ export default class OverlayExpress {
1431
1622
  const readBasmTopic = (req) => {
1432
1623
  const header = req.headers['x-bsv-topic'];
1433
1624
  if (typeof header !== 'string' || header.length === 0) {
1434
- throw new TypeError('Missing x-bsv-topic header');
1625
+ throw new PublicRequestError('Missing x-bsv-topic header');
1435
1626
  }
1436
1627
  return header;
1437
1628
  };
@@ -1453,7 +1644,7 @@ export default class OverlayExpress {
1453
1644
  console.error(chalk.red(`Error in ${path}:`), error);
1454
1645
  return res.status(400).json({
1455
1646
  status: 'error',
1456
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1647
+ message: publicErrorMessage(error)
1457
1648
  });
1458
1649
  }
1459
1650
  })().catch(() => {
@@ -1463,14 +1654,25 @@ export default class OverlayExpress {
1463
1654
  };
1464
1655
  const requireTxids = (value) => {
1465
1656
  if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1466
- throw new TypeError('txids must be an array of strings');
1657
+ throw new PublicRequestError('txids must be an array of strings');
1658
+ }
1659
+ if (maxBasmTxids !== -1 && value.length > maxBasmTxids) {
1660
+ throw new PublicRequestError(`txids must contain at most ${maxBasmTxids} entries`);
1467
1661
  }
1468
1662
  return value;
1469
1663
  };
1470
1664
  registerJsonRoute('/requestTopicAnchorTip', async (req) => await basmEngine.provideTopicAnchorTip(readBasmTopic(req)));
1471
1665
  registerJsonRoute('/requestTopicAnchorRange', async (req) => {
1472
1666
  const { fromHeight, toHeight } = req.body;
1473
- return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), Number(fromHeight), Number(toHeight));
1667
+ const from = Number(fromHeight);
1668
+ const to = Number(toHeight);
1669
+ if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to < from) {
1670
+ throw new PublicRequestError('fromHeight and toHeight must define a valid ascending range');
1671
+ }
1672
+ if (maxBasmAnchorRange !== -1 && to - from + 1 > maxBasmAnchorRange) {
1673
+ throw new PublicRequestError(`topic anchor range must contain at most ${maxBasmAnchorRange} blocks`);
1674
+ }
1675
+ return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), from, to);
1474
1676
  });
1475
1677
  registerJsonRoute('/requestAdmittedList', async (req) => {
1476
1678
  const { blockHeight, blockHash } = req.body;
@@ -1496,6 +1698,7 @@ export default class OverlayExpress {
1496
1698
  if (this.serverWallet !== undefined) {
1497
1699
  const bsvAuth = createAuthMiddleware({
1498
1700
  wallet: this.serverWallet,
1701
+ sessionManager: this.authSessionManager,
1499
1702
  allowUnauthenticated: true
1500
1703
  });
1501
1704
  this.app.use(bsvAuth);
@@ -1522,14 +1725,17 @@ export default class OverlayExpress {
1522
1725
  const authHeader = req.headers.authorization;
1523
1726
  if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
1524
1727
  const token = authHeader.substring('Bearer '.length);
1525
- if (token === this.adminToken) {
1728
+ if (secretMatches(token, this.adminToken)) {
1526
1729
  next();
1527
1730
  return;
1528
1731
  }
1529
1732
  res.status(403).json({ status: 'error', message: 'Forbidden: Invalid credentials' });
1530
1733
  return;
1531
1734
  }
1532
- res.status(401).json({ status: 'error', message: 'Unauthorized: Provide a Bearer token or authenticate with your wallet' });
1735
+ res.status(401).json({
1736
+ status: 'error',
1737
+ message: 'Unauthorized: Provide a Bearer token or authenticate with your wallet'
1738
+ });
1533
1739
  };
1534
1740
  /**
1535
1741
  * Public endpoint that returns the admin identity key (if configured).
@@ -1579,7 +1785,7 @@ export default class OverlayExpress {
1579
1785
  catch (error) {
1580
1786
  return res.status(400).json({
1581
1787
  status: 'error',
1582
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1788
+ message: publicErrorMessage(error)
1583
1789
  });
1584
1790
  }
1585
1791
  })().catch(() => {
@@ -1596,11 +1802,7 @@ export default class OverlayExpress {
1596
1802
  const db = this.ensureMongo();
1597
1803
  const collection = db.collection('shipRecords');
1598
1804
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1599
- const rawPage = Number.parseInt(req.query.page, 10);
1600
- const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1601
- const rawLimit = Number.parseInt(req.query.limit, 10);
1602
- const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1603
- const skip = (page - 1) * limit;
1805
+ const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1604
1806
  const query = {};
1605
1807
  if (typeof search === 'string' && search.length > 0) {
1606
1808
  query.$or = [
@@ -1611,18 +1813,29 @@ export default class OverlayExpress {
1611
1813
  ];
1612
1814
  }
1613
1815
  const [records, total] = await Promise.all([
1614
- collection.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray(),
1816
+ (() => {
1817
+ let cursor = collection.find(query).sort({ createdAt: -1 }).skip(skip);
1818
+ if (limit !== -1)
1819
+ cursor = cursor.limit(limit);
1820
+ return cursor.toArray();
1821
+ })(),
1615
1822
  collection.countDocuments(query)
1616
1823
  ]);
1617
1824
  return res.status(200).json({
1618
1825
  status: 'success',
1619
- data: { records, total, page, limit, pages: Math.ceil(total / limit) }
1826
+ data: {
1827
+ records,
1828
+ total,
1829
+ page,
1830
+ limit,
1831
+ pages: limit === -1 ? 1 : Math.ceil(total / limit)
1832
+ }
1620
1833
  });
1621
1834
  }
1622
1835
  catch (error) {
1623
1836
  return res.status(400).json({
1624
1837
  status: 'error',
1625
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1838
+ message: publicErrorMessage(error)
1626
1839
  });
1627
1840
  }
1628
1841
  })().catch(() => {
@@ -1639,11 +1852,7 @@ export default class OverlayExpress {
1639
1852
  const db = this.ensureMongo();
1640
1853
  const collection = db.collection('slapRecords');
1641
1854
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1642
- const rawPage = Number.parseInt(req.query.page, 10);
1643
- const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1644
- const rawLimit = Number.parseInt(req.query.limit, 10);
1645
- const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1646
- const skip = (page - 1) * limit;
1855
+ const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1647
1856
  const query = {};
1648
1857
  if (typeof search === 'string' && search.length > 0) {
1649
1858
  query.$or = [
@@ -1654,18 +1863,29 @@ export default class OverlayExpress {
1654
1863
  ];
1655
1864
  }
1656
1865
  const [records, total] = await Promise.all([
1657
- collection.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray(),
1866
+ (() => {
1867
+ let cursor = collection.find(query).sort({ createdAt: -1 }).skip(skip);
1868
+ if (limit !== -1)
1869
+ cursor = cursor.limit(limit);
1870
+ return cursor.toArray();
1871
+ })(),
1658
1872
  collection.countDocuments(query)
1659
1873
  ]);
1660
1874
  return res.status(200).json({
1661
1875
  status: 'success',
1662
- data: { records, total, page, limit, pages: Math.ceil(total / limit) }
1876
+ data: {
1877
+ records,
1878
+ total,
1879
+ page,
1880
+ limit,
1881
+ pages: limit === -1 ? 1 : Math.ceil(total / limit)
1882
+ }
1663
1883
  });
1664
1884
  }
1665
1885
  catch (error) {
1666
1886
  return res.status(400).json({
1667
1887
  status: 'error',
1668
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1888
+ message: publicErrorMessage(error)
1669
1889
  });
1670
1890
  }
1671
1891
  })().catch(() => {
@@ -1690,7 +1910,7 @@ export default class OverlayExpress {
1690
1910
  catch (error) {
1691
1911
  return res.status(400).json({
1692
1912
  status: 'error',
1693
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1913
+ message: publicErrorMessage(error)
1694
1914
  });
1695
1915
  }
1696
1916
  })().catch(() => {
@@ -1705,11 +1925,16 @@ export default class OverlayExpress {
1705
1925
  (async () => {
1706
1926
  try {
1707
1927
  if (this.banService === undefined) {
1708
- return res.status(400).json({ status: 'error', message: 'Ban service not available (MongoDB not configured)' });
1928
+ return res.status(400).json({
1929
+ status: 'error',
1930
+ message: 'Ban service not available (MongoDB not configured)'
1931
+ });
1709
1932
  }
1710
1933
  const { type, value, reason } = req.body;
1711
1934
  if (type !== 'domain' && type !== 'outpoint') {
1712
- return res.status(400).json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1935
+ return res
1936
+ .status(400)
1937
+ .json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1713
1938
  }
1714
1939
  if (typeof value !== 'string' || value.length === 0) {
1715
1940
  return res.status(400).json({ status: 'error', message: 'value is required' });
@@ -1722,7 +1947,7 @@ export default class OverlayExpress {
1722
1947
  catch (error) {
1723
1948
  return res.status(400).json({
1724
1949
  status: 'error',
1725
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1950
+ message: publicErrorMessage(error)
1726
1951
  });
1727
1952
  }
1728
1953
  })().catch(() => {
@@ -1741,18 +1966,22 @@ export default class OverlayExpress {
1741
1966
  }
1742
1967
  const { type, value } = req.body;
1743
1968
  if (type !== 'domain' && type !== 'outpoint') {
1744
- return res.status(400).json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1969
+ return res
1970
+ .status(400)
1971
+ .json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1745
1972
  }
1746
1973
  if (typeof value !== 'string' || value.length === 0) {
1747
1974
  return res.status(400).json({ status: 'error', message: 'value is required' });
1748
1975
  }
1749
1976
  await this.banService.removeBan(type, value);
1750
- return res.status(200).json({ status: 'success', message: `${type} "${String(value)}" unbanned.` });
1977
+ return res
1978
+ .status(200)
1979
+ .json({ status: 'success', message: `${type} "${String(value)}" unbanned.` });
1751
1980
  }
1752
1981
  catch (error) {
1753
1982
  return res.status(400).json({
1754
1983
  status: 'error',
1755
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1984
+ message: publicErrorMessage(error)
1756
1985
  });
1757
1986
  }
1758
1987
  })().catch(() => {
@@ -1771,13 +2000,14 @@ export default class OverlayExpress {
1771
2000
  }
1772
2001
  const type = req.query.type;
1773
2002
  const validType = type === 'domain' || type === 'outpoint' ? type : undefined;
1774
- const bans = await this.banService.listBans(validType);
1775
- return res.status(200).json({ status: 'success', data: { bans } });
2003
+ const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
2004
+ const bans = await this.banService.listBans(validType, limit, skip);
2005
+ return res.status(200).json({ status: 'success', data: { bans, page, limit } });
1776
2006
  }
1777
2007
  catch (error) {
1778
2008
  return res.status(400).json({
1779
2009
  status: 'error',
1780
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2010
+ message: publicErrorMessage(error)
1781
2011
  });
1782
2012
  }
1783
2013
  })().catch(() => {
@@ -1793,7 +2023,10 @@ export default class OverlayExpress {
1793
2023
  try {
1794
2024
  const { txid, outputIndex, service, ban, banDomain: shouldBanDomain } = req.body;
1795
2025
  if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
1796
- return res.status(400).json({ status: 'error', message: 'txid (string) and outputIndex (number) are required' });
2026
+ return res.status(400).json({
2027
+ status: 'error',
2028
+ message: 'txid (string) and outputIndex (number) are required'
2029
+ });
1797
2030
  }
1798
2031
  // Look up domain before eviction if needed for banning
1799
2032
  let removedDomain;
@@ -1804,7 +2037,9 @@ export default class OverlayExpress {
1804
2037
  if (ban === true && this.banService !== undefined) {
1805
2038
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain);
1806
2039
  }
1807
- if (shouldBanDomain === true && typeof removedDomain === 'string' && this.banService !== undefined) {
2040
+ if (shouldBanDomain === true &&
2041
+ typeof removedDomain === 'string' &&
2042
+ this.banService !== undefined) {
1808
2043
  await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal');
1809
2044
  }
1810
2045
  const banMsg = ban === true ? ' Outpoint banned.' : '';
@@ -1819,7 +2054,7 @@ export default class OverlayExpress {
1819
2054
  catch (error) {
1820
2055
  return res.status(400).json({
1821
2056
  status: 'error',
1822
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2057
+ message: publicErrorMessage(error)
1823
2058
  });
1824
2059
  }
1825
2060
  })().catch(() => {
@@ -1834,13 +2069,15 @@ export default class OverlayExpress {
1834
2069
  (async () => {
1835
2070
  try {
1836
2071
  await engine.syncAdvertisements();
1837
- return res.status(200).json({ status: 'success', message: 'Advertisements synced successfully' });
2072
+ return res
2073
+ .status(200)
2074
+ .json({ status: 'success', message: 'Advertisements synced successfully' });
1838
2075
  }
1839
2076
  catch (error) {
1840
2077
  console.error(chalk.red('Error in /admin/syncAdvertisements:'), error);
1841
2078
  return res.status(400).json({
1842
2079
  status: 'error',
1843
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2080
+ message: publicErrorMessage(error)
1844
2081
  });
1845
2082
  }
1846
2083
  })().catch(() => {
@@ -1858,13 +2095,15 @@ export default class OverlayExpress {
1858
2095
  (async () => {
1859
2096
  try {
1860
2097
  await engine.startGASPSync();
1861
- return res.status(200).json({ status: 'success', message: 'GASP sync started and completed' });
2098
+ return res
2099
+ .status(200)
2100
+ .json({ status: 'success', message: 'GASP sync started and completed' });
1862
2101
  }
1863
2102
  catch (error) {
1864
2103
  console.error(chalk.red('Error in /admin/startGASPSync:'), error);
1865
2104
  return res.status(400).json({
1866
2105
  status: 'error',
1867
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2106
+ message: publicErrorMessage(error)
1868
2107
  });
1869
2108
  }
1870
2109
  })().catch(() => {
@@ -1948,7 +2187,7 @@ export default class OverlayExpress {
1948
2187
  console.error(chalk.red('Error in /admin/evictOutpoint:'), error);
1949
2188
  return res.status(400).json({
1950
2189
  status: 'error',
1951
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2190
+ message: publicErrorMessage(error)
1952
2191
  });
1953
2192
  }
1954
2193
  })().catch(() => {
@@ -1967,13 +2206,15 @@ export default class OverlayExpress {
1967
2206
  try {
1968
2207
  const janitor = this.createJanitor();
1969
2208
  const report = await janitor.run();
1970
- return res.status(200).json({ status: 'success', message: 'Janitor run completed', data: report });
2209
+ return res
2210
+ .status(200)
2211
+ .json({ status: 'success', message: 'Janitor run completed', data: report });
1971
2212
  }
1972
2213
  catch (error) {
1973
2214
  console.error(chalk.red('Error in /admin/janitor:'), error);
1974
2215
  return res.status(400).json({
1975
2216
  status: 'error',
1976
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2217
+ message: publicErrorMessage(error)
1977
2218
  });
1978
2219
  }
1979
2220
  })().catch(() => {
@@ -1991,7 +2232,7 @@ export default class OverlayExpress {
1991
2232
  this.logger.log(chalk.green('Knex migrations run'), result);
1992
2233
  // 404 handler for all other routes
1993
2234
  this.app.use((req, res) => {
1994
- this.logger.log(chalk.red('404 Not Found:'), req.url);
2235
+ this.logger.log(chalk.red(`404 Not Found: url=${serializeLogValue(req.url)}`));
1995
2236
  res.status(404).json({
1996
2237
  status: 'error',
1997
2238
  code: 'ERR_ROUTE_NOT_FOUND',
@@ -2000,10 +2241,54 @@ export default class OverlayExpress {
2000
2241
  });
2001
2242
  await this.runStartupSync();
2002
2243
  // Start listening on the configured port
2003
- this.app.listen(this.port, () => {
2244
+ this.server = this.app.listen(this.port, () => {
2004
2245
  this.isListening = true;
2005
2246
  this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
2006
2247
  });
2248
+ configureHttpServer(this.server, edgePolicy.environmentPrefix, edgePolicy.http);
2249
+ }
2250
+ /**
2251
+ * Stops new HTTP work, background synchronization, and database clients.
2252
+ *
2253
+ * The operation is idempotent so multiple signal handlers or embedding
2254
+ * runtimes can share shutdown ownership safely.
2255
+ */
2256
+ async close() {
2257
+ this.closePromise ??= this.closeResources();
2258
+ await this.closePromise;
2259
+ }
2260
+ async closeResources() {
2261
+ this.isListening = false;
2262
+ if (this.basmBlockPollTimer !== undefined) {
2263
+ clearInterval(this.basmBlockPollTimer);
2264
+ this.basmBlockPollTimer = undefined;
2265
+ }
2266
+ if (this.unprovenMaintenanceTimer !== undefined) {
2267
+ clearInterval(this.unprovenMaintenanceTimer);
2268
+ this.unprovenMaintenanceTimer = undefined;
2269
+ }
2270
+ this.reorgAdapter?.stop();
2271
+ this.reorgAdapter = undefined;
2272
+ const server = this.server;
2273
+ this.server = undefined;
2274
+ const closeServer = server === undefined
2275
+ ? Promise.resolve()
2276
+ : new Promise((resolve, reject) => {
2277
+ server.close(error => {
2278
+ if (error !== undefined)
2279
+ reject(error);
2280
+ else
2281
+ resolve();
2282
+ });
2283
+ });
2284
+ await closeServer;
2285
+ await Promise.all([
2286
+ this.knex?.destroy() ?? Promise.resolve(),
2287
+ this.mongoClient?.close() ?? Promise.resolve()
2288
+ ]);
2289
+ this.knex = undefined;
2290
+ this.mongoClient = undefined;
2291
+ this.mongoDb = undefined;
2007
2292
  }
2008
2293
  /**
2009
2294
  * Runs the post-listen startup work: advertiser init, advertisement sync,
@@ -2088,8 +2373,12 @@ export default class OverlayExpress {
2088
2373
  const basmEngine = this.engine;
2089
2374
  this.reorgAdapter = new ReorgSseAdapter({
2090
2375
  url: reorgStreamUrl,
2091
- onReorg: async (input) => { await basmEngine?.handleReorg(input); },
2092
- onConnect: async () => { await basmEngine?.revalidateRecentAnchors(reorgScanDepth); },
2376
+ onReorg: async (input) => {
2377
+ await basmEngine?.handleReorg(input);
2378
+ },
2379
+ onConnect: async () => {
2380
+ await basmEngine?.revalidateRecentAnchors(reorgScanDepth);
2381
+ },
2093
2382
  logger: this.logger
2094
2383
  });
2095
2384
  this.reorgAdapter.start();