@bsv/overlay-express 2.0.2 → 2.1.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 (52) hide show
  1. package/dist/cjs/mod.js +7 -1
  2. package/dist/cjs/mod.js.map +1 -1
  3. package/dist/cjs/package.json +3 -1
  4. package/dist/cjs/src/BanAwareLookupWrapper.js +76 -0
  5. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -0
  6. package/dist/cjs/src/BanService.js +118 -0
  7. package/dist/cjs/src/BanService.js.map +1 -0
  8. package/dist/cjs/src/JanitorService.js +206 -93
  9. package/dist/cjs/src/JanitorService.js.map +1 -1
  10. package/dist/cjs/src/OverlayExpress.js +522 -71
  11. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  12. package/dist/cjs/src/makeUserInterface.js +889 -217
  13. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  14. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  15. package/dist/esm/mod.js +4 -1
  16. package/dist/esm/mod.js.map +1 -1
  17. package/dist/esm/src/BanAwareLookupWrapper.js +78 -0
  18. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -0
  19. package/dist/esm/src/BanService.js +115 -0
  20. package/dist/esm/src/BanService.js.map +1 -0
  21. package/dist/esm/src/JanitorService.js +199 -92
  22. package/dist/esm/src/JanitorService.js.map +1 -1
  23. package/dist/esm/src/OverlayExpress.js +528 -72
  24. package/dist/esm/src/OverlayExpress.js.map +1 -1
  25. package/dist/esm/src/makeUserInterface.js +889 -217
  26. package/dist/esm/src/makeUserInterface.js.map +1 -1
  27. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  28. package/dist/types/mod.d.ts +4 -1
  29. package/dist/types/mod.d.ts.map +1 -1
  30. package/dist/types/src/BanAwareLookupWrapper.d.ts +31 -0
  31. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -0
  32. package/dist/types/src/BanService.d.ts +81 -0
  33. package/dist/types/src/BanService.d.ts.map +1 -0
  34. package/dist/types/src/JanitorService.d.ts +69 -13
  35. package/dist/types/src/JanitorService.d.ts.map +1 -1
  36. package/dist/types/src/OverlayExpress.d.ts +28 -4
  37. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  38. package/dist/types/src/makeUserInterface.d.ts +2 -0
  39. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  40. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  41. package/mod.ts +4 -1
  42. package/package.json +3 -1
  43. package/src/BanAwareLookupWrapper.ts +95 -0
  44. package/src/BanService.ts +154 -0
  45. package/src/JanitorService.ts +277 -101
  46. package/src/OverlayExpress.ts +575 -76
  47. package/src/__tests__/BanAwareLookupWrapper.test.ts +255 -0
  48. package/src/__tests__/BanService.test.ts +310 -0
  49. package/src/__tests__/JanitorService.test.ts +342 -5
  50. package/src/__tests__/OverlayExpress.test.ts +19 -6
  51. package/src/__tests__/makeUserInterface.test.ts +4 -3
  52. package/src/makeUserInterface.ts +892 -217
package/mod.ts CHANGED
@@ -1 +1,4 @@
1
- export { default } from "./src/OverlayExpress.js"
1
+ export { default } from './src/OverlayExpress.js'
2
+ export { BanService, type BannedRecord } from './src/BanService.js'
3
+ export { BanAwareLookupWrapper } from './src/BanAwareLookupWrapper.js'
4
+ export { JanitorService, type JanitorConfig, type JanitorReport, type HostHealthResult } from './src/JanitorService.js'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bsv/overlay-express",
3
- "version": "2.0.2",
3
+ "version": "2.1.1",
4
4
  "type": "module",
5
5
  "description": "BSV Blockchain Overlay Express",
6
6
  "main": "dist/cjs/mod.js",
@@ -65,9 +65,11 @@
65
65
  "typescript": "^5.2.2"
66
66
  },
67
67
  "dependencies": {
68
+ "@bsv/auth-express-middleware": "^2.0.2",
68
69
  "@bsv/overlay": "^2.0.2",
69
70
  "@bsv/overlay-discovery-services": "^2.0.2",
70
71
  "@bsv/sdk": "^2.0.4",
72
+ "@bsv/wallet-toolbox-client": "^2.0.20",
71
73
  "body-parser": "^2.2.2",
72
74
  "chalk": "^5.6.2",
73
75
  "express": "^5.2.1",
@@ -0,0 +1,95 @@
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
+ }
@@ -0,0 +1,154 @@
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 Error('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 !== undefined ? 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
+ }