@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.
- package/dist/cjs/mod.js +7 -1
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +3 -1
- package/dist/cjs/src/BanAwareLookupWrapper.js +76 -0
- package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -0
- package/dist/cjs/src/BanService.js +118 -0
- package/dist/cjs/src/BanService.js.map +1 -0
- package/dist/cjs/src/JanitorService.js +206 -93
- package/dist/cjs/src/JanitorService.js.map +1 -1
- package/dist/cjs/src/OverlayExpress.js +522 -71
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/src/makeUserInterface.js +889 -217
- package/dist/cjs/src/makeUserInterface.js.map +1 -1
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js +4 -1
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/BanAwareLookupWrapper.js +78 -0
- package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -0
- package/dist/esm/src/BanService.js +115 -0
- package/dist/esm/src/BanService.js.map +1 -0
- package/dist/esm/src/JanitorService.js +199 -92
- package/dist/esm/src/JanitorService.js.map +1 -1
- package/dist/esm/src/OverlayExpress.js +528 -72
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/src/makeUserInterface.js +889 -217
- package/dist/esm/src/makeUserInterface.js.map +1 -1
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +4 -1
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/BanAwareLookupWrapper.d.ts +31 -0
- package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -0
- package/dist/types/src/BanService.d.ts +81 -0
- package/dist/types/src/BanService.d.ts.map +1 -0
- package/dist/types/src/JanitorService.d.ts +69 -13
- package/dist/types/src/JanitorService.d.ts.map +1 -1
- package/dist/types/src/OverlayExpress.d.ts +28 -4
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/src/makeUserInterface.d.ts +2 -0
- package/dist/types/src/makeUserInterface.d.ts.map +1 -1
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +4 -1
- package/package.json +3 -1
- package/src/BanAwareLookupWrapper.ts +95 -0
- package/src/BanService.ts +154 -0
- package/src/JanitorService.ts +277 -101
- package/src/OverlayExpress.ts +575 -76
- package/src/__tests__/BanAwareLookupWrapper.test.ts +255 -0
- package/src/__tests__/BanService.test.ts +310 -0
- package/src/__tests__/JanitorService.test.ts +342 -5
- package/src/__tests__/OverlayExpress.test.ts +19 -6
- package/src/__tests__/makeUserInterface.test.ts +4 -3
- package/src/makeUserInterface.ts +892 -217
package/mod.ts
CHANGED
|
@@ -1 +1,4 @@
|
|
|
1
|
-
export { default } from
|
|
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.
|
|
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
|
+
}
|