@bsv/overlay-express 2.7.5 → 2.9.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 (220) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +2 -0
  3. package/PATENTS +12 -0
  4. package/README.md +179 -2
  5. package/THIRD_PARTY_NOTICES.md +1 -1
  6. package/dist/cjs/mod.d.ts +2 -1
  7. package/dist/cjs/mod.d.ts.map +1 -1
  8. package/dist/cjs/mod.js.map +1 -1
  9. package/dist/cjs/package.json +38 -10
  10. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -1
  11. package/dist/cjs/src/ArcadeProvider.js +6 -0
  12. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  13. package/dist/cjs/src/OutputLookupHTTPPolicy.d.ts +10 -0
  14. package/dist/cjs/src/OutputLookupHTTPPolicy.d.ts.map +1 -0
  15. package/dist/cjs/src/OutputLookupHTTPPolicy.js +125 -0
  16. package/dist/cjs/src/OutputLookupHTTPPolicy.js.map +1 -0
  17. package/dist/cjs/src/OutputLookupResponseGuard.d.ts +31 -0
  18. package/dist/cjs/src/OutputLookupResponseGuard.d.ts.map +1 -0
  19. package/dist/cjs/src/OutputLookupResponseGuard.js +91 -0
  20. package/dist/cjs/src/OutputLookupResponseGuard.js.map +1 -0
  21. package/dist/cjs/src/OutputLookupRoutes.d.ts +53 -0
  22. package/dist/cjs/src/OutputLookupRoutes.d.ts.map +1 -0
  23. package/dist/cjs/src/OutputLookupRoutes.js +274 -0
  24. package/dist/cjs/src/OutputLookupRoutes.js.map +1 -0
  25. package/dist/cjs/src/OverlayExpress.d.ts +82 -0
  26. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -1
  27. package/dist/cjs/src/OverlayExpress.js +294 -7
  28. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  29. package/dist/cjs/src/PrivateAcquisitionHTTPPolicy.d.ts +19 -0
  30. package/dist/cjs/src/PrivateAcquisitionHTTPPolicy.d.ts.map +1 -0
  31. package/dist/cjs/src/PrivateAcquisitionHTTPPolicy.js +90 -0
  32. package/dist/cjs/src/PrivateAcquisitionHTTPPolicy.js.map +1 -0
  33. package/dist/cjs/src/PrivateAcquisitionHTTPPorts.d.ts +43 -0
  34. package/dist/cjs/src/PrivateAcquisitionHTTPPorts.d.ts.map +1 -0
  35. package/dist/cjs/src/PrivateAcquisitionHTTPPorts.js +3 -0
  36. package/dist/cjs/src/PrivateAcquisitionHTTPPorts.js.map +1 -0
  37. package/dist/cjs/src/PrivateAcquisitionResponseGuard.d.ts +14 -0
  38. package/dist/cjs/src/PrivateAcquisitionResponseGuard.d.ts.map +1 -0
  39. package/dist/cjs/src/PrivateAcquisitionResponseGuard.js +108 -0
  40. package/dist/cjs/src/PrivateAcquisitionResponseGuard.js.map +1 -0
  41. package/dist/cjs/src/PrivateAcquisitionRoutes.d.ts +7 -0
  42. package/dist/cjs/src/PrivateAcquisitionRoutes.d.ts.map +1 -0
  43. package/dist/cjs/src/PrivateAcquisitionRoutes.js +269 -0
  44. package/dist/cjs/src/PrivateAcquisitionRoutes.js.map +1 -0
  45. package/dist/cjs/src/PrivateOverlayHost.d.ts +31 -0
  46. package/dist/cjs/src/PrivateOverlayHost.d.ts.map +1 -0
  47. package/dist/cjs/src/PrivateOverlayHost.js +64 -0
  48. package/dist/cjs/src/PrivateOverlayHost.js.map +1 -0
  49. package/dist/cjs/src/PrivatePublicationHTTPPolicy.d.ts +17 -0
  50. package/dist/cjs/src/PrivatePublicationHTTPPolicy.d.ts.map +1 -0
  51. package/dist/cjs/src/PrivatePublicationHTTPPolicy.js +38 -0
  52. package/dist/cjs/src/PrivatePublicationHTTPPolicy.js.map +1 -0
  53. package/dist/cjs/src/PrivatePublicationHTTPPorts.d.ts +40 -0
  54. package/dist/cjs/src/PrivatePublicationHTTPPorts.d.ts.map +1 -0
  55. package/dist/cjs/src/PrivatePublicationHTTPPorts.js +3 -0
  56. package/dist/cjs/src/PrivatePublicationHTTPPorts.js.map +1 -0
  57. package/dist/cjs/src/PrivatePublicationResponseGuard.d.ts +14 -0
  58. package/dist/cjs/src/PrivatePublicationResponseGuard.d.ts.map +1 -0
  59. package/dist/cjs/src/PrivatePublicationResponseGuard.js +82 -0
  60. package/dist/cjs/src/PrivatePublicationResponseGuard.js.map +1 -0
  61. package/dist/cjs/src/PrivatePublicationRoutes.d.ts +6 -0
  62. package/dist/cjs/src/PrivatePublicationRoutes.d.ts.map +1 -0
  63. package/dist/cjs/src/PrivatePublicationRoutes.js +249 -0
  64. package/dist/cjs/src/PrivatePublicationRoutes.js.map +1 -0
  65. package/dist/cjs/src/PrivatePurchaseHTTPPolicy.d.ts +19 -0
  66. package/dist/cjs/src/PrivatePurchaseHTTPPolicy.d.ts.map +1 -0
  67. package/dist/cjs/src/PrivatePurchaseHTTPPolicy.js +82 -0
  68. package/dist/cjs/src/PrivatePurchaseHTTPPolicy.js.map +1 -0
  69. package/dist/cjs/src/PrivatePurchaseHTTPPorts.d.ts +48 -0
  70. package/dist/cjs/src/PrivatePurchaseHTTPPorts.d.ts.map +1 -0
  71. package/dist/cjs/src/PrivatePurchaseHTTPPorts.js +3 -0
  72. package/dist/cjs/src/PrivatePurchaseHTTPPorts.js.map +1 -0
  73. package/dist/cjs/src/PrivatePurchaseResponseGuard.d.ts +15 -0
  74. package/dist/cjs/src/PrivatePurchaseResponseGuard.d.ts.map +1 -0
  75. package/dist/cjs/src/PrivatePurchaseResponseGuard.js +85 -0
  76. package/dist/cjs/src/PrivatePurchaseResponseGuard.js.map +1 -0
  77. package/dist/cjs/src/PrivatePurchaseRoutes.d.ts +7 -0
  78. package/dist/cjs/src/PrivatePurchaseRoutes.d.ts.map +1 -0
  79. package/dist/cjs/src/PrivatePurchaseRoutes.js +276 -0
  80. package/dist/cjs/src/PrivatePurchaseRoutes.js.map +1 -0
  81. package/dist/cjs/src/ProposalHTTPPolicy.d.ts +11 -0
  82. package/dist/cjs/src/ProposalHTTPPolicy.d.ts.map +1 -0
  83. package/dist/cjs/src/ProposalHTTPPolicy.js +38 -0
  84. package/dist/cjs/src/ProposalHTTPPolicy.js.map +1 -0
  85. package/dist/cjs/src/ProposalHTTPPorts.d.ts +59 -0
  86. package/dist/cjs/src/ProposalHTTPPorts.d.ts.map +1 -0
  87. package/dist/cjs/src/ProposalHTTPPorts.js +3 -0
  88. package/dist/cjs/src/ProposalHTTPPorts.js.map +1 -0
  89. package/dist/cjs/src/ProposalResponseGuard.d.ts +18 -0
  90. package/dist/cjs/src/ProposalResponseGuard.d.ts.map +1 -0
  91. package/dist/cjs/src/ProposalResponseGuard.js +61 -0
  92. package/dist/cjs/src/ProposalResponseGuard.js.map +1 -0
  93. package/dist/cjs/src/ProposalRoutes.d.ts +10 -0
  94. package/dist/cjs/src/ProposalRoutes.d.ts.map +1 -0
  95. package/dist/cjs/src/ProposalRoutes.js +239 -0
  96. package/dist/cjs/src/ProposalRoutes.js.map +1 -0
  97. package/dist/cjs/src/RootEvictionHTTPPolicy.d.ts +8 -0
  98. package/dist/cjs/src/RootEvictionHTTPPolicy.d.ts.map +1 -0
  99. package/dist/cjs/src/RootEvictionHTTPPolicy.js +77 -0
  100. package/dist/cjs/src/RootEvictionHTTPPolicy.js.map +1 -0
  101. package/dist/cjs/src/RootEvictionHTTPPorts.d.ts +73 -0
  102. package/dist/cjs/src/RootEvictionHTTPPorts.d.ts.map +1 -0
  103. package/dist/cjs/src/RootEvictionHTTPPorts.js +3 -0
  104. package/dist/cjs/src/RootEvictionHTTPPorts.js.map +1 -0
  105. package/dist/cjs/src/RootEvictionResponseGuard.d.ts +38 -0
  106. package/dist/cjs/src/RootEvictionResponseGuard.d.ts.map +1 -0
  107. package/dist/cjs/src/RootEvictionResponseGuard.js +83 -0
  108. package/dist/cjs/src/RootEvictionResponseGuard.js.map +1 -0
  109. package/dist/cjs/src/RootEvictionRoutes.d.ts +11 -0
  110. package/dist/cjs/src/RootEvictionRoutes.d.ts.map +1 -0
  111. package/dist/cjs/src/RootEvictionRoutes.js +198 -0
  112. package/dist/cjs/src/RootEvictionRoutes.js.map +1 -0
  113. package/dist/esm/mod.js.map +1 -1
  114. package/dist/esm/src/ArcadeProvider.js +6 -0
  115. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  116. package/dist/esm/src/OutputLookupHTTPPolicy.js +117 -0
  117. package/dist/esm/src/OutputLookupHTTPPolicy.js.map +1 -0
  118. package/dist/esm/src/OutputLookupResponseGuard.js +85 -0
  119. package/dist/esm/src/OutputLookupResponseGuard.js.map +1 -0
  120. package/dist/esm/src/OutputLookupRoutes.js +275 -0
  121. package/dist/esm/src/OutputLookupRoutes.js.map +1 -0
  122. package/dist/esm/src/OverlayExpress.js +270 -12
  123. package/dist/esm/src/OverlayExpress.js.map +1 -1
  124. package/dist/esm/src/PrivateAcquisitionHTTPPolicy.js +82 -0
  125. package/dist/esm/src/PrivateAcquisitionHTTPPolicy.js.map +1 -0
  126. package/dist/esm/src/PrivateAcquisitionHTTPPorts.js +2 -0
  127. package/dist/esm/src/PrivateAcquisitionHTTPPorts.js.map +1 -0
  128. package/dist/esm/src/PrivateAcquisitionResponseGuard.js +105 -0
  129. package/dist/esm/src/PrivateAcquisitionResponseGuard.js.map +1 -0
  130. package/dist/esm/src/PrivateAcquisitionRoutes.js +267 -0
  131. package/dist/esm/src/PrivateAcquisitionRoutes.js.map +1 -0
  132. package/dist/esm/src/PrivateOverlayHost.js +62 -0
  133. package/dist/esm/src/PrivateOverlayHost.js.map +1 -0
  134. package/dist/esm/src/PrivatePublicationHTTPPolicy.js +30 -0
  135. package/dist/esm/src/PrivatePublicationHTTPPolicy.js.map +1 -0
  136. package/dist/esm/src/PrivatePublicationHTTPPorts.js +2 -0
  137. package/dist/esm/src/PrivatePublicationHTTPPorts.js.map +1 -0
  138. package/dist/esm/src/PrivatePublicationResponseGuard.js +79 -0
  139. package/dist/esm/src/PrivatePublicationResponseGuard.js.map +1 -0
  140. package/dist/esm/src/PrivatePublicationRoutes.js +247 -0
  141. package/dist/esm/src/PrivatePublicationRoutes.js.map +1 -0
  142. package/dist/esm/src/PrivatePurchaseHTTPPolicy.js +74 -0
  143. package/dist/esm/src/PrivatePurchaseHTTPPolicy.js.map +1 -0
  144. package/dist/esm/src/PrivatePurchaseHTTPPorts.js +2 -0
  145. package/dist/esm/src/PrivatePurchaseHTTPPorts.js.map +1 -0
  146. package/dist/esm/src/PrivatePurchaseResponseGuard.js +82 -0
  147. package/dist/esm/src/PrivatePurchaseResponseGuard.js.map +1 -0
  148. package/dist/esm/src/PrivatePurchaseRoutes.js +275 -0
  149. package/dist/esm/src/PrivatePurchaseRoutes.js.map +1 -0
  150. package/dist/esm/src/ProposalHTTPPolicy.js +30 -0
  151. package/dist/esm/src/ProposalHTTPPolicy.js.map +1 -0
  152. package/dist/esm/src/ProposalHTTPPorts.js +2 -0
  153. package/dist/esm/src/ProposalHTTPPorts.js.map +1 -0
  154. package/dist/esm/src/ProposalResponseGuard.js +58 -0
  155. package/dist/esm/src/ProposalResponseGuard.js.map +1 -0
  156. package/dist/esm/src/ProposalRoutes.js +237 -0
  157. package/dist/esm/src/ProposalRoutes.js.map +1 -0
  158. package/dist/esm/src/RootEvictionHTTPPolicy.js +71 -0
  159. package/dist/esm/src/RootEvictionHTTPPolicy.js.map +1 -0
  160. package/dist/esm/src/RootEvictionHTTPPorts.js +2 -0
  161. package/dist/esm/src/RootEvictionHTTPPorts.js.map +1 -0
  162. package/dist/esm/src/RootEvictionResponseGuard.js +80 -0
  163. package/dist/esm/src/RootEvictionResponseGuard.js.map +1 -0
  164. package/dist/esm/src/RootEvictionRoutes.js +196 -0
  165. package/dist/esm/src/RootEvictionRoutes.js.map +1 -0
  166. package/dist/types/mod.d.ts +2 -1
  167. package/dist/types/mod.d.ts.map +1 -1
  168. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  169. package/dist/types/src/OutputLookupHTTPPolicy.d.ts +10 -0
  170. package/dist/types/src/OutputLookupHTTPPolicy.d.ts.map +1 -0
  171. package/dist/types/src/OutputLookupResponseGuard.d.ts +31 -0
  172. package/dist/types/src/OutputLookupResponseGuard.d.ts.map +1 -0
  173. package/dist/types/src/OutputLookupRoutes.d.ts +53 -0
  174. package/dist/types/src/OutputLookupRoutes.d.ts.map +1 -0
  175. package/dist/types/src/OverlayExpress.d.ts +82 -0
  176. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  177. package/dist/types/src/PrivateAcquisitionHTTPPolicy.d.ts +19 -0
  178. package/dist/types/src/PrivateAcquisitionHTTPPolicy.d.ts.map +1 -0
  179. package/dist/types/src/PrivateAcquisitionHTTPPorts.d.ts +43 -0
  180. package/dist/types/src/PrivateAcquisitionHTTPPorts.d.ts.map +1 -0
  181. package/dist/types/src/PrivateAcquisitionResponseGuard.d.ts +14 -0
  182. package/dist/types/src/PrivateAcquisitionResponseGuard.d.ts.map +1 -0
  183. package/dist/types/src/PrivateAcquisitionRoutes.d.ts +7 -0
  184. package/dist/types/src/PrivateAcquisitionRoutes.d.ts.map +1 -0
  185. package/dist/types/src/PrivateOverlayHost.d.ts +31 -0
  186. package/dist/types/src/PrivateOverlayHost.d.ts.map +1 -0
  187. package/dist/types/src/PrivatePublicationHTTPPolicy.d.ts +17 -0
  188. package/dist/types/src/PrivatePublicationHTTPPolicy.d.ts.map +1 -0
  189. package/dist/types/src/PrivatePublicationHTTPPorts.d.ts +40 -0
  190. package/dist/types/src/PrivatePublicationHTTPPorts.d.ts.map +1 -0
  191. package/dist/types/src/PrivatePublicationResponseGuard.d.ts +14 -0
  192. package/dist/types/src/PrivatePublicationResponseGuard.d.ts.map +1 -0
  193. package/dist/types/src/PrivatePublicationRoutes.d.ts +6 -0
  194. package/dist/types/src/PrivatePublicationRoutes.d.ts.map +1 -0
  195. package/dist/types/src/PrivatePurchaseHTTPPolicy.d.ts +19 -0
  196. package/dist/types/src/PrivatePurchaseHTTPPolicy.d.ts.map +1 -0
  197. package/dist/types/src/PrivatePurchaseHTTPPorts.d.ts +48 -0
  198. package/dist/types/src/PrivatePurchaseHTTPPorts.d.ts.map +1 -0
  199. package/dist/types/src/PrivatePurchaseResponseGuard.d.ts +15 -0
  200. package/dist/types/src/PrivatePurchaseResponseGuard.d.ts.map +1 -0
  201. package/dist/types/src/PrivatePurchaseRoutes.d.ts +7 -0
  202. package/dist/types/src/PrivatePurchaseRoutes.d.ts.map +1 -0
  203. package/dist/types/src/ProposalHTTPPolicy.d.ts +11 -0
  204. package/dist/types/src/ProposalHTTPPolicy.d.ts.map +1 -0
  205. package/dist/types/src/ProposalHTTPPorts.d.ts +59 -0
  206. package/dist/types/src/ProposalHTTPPorts.d.ts.map +1 -0
  207. package/dist/types/src/ProposalResponseGuard.d.ts +18 -0
  208. package/dist/types/src/ProposalResponseGuard.d.ts.map +1 -0
  209. package/dist/types/src/ProposalRoutes.d.ts +10 -0
  210. package/dist/types/src/ProposalRoutes.d.ts.map +1 -0
  211. package/dist/types/src/RootEvictionHTTPPolicy.d.ts +8 -0
  212. package/dist/types/src/RootEvictionHTTPPolicy.d.ts.map +1 -0
  213. package/dist/types/src/RootEvictionHTTPPorts.d.ts +73 -0
  214. package/dist/types/src/RootEvictionHTTPPorts.d.ts.map +1 -0
  215. package/dist/types/src/RootEvictionResponseGuard.d.ts +38 -0
  216. package/dist/types/src/RootEvictionResponseGuard.d.ts.map +1 -0
  217. package/dist/types/src/RootEvictionRoutes.d.ts +11 -0
  218. package/dist/types/src/RootEvictionRoutes.d.ts.map +1 -0
  219. package/package.json +113 -15
  220. package/LICENSE.txt +0 -58
@@ -1,3 +1,4 @@
1
+ import { createServer } from 'node:http';
1
2
  import { Reader, Writer } from '@bsv/sdk/primitives/utils';
2
3
  import express from 'express';
3
4
  import bodyParser from 'body-parser';
@@ -23,7 +24,7 @@ import { ArcadeProvider, isTerminalArcStatus } from './ArcadeProvider.js';
23
24
  import { ProviderChainBroadcaster } from './ProviderChainBroadcaster.js';
24
25
  import { ChaintracksProvider } from './ChaintracksProvider.js';
25
26
  import { assertBoundedString, assertHash, assertNonnegativeSafeInteger, fetchWithDeadline, isRecord, readBoundedJson, secureServiceFetch } from './OutboundSecurity.js';
26
- import { bodyParserErrorHandler, concurrencyLimit, configureHttpServer, corsPolicy, initialDoubleSlashCompatibility, profileValue, readBodyLimitBytes, readResourceLimit, readResourceProfile, responseSizeLimit, securityHeaders } from './security/edgePolicy.js';
27
+ import { bodyParserErrorHandler, concurrencyLimit, configureHttpServer, corsPolicy, readCorsOriginSetting, initialDoubleSlashCompatibility, profileValue, readBodyLimitBytes, readResourceLimit, readResourceProfile, responseSizeLimit, securityHeaders } from './security/edgePolicy.js';
27
28
  /**
28
29
  * In-memory migration source for Knex migrations.
29
30
  * Allows running migrations defined in code rather than files.
@@ -107,6 +108,13 @@ function assertSharedSecret(value, label) {
107
108
  throw new TypeError(`${label} must not contain control characters`);
108
109
  }
109
110
  }
111
+ function assertScriptVerifier(verifier) {
112
+ if (typeof verifier !== 'object' ||
113
+ verifier === null ||
114
+ typeof verifier.verifyScripts !== 'function') {
115
+ throw new TypeError('Engine scriptVerifier must provide verifyScripts()');
116
+ }
117
+ }
110
118
  function assertConfigurationObject(value, label) {
111
119
  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
112
120
  throw new TypeError(`${label} must be an object`);
@@ -302,6 +310,11 @@ export default class OverlayExpress {
302
310
  serverWallet;
303
311
  // Optional shared store for BSV mutual-auth sessions.
304
312
  authSessionManager;
313
+ outputLookup;
314
+ rootEviction;
315
+ privateOverlayOptions = {};
316
+ proposalIdentity;
317
+ proposalRoutes;
305
318
  // Server start time for uptime tracking
306
319
  startTime;
307
320
  // Health endpoint configuration
@@ -333,6 +346,10 @@ export default class OverlayExpress {
333
346
  contentSecurityPolicy: "default-src 'none'; script-src 'none'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: https:; connect-src 'self' https:; font-src 'self' https://cdn.jsdelivr.net; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
334
347
  }
335
348
  };
349
+ // Application routers mounted by start(), in registration order
350
+ registeredRouters = [];
351
+ // Set once start() begins wiring routes; later registrations could never be reached
352
+ startInvoked = false;
336
353
  /**
337
354
  * Constructs an instance of OverlayExpress.
338
355
  * @param name - The name of the service
@@ -591,6 +608,26 @@ export default class OverlayExpress {
591
608
  });
592
609
  this.logger.log(chalk.blue(`Registered health check ${definition.name}`));
593
610
  }
611
+ /**
612
+ * Registers an application router. Its factory runs during `start()`, after the BRC-103
613
+ * authentication middleware is mounted and before the admin routes and the 404 handler, so
614
+ * the router inherits CORS, body parsing, response limits, and `req.auth`.
615
+ *
616
+ * @param path - Mount path, beginning with "/"
617
+ * @param factory - Receives the engine and server wallet and returns the router
618
+ */
619
+ registerRouter(path, factory) {
620
+ if (this.startInvoked)
621
+ throw new Error('registerRouter must be called before start()');
622
+ if (typeof path !== 'string' || !path.startsWith('/')) {
623
+ throw new TypeError('Router path must begin with "/"');
624
+ }
625
+ if (typeof factory !== 'function')
626
+ throw new TypeError('Router factory must be a function');
627
+ this.registeredRouters.push({ path, factory });
628
+ this.logger.log(chalk.blue(`Registered router at ${path}`));
629
+ return this;
630
+ }
594
631
  /**
595
632
  * Configures the admin identity key for wallet-based admin detection.
596
633
  * When set, the frontend can compare the user's wallet identity key against this
@@ -614,6 +651,110 @@ export default class OverlayExpress {
614
651
  this.authSessionManager = sessionManager;
615
652
  this.logger.log(chalk.blue('BSV authentication session manager has been configured.'));
616
653
  }
654
+ /**
655
+ * Opt in to a durable BRC-193 companion at its signed concrete base path.
656
+ * This never upgrades an existing finite LookupService or changes /lookup.
657
+ * Configure before start; the host retains ownership of provider storage.
658
+ */
659
+ configureOutputLookup(options) {
660
+ if (this.isListening)
661
+ throw new Error('Configure the live lookup companion before start');
662
+ this.outputLookup = {
663
+ ...options,
664
+ chain: { ...options.chain },
665
+ allowedOrigins: [...options.allowedOrigins]
666
+ };
667
+ }
668
+ /**
669
+ * Explicit root coordination routes sharing this host's authentication wallet.
670
+ * Configure before start. The caller retains database and worker ownership;
671
+ * this does not publish capabilities or retrofit existing serving paths.
672
+ */
673
+ configureRootEviction(options) {
674
+ if (this.isListening)
675
+ throw new Error('Configure root coordination before start');
676
+ assertSingleLineString(options.identity, 'Root coordination identity', 66, false);
677
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
678
+ throw new TypeError('Root origins must be an array');
679
+ this.rootEviction = {
680
+ ...options,
681
+ ...(options.allowedOrigins === undefined
682
+ ? {}
683
+ : { allowedOrigins: [...options.allowedOrigins] })
684
+ };
685
+ }
686
+ /**
687
+ * Opt-in non-final proposal routes; storage, policy and admission remain caller-owned.
688
+ * The closure retains the journal's record type without adding SDK types to legacy
689
+ * host declarations. No proposal enters ordinary admission except explicit finalize.
690
+ */
691
+ configureProposals(options) {
692
+ if (this.isListening)
693
+ throw new Error('Configure proposals before start');
694
+ assertSingleLineString(options.identity, 'Proposal identity', 66, false);
695
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
696
+ throw new TypeError('Proposal origins must be an array');
697
+ const owned = {
698
+ ...options,
699
+ ...(options.allowedOrigins === undefined
700
+ ? {}
701
+ : { allowedOrigins: [...options.allowedOrigins] })
702
+ };
703
+ this.proposalIdentity = options.identity;
704
+ this.proposalRoutes = async (authenticate, handleHandshake, limits) => {
705
+ const { createProposalRouter } = await import('./ProposalRoutes.js');
706
+ const origins = owned.allowedOrigins ?? limits.origins;
707
+ return createProposalRouter({
708
+ ...owned,
709
+ authenticate,
710
+ handleHandshake,
711
+ allowedOrigins: origins === '*' ? undefined : origins,
712
+ maximumRequestBytes: Math.min(owned.maximumRequestBytes ?? 1048576, limits.request),
713
+ maximumResponseBytes: Math.min(owned.maximumResponseBytes ?? 4194304, limits.response)
714
+ });
715
+ };
716
+ }
717
+ /** Optional private acquisition; the application owns durable storage and workers. */
718
+ configurePrivateAcquisition(options) {
719
+ if (this.isListening)
720
+ throw new Error('Configure private acquisition before start');
721
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
722
+ throw new TypeError('Private overlay origins must be an array');
723
+ this.privateOverlayOptions.acquisition = {
724
+ ...options,
725
+ ...(options.allowedOrigins === undefined
726
+ ? {}
727
+ : { allowedOrigins: [...options.allowedOrigins] })
728
+ };
729
+ }
730
+ /** Optional private publication using the same authentication and native response gate. */
731
+ configurePrivatePublication(options) {
732
+ if (this.isListening)
733
+ throw new Error('Configure private publication before start');
734
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
735
+ throw new TypeError('Private overlay origins must be an array');
736
+ this.privateOverlayOptions.publication = {
737
+ ...options,
738
+ ...(options.allowedOrigins === undefined
739
+ ? {}
740
+ : { allowedOrigins: [...options.allowedOrigins] })
741
+ };
742
+ }
743
+ /** Optional selected-host covenant purchases. The application owns durable
744
+ * preparation, exact transaction validation, release and physical disclosure.
745
+ */
746
+ configurePrivatePurchase(options) {
747
+ if (this.isListening)
748
+ throw new Error('Configure private purchase before start');
749
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
750
+ throw new TypeError('Private overlay origins must be an array');
751
+ this.privateOverlayOptions.purchase = {
752
+ ...options,
753
+ ...(options.allowedOrigins === undefined
754
+ ? {}
755
+ : { allowedOrigins: [...options.allowedOrigins] })
756
+ };
757
+ }
617
758
  /**
618
759
  * Configures the logger to be used by the server.
619
760
  * @param logger - A logger object (e.g., console)
@@ -986,6 +1127,8 @@ export default class OverlayExpress {
986
1127
  if (params.maxLookupResults !== undefined) {
987
1128
  assertIntegerOption(params.maxLookupResults, 'Engine maxLookupResults', 1, Number.MAX_SAFE_INTEGER, true);
988
1129
  }
1130
+ if (params.scriptVerifier !== undefined)
1131
+ assertScriptVerifier(params.scriptVerifier);
989
1132
  if (params.reorgStreamUrl !== undefined) {
990
1133
  assertSingleLineString(params.reorgStreamUrl, 'Engine reorgStreamUrl', 2048, false);
991
1134
  secureServiceFetch(params.reorgStreamUrl, undefined, params.reorgStreamAllowPrivateHosts ?? false);
@@ -1008,6 +1151,27 @@ export default class OverlayExpress {
1008
1151
  };
1009
1152
  this.logger.log(chalk.blue('Advanced Engine configuration params have been updated.'));
1010
1153
  }
1154
+ /**
1155
+ * Configures a script backend for the engine's SPV verification of submitted
1156
+ * and GASP-synced transactions, such as `BdkVerifier` from `@bsv/verifast`.
1157
+ * Without one, the SDK's JavaScript interpreter verifies scripts.
1158
+ *
1159
+ * Preload the verifier before serving traffic. Its default adaptive mode
1160
+ * keeps using the JavaScript interpreter until the WASM module has loaded:
1161
+ *
1162
+ * const verifier = new BdkVerifier()
1163
+ * await verifier.preload()
1164
+ * server.configureScriptVerifier(verifier)
1165
+ */
1166
+ configureScriptVerifier(verifier) {
1167
+ assertScriptVerifier(verifier);
1168
+ this.engineConfig = { ...this.engineConfig, scriptVerifier: verifier };
1169
+ this.logger.log(chalk.blue('Script verifier has been configured.'));
1170
+ const { isReady } = verifier;
1171
+ if (typeof isReady === 'function' && !isReady.call(verifier)) {
1172
+ this.logger.warn(chalk.yellow('Script verifier is not ready; call preload() first or scripts keep using the JavaScript interpreter.'));
1173
+ }
1174
+ }
1011
1175
  /**
1012
1176
  * Configures the Overlay Engine itself.
1013
1177
  * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
@@ -1055,7 +1219,7 @@ export default class OverlayExpress {
1055
1219
  const broadcaster = this.buildBroadcaster();
1056
1220
  const advertiser = await this.buildAdvertiser();
1057
1221
  const EngineWithBASM = Engine;
1058
- this.engine = new EngineWithBASM(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.engineConfig.shipTrackers ?? this.defaultDiscoveryTrackers(), this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? true, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks, maxLookupResults);
1222
+ this.engine = new EngineWithBASM(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.engineConfig.shipTrackers ?? this.defaultDiscoveryTrackers(), this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? true, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks, maxLookupResults, this.engineConfig.scriptVerifier);
1059
1223
  this.initServerWallet();
1060
1224
  this.logger.log(chalk.green('Engine has been configured.'));
1061
1225
  }
@@ -1700,6 +1864,41 @@ export default class OverlayExpress {
1700
1864
  async start() {
1701
1865
  const engine = this.ensureEngine();
1702
1866
  const knex = this.ensureKnex();
1867
+ const rootEviction = this.rootEviction;
1868
+ const proposalRoutes = this.proposalRoutes;
1869
+ let privateOverlay;
1870
+ if (this.privateOverlayOptions.acquisition ||
1871
+ this.privateOverlayOptions.publication ||
1872
+ this.privateOverlayOptions.purchase) {
1873
+ const { PrivateOverlayHost } = await import('./PrivateOverlayHost.js');
1874
+ privateOverlay = new PrivateOverlayHost(this.privateOverlayOptions);
1875
+ }
1876
+ const authenticatedLookup = this.outputLookup?.authentication === 'brc103';
1877
+ let companionAuth;
1878
+ if (authenticatedLookup || rootEviction || proposalRoutes || privateOverlay) {
1879
+ if (!this.serverWallet) {
1880
+ if (authenticatedLookup)
1881
+ throw new Error('Authenticated live lookup requires a server wallet');
1882
+ if (rootEviction)
1883
+ throw new Error('Root coordination requires a server wallet');
1884
+ if (privateOverlay)
1885
+ throw new Error('Private overlays require a server wallet');
1886
+ throw new Error('Proposals require a server wallet');
1887
+ }
1888
+ const { publicKey } = await this.serverWallet.getPublicKey({ identityKey: true });
1889
+ if (authenticatedLookup && publicKey !== this.outputLookup.identity)
1890
+ throw new Error('Live lookup identity must match the server authentication wallet');
1891
+ if (rootEviction && publicKey !== rootEviction.identity)
1892
+ throw new Error('Root coordination identity must match the server authentication wallet');
1893
+ if (proposalRoutes && publicKey !== this.proposalIdentity)
1894
+ throw new Error('Proposal identity must match the server authentication wallet');
1895
+ privateOverlay?.requireIdentity(publicKey);
1896
+ companionAuth = createAuthMiddleware({
1897
+ wallet: this.serverWallet,
1898
+ sessionManager: this.authSessionManager,
1899
+ allowUnauthenticated: true
1900
+ });
1901
+ }
1703
1902
  const hasConfiguredArcProvider = (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1704
1903
  (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0);
1705
1904
  if (hasConfiguredArcProvider &&
@@ -1707,6 +1906,7 @@ export default class OverlayExpress {
1707
1906
  throw new Error('ARC/Arcade is configured without an ARC callback token; configureArcCallbackToken is required');
1708
1907
  }
1709
1908
  this.startTime = new Date();
1909
+ this.startInvoked = true;
1710
1910
  const edgePolicy = this.edgePolicyConfig;
1711
1911
  const resourceProfile = readResourceProfile(edgePolicy.environmentPrefix);
1712
1912
  const maxResponseBytes = readResourceLimit(edgePolicy.environmentPrefix, 'MAX_RESPONSE_BYTES', profileValue(resourceProfile, {
@@ -1785,14 +1985,60 @@ export default class OverlayExpress {
1785
1985
  ...edgePolicy.securityHeaders,
1786
1986
  environmentPrefix: edgePolicy.environmentPrefix
1787
1987
  }));
1988
+ const requestCapacity = concurrencyLimit(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests === 200
1989
+ ? profileValue(resourceProfile, { small: 8, standard: 24, highThroughput: 96 })
1990
+ : edgePolicy.maxConcurrentRequests);
1991
+ if (this.outputLookup || rootEviction || proposalRoutes || privateOverlay) {
1992
+ // All companions share host capacity, including long polls. Raw signed
1993
+ // requests stay before legacy parsers, transformations and payload logging.
1994
+ this.app.use(requestCapacity);
1995
+ const jsonBytes = readBodyLimitBytes(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes);
1996
+ if (this.outputLookup) {
1997
+ const { createOutputLookupRouter } = await import('./OutputLookupRoutes.js');
1998
+ this.app.use(createOutputLookupRouter({
1999
+ ...this.outputLookup,
2000
+ authenticate: companionAuth,
2001
+ maximumRequestBytes: Math.min(this.outputLookup.maximumRequestBytes ?? 1048576, jsonBytes),
2002
+ maximumResponseBytes: Math.min(this.outputLookup.maximumResponseBytes ?? 4194304, maxResponseBytes === -1 ? 4194304 : maxResponseBytes)
2003
+ }));
2004
+ }
2005
+ if (rootEviction) {
2006
+ const { createRootEvictionRouter } = await import('./RootEvictionRoutes.js');
2007
+ const originSetting = rootEviction.allowedOrigins ??
2008
+ edgePolicy.allowedOrigins ??
2009
+ readCorsOriginSetting(edgePolicy.environmentPrefix);
2010
+ this.app.use(createRootEvictionRouter({
2011
+ ...rootEviction,
2012
+ authenticate: companionAuth,
2013
+ handleHandshake: !authenticatedLookup,
2014
+ allowedOrigins: originSetting === '*' ? undefined : originSetting,
2015
+ maximumRequestBytes: Math.min(rootEviction.maximumRequestBytes ?? 1048576, jsonBytes),
2016
+ maximumResponseBytes: Math.min(rootEviction.maximumResponseBytes ?? 1048576, maxResponseBytes === -1 ? 1048576 : maxResponseBytes)
2017
+ }));
2018
+ }
2019
+ if (proposalRoutes) {
2020
+ this.app.use(await proposalRoutes(companionAuth, !authenticatedLookup && !rootEviction, {
2021
+ request: jsonBytes,
2022
+ response: maxResponseBytes === -1 ? 4194304 : maxResponseBytes,
2023
+ origins: edgePolicy.allowedOrigins ?? readCorsOriginSetting(edgePolicy.environmentPrefix)
2024
+ }));
2025
+ }
2026
+ if (privateOverlay) {
2027
+ for (const router of privateOverlay.routes(companionAuth, !authenticatedLookup && !rootEviction && !proposalRoutes, {
2028
+ request: jsonBytes,
2029
+ response: maxResponseBytes === -1 ? 4194304 : maxResponseBytes,
2030
+ origins: edgePolicy.allowedOrigins ?? readCorsOriginSetting(edgePolicy.environmentPrefix)
2031
+ }))
2032
+ this.app.use(router);
2033
+ }
2034
+ }
1788
2035
  this.app.use(corsPolicy({
1789
2036
  environmentPrefix: edgePolicy.environmentPrefix,
1790
2037
  allowedOrigins: edgePolicy.allowedOrigins,
1791
2038
  methods: ['GET', 'POST', 'OPTIONS']
1792
2039
  }));
1793
- this.app.use(concurrencyLimit(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests === 200
1794
- ? profileValue(resourceProfile, { small: 8, standard: 24, highThroughput: 96 })
1795
- : edgePolicy.maxConcurrentRequests));
2040
+ if (!this.outputLookup && !rootEviction && !proposalRoutes && !privateOverlay)
2041
+ this.app.use(requestCapacity);
1796
2042
  this.app.use(bodyParser.json({
1797
2043
  limit: readBodyLimitBytes(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes),
1798
2044
  type: 'application/json'
@@ -2294,14 +2540,22 @@ export default class OverlayExpress {
2294
2540
  * are present, allowing Bearer token fallback.
2295
2541
  */
2296
2542
  if (this.serverWallet !== undefined) {
2297
- const bsvAuth = createAuthMiddleware({
2298
- wallet: this.serverWallet,
2299
- sessionManager: this.authSessionManager,
2300
- allowUnauthenticated: true
2301
- });
2543
+ const bsvAuth = companionAuth ??
2544
+ createAuthMiddleware({
2545
+ wallet: this.serverWallet,
2546
+ sessionManager: this.authSessionManager,
2547
+ allowUnauthenticated: true
2548
+ });
2302
2549
  this.app.use(bsvAuth);
2303
2550
  this.logger.log(chalk.blue('BSV mutual authentication middleware enabled.'));
2304
2551
  }
2552
+ // Routers mount strictly in registration order: each factory starts after the previous one
2553
+ // was mounted. reduce invokes every callback up front, so nothing may run before the await.
2554
+ await this.registeredRouters.reduce(async (previous, { path, factory }) => {
2555
+ await previous;
2556
+ this.app.use(path, await factory({ engine, wallet: this.serverWallet }));
2557
+ this.logger.log(chalk.blue(`Mounted registered router at ${path}`));
2558
+ }, Promise.resolve());
2305
2559
  /**
2306
2560
  * Middleware for checking admin authentication.
2307
2561
  * Supports two authentication methods:
@@ -2851,10 +3105,14 @@ export default class OverlayExpress {
2851
3105
  });
2852
3106
  await this.runStartupSync();
2853
3107
  // Start listening on the configured port
2854
- this.server = this.app.listen(this.port, () => {
3108
+ const listening = () => {
2855
3109
  this.isListening = true;
2856
3110
  this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
2857
- });
3111
+ };
3112
+ this.server =
3113
+ privateOverlay?.maximumHeaderBytes === undefined
3114
+ ? this.app.listen(this.port, listening)
3115
+ : createServer({ maxHeaderSize: privateOverlay.maximumHeaderBytes }, this.app).listen(this.port, listening);
2858
3116
  configureHttpServer(this.server, edgePolicy.environmentPrefix, edgePolicy.http);
2859
3117
  }
2860
3118
  /**