@bsv/overlay-express 2.2.1 → 2.3.1

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 (53) hide show
  1. package/README.md +33 -0
  2. package/dist/cjs/mod.js +10 -1
  3. package/dist/cjs/mod.js.map +1 -1
  4. package/dist/cjs/package.json +12 -11
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  6. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  8. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  9. package/dist/cjs/src/OverlayExpress.js +375 -96
  10. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  11. package/dist/cjs/src/OverlayMonitor.js +464 -0
  12. package/dist/cjs/src/OverlayMonitor.js.map +1 -0
  13. package/dist/cjs/src/ReorgStream.js +193 -0
  14. package/dist/cjs/src/ReorgStream.js.map +1 -0
  15. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  16. package/dist/esm/mod.js +3 -0
  17. package/dist/esm/mod.js.map +1 -1
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  19. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  20. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  21. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  22. package/dist/esm/src/OverlayExpress.js +375 -94
  23. package/dist/esm/src/OverlayExpress.js.map +1 -1
  24. package/dist/esm/src/OverlayMonitor.js +458 -0
  25. package/dist/esm/src/OverlayMonitor.js.map +1 -0
  26. package/dist/esm/src/ReorgStream.js +190 -0
  27. package/dist/esm/src/ReorgStream.js.map +1 -0
  28. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  29. package/dist/types/mod.d.ts +4 -1
  30. package/dist/types/mod.d.ts.map +1 -1
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  32. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  34. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  35. package/dist/types/src/OverlayExpress.d.ts +82 -4
  36. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  37. package/dist/types/src/OverlayMonitor.d.ts +169 -0
  38. package/dist/types/src/OverlayMonitor.d.ts.map +1 -0
  39. package/dist/types/src/ReorgStream.d.ts +74 -0
  40. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  41. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  42. package/mod.ts +20 -1
  43. package/package.json +12 -11
  44. package/src/BanAwareDiscoveryStorage.ts +91 -0
  45. package/src/BanAwareTopicManager.ts +87 -0
  46. package/src/OverlayExpress.ts +461 -102
  47. package/src/OverlayMonitor.ts +657 -0
  48. package/src/ReorgStream.ts +221 -0
  49. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  50. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  51. package/src/__tests__/OverlayExpress.test.ts +86 -1
  52. package/src/__tests__/OverlayMonitor.test.ts +181 -0
  53. package/src/__tests__/ReorgStream.test.ts +66 -0
@@ -0,0 +1,221 @@
1
+ /**
2
+ * Consumes the go-chaintracks (Arcade) reorg SSE stream (`GET /v2/reorg/stream`)
3
+ * and normalizes each `ReorgEvent` into the overlay engine's `handleReorg` input.
4
+ *
5
+ * The stream emits `data: <JSON>\n\n` frames (no `event:`/`id:` lines) with
6
+ * `: keepalive` comment frames in between. Because there are no event ids, a
7
+ * reconnect cannot replay events missed while disconnected — so every (re)connect
8
+ * triggers an `onConnect` catch-up (the engine's revalidation sweep).
9
+ */
10
+
11
+ /** Input shape accepted by `Engine.handleReorg`. */
12
+ export interface ReorgHandlerInput {
13
+ orphanedBlockHashes: string[]
14
+ rebuildFromHeight: number
15
+ newTipHeight: number
16
+ }
17
+
18
+ /**
19
+ * Parses a single SSE data frame (a go-chaintracks `ReorgEvent` JSON document)
20
+ * into `handleReorg` input. Returns `null` for malformed frames.
21
+ *
22
+ * `ReorgEvent` = { orphanedHashes: string[], commonAncestor: BlockHeader|null,
23
+ * newTip: BlockHeader, depth: number }. Block hashes are go-sdk `chainhash.Hash`
24
+ * values marshaled as reversed (display) hex; they are lower-cased here to match
25
+ * the overlay's stored block hashes.
26
+ */
27
+ export function parseReorgEvent (frame: string): ReorgHandlerInput | null {
28
+ let event: any
29
+ try {
30
+ event = JSON.parse(frame)
31
+ } catch {
32
+ return null
33
+ }
34
+
35
+ const newTipHeight = event?.newTip?.height
36
+ if (typeof newTipHeight !== 'number') {
37
+ return null
38
+ }
39
+
40
+ const orphanedBlockHashes: string[] = Array.isArray(event.orphanedHashes)
41
+ ? event.orphanedHashes
42
+ .filter((hash: unknown): hash is string => typeof hash === 'string')
43
+ .map((hash: string) => hash.toLowerCase())
44
+ : []
45
+
46
+ const ancestorHeight: unknown = event?.commonAncestor?.height
47
+ const depth: unknown = event?.depth
48
+ let rebuildFromHeight: number
49
+ if (typeof ancestorHeight === 'number') {
50
+ rebuildFromHeight = ancestorHeight + 1
51
+ } else if (typeof depth === 'number') {
52
+ // No common ancestor (e.g. reorg deeper than retained history): fall back to
53
+ // the reported depth from the new tip.
54
+ rebuildFromHeight = Math.max(0, newTipHeight - depth + 1)
55
+ } else {
56
+ return null
57
+ }
58
+
59
+ return { orphanedBlockHashes, rebuildFromHeight, newTipHeight }
60
+ }
61
+
62
+ /**
63
+ * Splits an SSE byte buffer into complete event payloads. Frames are delimited by
64
+ * a blank line (`\n\n`); within a frame, `data:` lines are concatenated and
65
+ * comment lines (starting with `:`) are ignored. Any trailing partial frame is
66
+ * returned in `rest` for the next read.
67
+ */
68
+ export function extractSseFrames (buffer: string): { events: string[], rest: string } {
69
+ const events: string[] = []
70
+ let working = buffer
71
+ let boundary = working.indexOf('\n\n')
72
+ while (boundary !== -1) {
73
+ const block = working.slice(0, boundary)
74
+ working = working.slice(boundary + 2)
75
+ const dataLines: string[] = []
76
+ for (const line of block.split('\n')) {
77
+ if (line.startsWith(':')) {
78
+ continue
79
+ }
80
+ if (line.startsWith('data:')) {
81
+ dataLines.push(line.slice(5).replace(/^ /, ''))
82
+ }
83
+ }
84
+ if (dataLines.length > 0) {
85
+ events.push(dataLines.join(''))
86
+ }
87
+ boundary = working.indexOf('\n\n')
88
+ }
89
+ return { events, rest: working }
90
+ }
91
+
92
+ export interface ReorgSseAdapterOptions {
93
+ /** Reorg SSE URL, e.g. `https://arcade.example/v2/reorg/stream`. */
94
+ url: string
95
+ /** Invoked for each parsed reorg event. */
96
+ onReorg: (input: ReorgHandlerInput) => Promise<void>
97
+ /** Invoked on every (re)connect for catch-up, since the stream has no replay. */
98
+ onConnect?: () => Promise<void>
99
+ logger?: Pick<typeof console, 'log' | 'warn' | 'error'>
100
+ /** Delay before reconnecting after the stream ends or errors. */
101
+ reconnectDelayMs?: number
102
+ /** Injectable fetch (defaults to global fetch); aids testing. */
103
+ fetchImpl?: typeof fetch
104
+ }
105
+
106
+ /**
107
+ * Long-lived SSE client that keeps the overlay's BASM anchors reconciled with
108
+ * chain reorgs. Auto-reconnects with a fixed delay and runs a catch-up on connect.
109
+ */
110
+ export class ReorgSseAdapter {
111
+ private readonly url: string
112
+ private readonly onReorg: (input: ReorgHandlerInput) => Promise<void>
113
+ private readonly onConnect?: () => Promise<void>
114
+ private readonly logger: Pick<typeof console, 'log' | 'warn' | 'error'>
115
+ private readonly reconnectDelayMs: number
116
+ private readonly fetchImpl: typeof fetch
117
+ private controller?: AbortController
118
+ private stopped = false
119
+
120
+ constructor (options: ReorgSseAdapterOptions) {
121
+ this.url = options.url
122
+ this.onReorg = options.onReorg
123
+ this.onConnect = options.onConnect
124
+ this.logger = options.logger ?? console
125
+ this.reconnectDelayMs = options.reconnectDelayMs ?? 5000
126
+ this.fetchImpl = options.fetchImpl ?? fetch
127
+ }
128
+
129
+ /** Begins consuming the stream in the background. */
130
+ start (): void {
131
+ if (this.stopped) {
132
+ return
133
+ }
134
+ void this.runLoop()
135
+ }
136
+
137
+ /** Stops consuming and aborts any in-flight connection. */
138
+ stop (): void {
139
+ this.stopped = true
140
+ this.controller?.abort()
141
+ }
142
+
143
+ private async runLoop (): Promise<void> {
144
+ while (!this.stopped) {
145
+ try {
146
+ await this.connectOnce()
147
+ } catch (error) {
148
+ if (!this.stopped) {
149
+ this.logger.warn(`[BASM] reorg stream error: ${error instanceof Error ? error.message : String(error)}`)
150
+ }
151
+ }
152
+ if (this.stopped) {
153
+ break
154
+ }
155
+ await this.delay(this.reconnectDelayMs)
156
+ }
157
+ }
158
+
159
+ private async connectOnce (): Promise<void> {
160
+ this.controller = new AbortController()
161
+ const response = await this.fetchImpl(this.url, {
162
+ headers: { Accept: 'text/event-stream' },
163
+ signal: this.controller.signal
164
+ })
165
+ if (!response.ok || response.body == null) {
166
+ throw new Error(`reorg stream responded ${response.status}`)
167
+ }
168
+
169
+ // No event-id replay on this stream: catch up on (re)connect.
170
+ await this.runCatchUp()
171
+ await this.pumpEvents(response.body.getReader())
172
+ }
173
+
174
+ private async runCatchUp (): Promise<void> {
175
+ if (this.onConnect === undefined) {
176
+ return
177
+ }
178
+ try {
179
+ await this.onConnect()
180
+ } catch (error) {
181
+ this.logger.warn(`[BASM] reorg catch-up failed: ${error instanceof Error ? error.message : String(error)}`)
182
+ }
183
+ }
184
+
185
+ private async pumpEvents (reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
186
+ const decoder = new TextDecoder()
187
+ let buffer = ''
188
+ while (!this.stopped) {
189
+ const { value, done } = await reader.read()
190
+ if (done) {
191
+ break
192
+ }
193
+ buffer += decoder.decode(value, { stream: true })
194
+ const { events, rest } = extractSseFrames(buffer)
195
+ buffer = rest
196
+ for (const frame of events) {
197
+ await this.processReorgFrame(frame)
198
+ }
199
+ }
200
+ }
201
+
202
+ private async processReorgFrame (frame: string): Promise<void> {
203
+ const input = parseReorgEvent(frame)
204
+ if (input === null) {
205
+ this.logger.warn('[BASM] skipping malformed reorg frame')
206
+ return
207
+ }
208
+ try {
209
+ await this.onReorg(input)
210
+ } catch (error) {
211
+ this.logger.error(`[BASM] handleReorg failed: ${error instanceof Error ? error.message : String(error)}`)
212
+ }
213
+ }
214
+
215
+ private async delay (ms: number): Promise<void> {
216
+ await new Promise<void>(resolve => {
217
+ const timer = setTimeout(resolve, ms)
218
+ timer.unref?.()
219
+ })
220
+ }
221
+ }
@@ -0,0 +1,131 @@
1
+ import { describe, it, expect, jest, beforeEach } from '@jest/globals'
2
+ import { BanService } from '../BanService.js'
3
+ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from '../BanAwareDiscoveryStorage.js'
4
+
5
+ describe('BanAwareDiscoveryStorage', () => {
6
+ let mockBanService: jest.Mocked<BanService>
7
+ let mockLogger: any
8
+
9
+ beforeEach(() => {
10
+ jest.clearAllMocks()
11
+ mockBanService = {
12
+ isOutpointBanned: jest.fn<any>().mockResolvedValue(false),
13
+ isDomainBanned: jest.fn<any>().mockResolvedValue(false)
14
+ } as any
15
+ mockLogger = {
16
+ log: jest.fn()
17
+ }
18
+ })
19
+
20
+ describe('BanAwareSHIPStorage', () => {
21
+ it('should block banned outpoints', async () => {
22
+ const wrapped = {
23
+ storeSHIPRecord: jest.fn<any>().mockResolvedValue(undefined)
24
+ }
25
+ mockBanService.isOutpointBanned.mockResolvedValue(true)
26
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
27
+
28
+ await storage.storeSHIPRecord('txid', 1, 'identity', 'https://good.example', 'tm_users')
29
+
30
+ expect(wrapped.storeSHIPRecord).not.toHaveBeenCalled()
31
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned outpoint'))
32
+ })
33
+
34
+ it('should block banned domains', async () => {
35
+ const wrapped = {
36
+ storeSHIPRecord: jest.fn<any>().mockResolvedValue(undefined)
37
+ }
38
+ mockBanService.isDomainBanned.mockResolvedValue(true)
39
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
40
+
41
+ await storage.storeSHIPRecord('txid', 1, 'identity', 'https://banned.example', 'tm_users')
42
+
43
+ expect(wrapped.storeSHIPRecord).not.toHaveBeenCalled()
44
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned domain'))
45
+ })
46
+
47
+ it('should delegate when not banned', async () => {
48
+ const wrapped = {
49
+ storeSHIPRecord: jest.fn<any>().mockResolvedValue(undefined)
50
+ }
51
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
52
+
53
+ await storage.storeSHIPRecord('txid', 1, 'identity', 'https://good.example', 'tm_users')
54
+
55
+ expect(wrapped.storeSHIPRecord).toHaveBeenCalledWith('txid', 1, 'identity', 'https://good.example', 'tm_users')
56
+ })
57
+
58
+ it('should delegate read and delete methods', async () => {
59
+ const wrapped = {
60
+ ensureIndexes: jest.fn<any>().mockResolvedValue(undefined),
61
+ hasDuplicateRecord: jest.fn<any>().mockResolvedValue(true),
62
+ deleteSHIPRecord: jest.fn<any>().mockResolvedValue(undefined),
63
+ findRecord: jest.fn<any>().mockResolvedValue([{ txid: 'a', outputIndex: 1 }]),
64
+ findAll: jest.fn<any>().mockResolvedValue([{ txid: 'b', outputIndex: 2 }])
65
+ }
66
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
67
+
68
+ await storage.ensureIndexes()
69
+ await expect(storage.hasDuplicateRecord('identity', 'https://good.example', 'tm_users')).resolves.toBe(true)
70
+ await storage.deleteSHIPRecord('txid', 1)
71
+ await expect(storage.findRecord({ domain: 'https://good.example' })).resolves.toEqual([{ txid: 'a', outputIndex: 1 }])
72
+ await expect(storage.findAll(10, 0, 'desc')).resolves.toEqual([{ txid: 'b', outputIndex: 2 }])
73
+ })
74
+ })
75
+
76
+ describe('BanAwareSLAPStorage', () => {
77
+ it('should block banned outpoints', async () => {
78
+ const wrapped = {
79
+ storeSLAPRecord: jest.fn<any>().mockResolvedValue(undefined)
80
+ }
81
+ mockBanService.isOutpointBanned.mockResolvedValue(true)
82
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
83
+
84
+ await storage.storeSLAPRecord('txid', 1, 'identity', 'https://good.example', 'ls_users')
85
+
86
+ expect(wrapped.storeSLAPRecord).not.toHaveBeenCalled()
87
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned outpoint'))
88
+ })
89
+
90
+ it('should block banned domains', async () => {
91
+ const wrapped = {
92
+ storeSLAPRecord: jest.fn<any>().mockResolvedValue(undefined)
93
+ }
94
+ mockBanService.isDomainBanned.mockResolvedValue(true)
95
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
96
+
97
+ await storage.storeSLAPRecord('txid', 1, 'identity', 'https://banned.example', 'ls_users')
98
+
99
+ expect(wrapped.storeSLAPRecord).not.toHaveBeenCalled()
100
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned domain'))
101
+ })
102
+
103
+ it('should delegate when not banned', async () => {
104
+ const wrapped = {
105
+ storeSLAPRecord: jest.fn<any>().mockResolvedValue(undefined)
106
+ }
107
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
108
+
109
+ await storage.storeSLAPRecord('txid', 1, 'identity', 'https://good.example', 'ls_users')
110
+
111
+ expect(wrapped.storeSLAPRecord).toHaveBeenCalledWith('txid', 1, 'identity', 'https://good.example', 'ls_users')
112
+ })
113
+
114
+ it('should delegate read and delete methods', async () => {
115
+ const wrapped = {
116
+ ensureIndexes: jest.fn<any>().mockResolvedValue(undefined),
117
+ hasDuplicateRecord: jest.fn<any>().mockResolvedValue(true),
118
+ deleteSLAPRecord: jest.fn<any>().mockResolvedValue(undefined),
119
+ findRecord: jest.fn<any>().mockResolvedValue([{ txid: 'a', outputIndex: 1 }]),
120
+ findAll: jest.fn<any>().mockResolvedValue([{ txid: 'b', outputIndex: 2 }])
121
+ }
122
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
123
+
124
+ await storage.ensureIndexes()
125
+ await expect(storage.hasDuplicateRecord('identity', 'https://good.example', 'ls_users')).resolves.toBe(true)
126
+ await storage.deleteSLAPRecord('txid', 1)
127
+ await expect(storage.findRecord({ domain: 'https://good.example' })).resolves.toEqual([{ txid: 'a', outputIndex: 1 }])
128
+ await expect(storage.findAll(10, 0, 'desc')).resolves.toEqual([{ txid: 'b', outputIndex: 2 }])
129
+ })
130
+ })
131
+ })
@@ -0,0 +1,132 @@
1
+ import { describe, it, expect, jest, beforeEach } from '@jest/globals'
2
+ import { TopicManager } from '@bsv/overlay'
3
+ import { PushDrop, Transaction, Utils } from '@bsv/sdk'
4
+ import { BanAwareTopicManager } from '../BanAwareTopicManager.js'
5
+ import { BanService } from '../BanService.js'
6
+
7
+ jest.mock('@bsv/sdk', () => ({
8
+ PushDrop: {
9
+ decode: jest.fn()
10
+ },
11
+ Transaction: {
12
+ fromBEEF: jest.fn()
13
+ },
14
+ Utils: {
15
+ toUTF8: jest.fn()
16
+ }
17
+ }))
18
+
19
+ const mockPushDropDecode = PushDrop.decode as unknown as jest.Mock<any>
20
+ const mockTransactionFromBEEF = Transaction.fromBEEF as unknown as jest.Mock<any>
21
+ const mockToUTF8 = Utils.toUTF8 as unknown as jest.Mock<any>
22
+
23
+ describe('BanAwareTopicManager', () => {
24
+ let wrapper: BanAwareTopicManager
25
+ let mockWrapped: jest.Mocked<TopicManager>
26
+ let mockBanService: jest.Mocked<BanService>
27
+ let mockLogger: any
28
+
29
+ beforeEach(() => {
30
+ jest.clearAllMocks()
31
+
32
+ mockWrapped = {
33
+ identifyAdmissibleOutputs: jest.fn<any>().mockResolvedValue({
34
+ outputsToAdmit: [0, 1],
35
+ coinsToRetain: [0],
36
+ coinsRemoved: [1]
37
+ }),
38
+ identifyNeededInputs: jest.fn<any>().mockResolvedValue([{ txid: 'needed-txid', outputIndex: 0 }]),
39
+ getDocumentation: jest.fn<any>().mockResolvedValue('docs'),
40
+ getMetaData: jest.fn<any>().mockResolvedValue({ name: 'test', shortDescription: 'test' })
41
+ } as any
42
+
43
+ mockBanService = {
44
+ isOutpointBanned: jest.fn<any>().mockResolvedValue(false),
45
+ isDomainBanned: jest.fn<any>().mockResolvedValue(false)
46
+ } as any
47
+
48
+ mockLogger = {
49
+ log: jest.fn()
50
+ }
51
+
52
+ mockTransactionFromBEEF.mockReturnValue({
53
+ id: jest.fn().mockReturnValue('ad-txid'),
54
+ outputs: [
55
+ { lockingScript: 'script-0' },
56
+ { lockingScript: 'script-1' }
57
+ ]
58
+ })
59
+ mockPushDropDecode.mockReturnValue({
60
+ fields: [Buffer.from('SHIP'), Buffer.from('topic'), Buffer.from('https://good.example')]
61
+ })
62
+ mockToUTF8.mockImplementation((value: Buffer) => value.toString('utf8'))
63
+
64
+ wrapper = new BanAwareTopicManager(mockWrapped, mockBanService, 'SHIP', mockLogger)
65
+ })
66
+
67
+ it('should remove banned outpoints from admittance instructions', async () => {
68
+ mockBanService.isOutpointBanned.mockResolvedValueOnce(true).mockResolvedValue(false)
69
+
70
+ const result = await wrapper.identifyAdmissibleOutputs([1, 2, 3], [0], [42], 'current-tx')
71
+
72
+ expect(result.outputsToAdmit).toEqual([1])
73
+ expect(mockWrapped.identifyAdmissibleOutputs).toHaveBeenCalledWith([1, 2, 3], [0], [42], 'current-tx')
74
+ expect(mockBanService.isOutpointBanned).toHaveBeenCalledWith('ad-txid', 0)
75
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned outpoint'))
76
+ })
77
+
78
+ it('should remove outputs whose advertised domain is banned', async () => {
79
+ mockBanService.isDomainBanned.mockResolvedValueOnce(true).mockResolvedValue(false)
80
+
81
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
82
+
83
+ expect(result.outputsToAdmit).toEqual([1])
84
+ expect(mockBanService.isDomainBanned).toHaveBeenCalledWith('https://good.example')
85
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned domain'))
86
+ })
87
+
88
+ it('should preserve all outputs when nothing is banned', async () => {
89
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
90
+
91
+ expect(result.outputsToAdmit).toEqual([0, 1])
92
+ })
93
+
94
+ it('should preserve wrapped instructions when BEEF parsing fails', async () => {
95
+ mockTransactionFromBEEF.mockImplementation(() => { throw new Error('bad beef') })
96
+
97
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
98
+
99
+ expect(result.outputsToAdmit).toEqual([0, 1])
100
+ expect(mockBanService.isOutpointBanned).not.toHaveBeenCalled()
101
+ })
102
+
103
+ it('should preserve wrapped instructions for non-standard outputs', async () => {
104
+ mockPushDropDecode.mockImplementation(() => { throw new Error('bad script') })
105
+
106
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
107
+
108
+ expect(result.outputsToAdmit).toEqual([0, 1])
109
+ expect(mockBanService.isDomainBanned).not.toHaveBeenCalled()
110
+ })
111
+
112
+ it('should delegate identifyNeededInputs', async () => {
113
+ await expect(wrapper.identifyNeededInputs([1], [2])).resolves.toEqual([{ txid: 'needed-txid', outputIndex: 0 }])
114
+ expect(mockWrapped.identifyNeededInputs).toHaveBeenCalledWith([1], [2])
115
+ })
116
+
117
+ it('should return no needed inputs when wrapped manager does not implement it', async () => {
118
+ const manager = new BanAwareTopicManager(
119
+ { ...mockWrapped, identifyNeededInputs: undefined },
120
+ mockBanService,
121
+ 'SLAP',
122
+ mockLogger
123
+ )
124
+
125
+ await expect(manager.identifyNeededInputs([1])).resolves.toEqual([])
126
+ })
127
+
128
+ it('should delegate documentation and metadata', async () => {
129
+ await expect(wrapper.getDocumentation()).resolves.toBe('docs')
130
+ await expect(wrapper.getMetaData()).resolves.toEqual({ name: 'test', shortDescription: 'test' })
131
+ })
132
+ })
@@ -872,6 +872,91 @@ describe('OverlayExpress', () => {
872
872
  expect(postSpy.mock.calls.some(call => call[0] === '/arc-ingest')).toBe(false)
873
873
  })
874
874
 
875
+ describe('ARC ingest callback token', () => {
876
+ const mockRes = (): any => {
877
+ const res: any = {}
878
+ res.status = jest.fn<any>().mockReturnValue(res)
879
+ res.json = jest.fn<any>().mockReturnValue(res)
880
+ return res
881
+ }
882
+ // Flush the async IIFE inside the /arc-ingest handler.
883
+ const flush = async (): Promise<void> => { await new Promise(resolve => setImmediate(resolve)) }
884
+
885
+ const captureArcIngestHandler = async (): Promise<any> => {
886
+ const postSpy = jest.spyOn(instance.app, 'post')
887
+ jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
888
+ callback()
889
+ return {} as any
890
+ })
891
+ await instance.start()
892
+ const handler = postSpy.mock.calls.find(call => call[0] === '/arc-ingest')?.[1]
893
+ expect(handler).toBeDefined()
894
+ return handler
895
+ }
896
+
897
+ it('rejects a callback with no token when a token is configured', async () => {
898
+ instance.configureArcApiKey('test-arc-key')
899
+ instance.configureArcCallbackToken('secret-token')
900
+ const handler = await captureArcIngestHandler()
901
+ const res = mockRes()
902
+
903
+ handler({ headers: {}, body: {} }, res)
904
+ await flush()
905
+
906
+ expect(res.status).toHaveBeenCalledWith(401)
907
+ })
908
+
909
+ it('rejects a callback with an invalid token', async () => {
910
+ instance.configureArcApiKey('test-arc-key')
911
+ instance.configureArcCallbackToken('secret-token')
912
+ const handler = await captureArcIngestHandler()
913
+ const res = mockRes()
914
+
915
+ handler({ headers: { authorization: 'Bearer wrong-token' }, body: {} }, res)
916
+ await flush()
917
+
918
+ expect(res.status).toHaveBeenCalledWith(401)
919
+ })
920
+
921
+ it('accepts a callback with a valid Bearer token', async () => {
922
+ instance.configureArcApiKey('test-arc-key')
923
+ instance.configureArcCallbackToken('secret-token')
924
+ const handler = await captureArcIngestHandler()
925
+ const res = mockRes()
926
+
927
+ handler({ headers: { authorization: 'Bearer secret-token' }, body: {} }, res)
928
+ await flush()
929
+
930
+ expect(res.status).not.toHaveBeenCalledWith(401)
931
+ expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
932
+ })
933
+
934
+ it('accepts a callback with a valid x-callback-token header', async () => {
935
+ instance.configureArcApiKey('test-arc-key')
936
+ instance.configureArcCallbackToken('secret-token')
937
+ const handler = await captureArcIngestHandler()
938
+ const res = mockRes()
939
+
940
+ handler({ headers: { 'x-callback-token': 'secret-token' }, body: {} }, res)
941
+ await flush()
942
+
943
+ expect(res.status).not.toHaveBeenCalledWith(401)
944
+ expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
945
+ })
946
+
947
+ it('does not enforce a token when none is configured', async () => {
948
+ instance.configureArcApiKey('test-arc-key')
949
+ const handler = await captureArcIngestHandler()
950
+ const res = mockRes()
951
+
952
+ handler({ headers: {}, body: {} }, res)
953
+ await flush()
954
+
955
+ expect(res.status).not.toHaveBeenCalledWith(401)
956
+ expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
957
+ })
958
+ })
959
+
875
960
  it('should run knex migrations on start', async () => {
876
961
  jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
877
962
  callback()
@@ -941,7 +1026,7 @@ describe('OverlayExpress', () => {
941
1026
  revokeAdvertisements: jest.fn(),
942
1027
  parseAdvertisement: jest.fn()
943
1028
  }
944
- instance.engine.advertiser = mockAdvertiser
1029
+ instance.engine!.advertiser = mockAdvertiser
945
1030
 
946
1031
  jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
947
1032
  callback()