@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
@@ -45,11 +45,12 @@ const mongodb_1 = require("mongodb");
45
45
  const makeUserInterface_js_1 = __importDefault(require("./makeUserInterface.js"));
46
46
  const DiscoveryServices = __importStar(require("@bsv/overlay-discovery-services"));
47
47
  const chalk_1 = __importDefault(require("chalk"));
48
- const node_util_1 = __importDefault(require("node:util"));
49
48
  const uuid_1 = require("uuid");
49
+ const node_crypto_1 = require("node:crypto");
50
50
  const JanitorService_js_1 = require("./JanitorService.js");
51
51
  const BanService_js_1 = require("./BanService.js");
52
52
  const BanAwareLookupWrapper_js_1 = require("./BanAwareLookupWrapper.js");
53
+ const ResourceBoundedLookupWrapper_js_1 = require("./ResourceBoundedLookupWrapper.js");
53
54
  const BanAwareTopicManager_js_1 = require("./BanAwareTopicManager.js");
54
55
  const BanAwareDiscoveryStorage_js_1 = require("./BanAwareDiscoveryStorage.js");
55
56
  const ReorgStream_js_1 = require("./ReorgStream.js");
@@ -58,6 +59,7 @@ const auth_express_middleware_1 = require("@bsv/auth-express-middleware");
58
59
  const ArcadeProvider_js_1 = require("./ArcadeProvider.js");
59
60
  const ProviderChainBroadcaster_js_1 = require("./ProviderChainBroadcaster.js");
60
61
  const ChaintracksProvider_js_1 = require("./ChaintracksProvider.js");
62
+ const edgePolicy_js_1 = require("./security/edgePolicy.js");
61
63
  /**
62
64
  * In-memory migration source for Knex migrations.
63
65
  * Allows running migrations defined in code rather than files.
@@ -71,7 +73,7 @@ class InMemoryMigrationSource {
71
73
  * @param loadExtensions - Array of file extensions to filter by (not used here)
72
74
  * @returns Promise resolving to the array of migrations
73
75
  */
74
- async getMigrations(loadExtensions) {
76
+ async getMigrations(_loadExtensions) {
75
77
  return this.migrations;
76
78
  }
77
79
  /**
@@ -80,7 +82,9 @@ class InMemoryMigrationSource {
80
82
  * @returns The name of the migration
81
83
  */
82
84
  getMigrationName(migration) {
83
- return typeof migration.name === 'string' ? migration.name : `Migration at index ${this.migrations.indexOf(migration)}`;
85
+ return typeof migration.name === 'string'
86
+ ? migration.name
87
+ : `Migration at index ${this.migrations.indexOf(migration)}`;
84
88
  }
85
89
  /**
86
90
  * Gets the migration object.
@@ -91,13 +95,32 @@ class InMemoryMigrationSource {
91
95
  return await Promise.resolve(migration);
92
96
  }
93
97
  }
98
+ class PublicRequestError extends Error {
99
+ constructor(message) {
100
+ super(message);
101
+ this.name = 'PublicRequestError';
102
+ }
103
+ }
104
+ function publicErrorMessage(error, fallback = 'Request could not be processed') {
105
+ return error instanceof PublicRequestError ? error.message : fallback;
106
+ }
107
+ function secretMatches(provided, expected) {
108
+ const providedDigest = (0, node_crypto_1.createHash)('sha256').update(provided, 'utf8').digest();
109
+ const expectedDigest = (0, node_crypto_1.createHash)('sha256').update(expected, 'utf8').digest();
110
+ return (0, node_crypto_1.timingSafeEqual)(providedDigest, expectedDigest);
111
+ }
94
112
  function parseTopicsHeader(header) {
95
113
  const value = header.trim();
96
- const parsed = value.startsWith('[')
97
- ? JSON.parse(value)
98
- : value.split(',').map(topic => topic.trim());
99
- if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
100
- throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array');
114
+ let parsed;
115
+ try {
116
+ parsed = value.startsWith('[') ? JSON.parse(value) : value.split(',').map(topic => topic.trim());
117
+ }
118
+ catch {
119
+ throw new PublicRequestError('Invalid x-topics header: expected a comma-separated list or JSON string array');
120
+ }
121
+ if (!Array.isArray(parsed) ||
122
+ parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
123
+ throw new PublicRequestError('Invalid x-topics header: expected a comma-separated list or JSON string array');
101
124
  }
102
125
  return parsed;
103
126
  }
@@ -172,7 +195,10 @@ class OverlayExpress {
172
195
  this.janitorConfig = {
173
196
  requestTimeoutMs: 10000, // 10 seconds
174
197
  hostDownRevokeScore: 3,
175
- autoBanOnRemoval: true
198
+ autoBanOnRemoval: true,
199
+ allowPrivateHosts: false,
200
+ batchSize: undefined,
201
+ maxReportResults: undefined
176
202
  };
177
203
  // Health endpoint configuration
178
204
  this.healthConfig = {
@@ -183,6 +209,22 @@ class OverlayExpress {
183
209
  this.healthChecks = [];
184
210
  // Lifecycle marker for readiness/liveness reporting
185
211
  this.isListening = false;
212
+ this.edgePolicyConfig = {
213
+ environmentPrefix: 'OVERLAY',
214
+ jsonBodyLimitBytes: 8 * 1024 * 1024,
215
+ binaryBodyLimitBytes: 64 * 1024 * 1024,
216
+ maxConcurrentRequests: 200,
217
+ http: {
218
+ requestTimeoutMs: 2 * 60 * 1000,
219
+ headersTimeoutMs: 15000,
220
+ keepAliveTimeoutMs: 5000,
221
+ socketTimeoutMs: 2 * 60 * 1000,
222
+ maxRequestsPerSocket: 1000
223
+ },
224
+ securityHeaders: {
225
+ contentSecurityPolicy: "default-src 'none'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: https://bsvblockchain.org; connect-src 'self' https:; font-src 'self' https://cdn.jsdelivr.net; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
226
+ }
227
+ };
186
228
  this.app = (0, express_1.default)();
187
229
  this.logger.log(chalk_1.default.green.bold(`${name} constructed`));
188
230
  this.adminToken = adminToken !== null && adminToken !== void 0 ? adminToken : (0, uuid_1.v4)(); // generate random if not provided
@@ -215,6 +257,9 @@ class OverlayExpress {
215
257
  * - requestTimeoutMs: Timeout for health check requests (default: 10000ms)
216
258
  * - hostDownRevokeScore: Number of consecutive failures before deleting output (default: 3)
217
259
  * - autoBanOnRemoval: Whether to auto-ban domains when removed by janitor (default: true)
260
+ * - allowPrivateHosts: Permit private/HTTP targets for isolated local development (default: false)
261
+ * - batchSize: Mongo scan batch size; -1 uses the driver default
262
+ * - maxReportResults: Maximum retained result details; -1 retains all
218
263
  */
219
264
  configureJanitor(config) {
220
265
  this.janitorConfig = {
@@ -233,6 +278,30 @@ class OverlayExpress {
233
278
  };
234
279
  this.logger.log(chalk_1.default.blue('Health reporting has been configured.'));
235
280
  }
281
+ /**
282
+ * Configures explicit browser origins and bounded request/resource policy.
283
+ * Public cross-origin access is the default; pass allowedOrigins or set
284
+ * OVERLAY_CORS_MODE=allowlist to restrict browser callers.
285
+ */
286
+ configureEdgePolicy(config) {
287
+ const { http, securityHeaders: headerConfig, ...topLevel } = config;
288
+ const definedTopLevel = Object.fromEntries(Object.entries(topLevel).filter(([, value]) => value !== undefined));
289
+ const definedHttp = Object.fromEntries(Object.entries(http !== null && http !== void 0 ? http : {}).filter(([, value]) => value !== undefined));
290
+ const definedHeaders = Object.fromEntries(Object.entries(headerConfig !== null && headerConfig !== void 0 ? headerConfig : {}).filter(([, value]) => value !== undefined));
291
+ this.edgePolicyConfig = {
292
+ ...this.edgePolicyConfig,
293
+ ...definedTopLevel,
294
+ http: {
295
+ ...this.edgePolicyConfig.http,
296
+ ...definedHttp
297
+ },
298
+ securityHeaders: {
299
+ ...this.edgePolicyConfig.securityHeaders,
300
+ ...definedHeaders
301
+ }
302
+ };
303
+ this.logger.log(chalk_1.default.blue('HTTP edge policy has been configured.'));
304
+ }
236
305
  /**
237
306
  * Registers an application-specific health check.
238
307
  */
@@ -256,6 +325,15 @@ class OverlayExpress {
256
325
  this.adminIdentityKey = identityKey;
257
326
  this.logger.log(chalk_1.default.blue('Admin identity key has been configured.'));
258
327
  }
328
+ /**
329
+ * Configures BRC-103 session storage for the administrative mutual-auth
330
+ * middleware. Horizontally scaled services should supply a shared
331
+ * AsyncSessionManager rather than use the default process-local store.
332
+ */
333
+ configureAuthSessionManager(sessionManager) {
334
+ this.authSessionManager = sessionManager;
335
+ this.logger.log(chalk_1.default.blue('BSV authentication session manager has been configured.'));
336
+ }
259
337
  /**
260
338
  * Configures the logger to be used by the server.
261
339
  * @param logger - A logger object (e.g., console)
@@ -513,8 +591,13 @@ class OverlayExpress {
513
591
  * @param autoConfigureShipSlap - Whether to auto-configure SHIP and SLAP services (default: true)
514
592
  */
515
593
  async configureEngine(autoConfigureShipSlap = true) {
516
- var _a, _b, _c, _d, _e, _f, _g, _h, _j;
594
+ var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
517
595
  const knex = this.ensureKnex();
596
+ const maxLookupResults = (_a = this.engineConfig.maxLookupResults) !== null && _a !== void 0 ? _a : (0, edgePolicy_js_1.readResourceLimit)(this.edgePolicyConfig.environmentPrefix, 'MAX_LOOKUP_RESULTS', (0, edgePolicy_js_1.profileValue)((0, edgePolicy_js_1.readResourceProfile)(this.edgePolicyConfig.environmentPrefix), {
597
+ small: 500,
598
+ standard: 1000,
599
+ highThroughput: 5000
600
+ }), 1000000);
518
601
  if (autoConfigureShipSlap) {
519
602
  const mongoDb = this.ensureMongo();
520
603
  const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb);
@@ -531,8 +614,8 @@ class OverlayExpress {
531
614
  const slapStorageForLookup = this.banService === undefined
532
615
  ? slapStorage
533
616
  : new BanAwareDiscoveryStorage_js_1.BanAwareSLAPStorage(slapStorage, this.banService, this.logger);
534
- this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup);
535
- this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup);
617
+ this.services.ls_ship = new ResourceBoundedLookupWrapper_js_1.ResourceBoundedLookupWrapper(new DiscoveryServices.SHIPLookupService(shipStorageForLookup), maxLookupResults);
618
+ this.services.ls_slap = new ResourceBoundedLookupWrapper_js_1.ResourceBoundedLookupWrapper(new DiscoveryServices.SLAPLookupService(slapStorageForLookup), maxLookupResults);
536
619
  this.logger.log(chalk_1.default.blue('Configured lookup service ls_ship with MongoDB'));
537
620
  this.logger.log(chalk_1.default.blue('Configured lookup service ls_slap with MongoDB'));
538
621
  }
@@ -543,9 +626,9 @@ class OverlayExpress {
543
626
  const broadcaster = this.buildBroadcaster();
544
627
  const advertiser = await this.buildAdvertiser();
545
628
  const EngineWithBASM = overlay_1.Engine;
546
- this.engine = new EngineWithBASM(this.managers, this.services, storage, (_a = this.engineConfig.chainTracker) !== null && _a !== void 0 ? _a : this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
547
- ? ((_b = this.engineConfig.shipTrackers) !== null && _b !== void 0 ? _b : sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS)
548
- : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster !== null && broadcaster !== void 0 ? broadcaster : this.engineConfig.broadcaster, advertiser, syncConfig, (_c = this.engineConfig.logTime) !== null && _c !== void 0 ? _c : false, (_d = this.engineConfig.logPrefix) !== null && _d !== void 0 ? _d : '[OVERLAY_ENGINE] ', (_e = this.engineConfig.throwOnBroadcastFailure) !== null && _e !== void 0 ? _e : true, (_f = this.engineConfig.overlayBroadcastFacilitator) !== null && _f !== void 0 ? _f : new sdk_1.HTTPSOverlayBroadcastFacilitator(), this.logger, (_g = this.engineConfig.suppressDefaultSyncAdvertisements) !== null && _g !== void 0 ? _g : true, this.buildTopicAnchorHeaderResolver(), (_h = this.engineConfig.enableBASMSync) !== null && _h !== void 0 ? _h : this.enableBASMSync, (_j = this.engineConfig.unprovenEvictionBlocks) !== null && _j !== void 0 ? _j : this.unprovenEvictionBlocks);
629
+ this.engine = new EngineWithBASM(this.managers, this.services, storage, (_b = this.engineConfig.chainTracker) !== null && _b !== void 0 ? _b : this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
630
+ ? ((_c = this.engineConfig.shipTrackers) !== null && _c !== void 0 ? _c : sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS)
631
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster !== null && broadcaster !== void 0 ? broadcaster : this.engineConfig.broadcaster, advertiser, syncConfig, (_d = this.engineConfig.logTime) !== null && _d !== void 0 ? _d : false, (_e = this.engineConfig.logPrefix) !== null && _e !== void 0 ? _e : '[OVERLAY_ENGINE] ', (_f = this.engineConfig.throwOnBroadcastFailure) !== null && _f !== void 0 ? _f : true, (_g = this.engineConfig.overlayBroadcastFacilitator) !== null && _g !== void 0 ? _g : new sdk_1.HTTPSOverlayBroadcastFacilitator(), this.logger, (_h = this.engineConfig.suppressDefaultSyncAdvertisements) !== null && _h !== void 0 ? _h : true, this.buildTopicAnchorHeaderResolver(), (_j = this.engineConfig.enableBASMSync) !== null && _j !== void 0 ? _j : this.enableBASMSync, (_k = this.engineConfig.unprovenEvictionBlocks) !== null && _k !== void 0 ? _k : this.unprovenEvictionBlocks, maxLookupResults);
549
632
  this.initServerWallet();
550
633
  this.logger.log(chalk_1.default.green('Engine has been configured.'));
551
634
  }
@@ -678,7 +761,7 @@ class OverlayExpress {
678
761
  if (!response.ok) {
679
762
  throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`);
680
763
  }
681
- const header = await response.json();
764
+ const header = (await response.json());
682
765
  if (typeof header.hash !== 'string') {
683
766
  throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`);
684
767
  }
@@ -760,14 +843,20 @@ class OverlayExpress {
760
843
  * Creates a JanitorService instance with current configuration.
761
844
  */
762
845
  createJanitor() {
846
+ var _a, _b;
763
847
  const mongoDb = this.ensureMongo();
848
+ const prefix = this.edgePolicyConfig.environmentPrefix;
849
+ const profile = (0, edgePolicy_js_1.readResourceProfile)(prefix);
764
850
  return new JanitorService_js_1.JanitorService({
765
851
  mongoDb,
766
852
  logger: this.logger,
767
853
  requestTimeoutMs: this.janitorConfig.requestTimeoutMs,
768
854
  hostDownRevokeScore: this.janitorConfig.hostDownRevokeScore,
769
855
  banService: this.banService,
770
- autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval
856
+ autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval,
857
+ allowPrivateHosts: this.janitorConfig.allowPrivateHosts,
858
+ batchSize: (_a = this.janitorConfig.batchSize) !== null && _a !== void 0 ? _a : (0, edgePolicy_js_1.readResourceLimit)(prefix, 'JANITOR_BATCH_SIZE', (0, edgePolicy_js_1.profileValue)(profile, { small: 100, standard: 250, highThroughput: 1000 }), 100000),
859
+ maxReportResults: (_b = this.janitorConfig.maxReportResults) !== null && _b !== void 0 ? _b : (0, edgePolicy_js_1.readResourceLimit)(prefix, 'JANITOR_MAX_REPORT_RESULTS', (0, edgePolicy_js_1.profileValue)(profile, { small: 500, standard: 1000, highThroughput: 5000 }), 1000000)
771
860
  });
772
861
  }
773
862
  /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
@@ -787,7 +876,9 @@ class OverlayExpress {
787
876
  async handleBanOutpoint(res, engine, value, reason) {
788
877
  const dotIndex = value.lastIndexOf('.');
789
878
  if (dotIndex === -1) {
790
- return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
879
+ return res
880
+ .status(400)
881
+ .json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
791
882
  }
792
883
  const txid = value.substring(0, dotIndex);
793
884
  const outputIndex = Number.parseInt(value.substring(dotIndex + 1));
@@ -813,7 +904,9 @@ class OverlayExpress {
813
904
  try {
814
905
  await svc.outputEvicted(txid, outputIndex);
815
906
  }
816
- catch { /* best-effort */ }
907
+ catch {
908
+ /* best-effort */
909
+ }
817
910
  }
818
911
  }
819
912
  /** Look up the domain of an outpoint from SHIP or SLAP records. */
@@ -838,11 +931,12 @@ class OverlayExpress {
838
931
  async runHealthCheck(definition) {
839
932
  var _a, _b;
840
933
  const startedAt = Date.now();
934
+ let timeout;
841
935
  try {
842
936
  const result = ((_a = (await Promise.race([
843
937
  Promise.resolve(definition.handler()),
844
938
  new Promise((_, reject) => {
845
- setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
939
+ timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
846
940
  })
847
941
  ]))) !== null && _a !== void 0 ? _a : {});
848
942
  return {
@@ -856,18 +950,28 @@ class OverlayExpress {
856
950
  };
857
951
  }
858
952
  catch (error) {
953
+ this.logger.error({
954
+ operation: 'overlay.health_check',
955
+ check: definition.name,
956
+ error
957
+ });
859
958
  return {
860
959
  name: definition.name,
861
960
  scope: definition.scope,
862
961
  critical: definition.critical,
863
962
  status: 'error',
864
- message: error instanceof Error ? error.message : 'Unknown health-check error',
963
+ message: 'Health check failed',
865
964
  durationMs: Date.now() - startedAt
866
965
  };
867
966
  }
967
+ finally {
968
+ if (timeout !== undefined)
969
+ clearTimeout(timeout);
970
+ }
868
971
  }
869
972
  async collectHealthReport(mode) {
870
- var _a, _b, _c;
973
+ var _a;
974
+ var _b, _c;
871
975
  const definitions = [
872
976
  {
873
977
  name: 'process',
@@ -902,7 +1006,8 @@ class OverlayExpress {
902
1006
  scope: 'ready',
903
1007
  critical: true,
904
1008
  handler: async () => {
905
- var _a, _b, _c;
1009
+ var _a, _b;
1010
+ var _c;
906
1011
  if (this.knex === undefined) {
907
1012
  throw new TypeError('Knex is not configured');
908
1013
  }
@@ -936,12 +1041,12 @@ class OverlayExpress {
936
1041
  for (const check of this.healthChecks) {
937
1042
  definitions.push({
938
1043
  name: check.name,
939
- scope: (_a = check.scope) !== null && _a !== void 0 ? _a : 'ready',
940
- critical: (_b = check.critical) !== null && _b !== void 0 ? _b : false,
1044
+ scope: (_b = check.scope) !== null && _b !== void 0 ? _b : 'ready',
1045
+ critical: (_c = check.critical) !== null && _c !== void 0 ? _c : false,
941
1046
  handler: check.handler
942
1047
  });
943
1048
  }
944
- const filteredDefinitions = definitions.filter((definition) => {
1049
+ const filteredDefinitions = definitions.filter(definition => {
945
1050
  if (mode === 'full') {
946
1051
  return true;
947
1052
  }
@@ -971,14 +1076,18 @@ class OverlayExpress {
971
1076
  advertisableFQDN: this.advertisableFQDN,
972
1077
  port: this.port,
973
1078
  network: this.network,
974
- startedAt: (_c = this.startTime) === null || _c === void 0 ? void 0 : _c.toISOString(),
1079
+ startedAt: (_a = this.startTime) === null || _a === void 0 ? void 0 : _a.toISOString(),
975
1080
  uptimeMs: this.startTime === undefined ? 0 : Date.now() - this.startTime.getTime(),
976
1081
  topicManagerCount: Object.keys(this.managers).length,
977
1082
  lookupServiceCount: Object.keys(this.services).length
978
1083
  },
979
1084
  checks: this.healthConfig.includeDetails
980
1085
  ? checks
981
- : checks.map(({ details, ...check }) => check),
1086
+ : checks.map(check => {
1087
+ const publicCheck = { ...check };
1088
+ delete publicCheck.details;
1089
+ return publicCheck;
1090
+ }),
982
1091
  context
983
1092
  };
984
1093
  return report;
@@ -986,20 +1095,83 @@ class OverlayExpress {
986
1095
  /**
987
1096
  * Renders a request or response body for verbose logging, truncating overly long payloads.
988
1097
  */
989
- formatBodyForLog(body, tooLongLabel, okPrefix) {
990
- let bodyString;
991
- if (typeof body === 'object') {
992
- bodyString = JSON.stringify(body, null, 2);
1098
+ formatBodyForLog(body, okPrefix) {
1099
+ if (Buffer.isBuffer(body)) {
1100
+ return chalk_1.default.green(`${okPrefix} binary body (${(0, overlay_1.serializeLogValue)(body.byteLength)} bytes)`);
993
1101
  }
994
- else if (Buffer.isBuffer(body)) {
995
- bodyString = body.toString('utf8');
1102
+ if (typeof body === 'string') {
1103
+ return chalk_1.default.green(`${okPrefix} string body (${(0, overlay_1.serializeLogValue)(Buffer.byteLength(body, 'utf8'))} bytes)`);
996
1104
  }
997
- else {
998
- bodyString = String(body);
1105
+ if (body != null && typeof body === 'object') {
1106
+ const keys = Array.isArray(body) ? body.length : Object.keys(body).length;
1107
+ return chalk_1.default.green(`${okPrefix} structured body (${(0, overlay_1.serializeLogValue)(keys)} top-level item(s))`);
999
1108
  }
1000
- return bodyString.length > 280
1001
- ? chalk_1.default.yellow(`(${tooLongLabel}, length: ${String(bodyString.length)} characters)`)
1002
- : chalk_1.default.green(`${okPrefix}\n${bodyString}`);
1109
+ return chalk_1.default.green(`${okPrefix} type=${(0, overlay_1.serializeLogValue)(typeof body)}`);
1110
+ }
1111
+ redactHeadersForLog(headers) {
1112
+ const sensitiveHeader = /authorization|cookie|token|secret|payment|signature|nonce/i;
1113
+ return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
1114
+ name,
1115
+ sensitiveHeader.test(name) ? '[REDACTED]' : value
1116
+ ]));
1117
+ }
1118
+ arcCallbackRequestToken(req) {
1119
+ const authorization = req.headers.authorization;
1120
+ const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1121
+ if (typeof headerToken === 'string' && headerToken.startsWith('Bearer ')) {
1122
+ return headerToken.slice('Bearer '.length);
1123
+ }
1124
+ return headerToken;
1125
+ }
1126
+ arcCallbackAuthorized(req) {
1127
+ if (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0) {
1128
+ return true;
1129
+ }
1130
+ const callbackHeader = req.headers['x-callback-token'];
1131
+ const callbackToken = Array.isArray(callbackHeader) ? callbackHeader[0] : callbackHeader;
1132
+ return (this.arcCallbackRequestToken(req) === this.arcCallbackToken ||
1133
+ callbackToken === this.arcCallbackToken);
1134
+ }
1135
+ async processArcIngest(engine, req, res) {
1136
+ if (!this.arcCallbackAuthorized(req)) {
1137
+ return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1138
+ }
1139
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1140
+ if (typeof txid !== 'string' || txid === '') {
1141
+ throw new PublicRequestError('Provider callback is missing txid');
1142
+ }
1143
+ if ((0, ArcadeProvider_js_1.isTerminalArcStatus)(txStatus, extraInfo)) {
1144
+ const report = await engine.evictAppliedTransaction(txid, {
1145
+ topic: typeof topic === 'string' ? topic : undefined,
1146
+ reason: `${txStatus !== null && txStatus !== void 0 ? txStatus : ''} ${extraInfo !== null && extraInfo !== void 0 ? extraInfo : ''}`.trim()
1147
+ });
1148
+ this.logger.warn({
1149
+ operation: 'overlay.provider_callback',
1150
+ outcome: 'terminal_evicted',
1151
+ txid,
1152
+ txStatus,
1153
+ competingTxs,
1154
+ report
1155
+ });
1156
+ return res.status(200).json({
1157
+ status: 'success',
1158
+ message: 'Terminal transaction status processed',
1159
+ data: { ...report, txStatus, competingTxs }
1160
+ });
1161
+ }
1162
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1163
+ return res
1164
+ .status(202)
1165
+ .json({ status: 'success', message: 'Transaction status received without proof' });
1166
+ }
1167
+ await engine.handleNewMerkleProof(txid, sdk_1.MerklePath.fromHex(merklePathHex), blockHeight);
1168
+ this.logger.log({
1169
+ operation: 'overlay.provider_callback',
1170
+ outcome: 'proof_ingested',
1171
+ txid,
1172
+ blockHeight
1173
+ });
1174
+ return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
1003
1175
  }
1004
1176
  /**
1005
1177
  * Installs middleware that verbosely logs incoming requests and outgoing responses.
@@ -1008,13 +1180,11 @@ class OverlayExpress {
1008
1180
  this.app.use((req, res, next) => {
1009
1181
  const startTime = Date.now();
1010
1182
  // Log incoming request details
1011
- this.logger.log(chalk_1.default.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
1012
- // Pretty-print headers
1013
- this.logger.log(chalk_1.default.cyan('Headers:'));
1014
- this.logger.log(node_util_1.default.inspect(req.headers, { colors: true, depth: null }));
1183
+ this.logger.log(chalk_1.default.magenta.bold(`Incoming Request: method=${(0, overlay_1.serializeLogValue)(req.method)} url=${(0, overlay_1.serializeLogValue)(req.originalUrl)}`));
1184
+ this.logger.log(chalk_1.default.cyan(`Headers: ${(0, overlay_1.serializeLogValue)(this.redactHeadersForLog(req.headers))}`));
1015
1185
  // Handle request body
1016
1186
  if (req.body != null && Object.keys(req.body).length > 0) {
1017
- this.logger.log(this.formatBodyForLog(req.body, 'Body too long to display', 'Request Body:'));
1187
+ this.logger.log(this.formatBodyForLog(req.body, 'Request Body:'));
1018
1188
  }
1019
1189
  // Intercept the res.send method to log responses
1020
1190
  const originalSend = res.send;
@@ -1026,12 +1196,11 @@ class OverlayExpress {
1026
1196
  // Log outgoing response details after the response is finished
1027
1197
  res.on('finish', () => {
1028
1198
  const duration = Date.now() - startTime;
1029
- this.logger.log(chalk_1.default.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
1030
- this.logger.log(chalk_1.default.cyan('Response Headers:'));
1031
- this.logger.log(node_util_1.default.inspect(res.getHeaders(), { colors: true, depth: null }));
1199
+ this.logger.log(chalk_1.default.magenta.bold(`Outgoing Response: method=${(0, overlay_1.serializeLogValue)(req.method)} url=${(0, overlay_1.serializeLogValue)(req.originalUrl)} status=${(0, overlay_1.serializeLogValue)(res.statusCode)} durationMs=${(0, overlay_1.serializeLogValue)(duration)}`));
1200
+ this.logger.log(chalk_1.default.cyan(`Response Headers: ${(0, overlay_1.serializeLogValue)(this.redactHeadersForLog(res.getHeaders()))}`));
1032
1201
  // Handle response body
1033
1202
  if (responseBody != null) {
1034
- this.logger.log(this.formatBodyForLog(responseBody, 'Response body too long to display', 'Response Body:'));
1203
+ this.logger.log(this.formatBodyForLog(responseBody, 'Response Body:'));
1035
1204
  }
1036
1205
  });
1037
1206
  next();
@@ -1045,25 +1214,77 @@ class OverlayExpress {
1045
1214
  const engine = this.ensureEngine();
1046
1215
  const knex = this.ensureKnex();
1047
1216
  this.startTime = new Date();
1048
- this.app.use(body_parser_1.default.json({ limit: '1gb', type: 'application/json' }));
1049
- this.app.use(body_parser_1.default.raw({ limit: '1gb', type: 'application/octet-stream' }));
1050
- if (this.verboseRequestLogging) {
1051
- this.setupVerboseRequestLogging();
1217
+ const edgePolicy = this.edgePolicyConfig;
1218
+ const resourceProfile = (0, edgePolicy_js_1.readResourceProfile)(edgePolicy.environmentPrefix);
1219
+ const maxResponseBytes = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'MAX_RESPONSE_BYTES', (0, edgePolicy_js_1.profileValue)(resourceProfile, {
1220
+ small: 4 * 1024 * 1024,
1221
+ standard: 8 * 1024 * 1024,
1222
+ highThroughput: 32 * 1024 * 1024
1223
+ }), 512 * 1024 * 1024);
1224
+ const maxBasmTxids = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'MAX_BASM_TXIDS', (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 500, standard: 1000, highThroughput: 5000 }), 1000000);
1225
+ const maxBasmAnchorRange = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'MAX_BASM_ANCHOR_RANGE', (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 500, standard: 1000, highThroughput: 5000 }), 1000000);
1226
+ const adminListDefaultLimit = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'ADMIN_LIST_DEFAULT_LIMIT', (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 25, standard: 50, highThroughput: 100 }), 1000000);
1227
+ const adminListMaxLimit = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'ADMIN_LIST_MAX_LIMIT', (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 100, standard: 200, highThroughput: 1000 }), 1000000);
1228
+ const adminListMaxOffset = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'ADMIN_LIST_MAX_OFFSET', (0, edgePolicy_js_1.profileValue)(resourceProfile, {
1229
+ small: 10000,
1230
+ standard: 100000,
1231
+ highThroughput: 1000000
1232
+ }), 100000000);
1233
+ if (adminListDefaultLimit !== -1 &&
1234
+ adminListMaxLimit !== -1 &&
1235
+ adminListDefaultLimit > adminListMaxLimit) {
1236
+ throw new TypeError('OVERLAY_ADMIN_LIST_DEFAULT_LIMIT cannot exceed OVERLAY_ADMIN_LIST_MAX_LIMIT');
1052
1237
  }
1053
- // Enable CORS
1054
- this.app.use((req, res, next) => {
1055
- res.header('Access-Control-Allow-Origin', '*');
1056
- res.header('Access-Control-Allow-Headers', '*');
1057
- res.header('Access-Control-Allow-Methods', '*');
1058
- res.header('Access-Control-Expose-Headers', '*');
1059
- res.header('Access-Control-Allow-Private-Network', 'true');
1060
- if (req.method === 'OPTIONS') {
1061
- res.sendStatus(200);
1238
+ const parseAdminPage = (rawPageValue, rawLimitValue) => {
1239
+ const rawPage = Number.parseInt(typeof rawPageValue === 'string' ? rawPageValue : '', 10);
1240
+ const requestedPage = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1241
+ const rawLimitText = typeof rawLimitValue === 'string' ? rawLimitValue.trim().toLowerCase() : '';
1242
+ const parsedLimit = rawLimitText === '-1' || rawLimitText === 'unlimited'
1243
+ ? -1
1244
+ : Number.parseInt(rawLimitText, 10);
1245
+ const requestedLimit = rawLimitText.length === 0 || Number.isNaN(parsedLimit) ? adminListDefaultLimit : parsedLimit;
1246
+ if (requestedLimit !== -1 && (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1)) {
1247
+ throw new TypeError('limit must be a positive integer, -1, or unlimited');
1062
1248
  }
1063
- else {
1064
- next();
1249
+ let limit = requestedLimit;
1250
+ if (adminListMaxLimit !== -1) {
1251
+ limit =
1252
+ requestedLimit === -1 ? adminListMaxLimit : Math.min(requestedLimit, adminListMaxLimit);
1065
1253
  }
1066
- });
1254
+ const page = limit === -1 ? 1 : requestedPage;
1255
+ const skip = limit === -1 ? 0 : (page - 1) * limit;
1256
+ if (!Number.isSafeInteger(skip) || (adminListMaxOffset !== -1 && skip > adminListMaxOffset)) {
1257
+ throw new TypeError('requested page exceeds the configured maximum offset');
1258
+ }
1259
+ return { page, limit, skip };
1260
+ };
1261
+ this.app.disable('x-powered-by');
1262
+ this.app.use(edgePolicy_js_1.initialDoubleSlashCompatibility);
1263
+ this.app.use((0, edgePolicy_js_1.securityHeaders)({
1264
+ environmentPrefix: edgePolicy.environmentPrefix,
1265
+ ...edgePolicy.securityHeaders
1266
+ }));
1267
+ this.app.use((0, edgePolicy_js_1.corsPolicy)({
1268
+ environmentPrefix: edgePolicy.environmentPrefix,
1269
+ allowedOrigins: edgePolicy.allowedOrigins,
1270
+ methods: ['GET', 'POST', 'OPTIONS']
1271
+ }));
1272
+ this.app.use((0, edgePolicy_js_1.concurrencyLimit)(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests === 200
1273
+ ? (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 8, standard: 24, highThroughput: 96 })
1274
+ : edgePolicy.maxConcurrentRequests));
1275
+ this.app.use(body_parser_1.default.json({
1276
+ limit: (0, edgePolicy_js_1.readBodyLimitBytes)(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes),
1277
+ type: 'application/json'
1278
+ }));
1279
+ this.app.use(body_parser_1.default.raw({
1280
+ limit: (0, edgePolicy_js_1.readBodyLimitBytes)(`${edgePolicy.environmentPrefix}_BINARY`, edgePolicy.binaryBodyLimitBytes),
1281
+ type: 'application/octet-stream'
1282
+ }));
1283
+ this.app.use(edgePolicy_js_1.bodyParserErrorHandler);
1284
+ this.app.use((0, edgePolicy_js_1.responseSizeLimit)(edgePolicy.environmentPrefix, maxResponseBytes));
1285
+ if (this.verboseRequestLogging) {
1286
+ this.setupVerboseRequestLogging();
1287
+ }
1067
1288
  // Serve a static documentation site or user interface
1068
1289
  this.app.get('/', (req, res) => {
1069
1290
  res.set('content-type', 'text/html');
@@ -1078,22 +1299,35 @@ class OverlayExpress {
1078
1299
  (async () => {
1079
1300
  const report = await this.collectHealthReport('live');
1080
1301
  return res.status(report.live ? 200 : 503).json(report);
1081
- })().catch((error) => {
1302
+ })().catch(error => {
1303
+ this.logger.error({ operation: 'overlay.health_live', error });
1082
1304
  res.status(500).json({
1083
1305
  status: 'error',
1084
- message: error instanceof Error ? error.message : 'Unexpected error'
1306
+ message: 'Health report unavailable'
1085
1307
  });
1086
1308
  });
1087
1309
  });
1310
+ // Compatibility alias used by Kubernetes probes and existing deployments.
1311
+ this.app.get('/healthz', (_, res) => {
1312
+ ;
1313
+ (async () => {
1314
+ const report = await this.collectHealthReport('live');
1315
+ return res.status(report.live ? 200 : 503).json(report);
1316
+ })().catch(error => {
1317
+ this.logger.error({ operation: 'overlay.healthz', error });
1318
+ res.status(500).json({ status: 'error', message: 'Health report unavailable' });
1319
+ });
1320
+ });
1088
1321
  this.app.get('/health/ready', (_, res) => {
1089
1322
  ;
1090
1323
  (async () => {
1091
1324
  const report = await this.collectHealthReport('ready');
1092
1325
  return res.status(report.ready ? 200 : 503).json(report);
1093
- })().catch((error) => {
1326
+ })().catch(error => {
1327
+ this.logger.error({ operation: 'overlay.health_ready', error });
1094
1328
  res.status(500).json({
1095
1329
  status: 'error',
1096
- message: error instanceof Error ? error.message : 'Unexpected error'
1330
+ message: 'Health report unavailable'
1097
1331
  });
1098
1332
  });
1099
1333
  });
@@ -1102,10 +1336,11 @@ class OverlayExpress {
1102
1336
  (async () => {
1103
1337
  const report = await this.collectHealthReport('full');
1104
1338
  return res.status(report.ready ? 200 : 503).json(report);
1105
- })().catch((error) => {
1339
+ })().catch(error => {
1340
+ this.logger.error({ operation: 'overlay.health_full', error });
1106
1341
  res.status(500).json({
1107
1342
  status: 'error',
1108
- message: error instanceof Error ? error.message : 'Unexpected error'
1343
+ message: 'Health report unavailable'
1109
1344
  });
1110
1345
  });
1111
1346
  });
@@ -1120,7 +1355,7 @@ class OverlayExpress {
1120
1355
  catch (error) {
1121
1356
  return res.status(400).json({
1122
1357
  status: 'error',
1123
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1358
+ message: publicErrorMessage(error)
1124
1359
  });
1125
1360
  }
1126
1361
  })().catch(() => {
@@ -1140,7 +1375,7 @@ class OverlayExpress {
1140
1375
  catch (error) {
1141
1376
  return res.status(400).json({
1142
1377
  status: 'error',
1143
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1378
+ message: publicErrorMessage(error)
1144
1379
  });
1145
1380
  }
1146
1381
  })().catch(() => {
@@ -1163,7 +1398,7 @@ class OverlayExpress {
1163
1398
  catch (error) {
1164
1399
  return res.status(400).json({
1165
1400
  status: 'error',
1166
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1401
+ message: publicErrorMessage(error)
1167
1402
  });
1168
1403
  }
1169
1404
  })().catch(() => {
@@ -1185,7 +1420,7 @@ class OverlayExpress {
1185
1420
  catch (error) {
1186
1421
  return res.status(400).json({
1187
1422
  status: 'error',
1188
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1423
+ message: publicErrorMessage(error)
1189
1424
  });
1190
1425
  }
1191
1426
  })().catch(() => {
@@ -1204,12 +1439,12 @@ class OverlayExpress {
1204
1439
  const topicsHeader = req.headers['x-topics'];
1205
1440
  const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true';
1206
1441
  if (typeof topicsHeader !== 'string') {
1207
- throw new TypeError('Missing x-topics header');
1442
+ throw new PublicRequestError('Missing x-topics header');
1208
1443
  }
1209
1444
  const topics = parseTopicsHeader(topicsHeader);
1210
1445
  const body = req.body;
1211
1446
  if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
1212
- throw new TypeError('Missing or empty BEEF body');
1447
+ throw new PublicRequestError('Missing or empty BEEF body');
1213
1448
  }
1214
1449
  let offChainValues;
1215
1450
  let beef = Array.from(body);
@@ -1235,10 +1470,10 @@ class OverlayExpress {
1235
1470
  }
1236
1471
  }
1237
1472
  catch (error) {
1238
- console.error(chalk_1.default.red('Error in /submit:'), error);
1473
+ this.logger.error(chalk_1.default.red(`Error in /submit: error=${(0, overlay_1.serializeErrorForLog)(error)}`));
1239
1474
  return res.status(400).json({
1240
1475
  status: 'error',
1241
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1476
+ message: publicErrorMessage(error)
1242
1477
  });
1243
1478
  }
1244
1479
  })().catch(() => {
@@ -1282,7 +1517,7 @@ class OverlayExpress {
1282
1517
  // Write outputIndex
1283
1518
  writer.writeVarIntNum(output.outputIndex);
1284
1519
  // Write context length and data
1285
- if ((output.context != null) && output.context.length > 0) {
1520
+ if (output.context != null && output.context.length > 0) {
1286
1521
  writer.writeVarIntNum(output.context.length);
1287
1522
  writer.write(output.context);
1288
1523
  }
@@ -1297,10 +1532,10 @@ class OverlayExpress {
1297
1532
  return res.status(200).send(Buffer.from(writer.toArray()));
1298
1533
  }
1299
1534
  catch (error) {
1300
- console.error(chalk_1.default.red('Error in /lookup:'), error);
1535
+ this.logger.error(chalk_1.default.red(`Error in /lookup: error=${(0, overlay_1.serializeErrorForLog)(error)}`));
1301
1536
  return res.status(400).json({
1302
1537
  status: 'error',
1303
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1538
+ message: publicErrorMessage(error)
1304
1539
  });
1305
1540
  }
1306
1541
  })().catch(() => {
@@ -1317,63 +1552,13 @@ class OverlayExpress {
1317
1552
  ;
1318
1553
  (async () => {
1319
1554
  try {
1320
- if (typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0) {
1321
- const authorization = req.headers.authorization;
1322
- const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1323
- const xCallbackToken = req.headers['x-callback-token'];
1324
- const callbackToken = Array.isArray(xCallbackToken) ? xCallbackToken[0] : xCallbackToken;
1325
- const bearerToken = typeof headerToken === 'string' && headerToken.startsWith('Bearer ')
1326
- ? headerToken.slice('Bearer '.length)
1327
- : headerToken;
1328
- if (bearerToken !== this.arcCallbackToken && callbackToken !== this.arcCallbackToken) {
1329
- return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1330
- }
1331
- }
1332
- const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1333
- if (typeof txid !== 'string' || txid === '') {
1334
- throw new TypeError('Provider callback is missing txid');
1335
- }
1336
- if ((0, ArcadeProvider_js_1.isTerminalArcStatus)(txStatus, extraInfo)) {
1337
- const report = await engine.evictAppliedTransaction(txid, {
1338
- topic: typeof topic === 'string' ? topic : undefined,
1339
- reason: `${txStatus !== null && txStatus !== void 0 ? txStatus : ''} ${extraInfo !== null && extraInfo !== void 0 ? extraInfo : ''}`.trim()
1340
- });
1341
- this.logger.warn({
1342
- operation: 'overlay.provider_callback',
1343
- outcome: 'terminal_evicted',
1344
- txid,
1345
- txStatus,
1346
- competingTxs,
1347
- report
1348
- });
1349
- return res.status(200).json({
1350
- status: 'success',
1351
- message: 'Terminal transaction status processed',
1352
- data: {
1353
- ...report,
1354
- txStatus,
1355
- competingTxs
1356
- }
1357
- });
1358
- }
1359
- if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1360
- return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' });
1361
- }
1362
- const merklePath = sdk_1.MerklePath.fromHex(merklePathHex);
1363
- await engine.handleNewMerkleProof(txid, merklePath, blockHeight);
1364
- this.logger.log({
1365
- operation: 'overlay.provider_callback',
1366
- outcome: 'proof_ingested',
1367
- txid,
1368
- blockHeight
1369
- });
1370
- return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
1555
+ return await this.processArcIngest(engine, req, res);
1371
1556
  }
1372
1557
  catch (error) {
1373
- console.error(chalk_1.default.red('Error in /arc-ingest:'), error);
1558
+ this.logger.error(chalk_1.default.red(`Error in /arc-ingest: error=${(0, overlay_1.serializeErrorForLog)(error)}`));
1374
1559
  return res.status(400).json({
1375
1560
  status: 'error',
1376
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1561
+ message: publicErrorMessage(error)
1377
1562
  });
1378
1563
  }
1379
1564
  })().catch(() => {
@@ -1401,7 +1586,7 @@ class OverlayExpress {
1401
1586
  console.error(chalk_1.default.red('Error in /requestSyncResponse:'), error);
1402
1587
  return res.status(400).json({
1403
1588
  status: 'error',
1404
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1589
+ message: publicErrorMessage(error)
1405
1590
  });
1406
1591
  }
1407
1592
  })().catch(() => {
@@ -1423,7 +1608,7 @@ class OverlayExpress {
1423
1608
  console.error(chalk_1.default.red('Error in /requestForeignGASPNode:'), error);
1424
1609
  return res.status(400).json({
1425
1610
  status: 'error',
1426
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1611
+ message: publicErrorMessage(error)
1427
1612
  });
1428
1613
  }
1429
1614
  })().catch(() => {
@@ -1442,7 +1627,7 @@ class OverlayExpress {
1442
1627
  const readBasmTopic = (req) => {
1443
1628
  const header = req.headers['x-bsv-topic'];
1444
1629
  if (typeof header !== 'string' || header.length === 0) {
1445
- throw new TypeError('Missing x-bsv-topic header');
1630
+ throw new PublicRequestError('Missing x-bsv-topic header');
1446
1631
  }
1447
1632
  return header;
1448
1633
  };
@@ -1464,7 +1649,7 @@ class OverlayExpress {
1464
1649
  console.error(chalk_1.default.red(`Error in ${path}:`), error);
1465
1650
  return res.status(400).json({
1466
1651
  status: 'error',
1467
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1652
+ message: publicErrorMessage(error)
1468
1653
  });
1469
1654
  }
1470
1655
  })().catch(() => {
@@ -1474,14 +1659,25 @@ class OverlayExpress {
1474
1659
  };
1475
1660
  const requireTxids = (value) => {
1476
1661
  if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1477
- throw new TypeError('txids must be an array of strings');
1662
+ throw new PublicRequestError('txids must be an array of strings');
1663
+ }
1664
+ if (maxBasmTxids !== -1 && value.length > maxBasmTxids) {
1665
+ throw new PublicRequestError(`txids must contain at most ${maxBasmTxids} entries`);
1478
1666
  }
1479
1667
  return value;
1480
1668
  };
1481
1669
  registerJsonRoute('/requestTopicAnchorTip', async (req) => await basmEngine.provideTopicAnchorTip(readBasmTopic(req)));
1482
1670
  registerJsonRoute('/requestTopicAnchorRange', async (req) => {
1483
1671
  const { fromHeight, toHeight } = req.body;
1484
- return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), Number(fromHeight), Number(toHeight));
1672
+ const from = Number(fromHeight);
1673
+ const to = Number(toHeight);
1674
+ if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to < from) {
1675
+ throw new PublicRequestError('fromHeight and toHeight must define a valid ascending range');
1676
+ }
1677
+ if (maxBasmAnchorRange !== -1 && to - from + 1 > maxBasmAnchorRange) {
1678
+ throw new PublicRequestError(`topic anchor range must contain at most ${maxBasmAnchorRange} blocks`);
1679
+ }
1680
+ return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), from, to);
1485
1681
  });
1486
1682
  registerJsonRoute('/requestAdmittedList', async (req) => {
1487
1683
  const { blockHeight, blockHash } = req.body;
@@ -1507,6 +1703,7 @@ class OverlayExpress {
1507
1703
  if (this.serverWallet !== undefined) {
1508
1704
  const bsvAuth = (0, auth_express_middleware_1.createAuthMiddleware)({
1509
1705
  wallet: this.serverWallet,
1706
+ sessionManager: this.authSessionManager,
1510
1707
  allowUnauthenticated: true
1511
1708
  });
1512
1709
  this.app.use(bsvAuth);
@@ -1533,14 +1730,17 @@ class OverlayExpress {
1533
1730
  const authHeader = req.headers.authorization;
1534
1731
  if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
1535
1732
  const token = authHeader.substring('Bearer '.length);
1536
- if (token === this.adminToken) {
1733
+ if (secretMatches(token, this.adminToken)) {
1537
1734
  next();
1538
1735
  return;
1539
1736
  }
1540
1737
  res.status(403).json({ status: 'error', message: 'Forbidden: Invalid credentials' });
1541
1738
  return;
1542
1739
  }
1543
- res.status(401).json({ status: 'error', message: 'Unauthorized: Provide a Bearer token or authenticate with your wallet' });
1740
+ res.status(401).json({
1741
+ status: 'error',
1742
+ message: 'Unauthorized: Provide a Bearer token or authenticate with your wallet'
1743
+ });
1544
1744
  };
1545
1745
  /**
1546
1746
  * Public endpoint that returns the admin identity key (if configured).
@@ -1561,13 +1761,14 @@ class OverlayExpress {
1561
1761
  this.app.get('/admin/stats', checkAdminAuth, (req, res) => {
1562
1762
  ;
1563
1763
  (async () => {
1564
- var _a, _b, _c;
1764
+ var _a, _b;
1765
+ var _c;
1565
1766
  try {
1566
1767
  const db = this.ensureMongo();
1567
1768
  const [shipCount, slapCount, banStats] = await Promise.all([
1568
1769
  db.collection('shipRecords').countDocuments(),
1569
1770
  db.collection('slapRecords').countDocuments(),
1570
- (_b = (_a = this.banService) === null || _a === void 0 ? void 0 : _a.getStats()) !== null && _b !== void 0 ? _b : { domainBans: 0, outpointBans: 0, totalBans: 0 }
1771
+ (_c = (_a = this.banService) === null || _a === void 0 ? void 0 : _a.getStats()) !== null && _c !== void 0 ? _c : { domainBans: 0, outpointBans: 0, totalBans: 0 }
1571
1772
  ]);
1572
1773
  return res.status(200).json({
1573
1774
  status: 'success',
@@ -1575,7 +1776,7 @@ class OverlayExpress {
1575
1776
  nodeName: this.name,
1576
1777
  network: this.network,
1577
1778
  uptime: this.startTime != null ? Date.now() - this.startTime.getTime() : 0,
1578
- startedAt: (_c = this.startTime) === null || _c === void 0 ? void 0 : _c.toISOString(),
1779
+ startedAt: (_b = this.startTime) === null || _b === void 0 ? void 0 : _b.toISOString(),
1579
1780
  shipRecordCount: shipCount,
1580
1781
  slapRecordCount: slapCount,
1581
1782
  bannedDomains: banStats.domainBans,
@@ -1592,7 +1793,7 @@ class OverlayExpress {
1592
1793
  catch (error) {
1593
1794
  return res.status(400).json({
1594
1795
  status: 'error',
1595
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1796
+ message: publicErrorMessage(error)
1596
1797
  });
1597
1798
  }
1598
1799
  })().catch(() => {
@@ -1609,11 +1810,7 @@ class OverlayExpress {
1609
1810
  const db = this.ensureMongo();
1610
1811
  const collection = db.collection('shipRecords');
1611
1812
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1612
- const rawPage = Number.parseInt(req.query.page, 10);
1613
- const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1614
- const rawLimit = Number.parseInt(req.query.limit, 10);
1615
- const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1616
- const skip = (page - 1) * limit;
1813
+ const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1617
1814
  const query = {};
1618
1815
  if (typeof search === 'string' && search.length > 0) {
1619
1816
  query.$or = [
@@ -1624,18 +1821,29 @@ class OverlayExpress {
1624
1821
  ];
1625
1822
  }
1626
1823
  const [records, total] = await Promise.all([
1627
- collection.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray(),
1824
+ (() => {
1825
+ let cursor = collection.find(query).sort({ createdAt: -1 }).skip(skip);
1826
+ if (limit !== -1)
1827
+ cursor = cursor.limit(limit);
1828
+ return cursor.toArray();
1829
+ })(),
1628
1830
  collection.countDocuments(query)
1629
1831
  ]);
1630
1832
  return res.status(200).json({
1631
1833
  status: 'success',
1632
- data: { records, total, page, limit, pages: Math.ceil(total / limit) }
1834
+ data: {
1835
+ records,
1836
+ total,
1837
+ page,
1838
+ limit,
1839
+ pages: limit === -1 ? 1 : Math.ceil(total / limit)
1840
+ }
1633
1841
  });
1634
1842
  }
1635
1843
  catch (error) {
1636
1844
  return res.status(400).json({
1637
1845
  status: 'error',
1638
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1846
+ message: publicErrorMessage(error)
1639
1847
  });
1640
1848
  }
1641
1849
  })().catch(() => {
@@ -1652,11 +1860,7 @@ class OverlayExpress {
1652
1860
  const db = this.ensureMongo();
1653
1861
  const collection = db.collection('slapRecords');
1654
1862
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1655
- const rawPage = Number.parseInt(req.query.page, 10);
1656
- const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1657
- const rawLimit = Number.parseInt(req.query.limit, 10);
1658
- const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1659
- const skip = (page - 1) * limit;
1863
+ const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
1660
1864
  const query = {};
1661
1865
  if (typeof search === 'string' && search.length > 0) {
1662
1866
  query.$or = [
@@ -1667,18 +1871,29 @@ class OverlayExpress {
1667
1871
  ];
1668
1872
  }
1669
1873
  const [records, total] = await Promise.all([
1670
- collection.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray(),
1874
+ (() => {
1875
+ let cursor = collection.find(query).sort({ createdAt: -1 }).skip(skip);
1876
+ if (limit !== -1)
1877
+ cursor = cursor.limit(limit);
1878
+ return cursor.toArray();
1879
+ })(),
1671
1880
  collection.countDocuments(query)
1672
1881
  ]);
1673
1882
  return res.status(200).json({
1674
1883
  status: 'success',
1675
- data: { records, total, page, limit, pages: Math.ceil(total / limit) }
1884
+ data: {
1885
+ records,
1886
+ total,
1887
+ page,
1888
+ limit,
1889
+ pages: limit === -1 ? 1 : Math.ceil(total / limit)
1890
+ }
1676
1891
  });
1677
1892
  }
1678
1893
  catch (error) {
1679
1894
  return res.status(400).json({
1680
1895
  status: 'error',
1681
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1896
+ message: publicErrorMessage(error)
1682
1897
  });
1683
1898
  }
1684
1899
  })().catch(() => {
@@ -1704,7 +1919,7 @@ class OverlayExpress {
1704
1919
  catch (error) {
1705
1920
  return res.status(400).json({
1706
1921
  status: 'error',
1707
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1922
+ message: publicErrorMessage(error)
1708
1923
  });
1709
1924
  }
1710
1925
  })().catch(() => {
@@ -1719,11 +1934,16 @@ class OverlayExpress {
1719
1934
  (async () => {
1720
1935
  try {
1721
1936
  if (this.banService === undefined) {
1722
- return res.status(400).json({ status: 'error', message: 'Ban service not available (MongoDB not configured)' });
1937
+ return res.status(400).json({
1938
+ status: 'error',
1939
+ message: 'Ban service not available (MongoDB not configured)'
1940
+ });
1723
1941
  }
1724
1942
  const { type, value, reason } = req.body;
1725
1943
  if (type !== 'domain' && type !== 'outpoint') {
1726
- return res.status(400).json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1944
+ return res
1945
+ .status(400)
1946
+ .json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1727
1947
  }
1728
1948
  if (typeof value !== 'string' || value.length === 0) {
1729
1949
  return res.status(400).json({ status: 'error', message: 'value is required' });
@@ -1736,7 +1956,7 @@ class OverlayExpress {
1736
1956
  catch (error) {
1737
1957
  return res.status(400).json({
1738
1958
  status: 'error',
1739
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1959
+ message: publicErrorMessage(error)
1740
1960
  });
1741
1961
  }
1742
1962
  })().catch(() => {
@@ -1755,18 +1975,22 @@ class OverlayExpress {
1755
1975
  }
1756
1976
  const { type, value } = req.body;
1757
1977
  if (type !== 'domain' && type !== 'outpoint') {
1758
- return res.status(400).json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1978
+ return res
1979
+ .status(400)
1980
+ .json({ status: 'error', message: 'type must be "domain" or "outpoint"' });
1759
1981
  }
1760
1982
  if (typeof value !== 'string' || value.length === 0) {
1761
1983
  return res.status(400).json({ status: 'error', message: 'value is required' });
1762
1984
  }
1763
1985
  await this.banService.removeBan(type, value);
1764
- return res.status(200).json({ status: 'success', message: `${type} "${String(value)}" unbanned.` });
1986
+ return res
1987
+ .status(200)
1988
+ .json({ status: 'success', message: `${type} "${String(value)}" unbanned.` });
1765
1989
  }
1766
1990
  catch (error) {
1767
1991
  return res.status(400).json({
1768
1992
  status: 'error',
1769
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1993
+ message: publicErrorMessage(error)
1770
1994
  });
1771
1995
  }
1772
1996
  })().catch(() => {
@@ -1785,13 +2009,14 @@ class OverlayExpress {
1785
2009
  }
1786
2010
  const type = req.query.type;
1787
2011
  const validType = type === 'domain' || type === 'outpoint' ? type : undefined;
1788
- const bans = await this.banService.listBans(validType);
1789
- return res.status(200).json({ status: 'success', data: { bans } });
2012
+ const { page, limit, skip } = parseAdminPage(req.query.page, req.query.limit);
2013
+ const bans = await this.banService.listBans(validType, limit, skip);
2014
+ return res.status(200).json({ status: 'success', data: { bans, page, limit } });
1790
2015
  }
1791
2016
  catch (error) {
1792
2017
  return res.status(400).json({
1793
2018
  status: 'error',
1794
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2019
+ message: publicErrorMessage(error)
1795
2020
  });
1796
2021
  }
1797
2022
  })().catch(() => {
@@ -1807,7 +2032,10 @@ class OverlayExpress {
1807
2032
  try {
1808
2033
  const { txid, outputIndex, service, ban, banDomain: shouldBanDomain } = req.body;
1809
2034
  if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
1810
- return res.status(400).json({ status: 'error', message: 'txid (string) and outputIndex (number) are required' });
2035
+ return res.status(400).json({
2036
+ status: 'error',
2037
+ message: 'txid (string) and outputIndex (number) are required'
2038
+ });
1811
2039
  }
1812
2040
  // Look up domain before eviction if needed for banning
1813
2041
  let removedDomain;
@@ -1818,7 +2046,9 @@ class OverlayExpress {
1818
2046
  if (ban === true && this.banService !== undefined) {
1819
2047
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain);
1820
2048
  }
1821
- if (shouldBanDomain === true && typeof removedDomain === 'string' && this.banService !== undefined) {
2049
+ if (shouldBanDomain === true &&
2050
+ typeof removedDomain === 'string' &&
2051
+ this.banService !== undefined) {
1822
2052
  await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal');
1823
2053
  }
1824
2054
  const banMsg = ban === true ? ' Outpoint banned.' : '';
@@ -1833,7 +2063,7 @@ class OverlayExpress {
1833
2063
  catch (error) {
1834
2064
  return res.status(400).json({
1835
2065
  status: 'error',
1836
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2066
+ message: publicErrorMessage(error)
1837
2067
  });
1838
2068
  }
1839
2069
  })().catch(() => {
@@ -1848,13 +2078,15 @@ class OverlayExpress {
1848
2078
  (async () => {
1849
2079
  try {
1850
2080
  await engine.syncAdvertisements();
1851
- return res.status(200).json({ status: 'success', message: 'Advertisements synced successfully' });
2081
+ return res
2082
+ .status(200)
2083
+ .json({ status: 'success', message: 'Advertisements synced successfully' });
1852
2084
  }
1853
2085
  catch (error) {
1854
2086
  console.error(chalk_1.default.red('Error in /admin/syncAdvertisements:'), error);
1855
2087
  return res.status(400).json({
1856
2088
  status: 'error',
1857
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2089
+ message: publicErrorMessage(error)
1858
2090
  });
1859
2091
  }
1860
2092
  })().catch(() => {
@@ -1872,13 +2104,15 @@ class OverlayExpress {
1872
2104
  (async () => {
1873
2105
  try {
1874
2106
  await engine.startGASPSync();
1875
- return res.status(200).json({ status: 'success', message: 'GASP sync started and completed' });
2107
+ return res
2108
+ .status(200)
2109
+ .json({ status: 'success', message: 'GASP sync started and completed' });
1876
2110
  }
1877
2111
  catch (error) {
1878
2112
  console.error(chalk_1.default.red('Error in /admin/startGASPSync:'), error);
1879
2113
  return res.status(400).json({
1880
2114
  status: 'error',
1881
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2115
+ message: publicErrorMessage(error)
1882
2116
  });
1883
2117
  }
1884
2118
  })().catch(() => {
@@ -1965,7 +2199,7 @@ class OverlayExpress {
1965
2199
  console.error(chalk_1.default.red('Error in /admin/evictOutpoint:'), error);
1966
2200
  return res.status(400).json({
1967
2201
  status: 'error',
1968
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2202
+ message: publicErrorMessage(error)
1969
2203
  });
1970
2204
  }
1971
2205
  })().catch(() => {
@@ -1984,13 +2218,15 @@ class OverlayExpress {
1984
2218
  try {
1985
2219
  const janitor = this.createJanitor();
1986
2220
  const report = await janitor.run();
1987
- return res.status(200).json({ status: 'success', message: 'Janitor run completed', data: report });
2221
+ return res
2222
+ .status(200)
2223
+ .json({ status: 'success', message: 'Janitor run completed', data: report });
1988
2224
  }
1989
2225
  catch (error) {
1990
2226
  console.error(chalk_1.default.red('Error in /admin/janitor:'), error);
1991
2227
  return res.status(400).json({
1992
2228
  status: 'error',
1993
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2229
+ message: publicErrorMessage(error)
1994
2230
  });
1995
2231
  }
1996
2232
  })().catch(() => {
@@ -2008,7 +2244,7 @@ class OverlayExpress {
2008
2244
  this.logger.log(chalk_1.default.green('Knex migrations run'), result);
2009
2245
  // 404 handler for all other routes
2010
2246
  this.app.use((req, res) => {
2011
- this.logger.log(chalk_1.default.red('404 Not Found:'), req.url);
2247
+ this.logger.log(chalk_1.default.red(`404 Not Found: url=${(0, overlay_1.serializeLogValue)(req.url)}`));
2012
2248
  res.status(404).json({
2013
2249
  status: 'error',
2014
2250
  code: 'ERR_ROUTE_NOT_FOUND',
@@ -2017,10 +2253,57 @@ class OverlayExpress {
2017
2253
  });
2018
2254
  await this.runStartupSync();
2019
2255
  // Start listening on the configured port
2020
- this.app.listen(this.port, () => {
2256
+ this.server = this.app.listen(this.port, () => {
2021
2257
  this.isListening = true;
2022
2258
  this.logger.log(chalk_1.default.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
2023
2259
  });
2260
+ (0, edgePolicy_js_1.configureHttpServer)(this.server, edgePolicy.environmentPrefix, edgePolicy.http);
2261
+ }
2262
+ /**
2263
+ * Stops new HTTP work, background synchronization, and database clients.
2264
+ *
2265
+ * The operation is idempotent so multiple signal handlers or embedding
2266
+ * runtimes can share shutdown ownership safely.
2267
+ */
2268
+ async close() {
2269
+ var _a;
2270
+ (_a = this.closePromise) !== null && _a !== void 0 ? _a : (this.closePromise = this.closeResources());
2271
+ await this.closePromise;
2272
+ }
2273
+ async closeResources() {
2274
+ var _a, _b, _c;
2275
+ var _d, _e;
2276
+ this.isListening = false;
2277
+ if (this.basmBlockPollTimer !== undefined) {
2278
+ clearInterval(this.basmBlockPollTimer);
2279
+ this.basmBlockPollTimer = undefined;
2280
+ }
2281
+ if (this.unprovenMaintenanceTimer !== undefined) {
2282
+ clearInterval(this.unprovenMaintenanceTimer);
2283
+ this.unprovenMaintenanceTimer = undefined;
2284
+ }
2285
+ (_a = this.reorgAdapter) === null || _a === void 0 ? void 0 : _a.stop();
2286
+ this.reorgAdapter = undefined;
2287
+ const server = this.server;
2288
+ this.server = undefined;
2289
+ const closeServer = server === undefined
2290
+ ? Promise.resolve()
2291
+ : new Promise((resolve, reject) => {
2292
+ server.close(error => {
2293
+ if (error !== undefined)
2294
+ reject(error);
2295
+ else
2296
+ resolve();
2297
+ });
2298
+ });
2299
+ await closeServer;
2300
+ await Promise.all([
2301
+ (_d = (_b = this.knex) === null || _b === void 0 ? void 0 : _b.destroy()) !== null && _d !== void 0 ? _d : Promise.resolve(),
2302
+ (_e = (_c = this.mongoClient) === null || _c === void 0 ? void 0 : _c.close()) !== null && _e !== void 0 ? _e : Promise.resolve()
2303
+ ]);
2304
+ this.knex = undefined;
2305
+ this.mongoClient = undefined;
2306
+ this.mongoDb = undefined;
2024
2307
  }
2025
2308
  /**
2026
2309
  * Runs the post-listen startup work: advertiser init, advertisement sync,
@@ -2110,8 +2393,12 @@ class OverlayExpress {
2110
2393
  const basmEngine = this.engine;
2111
2394
  this.reorgAdapter = new ReorgStream_js_1.ReorgSseAdapter({
2112
2395
  url: reorgStreamUrl,
2113
- onReorg: async (input) => { await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.handleReorg(input)); },
2114
- onConnect: async () => { await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.revalidateRecentAnchors(reorgScanDepth)); },
2396
+ onReorg: async (input) => {
2397
+ await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.handleReorg(input));
2398
+ },
2399
+ onConnect: async () => {
2400
+ await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.revalidateRecentAnchors(reorgScanDepth));
2401
+ },
2115
2402
  logger: this.logger
2116
2403
  });
2117
2404
  this.reorgAdapter.start();
@@ -2129,23 +2416,26 @@ class OverlayExpress {
2129
2416
  }
2130
2417
  /** Revalidate recent BASM anchors against the chain tracker, reconciling any reorg. */
2131
2418
  async revalidateBASMAnchors() {
2132
- var _a, _b;
2419
+ var _a;
2420
+ var _b;
2133
2421
  try {
2134
- const depth = (_a = this.engineConfig.reorgScanDepth) !== null && _a !== void 0 ? _a : this.reorgScanDepth;
2135
- await ((_b = this.engine) === null || _b === void 0 ? void 0 : _b.revalidateRecentAnchors(depth));
2422
+ const depth = (_b = this.engineConfig.reorgScanDepth) !== null && _b !== void 0 ? _b : this.reorgScanDepth;
2423
+ await ((_a = this.engine) === null || _a === void 0 ? void 0 : _a.revalidateRecentAnchors(depth));
2136
2424
  }
2137
2425
  catch (e) {
2138
2426
  console.error(chalk_1.default.red('Failed to revalidate BASM anchors'), e);
2139
2427
  }
2140
2428
  }
2141
2429
  startUnprovenMaintenance() {
2142
- var _a, _b, _c;
2143
- const intervalMs = (_a = this.engineConfig.unprovenMaintenanceIntervalMs) !== null && _a !== void 0 ? _a : this.unprovenMaintenanceIntervalMs;
2430
+ var _a, _b;
2431
+ var _c;
2432
+ const intervalMs = (_c = this.engineConfig.unprovenMaintenanceIntervalMs) !== null && _c !== void 0 ? _c : this.unprovenMaintenanceIntervalMs;
2144
2433
  if (intervalMs <= 0)
2145
2434
  return;
2146
2435
  const run = () => {
2147
2436
  void (async () => {
2148
- var _a, _b;
2437
+ var _a;
2438
+ var _b;
2149
2439
  try {
2150
2440
  const report = await ((_a = this.engine) === null || _a === void 0 ? void 0 : _a.maintainUnprovenTransactions({
2151
2441
  thresholdBlocks: (_b = this.engineConfig.unprovenEvictionBlocks) !== null && _b !== void 0 ? _b : this.unprovenEvictionBlocks,
@@ -2160,7 +2450,7 @@ class OverlayExpress {
2160
2450
  };
2161
2451
  run();
2162
2452
  this.unprovenMaintenanceTimer = setInterval(run, intervalMs);
2163
- (_c = (_b = this.unprovenMaintenanceTimer).unref) === null || _c === void 0 ? void 0 : _c.call(_b);
2453
+ (_b = (_a = this.unprovenMaintenanceTimer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
2164
2454
  }
2165
2455
  }
2166
2456
  exports.default = OverlayExpress;