@bsv/overlay-express 2.4.2 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/LICENSE.txt +57 -27
  2. package/README.md +141 -56
  3. package/dist/cjs/mod.d.ts +11 -0
  4. package/dist/cjs/mod.d.ts.map +1 -0
  5. package/dist/cjs/mod.js.map +1 -1
  6. package/dist/cjs/package.json +26 -13
  7. package/dist/cjs/src/ArcadeProvider.d.ts +37 -0
  8. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -0
  9. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  10. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts +36 -0
  11. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  12. package/dist/cjs/src/BanAwareDiscoveryStorage.js +5 -4
  13. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -1
  14. package/dist/cjs/src/BanAwareLookupWrapper.d.ts +31 -0
  15. package/dist/cjs/src/BanAwareLookupWrapper.d.ts.map +1 -0
  16. package/dist/cjs/src/BanAwareLookupWrapper.js +3 -2
  17. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -1
  18. package/dist/cjs/src/BanAwareTopicManager.d.ts +28 -0
  19. package/dist/cjs/src/BanAwareTopicManager.d.ts.map +1 -0
  20. package/dist/cjs/src/BanAwareTopicManager.js +3 -2
  21. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -1
  22. package/dist/cjs/src/BanService.d.ts +79 -0
  23. package/dist/cjs/src/BanService.d.ts.map +1 -0
  24. package/dist/cjs/src/BanService.js +18 -5
  25. package/dist/cjs/src/BanService.js.map +1 -1
  26. package/dist/cjs/src/ChaintracksProvider.d.ts +29 -0
  27. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -0
  28. package/dist/cjs/src/ChaintracksProvider.js +1 -1
  29. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  30. package/dist/cjs/src/JanitorService.d.ts +135 -0
  31. package/dist/cjs/src/JanitorService.d.ts.map +1 -0
  32. package/dist/cjs/src/JanitorService.js +168 -48
  33. package/dist/cjs/src/JanitorService.js.map +1 -1
  34. package/dist/cjs/src/OverlayExpress.d.ts +472 -0
  35. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -0
  36. package/dist/cjs/src/OverlayExpress.js +483 -193
  37. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  38. package/dist/cjs/src/OverlayMonitor.d.ts +197 -0
  39. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -0
  40. package/dist/cjs/src/OverlayMonitor.js +6 -4
  41. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  42. package/dist/cjs/src/ProviderChainBroadcaster.d.ts +18 -0
  43. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -0
  44. package/dist/cjs/src/ProviderChainBroadcaster.js +7 -3
  45. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  46. package/dist/cjs/src/ReorgStream.d.ts +74 -0
  47. package/dist/cjs/src/ReorgStream.d.ts.map +1 -0
  48. package/dist/cjs/src/ReorgStream.js +14 -6
  49. package/dist/cjs/src/ReorgStream.js.map +1 -1
  50. package/dist/cjs/src/ResourceBoundedLookupWrapper.d.ts +26 -0
  51. package/dist/cjs/src/ResourceBoundedLookupWrapper.d.ts.map +1 -0
  52. package/dist/cjs/src/ResourceBoundedLookupWrapper.js +70 -0
  53. package/dist/cjs/src/ResourceBoundedLookupWrapper.js.map +1 -0
  54. package/dist/cjs/src/generalGuide.md.d.ts +3 -0
  55. package/dist/cjs/src/generalGuide.md.d.ts.map +1 -0
  56. package/dist/cjs/src/generalGuide.md.js.map +1 -1
  57. package/dist/cjs/src/makeUserInterface.d.ts +22 -0
  58. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -0
  59. package/dist/cjs/src/makeUserInterface.js +4 -4
  60. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  61. package/dist/cjs/src/security/edgePolicy.d.ts +84 -0
  62. package/dist/cjs/src/security/edgePolicy.d.ts.map +1 -0
  63. package/dist/cjs/src/security/edgePolicy.js +533 -0
  64. package/dist/cjs/src/security/edgePolicy.js.map +1 -0
  65. package/dist/esm/mod.js.map +1 -1
  66. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  67. package/dist/esm/src/BanAwareDiscoveryStorage.js +5 -4
  68. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  69. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  70. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  71. package/dist/esm/src/BanAwareTopicManager.js +3 -2
  72. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  73. package/dist/esm/src/BanService.js +18 -5
  74. package/dist/esm/src/BanService.js.map +1 -1
  75. package/dist/esm/src/ChaintracksProvider.js +1 -1
  76. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  77. package/dist/esm/src/JanitorService.js +146 -19
  78. package/dist/esm/src/JanitorService.js.map +1 -1
  79. package/dist/esm/src/OverlayExpress.js +465 -176
  80. package/dist/esm/src/OverlayExpress.js.map +1 -1
  81. package/dist/esm/src/ProviderChainBroadcaster.js +7 -3
  82. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  83. package/dist/esm/src/ReorgStream.js +14 -6
  84. package/dist/esm/src/ReorgStream.js.map +1 -1
  85. package/dist/esm/src/ResourceBoundedLookupWrapper.js +70 -0
  86. package/dist/esm/src/ResourceBoundedLookupWrapper.js.map +1 -0
  87. package/dist/esm/src/makeUserInterface.js +3 -4
  88. package/dist/esm/src/makeUserInterface.js.map +1 -1
  89. package/dist/esm/src/security/edgePolicy.js +522 -0
  90. package/dist/esm/src/security/edgePolicy.js.map +1 -0
  91. package/dist/types/mod.d.ts +1 -1
  92. package/dist/types/mod.d.ts.map +1 -1
  93. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  94. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  95. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  96. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  97. package/dist/types/src/BanService.d.ts +2 -4
  98. package/dist/types/src/BanService.d.ts.map +1 -1
  99. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  100. package/dist/types/src/JanitorService.d.ts +21 -1
  101. package/dist/types/src/JanitorService.d.ts.map +1 -1
  102. package/dist/types/src/OverlayExpress.d.ts +54 -2
  103. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  104. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  105. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  106. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  107. package/dist/types/src/ResourceBoundedLookupWrapper.d.ts +26 -0
  108. package/dist/types/src/ResourceBoundedLookupWrapper.d.ts.map +1 -0
  109. package/dist/types/src/generalGuide.md.d.ts +1 -1
  110. package/dist/types/src/generalGuide.md.d.ts.map +1 -1
  111. package/dist/types/src/makeUserInterface.d.ts +1 -2
  112. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  113. package/dist/types/src/security/edgePolicy.d.ts +84 -0
  114. package/dist/types/src/security/edgePolicy.d.ts.map +1 -0
  115. package/package.json +47 -25
  116. package/dist/cjs/tsconfig.cjs.tsbuildinfo +0 -1
  117. package/dist/esm/tsconfig.esm.tsbuildinfo +0 -1
  118. package/dist/types/tsconfig.types.tsbuildinfo +0 -1
  119. package/mod.ts +0 -47
  120. package/src/ArcadeProvider.ts +0 -232
  121. package/src/BanAwareDiscoveryStorage.ts +0 -91
  122. package/src/BanAwareLookupWrapper.ts +0 -95
  123. package/src/BanAwareTopicManager.ts +0 -87
  124. package/src/BanService.ts +0 -154
  125. package/src/ChaintracksProvider.ts +0 -79
  126. package/src/JanitorService.ts +0 -423
  127. package/src/OverlayExpress.ts +0 -2479
  128. package/src/OverlayMonitor.ts +0 -817
  129. package/src/ProviderChainBroadcaster.ts +0 -108
  130. package/src/ReorgStream.ts +0 -221
  131. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +0 -131
  132. package/src/__tests__/BanAwareLookupWrapper.test.ts +0 -255
  133. package/src/__tests__/BanAwareTopicManager.test.ts +0 -132
  134. package/src/__tests__/BanService.test.ts +0 -310
  135. package/src/__tests__/InMemoryMigrationSource.test.ts +0 -11
  136. package/src/__tests__/JanitorService.test.ts +0 -941
  137. package/src/__tests__/OverlayExpress.test.ts +0 -1300
  138. package/src/__tests__/OverlayMonitor.test.ts +0 -255
  139. package/src/__tests__/OverlayProviders.live.test.ts +0 -43
  140. package/src/__tests__/OverlayProviders.test.ts +0 -123
  141. package/src/__tests__/README.md +0 -105
  142. package/src/__tests__/ReorgStream.test.ts +0 -66
  143. package/src/__tests__/makeUserInterface.test.ts +0 -193
  144. package/src/__tests__/setup.ts +0 -36
  145. package/src/auth-express-middleware.d.ts +0 -16
  146. package/src/generalGuide.md.ts +0 -74
  147. package/src/makeUserInterface.ts +0 -1224
@@ -1,232 +0,0 @@
1
- import {
2
- BroadcastFailure,
3
- Broadcaster,
4
- BroadcastResponse,
5
- MerklePath,
6
- Transaction
7
- } from '@bsv/sdk'
8
-
9
- export interface ArcadeProviderConfig {
10
- apiKey?: string
11
- callbackUrl?: string
12
- callbackToken?: string
13
- deploymentId?: string
14
- headers?: Record<string, string>
15
- fetch?: typeof fetch
16
- }
17
-
18
- export interface ArcadeMerkleProof {
19
- txid: string
20
- merklePath: MerklePath
21
- blockHeight?: number
22
- blockHash?: string
23
- merkleRoot: string
24
- }
25
-
26
- interface ArcadeTxResponse {
27
- txid?: string
28
- txStatus?: string
29
- status?: number | string
30
- extraInfo?: string
31
- detail?: string
32
- error?: string
33
- reason?: string
34
- competingTxs?: string[]
35
- merklePath?: string
36
- blockHeight?: number
37
- blockHash?: string
38
- }
39
-
40
- const TERMINAL_STATUSES = new Set([
41
- 'DOUBLE_SPEND_ATTEMPTED',
42
- 'REJECTED',
43
- 'INVALID',
44
- 'MALFORMED',
45
- 'MINED_IN_STALE_BLOCK'
46
- ])
47
-
48
- const SUCCESS_STATUSES = new Set([
49
- 'RECEIVED',
50
- 'SENT_TO_NETWORK',
51
- 'ANNOUNCED_TO_NETWORK',
52
- 'ACCEPTED_BY_NETWORK',
53
- 'SEEN_ON_NETWORK',
54
- 'STORED',
55
- 'MINED',
56
- 'IMMUTABLE'
57
- ])
58
-
59
- export function isTerminalArcStatus (status: unknown, extraInfo?: unknown): boolean {
60
- const statusText = typeof status === 'string' ? status.toUpperCase() : ''
61
- const extraText = typeof extraInfo === 'string' ? extraInfo.toUpperCase() : ''
62
- return TERMINAL_STATUSES.has(statusText) || statusText.includes('ORPHAN') || extraText.includes('ORPHAN')
63
- }
64
-
65
- function trimBaseUrl (url: string): string {
66
- let base = url
67
- while (base.endsWith('/')) base = base.slice(0, -1)
68
- return base
69
- }
70
-
71
- function parseDescription (data: unknown, fallback: string): string {
72
- if (typeof data === 'string') return data
73
- if (typeof data === 'object' && data !== null) {
74
- const d = data as ArcadeTxResponse
75
- return d.detail ?? d.reason ?? d.error ?? `${d.txStatus ?? ''} ${d.extraInfo ?? ''}`.trim() ?? fallback
76
- }
77
- return fallback
78
- }
79
-
80
- function rawTxForArcade (tx: Transaction): string {
81
- try {
82
- return tx.toHexEF()
83
- } catch (error: unknown) {
84
- if (
85
- error instanceof Error &&
86
- error.message === 'All inputs must have source transactions when serializing to EF format'
87
- ) {
88
- return tx.toHex()
89
- }
90
- throw error
91
- }
92
- }
93
-
94
- /**
95
- * Broadcaster/proof client for bsv-blockchain/arcade.
96
- *
97
- * Arcade exposes transaction propagation at `/tx` and status/proofs at
98
- * `/tx/{txid}`. It returns terminal validation and double-spend statuses in the
99
- * body, so callers must classify those as failed broadcasts even when HTTP
100
- * accepted the request.
101
- */
102
- export class ArcadeProvider implements Broadcaster {
103
- readonly name = 'Arcade'
104
- private readonly baseUrl: string
105
- private readonly fetcher: typeof fetch
106
-
107
- constructor (url: string, private readonly config: ArcadeProviderConfig = {}) {
108
- this.baseUrl = trimBaseUrl(url)
109
- this.fetcher = config.fetch ?? fetch
110
- }
111
-
112
- async broadcast (tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
113
- const rawTx = rawTxForArcade(tx)
114
- try {
115
- const response = await this.fetcher(`${this.baseUrl}/tx`, {
116
- method: 'POST',
117
- headers: this.requestHeaders(),
118
- body: JSON.stringify({ rawTx })
119
- })
120
- const data = await this.readResponse<ArcadeTxResponse>(response)
121
- if (!response.ok) {
122
- const failure: BroadcastFailure = {
123
- status: 'error',
124
- code: data?.txStatus ?? String(response.status),
125
- txid: data?.txid,
126
- description: parseDescription(data, response.statusText)
127
- }
128
- const more: Record<string, unknown> = {
129
- provider: this.name,
130
- httpStatus: response.status,
131
- terminal: response.status === 400 || isTerminalArcStatus(data?.txStatus, data?.extraInfo),
132
- response: data
133
- }
134
- if (data?.competingTxs !== undefined) {
135
- more.competingTxs = data.competingTxs
136
- }
137
- failure.more = more
138
- return failure
139
- }
140
-
141
- const txStatus = data?.txStatus
142
- if (isTerminalArcStatus(txStatus, data?.extraInfo)) {
143
- const failure: BroadcastFailure = {
144
- status: 'error',
145
- code: txStatus ?? 'UNKNOWN',
146
- txid: data?.txid,
147
- description: `${txStatus ?? ''} ${data?.extraInfo ?? ''}`.trim()
148
- }
149
- const more: Record<string, unknown> = { provider: this.name, terminal: true, response: data }
150
- if (data?.competingTxs !== undefined) {
151
- more.competingTxs = data.competingTxs
152
- }
153
- failure.more = more
154
- return failure
155
- }
156
-
157
- const statusText = typeof txStatus === 'string' ? txStatus.toUpperCase() : undefined
158
- return {
159
- status: 'success',
160
- txid: data?.txid ?? tx.id('hex'),
161
- message: `${txStatus ?? (SUCCESS_STATUSES.has(statusText ?? '') ? statusText ?? '' : response.statusText)} ${data?.extraInfo ?? ''}`.trim(),
162
- competingTxs: data?.competingTxs
163
- }
164
- } catch (error: unknown) {
165
- return {
166
- status: 'error',
167
- code: '500',
168
- description: error instanceof Error ? error.message : 'Internal Server Error',
169
- more: { provider: this.name, terminal: false }
170
- }
171
- }
172
- }
173
-
174
- async fetchMerkleProof (txid: string): Promise<ArcadeMerkleProof | undefined> {
175
- const response = await this.fetcher(`${this.baseUrl}/tx/${txid}`, {
176
- method: 'GET',
177
- headers: this.requestHeaders({ accept: 'application/json' })
178
- })
179
- if (response.status === 404) return undefined
180
- const data = await this.readResponse<ArcadeTxResponse>(response)
181
- if (!response.ok) {
182
- throw new Error(`Arcade proof lookup failed for ${txid}: ${response.status} ${parseDescription(data, response.statusText)}`)
183
- }
184
- const mined = data?.txStatus === 'MINED' || data?.txStatus === 'IMMUTABLE'
185
- if (!mined || data?.merklePath === undefined || data.merklePath === '') {
186
- return undefined
187
- }
188
- const merklePath = MerklePath.fromHex(data.merklePath)
189
- return {
190
- txid,
191
- merklePath,
192
- blockHeight: data.blockHeight ?? merklePath.blockHeight,
193
- blockHash: data.blockHash,
194
- merkleRoot: merklePath.computeRoot(txid)
195
- }
196
- }
197
-
198
- private requestHeaders (options: { accept?: string } = {}): Record<string, string> {
199
- const headers: Record<string, string> = {
200
- Accept: options.accept ?? 'application/json',
201
- 'Content-Type': 'application/json'
202
- }
203
- if (this.config.deploymentId !== undefined && this.config.deploymentId !== '') {
204
- headers['XDeployment-ID'] = this.config.deploymentId
205
- }
206
- if (this.config.apiKey !== undefined && this.config.apiKey !== '') {
207
- headers.Authorization = `Bearer ${this.config.apiKey}`
208
- }
209
- if (this.config.callbackUrl !== undefined && this.config.callbackUrl !== '') {
210
- headers['X-CallbackUrl'] = this.config.callbackUrl
211
- }
212
- if (this.config.callbackToken !== undefined && this.config.callbackToken !== '') {
213
- headers['X-CallbackToken'] = this.config.callbackToken
214
- }
215
- if (this.config.headers !== undefined) {
216
- for (const [key, value] of Object.entries(this.config.headers)) {
217
- headers[key] = value
218
- }
219
- }
220
- return headers
221
- }
222
-
223
- private async readResponse<T>(response: Response): Promise<T | undefined> {
224
- const text = await response.text()
225
- if (text === '') return undefined
226
- try {
227
- return JSON.parse(text) as T
228
- } catch {
229
- return text as T
230
- }
231
- }
232
- }
@@ -1,91 +0,0 @@
1
- import * as DiscoveryServices from '@bsv/overlay-discovery-services'
2
- import { BanService } from './BanService.js'
3
-
4
- type SHIPStorage = InstanceType<typeof DiscoveryServices.SHIPStorage>
5
- type SLAPStorage = InstanceType<typeof DiscoveryServices.SLAPStorage>
6
-
7
- /**
8
- * Prevents banned SHIP records from being written to discovery storage.
9
- */
10
- export class BanAwareSHIPStorage {
11
- constructor (
12
- private readonly wrapped: SHIPStorage,
13
- private readonly banService: BanService,
14
- private readonly logger: typeof console = console
15
- ) {}
16
-
17
- async ensureIndexes (): Promise<void> {
18
- return await this.wrapped.ensureIndexes()
19
- }
20
-
21
- async hasDuplicateRecord (identityKey: string, domain: string, topic: string): Promise<boolean> {
22
- return await this.wrapped.hasDuplicateRecord(identityKey, domain, topic)
23
- }
24
-
25
- async storeSHIPRecord (txid: string, outputIndex: number, identityKey: string, domain: string, topic: string): Promise<void> {
26
- if (await this.banService.isOutpointBanned(txid, outputIndex)) {
27
- this.logger.log(`[BAN] Blocked banned outpoint ${txid}.${outputIndex} from SHIP storage`)
28
- return
29
- }
30
- if (await this.banService.isDomainBanned(domain)) {
31
- this.logger.log(`[BAN] Blocked banned domain ${domain} from SHIP storage (${txid}.${outputIndex})`)
32
- return
33
- }
34
- return await this.wrapped.storeSHIPRecord(txid, outputIndex, identityKey, domain, topic)
35
- }
36
-
37
- async deleteSHIPRecord (txid: string, outputIndex: number): Promise<void> {
38
- return await this.wrapped.deleteSHIPRecord(txid, outputIndex)
39
- }
40
-
41
- async findRecord (...args: Parameters<SHIPStorage['findRecord']>): ReturnType<SHIPStorage['findRecord']> {
42
- return await this.wrapped.findRecord(...args)
43
- }
44
-
45
- async findAll (...args: Parameters<SHIPStorage['findAll']>): ReturnType<SHIPStorage['findAll']> {
46
- return await this.wrapped.findAll(...args)
47
- }
48
- }
49
-
50
- /**
51
- * Prevents banned SLAP records from being written to discovery storage.
52
- */
53
- export class BanAwareSLAPStorage {
54
- constructor (
55
- private readonly wrapped: SLAPStorage,
56
- private readonly banService: BanService,
57
- private readonly logger: typeof console = console
58
- ) {}
59
-
60
- async ensureIndexes (): Promise<void> {
61
- return await this.wrapped.ensureIndexes()
62
- }
63
-
64
- async hasDuplicateRecord (identityKey: string, domain: string, service: string): Promise<boolean> {
65
- return await this.wrapped.hasDuplicateRecord(identityKey, domain, service)
66
- }
67
-
68
- async storeSLAPRecord (txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> {
69
- if (await this.banService.isOutpointBanned(txid, outputIndex)) {
70
- this.logger.log(`[BAN] Blocked banned outpoint ${txid}.${outputIndex} from SLAP storage`)
71
- return
72
- }
73
- if (await this.banService.isDomainBanned(domain)) {
74
- this.logger.log(`[BAN] Blocked banned domain ${domain} from SLAP storage (${txid}.${outputIndex})`)
75
- return
76
- }
77
- return await this.wrapped.storeSLAPRecord(txid, outputIndex, identityKey, domain, service)
78
- }
79
-
80
- async deleteSLAPRecord (txid: string, outputIndex: number): Promise<void> {
81
- return await this.wrapped.deleteSLAPRecord(txid, outputIndex)
82
- }
83
-
84
- async findRecord (...args: Parameters<SLAPStorage['findRecord']>): ReturnType<SLAPStorage['findRecord']> {
85
- return await this.wrapped.findRecord(...args)
86
- }
87
-
88
- async findAll (...args: Parameters<SLAPStorage['findAll']>): ReturnType<SLAPStorage['findAll']> {
89
- return await this.wrapped.findAll(...args)
90
- }
91
- }
@@ -1,95 +0,0 @@
1
- import {
2
- LookupService,
3
- LookupFormula,
4
- AdmissionMode,
5
- SpendNotificationMode,
6
- OutputAdmittedByTopic,
7
- OutputSpent,
8
- LookupServiceMetaData
9
- } from '@bsv/overlay'
10
- import { PushDrop, Utils, LookupQuestion } from '@bsv/sdk'
11
- import { BanService } from './BanService.js'
12
-
13
- /**
14
- * Wraps a SHIP or SLAP LookupService to intercept outputAdmittedByTopic calls
15
- * and block outputs whose domain or outpoint appears in the persistent ban list.
16
- *
17
- * This prevents GASP from re-syncing stale or banned tokens that were previously
18
- * removed by the Janitor or an admin.
19
- */
20
- export class BanAwareLookupWrapper implements LookupService {
21
- readonly admissionMode: AdmissionMode
22
- readonly spendNotificationMode: SpendNotificationMode
23
-
24
- constructor (
25
- private readonly wrapped: LookupService,
26
- private readonly banService: BanService,
27
- private readonly protocol: 'SHIP' | 'SLAP',
28
- private readonly logger: typeof console = console
29
- ) {
30
- this.admissionMode = wrapped.admissionMode
31
- this.spendNotificationMode = wrapped.spendNotificationMode
32
- }
33
-
34
- /**
35
- * Intercepts admission to check the ban list before delegating to the wrapped service.
36
- * If the output's domain or outpoint is banned, the admission is silently blocked.
37
- */
38
- async outputAdmittedByTopic (payload: OutputAdmittedByTopic): Promise<void> {
39
- if (payload.mode === 'locking-script') {
40
- const { txid, outputIndex, lockingScript } = payload
41
-
42
- // Check if the specific outpoint is banned
43
- if (await this.banService.isOutpointBanned(txid, outputIndex)) {
44
- this.logger.log(`[BAN] Blocked banned outpoint ${txid}.${outputIndex} from ${this.protocol}`)
45
- return
46
- }
47
-
48
- // Try to parse the domain from PushDrop fields and check domain ban
49
- try {
50
- const result = PushDrop.decode(lockingScript)
51
- if (result.fields.length >= 3) {
52
- const domain = Utils.toUTF8(result.fields[2])
53
- if (await this.banService.isDomainBanned(domain)) {
54
- this.logger.log(`[BAN] Blocked banned domain ${domain} from ${this.protocol} (${txid}.${outputIndex})`)
55
- return
56
- }
57
- }
58
- } catch {
59
- // If we can't parse PushDrop fields, let it through to the wrapped service
60
- // which will apply its own validation
61
- }
62
- }
63
-
64
- // Delegate to the wrapped service
65
- return await this.wrapped.outputAdmittedByTopic(payload)
66
- }
67
-
68
- async outputSpent (payload: OutputSpent): Promise<void> {
69
- if (typeof this.wrapped.outputSpent === 'function') {
70
- return await this.wrapped.outputSpent(payload)
71
- }
72
- }
73
-
74
- async outputNoLongerRetainedInHistory (txid: string, outputIndex: number, topic: string): Promise<void> {
75
- if (typeof this.wrapped.outputNoLongerRetainedInHistory === 'function') {
76
- return await this.wrapped.outputNoLongerRetainedInHistory(txid, outputIndex, topic)
77
- }
78
- }
79
-
80
- async outputEvicted (txid: string, outputIndex: number): Promise<void> {
81
- return await this.wrapped.outputEvicted(txid, outputIndex)
82
- }
83
-
84
- async lookup (question: LookupQuestion): Promise<LookupFormula> {
85
- return await this.wrapped.lookup(question)
86
- }
87
-
88
- async getDocumentation (): Promise<string> {
89
- return await this.wrapped.getDocumentation()
90
- }
91
-
92
- async getMetaData (): Promise<LookupServiceMetaData> {
93
- return await this.wrapped.getMetaData()
94
- }
95
- }
@@ -1,87 +0,0 @@
1
- import { TopicManager } from '@bsv/overlay'
2
- import { AdmittanceInstructions, PushDrop, Transaction, Utils } from '@bsv/sdk'
3
- import { BanService } from './BanService.js'
4
-
5
- /**
6
- * Filters banned SHIP or SLAP advertisement outputs before the overlay engine
7
- * admits them into topic storage.
8
- */
9
- export class BanAwareTopicManager implements TopicManager {
10
- constructor (
11
- private readonly wrapped: TopicManager,
12
- private readonly banService: BanService,
13
- private readonly protocol: 'SHIP' | 'SLAP',
14
- private readonly logger: typeof console = console
15
- ) {}
16
-
17
- async identifyAdmissibleOutputs (
18
- beef: number[],
19
- previousCoins: number[],
20
- offChainValues?: number[],
21
- mode?: 'historical-tx' | 'current-tx' | 'historical-tx-no-spv'
22
- ): Promise<AdmittanceInstructions> {
23
- const instructions = await this.wrapped.identifyAdmissibleOutputs(beef, previousCoins, offChainValues, mode)
24
- if (instructions.outputsToAdmit.length === 0) return instructions
25
-
26
- let tx: Transaction
27
- try {
28
- tx = Transaction.fromBEEF(beef)
29
- } catch {
30
- return instructions
31
- }
32
-
33
- const txid = tx.id('hex')
34
- const outputsToAdmit: number[] = []
35
-
36
- for (const outputIndex of instructions.outputsToAdmit) {
37
- if (await this.banService.isOutpointBanned(txid, outputIndex)) {
38
- this.logger.log(`[BAN] Blocked banned outpoint ${txid}.${outputIndex} from ${this.protocol} topic admittance`)
39
- continue
40
- }
41
-
42
- const output = tx.outputs[outputIndex]
43
- if (output === undefined) continue
44
-
45
- try {
46
- const result = PushDrop.decode(output.lockingScript)
47
- if (result.fields.length >= 3 && Utils.toUTF8(result.fields[0]) === this.protocol) {
48
- const domain = Utils.toUTF8(result.fields[2])
49
- if (await this.banService.isDomainBanned(domain)) {
50
- this.logger.log(`[BAN] Blocked banned domain ${domain} from ${this.protocol} topic admittance (${txid}.${outputIndex})`)
51
- continue
52
- }
53
- }
54
- } catch {
55
- // Non PushDrop outputs remain subject to the wrapped manager's decision.
56
- }
57
-
58
- outputsToAdmit.push(outputIndex)
59
- }
60
-
61
- return {
62
- ...instructions,
63
- outputsToAdmit
64
- }
65
- }
66
-
67
- async identifyNeededInputs (beef: number[], offChainValues?: number[]): Promise<Array<{ txid: string, outputIndex: number }>> {
68
- if (typeof this.wrapped.identifyNeededInputs === 'function') {
69
- return await this.wrapped.identifyNeededInputs(beef, offChainValues)
70
- }
71
- return []
72
- }
73
-
74
- async getDocumentation (): Promise<string> {
75
- return await this.wrapped.getDocumentation()
76
- }
77
-
78
- async getMetaData (): Promise<{
79
- name: string
80
- shortDescription: string
81
- iconURL?: string
82
- version?: string
83
- informationURL?: string
84
- }> {
85
- return await this.wrapped.getMetaData()
86
- }
87
- }
package/src/BanService.ts DELETED
@@ -1,154 +0,0 @@
1
- import { Db, Collection } from 'mongodb'
2
-
3
- /**
4
- * Represents a banned record in the persistent ban list.
5
- * Bans survive server restarts, GASP re-syncs, and janitor runs.
6
- */
7
- export interface BannedRecord {
8
- type: 'domain' | 'outpoint'
9
- /** For domain bans: the domain URL. For outpoint bans: "txid.outputIndex" */
10
- value: string
11
- /** For outpoint bans, the associated domain (for reference) */
12
- domain?: string
13
- /** Human-readable reason for the ban */
14
- reason?: string
15
- /** When the ban was created */
16
- bannedAt: Date
17
- /** Identity key of the admin who created the ban */
18
- bannedBy?: string
19
- }
20
-
21
- /**
22
- * BanService provides a persistent ban list stored in MongoDB.
23
- *
24
- * When the Janitor or an admin removes a SHIP/SLAP token, the associated
25
- * domain or outpoint can be added to the ban list. The BanAwareLookupWrapper
26
- * checks this list before admitting new outputs, preventing GASP from
27
- * re-syncing previously removed stale tokens.
28
- */
29
- export class BanService {
30
- private readonly bans: Collection<BannedRecord>
31
-
32
- constructor (db: Db) {
33
- this.bans = db.collection<BannedRecord>('bannedRecords')
34
- }
35
-
36
- /**
37
- * Sanitizes a value for use in MongoDB queries, preventing NoSQL injection.
38
- * Ensures the value is a plain string and rejects objects/arrays that could
39
- * contain MongoDB operators like $ne, $gt, etc.
40
- */
41
- private sanitize (value: unknown): string {
42
- if (typeof value !== 'string') {
43
- throw new TypeError('Invalid input: expected a string value')
44
- }
45
- return value
46
- }
47
-
48
- /**
49
- * Creates indexes for efficient ban lookups.
50
- */
51
- async ensureIndexes (): Promise<void> {
52
- await this.bans.createIndex({ type: 1, value: 1 }, { unique: true })
53
- await this.bans.createIndex({ bannedAt: -1 })
54
- }
55
-
56
- /**
57
- * Bans a domain, preventing any SHIP/SLAP tokens referencing it from being stored.
58
- */
59
- async banDomain (domain: string, reason?: string, bannedBy?: string): Promise<void> {
60
- const safeDomain = this.sanitize(domain)
61
- await this.bans.updateOne(
62
- { type: 'domain', value: safeDomain },
63
- {
64
- $set: {
65
- type: 'domain',
66
- value: safeDomain,
67
- reason: reason ?? 'Manually banned',
68
- bannedAt: new Date(),
69
- bannedBy
70
- }
71
- },
72
- { upsert: true }
73
- )
74
- }
75
-
76
- /**
77
- * Removes a domain ban.
78
- */
79
- async unbanDomain (domain: string): Promise<void> {
80
- await this.bans.deleteOne({ type: 'domain', value: this.sanitize(domain) })
81
- }
82
-
83
- /**
84
- * Checks if a domain is banned.
85
- */
86
- async isDomainBanned (domain: string): Promise<boolean> {
87
- const record = await this.bans.findOne({ type: 'domain', value: this.sanitize(domain) })
88
- return record !== null
89
- }
90
-
91
- /**
92
- * Bans a specific outpoint (txid.outputIndex), preventing it from being re-admitted.
93
- */
94
- async banOutpoint (txid: string, outputIndex: number, reason?: string, domain?: string, bannedBy?: string): Promise<void> {
95
- const value = `${this.sanitize(txid)}.${Number(outputIndex)}`
96
- await this.bans.updateOne(
97
- { type: 'outpoint', value },
98
- {
99
- $set: {
100
- type: 'outpoint',
101
- value,
102
- domain: domain != null ? this.sanitize(domain) : undefined,
103
- reason: reason ?? 'Manually banned',
104
- bannedAt: new Date(),
105
- bannedBy
106
- }
107
- },
108
- { upsert: true }
109
- )
110
- }
111
-
112
- /**
113
- * Removes an outpoint ban.
114
- */
115
- async unbanOutpoint (txid: string, outputIndex: number): Promise<void> {
116
- const value = `${this.sanitize(txid)}.${Number(outputIndex)}`
117
- await this.bans.deleteOne({ type: 'outpoint', value })
118
- }
119
-
120
- /**
121
- * Checks if a specific outpoint is banned.
122
- */
123
- async isOutpointBanned (txid: string, outputIndex: number): Promise<boolean> {
124
- const value = `${this.sanitize(txid)}.${Number(outputIndex)}`
125
- const record = await this.bans.findOne({ type: 'outpoint', value })
126
- return record !== null
127
- }
128
-
129
- /**
130
- * Lists all bans, optionally filtered by type.
131
- */
132
- async listBans (type?: 'domain' | 'outpoint'): Promise<BannedRecord[]> {
133
- const query = typeof type === 'string' ? { type } : {}
134
- return await this.bans.find(query).sort({ bannedAt: -1 }).toArray()
135
- }
136
-
137
- /**
138
- * Removes a ban by type and value.
139
- */
140
- async removeBan (type: 'domain' | 'outpoint', value: string): Promise<void> {
141
- await this.bans.deleteOne({ type: this.sanitize(type) as 'domain' | 'outpoint', value: this.sanitize(value) })
142
- }
143
-
144
- /**
145
- * Returns ban statistics.
146
- */
147
- async getStats (): Promise<{ domainBans: number, outpointBans: number, totalBans: number }> {
148
- const [domainBans, outpointBans] = await Promise.all([
149
- this.bans.countDocuments({ type: 'domain' }),
150
- this.bans.countDocuments({ type: 'outpoint' })
151
- ])
152
- return { domainBans, outpointBans, totalBans: domainBans + outpointBans }
153
- }
154
- }