@genobank/biofs 1.3.4 → 1.4.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 (42) hide show
  1. package/BIONFS_DEPLOYMENT_GUIDE.md +408 -0
  2. package/BIONFS_MOUNT_INTEGRATION_PLAN.md +415 -0
  3. package/BIONFS_PROTOCOL_SPECIFICATION.md +688 -0
  4. package/BIONFS_SEQUENTIAS_INTEGRATION.md +457 -0
  5. package/BIONFT_NFS_PROTOCOL_ARCHITECTURE.md +583 -0
  6. package/GDPR_BIONFS_CONSENT_ARCHITECTURE.md +798 -0
  7. package/GDPR_BIONFS_IMPLEMENTATION_STATUS.md +462 -0
  8. package/SEQUENTIAS_PROTOCOL_ARCHITECTURE.md +880 -0
  9. package/ULTRATHINK_BIONFS_COMPLETE.md +458 -0
  10. package/WEB3FUSE_LICENSE_TOKEN_ANALYSIS.md +494 -0
  11. package/WHERE_PERMISSIONS_LIVE.md +165 -0
  12. package/dist/commands/access/revoke-consent.d.ts +13 -0
  13. package/dist/commands/access/revoke-consent.d.ts.map +1 -0
  14. package/dist/commands/access/revoke-consent.js +171 -0
  15. package/dist/commands/access/revoke-consent.js.map +1 -0
  16. package/dist/commands/download-with-consent.d.ts +12 -0
  17. package/dist/commands/download-with-consent.d.ts.map +1 -0
  18. package/dist/commands/download-with-consent.js +126 -0
  19. package/dist/commands/download-with-consent.js.map +1 -0
  20. package/dist/commands/mount.d.ts +11 -0
  21. package/dist/commands/mount.d.ts.map +1 -0
  22. package/dist/commands/mount.js +179 -0
  23. package/dist/commands/mount.js.map +1 -0
  24. package/dist/index.js +46 -10
  25. package/dist/index.js.map +1 -1
  26. package/dist/lib/biofiles/resolver.d.ts.map +1 -1
  27. package/dist/lib/biofiles/resolver.js +6 -1
  28. package/dist/lib/biofiles/resolver.js.map +1 -1
  29. package/dist/lib/consent/consent-manager.d.ts +34 -0
  30. package/dist/lib/consent/consent-manager.d.ts.map +1 -0
  31. package/dist/lib/consent/consent-manager.js +96 -0
  32. package/dist/lib/consent/consent-manager.js.map +1 -0
  33. package/dist/lib/consent/consent-prompt.d.ts +27 -0
  34. package/dist/lib/consent/consent-prompt.d.ts.map +1 -0
  35. package/dist/lib/consent/consent-prompt.js +118 -0
  36. package/dist/lib/consent/consent-prompt.js.map +1 -0
  37. package/dist/types/biofiles.d.ts +3 -0
  38. package/dist/types/biofiles.d.ts.map +1 -1
  39. package/lib/bionfs-client.js +125 -0
  40. package/lib/consent-manager.js +88 -0
  41. package/lib/consent-prompt.js +118 -0
  42. package/package.json +2 -2
@@ -0,0 +1,457 @@
1
+ # 🧬 BioNFS + Sequentias Blockchain Integration
2
+
3
+ ## 🎯 CRITICAL REALIZATION
4
+
5
+ **You already have a Sequentias blockchain running!** This changes everything about our BioNFS architecture.
6
+
7
+ ---
8
+
9
+ ## 📊 Current Sequentias Infrastructure
10
+
11
+ ### **Running Node:**
12
+ - **Instance**: `sequentias-single-node` (i-0b8a8eb879dbba2f1)
13
+ - **Type**: t3.small
14
+ - **Public IP**: 52.90.163.112
15
+ - **Status**: ✅ Running (since Sep 30, 2025)
16
+ - **Current Block**: #48,987+
17
+ - **Block Time**: ~12 seconds (Clique PoA)
18
+
19
+ ### **Blockchain Details:**
20
+ ```
21
+ Network: Sequentias-Network
22
+ Chain ID: 15132025
23
+ Consensus: Clique PoA (Proof of Authority)
24
+ Validator: 0x088ebE307b4200A62dC6190d0Ac52D55bcABac11
25
+ RPC Endpoint: http://52.90.163.112:8545
26
+ WebSocket: ws://52.90.163.112:8545
27
+ P2P: tcp://52.90.163.112:30303
28
+ ```
29
+
30
+ ### **Smart Contracts (Pre-Deployed in Genesis):**
31
+ ✅ **BioAssetRegistry** - `0x1000000000000000000000000000000000000001`
32
+ ✅ **ConsentRegistry** - `0x1000000000000000000000000000000000000002`
33
+ ✅ **SEQ Token (ERC20)** - (to be verified)
34
+ ✅ **ProvenanceTracker** - (to be verified)
35
+ ✅ **LicenseRegistry** - (to be verified)
36
+
37
+ ---
38
+
39
+ ## 🏗️ UPDATED BioNFS Architecture (With Sequentias Integration)
40
+
41
+ ### **Previous Plan (Before Discovery):**
42
+ ```
43
+ Sessions: DynamoDB or Cassandra
44
+ Permissions: Story Protocol (external blockchain)
45
+ ```
46
+
47
+ ### **NEW Plan (With Sequentias):**
48
+ ```
49
+ Sessions: DynamoDB (Phase 1) → Cassandra (Phase 2)
50
+ Permissions: SEQUENTIAS BLOCKCHAIN ✅ (source of truth!)
51
+ ```
52
+
53
+ ---
54
+
55
+ ## 📐 Complete Architecture Diagram
56
+
57
+ ```
58
+ ┌────────────────────────────────────────────────────────────┐
59
+ │ CLIENT (User's Computer) │
60
+ │ ┌──────────────────────────────────────────────────────┐ │
61
+ │ │ FUSE Layer (web3fuse) │ │
62
+ │ │ Mount: /mnt/genomics/ │ │
63
+ │ └──────────────┬───────────────────────────────────────┘ │
64
+ │ │ │
65
+ │ ┌──────────────▼───────────────────────────────────────┐ │
66
+ │ │ BioNFS Client Library (libbionfs) │ │
67
+ │ │ - Web3 authentication │ │
68
+ │ │ - Session management │ │
69
+ │ │ - Chunk streaming │ │
70
+ │ └──────────────┬───────────────────────────────────────┘ │
71
+ └─────────────────┼──────────────────────────────────────────┘
72
+ │
73
+ BioNFS Protocol
74
+ (HTTP/2 + WebSocket)
75
+ │
76
+ ┌─────────────────▼──────────────────────────────────────────┐
77
+ │ BioNFS SERVER (genobank.app) │
78
+ │ ┌──────────────────────────────────────────────────────┐ │
79
+ │ │ Authentication Layer │ │
80
+ │ │ - Verify Web3 signature │ │
81
+ │ │ - Create session (DynamoDB) │ │
82
+ │ │ - Query Sequentias for permissions │ │
83
+ │ └──────────────┬───────────────────────────────────────┘ │
84
+ │ │ │
85
+ │ ┌──────────────▼───────────────────────────────────────┐ │
86
+ │ │ Permission Layer (Sequentias Integration) │ │
87
+ │ │ - Query ConsentRegistry smart contract │ │
88
+ │ │ - Query LicenseRegistry smart contract │ │
89
+ │ │ - Cache results in MongoDB │ │
90
+ │ └──────────────┬───────────────────────────────────────┘ │
91
+ │ │ │
92
+ │ ┌──────────────▼───────────────────────────────────────┐ │
93
+ │ │ File Access Layer │ │
94
+ │ │ - Query BioAssetRegistry (get S3 path) │ │
95
+ │ │ - Verify ProvenanceTracker (data lineage) │ │
96
+ │ │ - Stream from S3 │ │
97
+ │ └──────────────┬───────────────────────────────────────┘ │
98
+ └─────────────────┼──────────────────────────────────────────┘
99
+ │
100
+ ┌──────────┼──────────┬──────────────┐
101
+ │ │ │ │
102
+ ▼ ▼ ▼ ▼
103
+ DynamoDB MongoDB S3 Buckets SEQUENTIAS BLOCKCHAIN
104
+ (Sessions) (Cache) (Files) (Source of Truth)
105
+ ┌──────────────────────┐
106
+ │ Smart Contracts: │
107
+ │ • ConsentRegistry │
108
+ │ • LicenseRegistry │
109
+ │ • BioAssetRegistry │
110
+ │ • ProvenanceTracker │
111
+ │ • SEQ Token (ERC20) │
112
+ └──────────────────────┘
113
+ ```
114
+
115
+ ---
116
+
117
+ ## 🔗 Integration Points
118
+
119
+ ### **1. Authentication Flow**
120
+
121
+ ```python
122
+ # BioNFS Server: /bionfs/v1/auth
123
+
124
+ async def authenticate(wallet: str, signature: str):
125
+ # Step 1: Verify Web3 signature (EIP-191)
126
+ recovered = ecrecover(signature, "BioNFS Access Request")
127
+ if recovered != wallet:
128
+ raise HTTPException(401, "Invalid signature")
129
+
130
+ # Step 2: Query Sequentias blockchain for permissions
131
+ web3 = Web3(Web3.HTTPProvider('http://52.90.163.112:8545'))
132
+
133
+ # ConsentRegistry: What can this wallet access?
134
+ consent_contract = web3.eth.contract(
135
+ address='0x1000000000000000000000000000000000000002',
136
+ abi=CONSENT_REGISTRY_ABI
137
+ )
138
+
139
+ # Get all biosamples this wallet has consent for
140
+ granted_consents = consent_contract.functions.getUserConsents(wallet).call()
141
+
142
+ # LicenseRegistry: What license tokens does this wallet hold?
143
+ license_contract = web3.eth.contract(
144
+ address=LICENSE_REGISTRY_ADDRESS,
145
+ abi=LICENSE_REGISTRY_ABI
146
+ )
147
+
148
+ granted_licenses = license_contract.functions.getUserLicenses(wallet).call()
149
+
150
+ # Step 3: Build granted files list
151
+ granted_files = []
152
+
153
+ for consent in granted_consents:
154
+ biosample_serial = consent['biosampleSerial']
155
+ # Query BioAssetRegistry for this biosample's files
156
+ bioassets = bioasset_contract.functions.getBiosampleAssets(
157
+ biosample_serial
158
+ ).call()
159
+ granted_files.extend(bioassets)
160
+
161
+ for license in granted_licenses:
162
+ ip_id = license['ipId']
163
+ granted_files.append(ip_id)
164
+
165
+ # Step 4: Create session in DynamoDB (cache)
166
+ session = await session_storage.create_session(
167
+ wallet=wallet,
168
+ granted_files=granted_files,
169
+ expires_at=time.time() + 86400 # 24 hours
170
+ )
171
+
172
+ # Step 5: Cache permissions in MongoDB (faster subsequent queries)
173
+ mongodb.update_one(
174
+ {"wallet": wallet},
175
+ {"$set": {
176
+ "granted_files": granted_files,
177
+ "updated_at": datetime.utcnow()
178
+ }},
179
+ upsert=True
180
+ )
181
+
182
+ return {
183
+ "session_token": session['session_token'],
184
+ "expires_at": session['expires_at'],
185
+ "granted_files": granted_files
186
+ }
187
+ ```
188
+
189
+ ### **2. File Access Flow**
190
+
191
+ ```python
192
+ # BioNFS Server: /bionfs/v1/stream/{ip_id}
193
+
194
+ async def stream_file(ip_id: str, session_token: str):
195
+ # Step 1: Verify session (DynamoDB - fast!)
196
+ session = await session_storage.get_session(session_token)
197
+ if not session:
198
+ raise HTTPException(401, "Session expired")
199
+
200
+ # Step 2: Check cached permission (MongoDB - faster!)
201
+ cache = mongodb.find_one({"wallet": session['wallet']})
202
+ if ip_id in cache.get('granted_files', []):
203
+ # Permission cached, proceed
204
+ pass
205
+ else:
206
+ # Step 3: Verify on Sequentias blockchain (source of truth)
207
+ web3 = Web3(Web3.HTTPProvider('http://52.90.163.112:8545'))
208
+
209
+ # Check ConsentRegistry
210
+ consent_valid = consent_contract.functions.verifyConsent(
211
+ ip_id,
212
+ session['wallet']
213
+ ).call()
214
+
215
+ # Check LicenseRegistry
216
+ license_valid = license_contract.functions.verifyLicense(
217
+ ip_id,
218
+ session['wallet'],
219
+ "read" # permission type
220
+ ).call()
221
+
222
+ if not (consent_valid or license_valid):
223
+ raise HTTPException(403, "Access denied")
224
+
225
+ # Update cache
226
+ mongodb.update_one(
227
+ {"wallet": session['wallet']},
228
+ {"$addToSet": {"granted_files": ip_id}}
229
+ )
230
+
231
+ # Step 4: Get file metadata from BioAssetRegistry
232
+ bioasset = bioasset_contract.functions.getBioAsset(ip_id).call()
233
+ s3_path = bioasset['s3Path']
234
+ file_size = bioasset['fileSize']
235
+
236
+ # Step 5: Stream from S3 (bypass presigned URLs!)
237
+ async def chunk_generator():
238
+ s3_client = boto3.client('s3')
239
+ response = s3_client.get_object(
240
+ Bucket='test.vault.genoverse.io',
241
+ Key=s3_path
242
+ )
243
+
244
+ for chunk in response['Body'].iter_chunks(chunk_size=1024*1024):
245
+ yield chunk
246
+
247
+ return StreamingResponse(
248
+ chunk_generator(),
249
+ media_type="application/octet-stream",
250
+ headers={
251
+ "Content-Disposition": f"attachment; filename={bioasset['name']}",
252
+ "X-BioNFS-IP-ID": ip_id,
253
+ "X-BioNFS-File-Size": str(file_size)
254
+ }
255
+ )
256
+ ```
257
+
258
+ ### **3. REVOKE Flow (GDPR Compliance)**
259
+
260
+ ```python
261
+ # BioNFS Server: /bionfs/v1/revoke
262
+
263
+ async def revoke_access(ip_id: str, wallet: str, signature: str):
264
+ # Step 1: Verify requester is owner
265
+ web3 = Web3(Web3.HTTPProvider('http://52.90.163.112:8545'))
266
+
267
+ bioasset = bioasset_contract.functions.getBioAsset(ip_id).call()
268
+ if bioasset['owner'].lower() != wallet.lower():
269
+ raise HTTPException(403, "Only owner can revoke")
270
+
271
+ # Step 2: Revoke consent on Sequentias blockchain
272
+ tx = consent_contract.functions.revokeConsent(
273
+ ip_id
274
+ ).build_transaction({
275
+ 'from': wallet,
276
+ 'nonce': web3.eth.get_transaction_count(wallet),
277
+ 'gas': 200000,
278
+ 'gasPrice': web3.eth.gas_price
279
+ })
280
+
281
+ # Sign transaction with owner's wallet
282
+ signed_tx = web3.eth.account.sign_transaction(tx, owner_private_key)
283
+ tx_hash = web3.eth.send_raw_transaction(signed_tx.rawTransaction)
284
+
285
+ # Wait for confirmation
286
+ receipt = web3.eth.wait_for_transaction_receipt(tx_hash)
287
+
288
+ # Step 3: Invalidate all sessions accessing this file
289
+ sessions_to_invalidate = mongodb.find({
290
+ "granted_files": ip_id
291
+ })
292
+
293
+ for session_data in sessions_to_invalidate:
294
+ # Remove from granted list
295
+ session_token = session_data['session_token']
296
+ session = await session_storage.get_session(session_token)
297
+ session['granted_files'].remove(ip_id)
298
+ await session_storage.update_session(session_token, session)
299
+
300
+ # Step 4: Clear MongoDB cache
301
+ mongodb.update_many(
302
+ {"granted_files": ip_id},
303
+ {"$pull": {"granted_files": ip_id}}
304
+ )
305
+
306
+ # Step 5: Delete from S3 (right to erasure)
307
+ s3_client.delete_object(
308
+ Bucket='test.vault.genoverse.io',
309
+ Key=bioasset['s3Path']
310
+ )
311
+
312
+ # Step 6: Emit event
313
+ emit_revocation_event(ip_id, wallet, tx_hash)
314
+
315
+ return {
316
+ "status": "success",
317
+ "tx_hash": tx_hash.hex(),
318
+ "message": "All access revoked and data deleted"
319
+ }
320
+ ```
321
+
322
+ ---
323
+
324
+ ## 🚀 Implementation Roadmap (UPDATED)
325
+
326
+ ### **Week 1: BioNFS Server Foundation**
327
+
328
+ #### Day 1: Sequentias Integration
329
+ ```bash
330
+ # Connect to existing Sequentias blockchain
331
+ ✅ Add Web3 provider: http://52.90.163.112:8545
332
+ ✅ Load smart contract ABIs
333
+ ✅ Test ConsentRegistry.verifyConsent()
334
+ ✅ Test LicenseRegistry.verifyLicense()
335
+ ✅ Test BioAssetRegistry.getBioAsset()
336
+ ```
337
+
338
+ #### Day 2: DynamoDB Session Storage
339
+ ```bash
340
+ ✅ Create bionfs_sessions table
341
+ ✅ Enable TTL (24-hour auto-expire)
342
+ ✅ Implement SessionStorageManager
343
+ ✅ Test session creation/retrieval
344
+ ```
345
+
346
+ #### Day 3: Authentication Endpoint
347
+ ```bash
348
+ ✅ POST /bionfs/v1/auth
349
+ - Verify Web3 signature
350
+ - Query Sequentias for permissions
351
+ - Create DynamoDB session
352
+ - Cache in MongoDB
353
+ ```
354
+
355
+ #### Day 4: File Access Endpoints
356
+ ```bash
357
+ ✅ GET /bionfs/v1/stream/{ip_id}
358
+ - Verify session
359
+ - Check permissions (cache → blockchain)
360
+ - Query BioAssetRegistry for S3 path
361
+ - Stream from S3
362
+ ```
363
+
364
+ #### Day 5: Testing & Documentation
365
+ ```bash
366
+ ✅ End-to-end testing
367
+ ✅ Performance benchmarks
368
+ ✅ API documentation
369
+ ✅ Deploy to production
370
+ ```
371
+
372
+ ---
373
+
374
+ ## 🔧 Required Environment Variables
375
+
376
+ ```bash
377
+ # /home/ubuntu/Genobank_APIs/bionfs_server/.env
378
+
379
+ # Sequentias Blockchain
380
+ SEQUENTIAS_RPC_URL=http://52.90.163.112:8545
381
+ SEQUENTIAS_CHAIN_ID=15132025
382
+ SEQUENTIAS_NETWORK_NAME=sequentias
383
+
384
+ # Smart Contract Addresses
385
+ BIOASSET_REGISTRY_ADDRESS=0x1000000000000000000000000000000000000001
386
+ CONSENT_REGISTRY_ADDRESS=0x1000000000000000000000000000000000000002
387
+ LICENSE_REGISTRY_ADDRESS=0x1000000000000000000000000000000000000003 # Verify
388
+ PROVENANCE_TRACKER_ADDRESS=0x1000000000000000000000000000000000000004 # Verify
389
+ SEQ_TOKEN_ADDRESS=0x1000000000000000000000000000000000000005 # Verify
390
+
391
+ # Session Storage (DynamoDB)
392
+ AWS_REGION=us-east-1
393
+ DYNAMODB_TABLE_NAME=bionfs_sessions
394
+
395
+ # Cache (MongoDB)
396
+ MONGO_DB_HOST=mongodb+srv://cluster... # Existing GenoBank MongoDB
397
+ MONGO_DB_NAME=genobank-api
398
+
399
+ # S3 Storage
400
+ S3_BUCKET=test.vault.genoverse.io
401
+ AWS_ACCESS_KEY_ID=...
402
+ AWS_SECRET_ACCESS_KEY=...
403
+ ```
404
+
405
+ ---
406
+
407
+ ## 💡 KEY ADVANTAGES
408
+
409
+ ### **1. Single Source of Truth**
410
+ ```
411
+ Before: Story Protocol (external) + MongoDB (cache) = potential inconsistency
412
+ After: Sequentias (owned) + MongoDB (cache) = full control
413
+ ```
414
+
415
+ ### **2. GDPR Compliance Built-In**
416
+ ```
417
+ ConsentRegistry.sol already has:
418
+ - grantConsent()
419
+ - revokeConsent()
420
+ - verifyConsent()
421
+
422
+ BioNFS just needs to INTEGRATE, not re-implement! ✅
423
+ ```
424
+
425
+ ### **3. Performance**
426
+ ```
427
+ Without Cache:
428
+ Sequentias RPC call: ~50ms (local network)
429
+
430
+ With MongoDB Cache:
431
+ First access: 50ms (query blockchain + cache)
432
+ Subsequent: <5ms (MongoDB lookup)
433
+
434
+ 24-hour session = only verify once per day!
435
+ ```
436
+
437
+ ### **4. Cost Efficiency**
438
+ ```
439
+ Sequentias Gas Costs: $0 (you own the validator!)
440
+ DynamoDB: $0 (free tier)
441
+ MongoDB: Already running
442
+ S3: Existing infrastructure
443
+
444
+ Total new cost: $0 🚀
445
+ ```
446
+
447
+ ---
448
+
449
+ ## 📋 Next Steps
450
+
451
+ 1. ✅ **Extract Smart Contract ABIs** from Sequentias-Network repository
452
+ 2. ✅ **Create BioNFS server skeleton** with Web3 integration
453
+ 3. ✅ **Implement authentication endpoint** with Sequentias queries
454
+ 4. ✅ **Test end-to-end flow** with existing Sequentias blockchain
455
+ 5. ✅ **Deploy BioNFS server** to genobank.app
456
+
457
+ **Should we start building the BioNFS server with Sequentias integration now?** 🧬