@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,8 +1,42 @@
1
1
  "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
2
35
  var __importDefault = (this && this.__importDefault) || function (mod) {
3
36
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
37
  };
5
38
  Object.defineProperty(exports, "__esModule", { value: true });
39
+ const node_http_1 = require("node:http");
6
40
  const utils_1 = require("@bsv/sdk/primitives/utils");
7
41
  const express_1 = __importDefault(require("express"));
8
42
  const body_parser_1 = __importDefault(require("body-parser"));
@@ -112,6 +146,13 @@ function assertSharedSecret(value, label) {
112
146
  throw new TypeError(`${label} must not contain control characters`);
113
147
  }
114
148
  }
149
+ function assertScriptVerifier(verifier) {
150
+ if (typeof verifier !== 'object' ||
151
+ verifier === null ||
152
+ typeof verifier.verifyScripts !== 'function') {
153
+ throw new TypeError('Engine scriptVerifier must provide verifyScripts()');
154
+ }
155
+ }
115
156
  function assertConfigurationObject(value, label) {
116
157
  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
117
158
  throw new TypeError(`${label} must be an object`);
@@ -285,6 +326,7 @@ class OverlayExpress {
285
326
  batchSize: undefined,
286
327
  maxReportResults: undefined
287
328
  };
329
+ this.privateOverlayOptions = {};
288
330
  // Health endpoint configuration
289
331
  this.healthConfig = {
290
332
  includeDetails: false,
@@ -310,6 +352,10 @@ class OverlayExpress {
310
352
  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'"
311
353
  }
312
354
  };
355
+ // Application routers mounted by start(), in registration order
356
+ this.registeredRouters = [];
357
+ // Set once start() begins wiring routes; later registrations could never be reached
358
+ this.startInvoked = false;
313
359
  if (adminToken !== undefined)
314
360
  assertSharedSecret(adminToken, 'The administrative Bearer token');
315
361
  this.advertisableFQDN = normalizeAdvertisableFQDN(advertisableFQDN);
@@ -558,6 +604,26 @@ class OverlayExpress {
558
604
  });
559
605
  this.logger.log(chalk_1.default.blue(`Registered health check ${definition.name}`));
560
606
  }
607
+ /**
608
+ * Registers an application router. Its factory runs during `start()`, after the BRC-103
609
+ * authentication middleware is mounted and before the admin routes and the 404 handler, so
610
+ * the router inherits CORS, body parsing, response limits, and `req.auth`.
611
+ *
612
+ * @param path - Mount path, beginning with "/"
613
+ * @param factory - Receives the engine and server wallet and returns the router
614
+ */
615
+ registerRouter(path, factory) {
616
+ if (this.startInvoked)
617
+ throw new Error('registerRouter must be called before start()');
618
+ if (typeof path !== 'string' || !path.startsWith('/')) {
619
+ throw new TypeError('Router path must begin with "/"');
620
+ }
621
+ if (typeof factory !== 'function')
622
+ throw new TypeError('Router factory must be a function');
623
+ this.registeredRouters.push({ path, factory });
624
+ this.logger.log(chalk_1.default.blue(`Registered router at ${path}`));
625
+ return this;
626
+ }
561
627
  /**
562
628
  * Configures the admin identity key for wallet-based admin detection.
563
629
  * When set, the frontend can compare the user's wallet identity key against this
@@ -581,6 +647,111 @@ class OverlayExpress {
581
647
  this.authSessionManager = sessionManager;
582
648
  this.logger.log(chalk_1.default.blue('BSV authentication session manager has been configured.'));
583
649
  }
650
+ /**
651
+ * Opt in to a durable BRC-193 companion at its signed concrete base path.
652
+ * This never upgrades an existing finite LookupService or changes /lookup.
653
+ * Configure before start; the host retains ownership of provider storage.
654
+ */
655
+ configureOutputLookup(options) {
656
+ if (this.isListening)
657
+ throw new Error('Configure the live lookup companion before start');
658
+ this.outputLookup = {
659
+ ...options,
660
+ chain: { ...options.chain },
661
+ allowedOrigins: [...options.allowedOrigins]
662
+ };
663
+ }
664
+ /**
665
+ * Explicit root coordination routes sharing this host's authentication wallet.
666
+ * Configure before start. The caller retains database and worker ownership;
667
+ * this does not publish capabilities or retrofit existing serving paths.
668
+ */
669
+ configureRootEviction(options) {
670
+ if (this.isListening)
671
+ throw new Error('Configure root coordination before start');
672
+ assertSingleLineString(options.identity, 'Root coordination identity', 66, false);
673
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
674
+ throw new TypeError('Root origins must be an array');
675
+ this.rootEviction = {
676
+ ...options,
677
+ ...(options.allowedOrigins === undefined
678
+ ? {}
679
+ : { allowedOrigins: [...options.allowedOrigins] })
680
+ };
681
+ }
682
+ /**
683
+ * Opt-in non-final proposal routes; storage, policy and admission remain caller-owned.
684
+ * The closure retains the journal's record type without adding SDK types to legacy
685
+ * host declarations. No proposal enters ordinary admission except explicit finalize.
686
+ */
687
+ configureProposals(options) {
688
+ if (this.isListening)
689
+ throw new Error('Configure proposals before start');
690
+ assertSingleLineString(options.identity, 'Proposal identity', 66, false);
691
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
692
+ throw new TypeError('Proposal origins must be an array');
693
+ const owned = {
694
+ ...options,
695
+ ...(options.allowedOrigins === undefined
696
+ ? {}
697
+ : { allowedOrigins: [...options.allowedOrigins] })
698
+ };
699
+ this.proposalIdentity = options.identity;
700
+ this.proposalRoutes = async (authenticate, handleHandshake, limits) => {
701
+ var _a, _b, _c;
702
+ const { createProposalRouter } = await Promise.resolve().then(() => __importStar(require('./ProposalRoutes.js')));
703
+ const origins = (_a = owned.allowedOrigins) !== null && _a !== void 0 ? _a : limits.origins;
704
+ return createProposalRouter({
705
+ ...owned,
706
+ authenticate,
707
+ handleHandshake,
708
+ allowedOrigins: origins === '*' ? undefined : origins,
709
+ maximumRequestBytes: Math.min((_b = owned.maximumRequestBytes) !== null && _b !== void 0 ? _b : 1048576, limits.request),
710
+ maximumResponseBytes: Math.min((_c = owned.maximumResponseBytes) !== null && _c !== void 0 ? _c : 4194304, limits.response)
711
+ });
712
+ };
713
+ }
714
+ /** Optional private acquisition; the application owns durable storage and workers. */
715
+ configurePrivateAcquisition(options) {
716
+ if (this.isListening)
717
+ throw new Error('Configure private acquisition before start');
718
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
719
+ throw new TypeError('Private overlay origins must be an array');
720
+ this.privateOverlayOptions.acquisition = {
721
+ ...options,
722
+ ...(options.allowedOrigins === undefined
723
+ ? {}
724
+ : { allowedOrigins: [...options.allowedOrigins] })
725
+ };
726
+ }
727
+ /** Optional private publication using the same authentication and native response gate. */
728
+ configurePrivatePublication(options) {
729
+ if (this.isListening)
730
+ throw new Error('Configure private publication before start');
731
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
732
+ throw new TypeError('Private overlay origins must be an array');
733
+ this.privateOverlayOptions.publication = {
734
+ ...options,
735
+ ...(options.allowedOrigins === undefined
736
+ ? {}
737
+ : { allowedOrigins: [...options.allowedOrigins] })
738
+ };
739
+ }
740
+ /** Optional selected-host covenant purchases. The application owns durable
741
+ * preparation, exact transaction validation, release and physical disclosure.
742
+ */
743
+ configurePrivatePurchase(options) {
744
+ if (this.isListening)
745
+ throw new Error('Configure private purchase before start');
746
+ if (options.allowedOrigins !== undefined && !Array.isArray(options.allowedOrigins))
747
+ throw new TypeError('Private overlay origins must be an array');
748
+ this.privateOverlayOptions.purchase = {
749
+ ...options,
750
+ ...(options.allowedOrigins === undefined
751
+ ? {}
752
+ : { allowedOrigins: [...options.allowedOrigins] })
753
+ };
754
+ }
584
755
  /**
585
756
  * Configures the logger to be used by the server.
586
757
  * @param logger - A logger object (e.g., console)
@@ -956,6 +1127,8 @@ class OverlayExpress {
956
1127
  if (params.maxLookupResults !== undefined) {
957
1128
  assertIntegerOption(params.maxLookupResults, 'Engine maxLookupResults', 1, Number.MAX_SAFE_INTEGER, true);
958
1129
  }
1130
+ if (params.scriptVerifier !== undefined)
1131
+ assertScriptVerifier(params.scriptVerifier);
959
1132
  if (params.reorgStreamUrl !== undefined) {
960
1133
  assertSingleLineString(params.reorgStreamUrl, 'Engine reorgStreamUrl', 2048, false);
961
1134
  (0, OutboundSecurity_js_1.secureServiceFetch)(params.reorgStreamUrl, undefined, (_a = params.reorgStreamAllowPrivateHosts) !== null && _a !== void 0 ? _a : false);
@@ -978,6 +1151,27 @@ class OverlayExpress {
978
1151
  };
979
1152
  this.logger.log(chalk_1.default.blue('Advanced Engine configuration params have been updated.'));
980
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_1.default.blue('Script verifier has been configured.'));
1170
+ const { isReady } = verifier;
1171
+ if (typeof isReady === 'function' && !isReady.call(verifier)) {
1172
+ this.logger.warn(chalk_1.default.yellow('Script verifier is not ready; call preload() first or scripts keep using the JavaScript interpreter.'));
1173
+ }
1174
+ }
981
1175
  /**
982
1176
  * Configures the Overlay Engine itself.
983
1177
  * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
@@ -1025,7 +1219,7 @@ class OverlayExpress {
1025
1219
  const broadcaster = this.buildBroadcaster();
1026
1220
  const advertiser = await this.buildAdvertiser();
1027
1221
  const EngineWithBASM = overlay_1.Engine;
1028
- this.engine = new EngineWithBASM(this.managers, this.services, storage, (_b = this.engineConfig.chainTracker) !== null && _b !== void 0 ? _b : this.chainTracker, `https://${this.advertisableFQDN}`, (_c = this.engineConfig.shipTrackers) !== null && _c !== void 0 ? _c : this.defaultDiscoveryTrackers(), 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);
1222
+ this.engine = new EngineWithBASM(this.managers, this.services, storage, (_b = this.engineConfig.chainTracker) !== null && _b !== void 0 ? _b : this.chainTracker, `https://${this.advertisableFQDN}`, (_c = this.engineConfig.shipTrackers) !== null && _c !== void 0 ? _c : this.defaultDiscoveryTrackers(), 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, this.engineConfig.scriptVerifier);
1029
1223
  this.initServerWallet();
1030
1224
  this.logger.log(chalk_1.default.green('Engine has been configured.'));
1031
1225
  }
@@ -1678,8 +1872,45 @@ class OverlayExpress {
1678
1872
  * Sets up routes and begins listening on the configured port.
1679
1873
  */
1680
1874
  async start() {
1875
+ var _a;
1876
+ var _b, _c, _d, _e, _f, _g, _h, _j;
1681
1877
  const engine = this.ensureEngine();
1682
1878
  const knex = this.ensureKnex();
1879
+ const rootEviction = this.rootEviction;
1880
+ const proposalRoutes = this.proposalRoutes;
1881
+ let privateOverlay;
1882
+ if (this.privateOverlayOptions.acquisition ||
1883
+ this.privateOverlayOptions.publication ||
1884
+ this.privateOverlayOptions.purchase) {
1885
+ const { PrivateOverlayHost } = await Promise.resolve().then(() => __importStar(require('./PrivateOverlayHost.js')));
1886
+ privateOverlay = new PrivateOverlayHost(this.privateOverlayOptions);
1887
+ }
1888
+ const authenticatedLookup = ((_a = this.outputLookup) === null || _a === void 0 ? void 0 : _a.authentication) === 'brc103';
1889
+ let companionAuth;
1890
+ if (authenticatedLookup || rootEviction || proposalRoutes || privateOverlay) {
1891
+ if (!this.serverWallet) {
1892
+ if (authenticatedLookup)
1893
+ throw new Error('Authenticated live lookup requires a server wallet');
1894
+ if (rootEviction)
1895
+ throw new Error('Root coordination requires a server wallet');
1896
+ if (privateOverlay)
1897
+ throw new Error('Private overlays require a server wallet');
1898
+ throw new Error('Proposals require a server wallet');
1899
+ }
1900
+ const { publicKey } = await this.serverWallet.getPublicKey({ identityKey: true });
1901
+ if (authenticatedLookup && publicKey !== this.outputLookup.identity)
1902
+ throw new Error('Live lookup identity must match the server authentication wallet');
1903
+ if (rootEviction && publicKey !== rootEviction.identity)
1904
+ throw new Error('Root coordination identity must match the server authentication wallet');
1905
+ if (proposalRoutes && publicKey !== this.proposalIdentity)
1906
+ throw new Error('Proposal identity must match the server authentication wallet');
1907
+ privateOverlay === null || privateOverlay === void 0 ? void 0 : privateOverlay.requireIdentity(publicKey);
1908
+ companionAuth = (0, auth_express_middleware_1.createAuthMiddleware)({
1909
+ wallet: this.serverWallet,
1910
+ sessionManager: this.authSessionManager,
1911
+ allowUnauthenticated: true
1912
+ });
1913
+ }
1683
1914
  const hasConfiguredArcProvider = (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1684
1915
  (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0);
1685
1916
  if (hasConfiguredArcProvider &&
@@ -1687,6 +1918,7 @@ class OverlayExpress {
1687
1918
  throw new Error('ARC/Arcade is configured without an ARC callback token; configureArcCallbackToken is required');
1688
1919
  }
1689
1920
  this.startTime = new Date();
1921
+ this.startInvoked = true;
1690
1922
  const edgePolicy = this.edgePolicyConfig;
1691
1923
  const resourceProfile = (0, edgePolicy_js_1.readResourceProfile)(edgePolicy.environmentPrefix);
1692
1924
  const maxResponseBytes = (0, edgePolicy_js_1.readResourceLimit)(edgePolicy.environmentPrefix, 'MAX_RESPONSE_BYTES', (0, edgePolicy_js_1.profileValue)(resourceProfile, {
@@ -1766,14 +1998,58 @@ class OverlayExpress {
1766
1998
  ...edgePolicy.securityHeaders,
1767
1999
  environmentPrefix: edgePolicy.environmentPrefix
1768
2000
  }));
2001
+ const requestCapacity = (0, edgePolicy_js_1.concurrencyLimit)(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests === 200
2002
+ ? (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 8, standard: 24, highThroughput: 96 })
2003
+ : edgePolicy.maxConcurrentRequests);
2004
+ if (this.outputLookup || rootEviction || proposalRoutes || privateOverlay) {
2005
+ // All companions share host capacity, including long polls. Raw signed
2006
+ // requests stay before legacy parsers, transformations and payload logging.
2007
+ this.app.use(requestCapacity);
2008
+ const jsonBytes = (0, edgePolicy_js_1.readBodyLimitBytes)(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes);
2009
+ if (this.outputLookup) {
2010
+ const { createOutputLookupRouter } = await Promise.resolve().then(() => __importStar(require('./OutputLookupRoutes.js')));
2011
+ this.app.use(createOutputLookupRouter({
2012
+ ...this.outputLookup,
2013
+ authenticate: companionAuth,
2014
+ maximumRequestBytes: Math.min((_b = this.outputLookup.maximumRequestBytes) !== null && _b !== void 0 ? _b : 1048576, jsonBytes),
2015
+ maximumResponseBytes: Math.min((_c = this.outputLookup.maximumResponseBytes) !== null && _c !== void 0 ? _c : 4194304, maxResponseBytes === -1 ? 4194304 : maxResponseBytes)
2016
+ }));
2017
+ }
2018
+ if (rootEviction) {
2019
+ const { createRootEvictionRouter } = await Promise.resolve().then(() => __importStar(require('./RootEvictionRoutes.js')));
2020
+ const originSetting = (_e = (_d = rootEviction.allowedOrigins) !== null && _d !== void 0 ? _d : edgePolicy.allowedOrigins) !== null && _e !== void 0 ? _e : (0, edgePolicy_js_1.readCorsOriginSetting)(edgePolicy.environmentPrefix);
2021
+ this.app.use(createRootEvictionRouter({
2022
+ ...rootEviction,
2023
+ authenticate: companionAuth,
2024
+ handleHandshake: !authenticatedLookup,
2025
+ allowedOrigins: originSetting === '*' ? undefined : originSetting,
2026
+ maximumRequestBytes: Math.min((_f = rootEviction.maximumRequestBytes) !== null && _f !== void 0 ? _f : 1048576, jsonBytes),
2027
+ maximumResponseBytes: Math.min((_g = rootEviction.maximumResponseBytes) !== null && _g !== void 0 ? _g : 1048576, maxResponseBytes === -1 ? 1048576 : maxResponseBytes)
2028
+ }));
2029
+ }
2030
+ if (proposalRoutes) {
2031
+ this.app.use(await proposalRoutes(companionAuth, !authenticatedLookup && !rootEviction, {
2032
+ request: jsonBytes,
2033
+ response: maxResponseBytes === -1 ? 4194304 : maxResponseBytes,
2034
+ origins: (_h = edgePolicy.allowedOrigins) !== null && _h !== void 0 ? _h : (0, edgePolicy_js_1.readCorsOriginSetting)(edgePolicy.environmentPrefix)
2035
+ }));
2036
+ }
2037
+ if (privateOverlay) {
2038
+ for (const router of privateOverlay.routes(companionAuth, !authenticatedLookup && !rootEviction && !proposalRoutes, {
2039
+ request: jsonBytes,
2040
+ response: maxResponseBytes === -1 ? 4194304 : maxResponseBytes,
2041
+ origins: (_j = edgePolicy.allowedOrigins) !== null && _j !== void 0 ? _j : (0, edgePolicy_js_1.readCorsOriginSetting)(edgePolicy.environmentPrefix)
2042
+ }))
2043
+ this.app.use(router);
2044
+ }
2045
+ }
1769
2046
  this.app.use((0, edgePolicy_js_1.corsPolicy)({
1770
2047
  environmentPrefix: edgePolicy.environmentPrefix,
1771
2048
  allowedOrigins: edgePolicy.allowedOrigins,
1772
2049
  methods: ['GET', 'POST', 'OPTIONS']
1773
2050
  }));
1774
- this.app.use((0, edgePolicy_js_1.concurrencyLimit)(edgePolicy.environmentPrefix, edgePolicy.maxConcurrentRequests === 200
1775
- ? (0, edgePolicy_js_1.profileValue)(resourceProfile, { small: 8, standard: 24, highThroughput: 96 })
1776
- : edgePolicy.maxConcurrentRequests));
2051
+ if (!this.outputLookup && !rootEviction && !proposalRoutes && !privateOverlay)
2052
+ this.app.use(requestCapacity);
1777
2053
  this.app.use(body_parser_1.default.json({
1778
2054
  limit: (0, edgePolicy_js_1.readBodyLimitBytes)(`${edgePolicy.environmentPrefix}_JSON`, edgePolicy.jsonBodyLimitBytes),
1779
2055
  type: 'application/json'
@@ -2275,7 +2551,7 @@ class OverlayExpress {
2275
2551
  * are present, allowing Bearer token fallback.
2276
2552
  */
2277
2553
  if (this.serverWallet !== undefined) {
2278
- const bsvAuth = (0, auth_express_middleware_1.createAuthMiddleware)({
2554
+ const bsvAuth = companionAuth !== null && companionAuth !== void 0 ? companionAuth : (0, auth_express_middleware_1.createAuthMiddleware)({
2279
2555
  wallet: this.serverWallet,
2280
2556
  sessionManager: this.authSessionManager,
2281
2557
  allowUnauthenticated: true
@@ -2283,6 +2559,13 @@ class OverlayExpress {
2283
2559
  this.app.use(bsvAuth);
2284
2560
  this.logger.log(chalk_1.default.blue('BSV mutual authentication middleware enabled.'));
2285
2561
  }
2562
+ // Routers mount strictly in registration order: each factory starts after the previous one
2563
+ // was mounted. reduce invokes every callback up front, so nothing may run before the await.
2564
+ await this.registeredRouters.reduce(async (previous, { path, factory }) => {
2565
+ await previous;
2566
+ this.app.use(path, await factory({ engine, wallet: this.serverWallet }));
2567
+ this.logger.log(chalk_1.default.blue(`Mounted registered router at ${path}`));
2568
+ }, Promise.resolve());
2286
2569
  /**
2287
2570
  * Middleware for checking admin authentication.
2288
2571
  * Supports two authentication methods:
@@ -2840,10 +3123,14 @@ class OverlayExpress {
2840
3123
  });
2841
3124
  await this.runStartupSync();
2842
3125
  // Start listening on the configured port
2843
- this.server = this.app.listen(this.port, () => {
3126
+ const listening = () => {
2844
3127
  this.isListening = true;
2845
3128
  this.logger.log(chalk_1.default.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
2846
- });
3129
+ };
3130
+ this.server =
3131
+ (privateOverlay === null || privateOverlay === void 0 ? void 0 : privateOverlay.maximumHeaderBytes) === undefined
3132
+ ? this.app.listen(this.port, listening)
3133
+ : (0, node_http_1.createServer)({ maxHeaderSize: privateOverlay.maximumHeaderBytes }, this.app).listen(this.port, listening);
2847
3134
  (0, edgePolicy_js_1.configureHttpServer)(this.server, edgePolicy.environmentPrefix, edgePolicy.http);
2848
3135
  }
2849
3136
  /**