@bsv/overlay-express 2.4.1 → 2.4.9

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 (137) 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 +36 -23
  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 +81 -0
  23. package/dist/cjs/src/BanService.d.ts.map +1 -0
  24. package/dist/cjs/src/BanService.js.map +1 -1
  25. package/dist/cjs/src/ChaintracksProvider.d.ts +29 -0
  26. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -0
  27. package/dist/cjs/src/ChaintracksProvider.js +1 -1
  28. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  29. package/dist/cjs/src/JanitorService.d.ts +128 -0
  30. package/dist/cjs/src/JanitorService.d.ts.map +1 -0
  31. package/dist/cjs/src/JanitorService.js +108 -37
  32. package/dist/cjs/src/JanitorService.js.map +1 -1
  33. package/dist/cjs/src/OverlayExpress.d.ts +466 -0
  34. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -0
  35. package/dist/cjs/src/OverlayExpress.js +337 -160
  36. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  37. package/dist/cjs/src/OverlayMonitor.d.ts +197 -0
  38. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -0
  39. package/dist/cjs/src/OverlayMonitor.js +6 -4
  40. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  41. package/dist/cjs/src/ProviderChainBroadcaster.d.ts +18 -0
  42. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -0
  43. package/dist/cjs/src/ProviderChainBroadcaster.js +7 -3
  44. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  45. package/dist/cjs/src/ReorgStream.d.ts +74 -0
  46. package/dist/cjs/src/ReorgStream.d.ts.map +1 -0
  47. package/dist/cjs/src/ReorgStream.js +14 -6
  48. package/dist/cjs/src/ReorgStream.js.map +1 -1
  49. package/dist/cjs/src/generalGuide.md.d.ts +3 -0
  50. package/dist/cjs/src/generalGuide.md.d.ts.map +1 -0
  51. package/dist/cjs/src/generalGuide.md.js +1 -1
  52. package/dist/cjs/src/generalGuide.md.js.map +1 -1
  53. package/dist/cjs/src/makeUserInterface.d.ts +22 -0
  54. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -0
  55. package/dist/cjs/src/makeUserInterface.js +4 -4
  56. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  57. package/dist/cjs/src/security/edgePolicy.d.ts +57 -0
  58. package/dist/cjs/src/security/edgePolicy.d.ts.map +1 -0
  59. package/dist/cjs/src/security/edgePolicy.js +379 -0
  60. package/dist/cjs/src/security/edgePolicy.js.map +1 -0
  61. package/dist/esm/mod.js.map +1 -1
  62. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  63. package/dist/esm/src/BanAwareDiscoveryStorage.js +5 -4
  64. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  65. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  66. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  67. package/dist/esm/src/BanAwareTopicManager.js +3 -2
  68. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  69. package/dist/esm/src/ChaintracksProvider.js +1 -1
  70. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  71. package/dist/esm/src/JanitorService.js +84 -8
  72. package/dist/esm/src/JanitorService.js.map +1 -1
  73. package/dist/esm/src/OverlayExpress.js +319 -146
  74. package/dist/esm/src/OverlayExpress.js.map +1 -1
  75. package/dist/esm/src/ProviderChainBroadcaster.js +7 -3
  76. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  77. package/dist/esm/src/ReorgStream.js +14 -6
  78. package/dist/esm/src/ReorgStream.js.map +1 -1
  79. package/dist/esm/src/generalGuide.md.js +1 -1
  80. package/dist/esm/src/makeUserInterface.js +3 -4
  81. package/dist/esm/src/makeUserInterface.js.map +1 -1
  82. package/dist/esm/src/security/edgePolicy.js +377 -0
  83. package/dist/esm/src/security/edgePolicy.js.map +1 -0
  84. package/dist/types/mod.d.ts +1 -1
  85. package/dist/types/mod.d.ts.map +1 -1
  86. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  87. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  88. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  89. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  90. package/dist/types/src/BanService.d.ts.map +1 -1
  91. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  92. package/dist/types/src/JanitorService.d.ts +14 -1
  93. package/dist/types/src/JanitorService.d.ts.map +1 -1
  94. package/dist/types/src/OverlayExpress.d.ts +48 -2
  95. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  96. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  97. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  98. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  99. package/dist/types/src/generalGuide.md.d.ts +1 -1
  100. package/dist/types/src/generalGuide.md.d.ts.map +1 -1
  101. package/dist/types/src/makeUserInterface.d.ts +1 -2
  102. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  103. package/dist/types/src/security/edgePolicy.d.ts +57 -0
  104. package/dist/types/src/security/edgePolicy.d.ts.map +1 -0
  105. package/package.json +51 -29
  106. package/dist/cjs/tsconfig.cjs.tsbuildinfo +0 -1
  107. package/dist/esm/tsconfig.esm.tsbuildinfo +0 -1
  108. package/dist/types/tsconfig.types.tsbuildinfo +0 -1
  109. package/mod.ts +0 -47
  110. package/src/ArcadeProvider.ts +0 -232
  111. package/src/BanAwareDiscoveryStorage.ts +0 -91
  112. package/src/BanAwareLookupWrapper.ts +0 -95
  113. package/src/BanAwareTopicManager.ts +0 -87
  114. package/src/BanService.ts +0 -154
  115. package/src/ChaintracksProvider.ts +0 -79
  116. package/src/JanitorService.ts +0 -423
  117. package/src/OverlayExpress.ts +0 -2456
  118. package/src/OverlayMonitor.ts +0 -817
  119. package/src/ProviderChainBroadcaster.ts +0 -108
  120. package/src/ReorgStream.ts +0 -221
  121. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +0 -131
  122. package/src/__tests__/BanAwareLookupWrapper.test.ts +0 -255
  123. package/src/__tests__/BanAwareTopicManager.test.ts +0 -132
  124. package/src/__tests__/BanService.test.ts +0 -310
  125. package/src/__tests__/InMemoryMigrationSource.test.ts +0 -11
  126. package/src/__tests__/JanitorService.test.ts +0 -941
  127. package/src/__tests__/OverlayExpress.test.ts +0 -1142
  128. package/src/__tests__/OverlayMonitor.test.ts +0 -255
  129. package/src/__tests__/OverlayProviders.live.test.ts +0 -39
  130. package/src/__tests__/OverlayProviders.test.ts +0 -123
  131. package/src/__tests__/README.md +0 -105
  132. package/src/__tests__/ReorgStream.test.ts +0 -66
  133. package/src/__tests__/makeUserInterface.test.ts +0 -193
  134. package/src/__tests__/setup.ts +0 -36
  135. package/src/auth-express-middleware.d.ts +0 -16
  136. package/src/generalGuide.md.ts +0 -74
  137. package/src/makeUserInterface.ts +0 -1224
@@ -1,14 +1,14 @@
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';
@@ -20,6 +20,7 @@ import { createAuthMiddleware } from '@bsv/auth-express-middleware';
20
20
  import { ArcadeProvider, isTerminalArcStatus } from './ArcadeProvider.js';
21
21
  import { ProviderChainBroadcaster } from './ProviderChainBroadcaster.js';
22
22
  import { ChaintracksProvider } from './ChaintracksProvider.js';
23
+ import { bodyParserErrorHandler, concurrencyLimit, configureHttpServer, corsPolicy, readBodyLimitBytes, securityHeaders } from './security/edgePolicy.js';
23
24
  /**
24
25
  * In-memory migration source for Knex migrations.
25
26
  * Allows running migrations defined in code rather than files.
@@ -34,7 +35,7 @@ class InMemoryMigrationSource {
34
35
  * @param loadExtensions - Array of file extensions to filter by (not used here)
35
36
  * @returns Promise resolving to the array of migrations
36
37
  */
37
- async getMigrations(loadExtensions) {
38
+ async getMigrations(_loadExtensions) {
38
39
  return this.migrations;
39
40
  }
40
41
  /**
@@ -54,6 +55,36 @@ class InMemoryMigrationSource {
54
55
  return await Promise.resolve(migration);
55
56
  }
56
57
  }
58
+ class PublicRequestError extends Error {
59
+ constructor(message) {
60
+ super(message);
61
+ this.name = 'PublicRequestError';
62
+ }
63
+ }
64
+ function publicErrorMessage(error, fallback = 'Request could not be processed') {
65
+ return error instanceof PublicRequestError ? error.message : fallback;
66
+ }
67
+ function secretMatches(provided, expected) {
68
+ const providedDigest = createHash('sha256').update(provided, 'utf8').digest();
69
+ const expectedDigest = createHash('sha256').update(expected, 'utf8').digest();
70
+ return timingSafeEqual(providedDigest, expectedDigest);
71
+ }
72
+ function parseTopicsHeader(header) {
73
+ const value = header.trim();
74
+ let parsed;
75
+ try {
76
+ parsed = value.startsWith('[')
77
+ ? JSON.parse(value)
78
+ : value.split(',').map(topic => topic.trim());
79
+ }
80
+ catch {
81
+ throw new PublicRequestError('Invalid x-topics header: expected a comma-separated list or JSON string array');
82
+ }
83
+ if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
84
+ throw new PublicRequestError('Invalid x-topics header: expected a comma-separated list or JSON string array');
85
+ }
86
+ return parsed;
87
+ }
57
88
  /**
58
89
  * OverlayExpress class provides an Express-based server for hosting Overlay Services.
59
90
  * It allows configuration of various components like databases, topic managers, and lookup services.
@@ -141,7 +172,8 @@ export default class OverlayExpress {
141
172
  janitorConfig = {
142
173
  requestTimeoutMs: 10000, // 10 seconds
143
174
  hostDownRevokeScore: 3,
144
- autoBanOnRemoval: true
175
+ autoBanOnRemoval: true,
176
+ allowPrivateHosts: false
145
177
  };
146
178
  // Ban service for persistent domain/outpoint blocking
147
179
  banService;
@@ -149,6 +181,8 @@ export default class OverlayExpress {
149
181
  adminIdentityKey;
150
182
  // Server-side wallet (WalletInterface) used for BSV mutual authentication
151
183
  serverWallet;
184
+ // Optional shared store for BSV mutual-auth sessions.
185
+ authSessionManager;
152
186
  // Server start time for uptime tracking
153
187
  startTime;
154
188
  // Health endpoint configuration
@@ -160,6 +194,26 @@ export default class OverlayExpress {
160
194
  healthChecks = [];
161
195
  // Lifecycle marker for readiness/liveness reporting
162
196
  isListening = false;
197
+ // Active HTTP server, retained so timeout policy is observable and the
198
+ // process can add graceful-close handling without replacing app.listen().
199
+ server;
200
+ closePromise;
201
+ edgePolicyConfig = {
202
+ environmentPrefix: 'OVERLAY',
203
+ jsonBodyLimitBytes: 8 * 1024 * 1024,
204
+ binaryBodyLimitBytes: 64 * 1024 * 1024,
205
+ maxConcurrentRequests: 200,
206
+ http: {
207
+ requestTimeoutMs: 2 * 60 * 1000,
208
+ headersTimeoutMs: 15_000,
209
+ keepAliveTimeoutMs: 5_000,
210
+ socketTimeoutMs: 2 * 60 * 1000,
211
+ maxRequestsPerSocket: 1_000
212
+ },
213
+ securityHeaders: {
214
+ 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'"
215
+ }
216
+ };
163
217
  /**
164
218
  * Constructs an instance of OverlayExpress.
165
219
  * @param name - The name of the service
@@ -204,6 +258,7 @@ export default class OverlayExpress {
204
258
  * - requestTimeoutMs: Timeout for health check requests (default: 10000ms)
205
259
  * - hostDownRevokeScore: Number of consecutive failures before deleting output (default: 3)
206
260
  * - autoBanOnRemoval: Whether to auto-ban domains when removed by janitor (default: true)
261
+ * - allowPrivateHosts: Permit private/HTTP targets for isolated local development (default: false)
207
262
  */
208
263
  configureJanitor(config) {
209
264
  this.janitorConfig = {
@@ -222,6 +277,30 @@ export default class OverlayExpress {
222
277
  };
223
278
  this.logger.log(chalk.blue('Health reporting has been configured.'));
224
279
  }
280
+ /**
281
+ * Configures explicit browser origins and bounded request/resource policy.
282
+ * Public cross-origin access is the default; pass allowedOrigins or set
283
+ * OVERLAY_CORS_MODE=allowlist to restrict browser callers.
284
+ */
285
+ configureEdgePolicy(config) {
286
+ const { http, securityHeaders: headerConfig, ...topLevel } = config;
287
+ const definedTopLevel = Object.fromEntries(Object.entries(topLevel).filter(([, value]) => value !== undefined));
288
+ const definedHttp = Object.fromEntries(Object.entries(http ?? {}).filter(([, value]) => value !== undefined));
289
+ const definedHeaders = Object.fromEntries(Object.entries(headerConfig ?? {}).filter(([, value]) => value !== undefined));
290
+ this.edgePolicyConfig = {
291
+ ...this.edgePolicyConfig,
292
+ ...definedTopLevel,
293
+ http: {
294
+ ...this.edgePolicyConfig.http,
295
+ ...definedHttp
296
+ },
297
+ securityHeaders: {
298
+ ...this.edgePolicyConfig.securityHeaders,
299
+ ...definedHeaders
300
+ }
301
+ };
302
+ this.logger.log(chalk.blue('HTTP edge policy has been configured.'));
303
+ }
225
304
  /**
226
305
  * Registers an application-specific health check.
227
306
  */
@@ -245,6 +324,15 @@ export default class OverlayExpress {
245
324
  this.adminIdentityKey = identityKey;
246
325
  this.logger.log(chalk.blue('Admin identity key has been configured.'));
247
326
  }
327
+ /**
328
+ * Configures BRC-103 session storage for the administrative mutual-auth
329
+ * middleware. Horizontally scaled services should supply a shared
330
+ * AsyncSessionManager rather than use the default process-local store.
331
+ */
332
+ configureAuthSessionManager(sessionManager) {
333
+ this.authSessionManager = sessionManager;
334
+ this.logger.log(chalk.blue('BSV authentication session manager has been configured.'));
335
+ }
248
336
  /**
249
337
  * Configures the logger to be used by the server.
250
338
  * @param logger - A logger object (e.g., console)
@@ -503,22 +591,25 @@ export default class OverlayExpress {
503
591
  async configureEngine(autoConfigureShipSlap = true) {
504
592
  const knex = this.ensureKnex();
505
593
  if (autoConfigureShipSlap) {
594
+ const mongoDb = this.ensureMongo();
595
+ const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb);
596
+ const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb);
597
+ // Run the one-time discovery migration before the engine can accept
598
+ // traffic, so a failed unique-index build is a visible startup failure.
599
+ await shipStorage.ensureIndexes();
600
+ await slapStorage.ensureIndexes();
506
601
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
507
602
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
508
- this.configureLookupServiceWithMongo('ls_ship', (db) => {
509
- const storage = new DiscoveryServices.SHIPStorage(db);
510
- const storageForLookup = this.banService === undefined
511
- ? storage
512
- : new BanAwareSHIPStorage(storage, this.banService, this.logger);
513
- return new DiscoveryServices.SHIPLookupService(storageForLookup);
514
- });
515
- this.configureLookupServiceWithMongo('ls_slap', (db) => {
516
- const storage = new DiscoveryServices.SLAPStorage(db);
517
- const storageForLookup = this.banService === undefined
518
- ? storage
519
- : new BanAwareSLAPStorage(storage, this.banService, this.logger);
520
- return new DiscoveryServices.SLAPLookupService(storageForLookup);
521
- });
603
+ const shipStorageForLookup = this.banService === undefined
604
+ ? shipStorage
605
+ : new BanAwareSHIPStorage(shipStorage, this.banService, this.logger);
606
+ const slapStorageForLookup = this.banService === undefined
607
+ ? slapStorage
608
+ : new BanAwareSLAPStorage(slapStorage, this.banService, this.logger);
609
+ this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup);
610
+ this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup);
611
+ this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'));
612
+ this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'));
522
613
  }
523
614
  this.wrapBanAwareServices();
524
615
  const syncConfig = this.buildSyncConfig();
@@ -747,7 +838,8 @@ export default class OverlayExpress {
747
838
  requestTimeoutMs: this.janitorConfig.requestTimeoutMs,
748
839
  hostDownRevokeScore: this.janitorConfig.hostDownRevokeScore,
749
840
  banService: this.banService,
750
- autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval
841
+ autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval,
842
+ allowPrivateHosts: this.janitorConfig.allowPrivateHosts
751
843
  });
752
844
  }
753
845
  /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
@@ -816,11 +908,12 @@ export default class OverlayExpress {
816
908
  }
817
909
  async runHealthCheck(definition) {
818
910
  const startedAt = Date.now();
911
+ let timeout;
819
912
  try {
820
913
  const result = ((await Promise.race([
821
914
  Promise.resolve(definition.handler()),
822
915
  new Promise((_, reject) => {
823
- setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
916
+ timeout = setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
824
917
  })
825
918
  ])) ?? {});
826
919
  return {
@@ -834,15 +927,24 @@ export default class OverlayExpress {
834
927
  };
835
928
  }
836
929
  catch (error) {
930
+ this.logger.error({
931
+ operation: 'overlay.health_check',
932
+ check: definition.name,
933
+ error
934
+ });
837
935
  return {
838
936
  name: definition.name,
839
937
  scope: definition.scope,
840
938
  critical: definition.critical,
841
939
  status: 'error',
842
- message: error instanceof Error ? error.message : 'Unknown health-check error',
940
+ message: 'Health check failed',
843
941
  durationMs: Date.now() - startedAt
844
942
  };
845
943
  }
944
+ finally {
945
+ if (timeout !== undefined)
946
+ clearTimeout(timeout);
947
+ }
846
948
  }
847
949
  async collectHealthReport(mode) {
848
950
  const definitions = [
@@ -954,7 +1056,11 @@ export default class OverlayExpress {
954
1056
  },
955
1057
  checks: this.healthConfig.includeDetails
956
1058
  ? checks
957
- : checks.map(({ details, ...check }) => check),
1059
+ : checks.map(check => {
1060
+ const publicCheck = { ...check };
1061
+ delete publicCheck.details;
1062
+ return publicCheck;
1063
+ }),
958
1064
  context
959
1065
  };
960
1066
  return report;
@@ -962,20 +1068,83 @@ export default class OverlayExpress {
962
1068
  /**
963
1069
  * Renders a request or response body for verbose logging, truncating overly long payloads.
964
1070
  */
965
- formatBodyForLog(body, tooLongLabel, okPrefix) {
966
- let bodyString;
967
- if (typeof body === 'object') {
968
- bodyString = JSON.stringify(body, null, 2);
1071
+ formatBodyForLog(body, okPrefix) {
1072
+ if (Buffer.isBuffer(body)) {
1073
+ return chalk.green(`${okPrefix} binary body (${serializeLogValue(body.byteLength)} bytes)`);
969
1074
  }
970
- else if (Buffer.isBuffer(body)) {
971
- bodyString = body.toString('utf8');
1075
+ if (typeof body === 'string') {
1076
+ return chalk.green(`${okPrefix} string body (${serializeLogValue(Buffer.byteLength(body, 'utf8'))} bytes)`);
972
1077
  }
973
- else {
974
- bodyString = String(body);
1078
+ if (body != null && typeof body === 'object') {
1079
+ const keys = Array.isArray(body) ? body.length : Object.keys(body).length;
1080
+ return chalk.green(`${okPrefix} structured body (${serializeLogValue(keys)} top-level item(s))`);
1081
+ }
1082
+ return chalk.green(`${okPrefix} type=${serializeLogValue(typeof body)}`);
1083
+ }
1084
+ redactHeadersForLog(headers) {
1085
+ const sensitiveHeader = /authorization|cookie|token|secret|payment|signature|nonce/i;
1086
+ return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
1087
+ name,
1088
+ sensitiveHeader.test(name) ? '[REDACTED]' : value
1089
+ ]));
1090
+ }
1091
+ arcCallbackRequestToken(req) {
1092
+ const authorization = req.headers.authorization;
1093
+ const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1094
+ if (typeof headerToken === 'string' && headerToken.startsWith('Bearer ')) {
1095
+ return headerToken.slice('Bearer '.length);
975
1096
  }
976
- return bodyString.length > 280
977
- ? chalk.yellow(`(${tooLongLabel}, length: ${String(bodyString.length)} characters)`)
978
- : chalk.green(`${okPrefix}\n${bodyString}`);
1097
+ return headerToken;
1098
+ }
1099
+ arcCallbackAuthorized(req) {
1100
+ if (typeof this.arcCallbackToken !== 'string' || this.arcCallbackToken.length === 0) {
1101
+ return true;
1102
+ }
1103
+ const callbackHeader = req.headers['x-callback-token'];
1104
+ const callbackToken = Array.isArray(callbackHeader) ? callbackHeader[0] : callbackHeader;
1105
+ return (this.arcCallbackRequestToken(req) === this.arcCallbackToken ||
1106
+ callbackToken === this.arcCallbackToken);
1107
+ }
1108
+ async processArcIngest(engine, req, res) {
1109
+ if (!this.arcCallbackAuthorized(req)) {
1110
+ return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1111
+ }
1112
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1113
+ if (typeof txid !== 'string' || txid === '') {
1114
+ throw new PublicRequestError('Provider callback is missing txid');
1115
+ }
1116
+ if (isTerminalArcStatus(txStatus, extraInfo)) {
1117
+ const report = await engine.evictAppliedTransaction(txid, {
1118
+ topic: typeof topic === 'string' ? topic : undefined,
1119
+ reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1120
+ });
1121
+ this.logger.warn({
1122
+ operation: 'overlay.provider_callback',
1123
+ outcome: 'terminal_evicted',
1124
+ txid,
1125
+ txStatus,
1126
+ competingTxs,
1127
+ report
1128
+ });
1129
+ return res.status(200).json({
1130
+ status: 'success',
1131
+ message: 'Terminal transaction status processed',
1132
+ data: { ...report, txStatus, competingTxs }
1133
+ });
1134
+ }
1135
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1136
+ return res
1137
+ .status(202)
1138
+ .json({ status: 'success', message: 'Transaction status received without proof' });
1139
+ }
1140
+ await engine.handleNewMerkleProof(txid, MerklePath.fromHex(merklePathHex), blockHeight);
1141
+ this.logger.log({
1142
+ operation: 'overlay.provider_callback',
1143
+ outcome: 'proof_ingested',
1144
+ txid,
1145
+ blockHeight
1146
+ });
1147
+ return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
979
1148
  }
980
1149
  /**
981
1150
  * Installs middleware that verbosely logs incoming requests and outgoing responses.
@@ -984,13 +1153,11 @@ export default class OverlayExpress {
984
1153
  this.app.use((req, res, next) => {
985
1154
  const startTime = Date.now();
986
1155
  // Log incoming request details
987
- this.logger.log(chalk.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
988
- // Pretty-print headers
989
- this.logger.log(chalk.cyan('Headers:'));
990
- this.logger.log(util.inspect(req.headers, { colors: true, depth: null }));
1156
+ this.logger.log(chalk.magenta.bold(`Incoming Request: method=${serializeLogValue(req.method)} url=${serializeLogValue(req.originalUrl)}`));
1157
+ this.logger.log(chalk.cyan(`Headers: ${serializeLogValue(this.redactHeadersForLog(req.headers))}`));
991
1158
  // Handle request body
992
1159
  if (req.body != null && Object.keys(req.body).length > 0) {
993
- this.logger.log(this.formatBodyForLog(req.body, 'Body too long to display', 'Request Body:'));
1160
+ this.logger.log(this.formatBodyForLog(req.body, 'Request Body:'));
994
1161
  }
995
1162
  // Intercept the res.send method to log responses
996
1163
  const originalSend = res.send;
@@ -1002,12 +1169,11 @@ export default class OverlayExpress {
1002
1169
  // Log outgoing response details after the response is finished
1003
1170
  res.on('finish', () => {
1004
1171
  const duration = Date.now() - startTime;
1005
- this.logger.log(chalk.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
1006
- this.logger.log(chalk.cyan('Response Headers:'));
1007
- this.logger.log(util.inspect(res.getHeaders(), { colors: true, depth: null }));
1172
+ this.logger.log(chalk.magenta.bold(`Outgoing Response: method=${serializeLogValue(req.method)} url=${serializeLogValue(req.originalUrl)} status=${serializeLogValue(res.statusCode)} durationMs=${serializeLogValue(duration)}`));
1173
+ this.logger.log(chalk.cyan(`Response Headers: ${serializeLogValue(this.redactHeadersForLog(res.getHeaders()))}`));
1008
1174
  // Handle response body
1009
1175
  if (responseBody != null) {
1010
- this.logger.log(this.formatBodyForLog(responseBody, 'Response body too long to display', 'Response Body:'));
1176
+ this.logger.log(this.formatBodyForLog(responseBody, 'Response Body:'));
1011
1177
  }
1012
1178
  });
1013
1179
  next();
@@ -1021,25 +1187,30 @@ export default class OverlayExpress {
1021
1187
  const engine = this.ensureEngine();
1022
1188
  const knex = this.ensureKnex();
1023
1189
  this.startTime = new Date();
1024
- this.app.use(bodyParser.json({ limit: '1gb', type: 'application/json' }));
1025
- this.app.use(bodyParser.raw({ limit: '1gb', type: 'application/octet-stream' }));
1190
+ const edgePolicy = this.edgePolicyConfig;
1191
+ this.app.disable('x-powered-by');
1192
+ this.app.use(securityHeaders({
1193
+ environmentPrefix: edgePolicy.environmentPrefix,
1194
+ ...edgePolicy.securityHeaders
1195
+ }));
1196
+ this.app.use(corsPolicy({
1197
+ environmentPrefix: edgePolicy.environmentPrefix,
1198
+ allowedOrigins: edgePolicy.allowedOrigins,
1199
+ methods: ['GET', 'POST', 'OPTIONS']
1200
+ }));
1201
+ this.app.use(concurrencyLimit(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests));
1202
+ this.app.use(bodyParser.json({
1203
+ limit: readBodyLimitBytes(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes),
1204
+ type: 'application/json'
1205
+ }));
1206
+ this.app.use(bodyParser.raw({
1207
+ limit: readBodyLimitBytes(`${edgePolicy.environmentPrefix}_BINARY`, edgePolicy.binaryBodyLimitBytes),
1208
+ type: 'application/octet-stream'
1209
+ }));
1210
+ this.app.use(bodyParserErrorHandler);
1026
1211
  if (this.verboseRequestLogging) {
1027
1212
  this.setupVerboseRequestLogging();
1028
1213
  }
1029
- // Enable CORS
1030
- this.app.use((req, res, next) => {
1031
- res.header('Access-Control-Allow-Origin', '*');
1032
- res.header('Access-Control-Allow-Headers', '*');
1033
- res.header('Access-Control-Allow-Methods', '*');
1034
- res.header('Access-Control-Expose-Headers', '*');
1035
- res.header('Access-Control-Allow-Private-Network', 'true');
1036
- if (req.method === 'OPTIONS') {
1037
- res.sendStatus(200);
1038
- }
1039
- else {
1040
- next();
1041
- }
1042
- });
1043
1214
  // Serve a static documentation site or user interface
1044
1215
  this.app.get('/', (req, res) => {
1045
1216
  res.set('content-type', 'text/html');
@@ -1055,9 +1226,10 @@ export default class OverlayExpress {
1055
1226
  const report = await this.collectHealthReport('live');
1056
1227
  return res.status(report.live ? 200 : 503).json(report);
1057
1228
  })().catch((error) => {
1229
+ this.logger.error({ operation: 'overlay.health_live', error });
1058
1230
  res.status(500).json({
1059
1231
  status: 'error',
1060
- message: error instanceof Error ? error.message : 'Unexpected error'
1232
+ message: 'Health report unavailable'
1061
1233
  });
1062
1234
  });
1063
1235
  });
@@ -1067,9 +1239,10 @@ export default class OverlayExpress {
1067
1239
  const report = await this.collectHealthReport('ready');
1068
1240
  return res.status(report.ready ? 200 : 503).json(report);
1069
1241
  })().catch((error) => {
1242
+ this.logger.error({ operation: 'overlay.health_ready', error });
1070
1243
  res.status(500).json({
1071
1244
  status: 'error',
1072
- message: error instanceof Error ? error.message : 'Unexpected error'
1245
+ message: 'Health report unavailable'
1073
1246
  });
1074
1247
  });
1075
1248
  });
@@ -1079,9 +1252,10 @@ export default class OverlayExpress {
1079
1252
  const report = await this.collectHealthReport('full');
1080
1253
  return res.status(report.ready ? 200 : 503).json(report);
1081
1254
  })().catch((error) => {
1255
+ this.logger.error({ operation: 'overlay.health_full', error });
1082
1256
  res.status(500).json({
1083
1257
  status: 'error',
1084
- message: error instanceof Error ? error.message : 'Unexpected error'
1258
+ message: 'Health report unavailable'
1085
1259
  });
1086
1260
  });
1087
1261
  });
@@ -1096,7 +1270,7 @@ export default class OverlayExpress {
1096
1270
  catch (error) {
1097
1271
  return res.status(400).json({
1098
1272
  status: 'error',
1099
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1273
+ message: publicErrorMessage(error)
1100
1274
  });
1101
1275
  }
1102
1276
  })().catch(() => {
@@ -1116,7 +1290,7 @@ export default class OverlayExpress {
1116
1290
  catch (error) {
1117
1291
  return res.status(400).json({
1118
1292
  status: 'error',
1119
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1293
+ message: publicErrorMessage(error)
1120
1294
  });
1121
1295
  }
1122
1296
  })().catch(() => {
@@ -1139,7 +1313,7 @@ export default class OverlayExpress {
1139
1313
  catch (error) {
1140
1314
  return res.status(400).json({
1141
1315
  status: 'error',
1142
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1316
+ message: publicErrorMessage(error)
1143
1317
  });
1144
1318
  }
1145
1319
  })().catch(() => {
@@ -1161,7 +1335,7 @@ export default class OverlayExpress {
1161
1335
  catch (error) {
1162
1336
  return res.status(400).json({
1163
1337
  status: 'error',
1164
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1338
+ message: publicErrorMessage(error)
1165
1339
  });
1166
1340
  }
1167
1341
  })().catch(() => {
@@ -1180,11 +1354,15 @@ export default class OverlayExpress {
1180
1354
  const topicsHeader = req.headers['x-topics'];
1181
1355
  const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true';
1182
1356
  if (typeof topicsHeader !== 'string') {
1183
- throw new TypeError('Missing x-topics header');
1357
+ throw new PublicRequestError('Missing x-topics header');
1358
+ }
1359
+ const topics = parseTopicsHeader(topicsHeader);
1360
+ const body = req.body;
1361
+ if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
1362
+ throw new PublicRequestError('Missing or empty BEEF body');
1184
1363
  }
1185
- const topics = JSON.parse(topicsHeader);
1186
1364
  let offChainValues;
1187
- let beef = Array.from(req.body);
1365
+ let beef = Array.from(body);
1188
1366
  if (includesOffChain) {
1189
1367
  const r = new Utils.Reader(beef);
1190
1368
  const l = r.readVarIntNum();
@@ -1207,10 +1385,10 @@ export default class OverlayExpress {
1207
1385
  }
1208
1386
  }
1209
1387
  catch (error) {
1210
- console.error(chalk.red('Error in /submit:'), error);
1388
+ this.logger.error(chalk.red(`Error in /submit: error=${serializeErrorForLog(error)}`));
1211
1389
  return res.status(400).json({
1212
1390
  status: 'error',
1213
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1391
+ message: publicErrorMessage(error)
1214
1392
  });
1215
1393
  }
1216
1394
  })().catch(() => {
@@ -1269,10 +1447,10 @@ export default class OverlayExpress {
1269
1447
  return res.status(200).send(Buffer.from(writer.toArray()));
1270
1448
  }
1271
1449
  catch (error) {
1272
- console.error(chalk.red('Error in /lookup:'), error);
1450
+ this.logger.error(chalk.red(`Error in /lookup: error=${serializeErrorForLog(error)}`));
1273
1451
  return res.status(400).json({
1274
1452
  status: 'error',
1275
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1453
+ message: publicErrorMessage(error)
1276
1454
  });
1277
1455
  }
1278
1456
  })().catch(() => {
@@ -1289,63 +1467,13 @@ export default class OverlayExpress {
1289
1467
  ;
1290
1468
  (async () => {
1291
1469
  try {
1292
- if (typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0) {
1293
- const authorization = req.headers.authorization;
1294
- const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1295
- const xCallbackToken = req.headers['x-callback-token'];
1296
- const callbackToken = Array.isArray(xCallbackToken) ? xCallbackToken[0] : xCallbackToken;
1297
- const bearerToken = typeof headerToken === 'string' && headerToken.startsWith('Bearer ')
1298
- ? headerToken.slice('Bearer '.length)
1299
- : headerToken;
1300
- if (bearerToken !== this.arcCallbackToken && callbackToken !== this.arcCallbackToken) {
1301
- return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1302
- }
1303
- }
1304
- const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1305
- if (typeof txid !== 'string' || txid === '') {
1306
- throw new TypeError('Provider callback is missing txid');
1307
- }
1308
- if (isTerminalArcStatus(txStatus, extraInfo)) {
1309
- const report = await engine.evictAppliedTransaction(txid, {
1310
- topic: typeof topic === 'string' ? topic : undefined,
1311
- reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1312
- });
1313
- this.logger.warn({
1314
- operation: 'overlay.provider_callback',
1315
- outcome: 'terminal_evicted',
1316
- txid,
1317
- txStatus,
1318
- competingTxs,
1319
- report
1320
- });
1321
- return res.status(200).json({
1322
- status: 'success',
1323
- message: 'Terminal transaction status processed',
1324
- data: {
1325
- ...report,
1326
- txStatus,
1327
- competingTxs
1328
- }
1329
- });
1330
- }
1331
- if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1332
- return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' });
1333
- }
1334
- const merklePath = MerklePath.fromHex(merklePathHex);
1335
- await engine.handleNewMerkleProof(txid, merklePath, blockHeight);
1336
- this.logger.log({
1337
- operation: 'overlay.provider_callback',
1338
- outcome: 'proof_ingested',
1339
- txid,
1340
- blockHeight
1341
- });
1342
- return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
1470
+ return await this.processArcIngest(engine, req, res);
1343
1471
  }
1344
1472
  catch (error) {
1345
- console.error(chalk.red('Error in /arc-ingest:'), error);
1473
+ this.logger.error(chalk.red(`Error in /arc-ingest: error=${serializeErrorForLog(error)}`));
1346
1474
  return res.status(400).json({
1347
1475
  status: 'error',
1348
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1476
+ message: publicErrorMessage(error)
1349
1477
  });
1350
1478
  }
1351
1479
  })().catch(() => {
@@ -1373,7 +1501,7 @@ export default class OverlayExpress {
1373
1501
  console.error(chalk.red('Error in /requestSyncResponse:'), error);
1374
1502
  return res.status(400).json({
1375
1503
  status: 'error',
1376
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1504
+ message: publicErrorMessage(error)
1377
1505
  });
1378
1506
  }
1379
1507
  })().catch(() => {
@@ -1395,7 +1523,7 @@ export default class OverlayExpress {
1395
1523
  console.error(chalk.red('Error in /requestForeignGASPNode:'), error);
1396
1524
  return res.status(400).json({
1397
1525
  status: 'error',
1398
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1526
+ message: publicErrorMessage(error)
1399
1527
  });
1400
1528
  }
1401
1529
  })().catch(() => {
@@ -1414,7 +1542,7 @@ export default class OverlayExpress {
1414
1542
  const readBasmTopic = (req) => {
1415
1543
  const header = req.headers['x-bsv-topic'];
1416
1544
  if (typeof header !== 'string' || header.length === 0) {
1417
- throw new TypeError('Missing x-bsv-topic header');
1545
+ throw new PublicRequestError('Missing x-bsv-topic header');
1418
1546
  }
1419
1547
  return header;
1420
1548
  };
@@ -1436,7 +1564,7 @@ export default class OverlayExpress {
1436
1564
  console.error(chalk.red(`Error in ${path}:`), error);
1437
1565
  return res.status(400).json({
1438
1566
  status: 'error',
1439
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1567
+ message: publicErrorMessage(error)
1440
1568
  });
1441
1569
  }
1442
1570
  })().catch(() => {
@@ -1446,7 +1574,7 @@ export default class OverlayExpress {
1446
1574
  };
1447
1575
  const requireTxids = (value) => {
1448
1576
  if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1449
- throw new TypeError('txids must be an array of strings');
1577
+ throw new PublicRequestError('txids must be an array of strings');
1450
1578
  }
1451
1579
  return value;
1452
1580
  };
@@ -1479,6 +1607,7 @@ export default class OverlayExpress {
1479
1607
  if (this.serverWallet !== undefined) {
1480
1608
  const bsvAuth = createAuthMiddleware({
1481
1609
  wallet: this.serverWallet,
1610
+ sessionManager: this.authSessionManager,
1482
1611
  allowUnauthenticated: true
1483
1612
  });
1484
1613
  this.app.use(bsvAuth);
@@ -1505,7 +1634,7 @@ export default class OverlayExpress {
1505
1634
  const authHeader = req.headers.authorization;
1506
1635
  if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
1507
1636
  const token = authHeader.substring('Bearer '.length);
1508
- if (token === this.adminToken) {
1637
+ if (secretMatches(token, this.adminToken)) {
1509
1638
  next();
1510
1639
  return;
1511
1640
  }
@@ -1562,7 +1691,7 @@ export default class OverlayExpress {
1562
1691
  catch (error) {
1563
1692
  return res.status(400).json({
1564
1693
  status: 'error',
1565
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1694
+ message: publicErrorMessage(error)
1566
1695
  });
1567
1696
  }
1568
1697
  })().catch(() => {
@@ -1605,7 +1734,7 @@ export default class OverlayExpress {
1605
1734
  catch (error) {
1606
1735
  return res.status(400).json({
1607
1736
  status: 'error',
1608
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1737
+ message: publicErrorMessage(error)
1609
1738
  });
1610
1739
  }
1611
1740
  })().catch(() => {
@@ -1648,7 +1777,7 @@ export default class OverlayExpress {
1648
1777
  catch (error) {
1649
1778
  return res.status(400).json({
1650
1779
  status: 'error',
1651
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1780
+ message: publicErrorMessage(error)
1652
1781
  });
1653
1782
  }
1654
1783
  })().catch(() => {
@@ -1662,7 +1791,7 @@ export default class OverlayExpress {
1662
1791
  ;
1663
1792
  (async () => {
1664
1793
  try {
1665
- const { url } = req.body;
1794
+ const url = req.body?.url;
1666
1795
  if (typeof url !== 'string' || url.length === 0) {
1667
1796
  return res.status(400).json({ status: 'error', message: 'url is required' });
1668
1797
  }
@@ -1673,7 +1802,7 @@ export default class OverlayExpress {
1673
1802
  catch (error) {
1674
1803
  return res.status(400).json({
1675
1804
  status: 'error',
1676
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1805
+ message: publicErrorMessage(error)
1677
1806
  });
1678
1807
  }
1679
1808
  })().catch(() => {
@@ -1705,7 +1834,7 @@ export default class OverlayExpress {
1705
1834
  catch (error) {
1706
1835
  return res.status(400).json({
1707
1836
  status: 'error',
1708
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1837
+ message: publicErrorMessage(error)
1709
1838
  });
1710
1839
  }
1711
1840
  })().catch(() => {
@@ -1735,7 +1864,7 @@ export default class OverlayExpress {
1735
1864
  catch (error) {
1736
1865
  return res.status(400).json({
1737
1866
  status: 'error',
1738
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1867
+ message: publicErrorMessage(error)
1739
1868
  });
1740
1869
  }
1741
1870
  })().catch(() => {
@@ -1760,7 +1889,7 @@ export default class OverlayExpress {
1760
1889
  catch (error) {
1761
1890
  return res.status(400).json({
1762
1891
  status: 'error',
1763
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1892
+ message: publicErrorMessage(error)
1764
1893
  });
1765
1894
  }
1766
1895
  })().catch(() => {
@@ -1802,7 +1931,7 @@ export default class OverlayExpress {
1802
1931
  catch (error) {
1803
1932
  return res.status(400).json({
1804
1933
  status: 'error',
1805
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1934
+ message: publicErrorMessage(error)
1806
1935
  });
1807
1936
  }
1808
1937
  })().catch(() => {
@@ -1823,7 +1952,7 @@ export default class OverlayExpress {
1823
1952
  console.error(chalk.red('Error in /admin/syncAdvertisements:'), error);
1824
1953
  return res.status(400).json({
1825
1954
  status: 'error',
1826
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1955
+ message: publicErrorMessage(error)
1827
1956
  });
1828
1957
  }
1829
1958
  })().catch(() => {
@@ -1847,7 +1976,7 @@ export default class OverlayExpress {
1847
1976
  console.error(chalk.red('Error in /admin/startGASPSync:'), error);
1848
1977
  return res.status(400).json({
1849
1978
  status: 'error',
1850
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1979
+ message: publicErrorMessage(error)
1851
1980
  });
1852
1981
  }
1853
1982
  })().catch(() => {
@@ -1931,7 +2060,7 @@ export default class OverlayExpress {
1931
2060
  console.error(chalk.red('Error in /admin/evictOutpoint:'), error);
1932
2061
  return res.status(400).json({
1933
2062
  status: 'error',
1934
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2063
+ message: publicErrorMessage(error)
1935
2064
  });
1936
2065
  }
1937
2066
  })().catch(() => {
@@ -1956,7 +2085,7 @@ export default class OverlayExpress {
1956
2085
  console.error(chalk.red('Error in /admin/janitor:'), error);
1957
2086
  return res.status(400).json({
1958
2087
  status: 'error',
1959
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2088
+ message: publicErrorMessage(error)
1960
2089
  });
1961
2090
  }
1962
2091
  })().catch(() => {
@@ -1974,7 +2103,7 @@ export default class OverlayExpress {
1974
2103
  this.logger.log(chalk.green('Knex migrations run'), result);
1975
2104
  // 404 handler for all other routes
1976
2105
  this.app.use((req, res) => {
1977
- this.logger.log(chalk.red('404 Not Found:'), req.url);
2106
+ this.logger.log(chalk.red(`404 Not Found: url=${serializeLogValue(req.url)}`));
1978
2107
  res.status(404).json({
1979
2108
  status: 'error',
1980
2109
  code: 'ERR_ROUTE_NOT_FOUND',
@@ -1983,10 +2112,54 @@ export default class OverlayExpress {
1983
2112
  });
1984
2113
  await this.runStartupSync();
1985
2114
  // Start listening on the configured port
1986
- this.app.listen(this.port, () => {
2115
+ this.server = this.app.listen(this.port, () => {
1987
2116
  this.isListening = true;
1988
2117
  this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1989
2118
  });
2119
+ configureHttpServer(this.server, edgePolicy.environmentPrefix, edgePolicy.http);
2120
+ }
2121
+ /**
2122
+ * Stops new HTTP work, background synchronization, and database clients.
2123
+ *
2124
+ * The operation is idempotent so multiple signal handlers or embedding
2125
+ * runtimes can share shutdown ownership safely.
2126
+ */
2127
+ async close() {
2128
+ this.closePromise ??= this.closeResources();
2129
+ await this.closePromise;
2130
+ }
2131
+ async closeResources() {
2132
+ this.isListening = false;
2133
+ if (this.basmBlockPollTimer !== undefined) {
2134
+ clearInterval(this.basmBlockPollTimer);
2135
+ this.basmBlockPollTimer = undefined;
2136
+ }
2137
+ if (this.unprovenMaintenanceTimer !== undefined) {
2138
+ clearInterval(this.unprovenMaintenanceTimer);
2139
+ this.unprovenMaintenanceTimer = undefined;
2140
+ }
2141
+ this.reorgAdapter?.stop();
2142
+ this.reorgAdapter = undefined;
2143
+ const server = this.server;
2144
+ this.server = undefined;
2145
+ const closeServer = server === undefined
2146
+ ? Promise.resolve()
2147
+ : new Promise((resolve, reject) => {
2148
+ server.close(error => {
2149
+ if (error !== undefined)
2150
+ reject(error);
2151
+ else
2152
+ resolve();
2153
+ });
2154
+ });
2155
+ await closeServer;
2156
+ await Promise.all([
2157
+ this.knex?.destroy() ?? Promise.resolve(),
2158
+ this.mongoClient?.close() ?? Promise.resolve()
2159
+ ]);
2160
+ this.knex = undefined;
2161
+ this.mongoClient = undefined;
2162
+ this.mongoDb = undefined;
1990
2163
  }
1991
2164
  /**
1992
2165
  * Runs the post-listen startup work: advertiser init, advertisement sync,