@genobank/biofs 2.4.1 → 2.5.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 (153) hide show
  1. package/CHANGELOG.md +2 -0
  2. package/LICENSE +37 -0
  3. package/README.md +2 -1
  4. package/bin/biofs.js +2 -1
  5. package/contracts/ClaraJobNFT.sol +101 -0
  6. package/dist/commands/agent/health.js +1 -1
  7. package/dist/commands/agent/health.js.map +1 -1
  8. package/dist/commands/agent/list.d.ts +14 -0
  9. package/dist/commands/agent/list.d.ts.map +1 -0
  10. package/dist/commands/agent/list.js +101 -0
  11. package/dist/commands/agent/list.js.map +1 -0
  12. package/dist/commands/agent/register.d.ts +18 -0
  13. package/dist/commands/agent/register.d.ts.map +1 -0
  14. package/dist/commands/agent/register.js +120 -0
  15. package/dist/commands/agent/register.js.map +1 -0
  16. package/dist/commands/agent/status.d.ts +14 -0
  17. package/dist/commands/agent/status.d.ts.map +1 -0
  18. package/dist/commands/agent/status.js +151 -0
  19. package/dist/commands/agent/status.js.map +1 -0
  20. package/dist/commands/annotate/status.d.ts +11 -0
  21. package/dist/commands/annotate/status.d.ts.map +1 -0
  22. package/dist/commands/annotate/status.js +123 -0
  23. package/dist/commands/annotate/status.js.map +1 -0
  24. package/dist/commands/annotate/submit.d.ts +23 -0
  25. package/dist/commands/annotate/submit.d.ts.map +1 -0
  26. package/dist/commands/annotate/submit.js +296 -0
  27. package/dist/commands/annotate/submit.js.map +1 -0
  28. package/dist/commands/family-status.d.ts +12 -0
  29. package/dist/commands/family-status.d.ts.map +1 -0
  30. package/dist/commands/family-status.js +220 -0
  31. package/dist/commands/family-status.js.map +1 -0
  32. package/dist/commands/job/status.d.ts +1 -0
  33. package/dist/commands/job/status.d.ts.map +1 -1
  34. package/dist/commands/job/status.js.map +1 -1
  35. package/dist/commands/link-clara.d.ts +20 -0
  36. package/dist/commands/link-clara.d.ts.map +1 -0
  37. package/dist/commands/link-clara.js +234 -0
  38. package/dist/commands/link-clara.js.map +1 -0
  39. package/dist/commands/mount-remote.d.ts +1 -1
  40. package/dist/commands/mount-remote.js +1 -1
  41. package/dist/commands/payment/balance.d.ts +12 -0
  42. package/dist/commands/payment/balance.d.ts.map +1 -0
  43. package/dist/commands/payment/balance.js +101 -0
  44. package/dist/commands/payment/balance.js.map +1 -0
  45. package/dist/commands/payment/faucet.d.ts +11 -0
  46. package/dist/commands/payment/faucet.d.ts.map +1 -0
  47. package/dist/commands/payment/faucet.js +92 -0
  48. package/dist/commands/payment/faucet.js.map +1 -0
  49. package/dist/commands/payment/history.d.ts +27 -0
  50. package/dist/commands/payment/history.d.ts.map +1 -0
  51. package/dist/commands/payment/history.js +162 -0
  52. package/dist/commands/payment/history.js.map +1 -0
  53. package/dist/commands/payment/pricing.d.ts +12 -0
  54. package/dist/commands/payment/pricing.d.ts.map +1 -0
  55. package/dist/commands/payment/pricing.js +65 -0
  56. package/dist/commands/payment/pricing.js.map +1 -0
  57. package/dist/commands/payment/setup.d.ts +25 -0
  58. package/dist/commands/payment/setup.d.ts.map +1 -0
  59. package/dist/commands/payment/setup.js +155 -0
  60. package/dist/commands/payment/setup.js.map +1 -0
  61. package/dist/commands/tokenize-biosample.d.ts +19 -0
  62. package/dist/commands/tokenize-biosample.d.ts.map +1 -0
  63. package/dist/commands/tokenize-biosample.js +253 -0
  64. package/dist/commands/tokenize-biosample.js.map +1 -0
  65. package/dist/index.js +281 -13
  66. package/dist/index.js.map +1 -1
  67. package/dist/lib/api/bionft-client.d.ts +35 -7
  68. package/dist/lib/api/bionft-client.d.ts.map +1 -1
  69. package/dist/lib/api/bionft-client.js +106 -16
  70. package/dist/lib/api/bionft-client.js.map +1 -1
  71. package/dist/lib/kite/agent.d.ts +85 -0
  72. package/dist/lib/kite/agent.d.ts.map +1 -0
  73. package/dist/lib/kite/agent.js +332 -0
  74. package/dist/lib/kite/agent.js.map +1 -0
  75. package/dist/lib/kite/index.d.ts +9 -0
  76. package/dist/lib/kite/index.d.ts.map +1 -0
  77. package/dist/lib/kite/index.js +25 -0
  78. package/dist/lib/kite/index.js.map +1 -0
  79. package/dist/lib/kite/passport.d.ts +69 -0
  80. package/dist/lib/kite/passport.d.ts.map +1 -0
  81. package/dist/lib/kite/passport.js +312 -0
  82. package/dist/lib/kite/passport.js.map +1 -0
  83. package/dist/lib/x402/client.d.ts +78 -0
  84. package/dist/lib/x402/client.d.ts.map +1 -0
  85. package/dist/lib/x402/client.js +298 -0
  86. package/dist/lib/x402/client.js.map +1 -0
  87. package/dist/lib/x402/index.d.ts +9 -0
  88. package/dist/lib/x402/index.d.ts.map +1 -0
  89. package/dist/lib/x402/index.js +37 -0
  90. package/dist/lib/x402/index.js.map +1 -0
  91. package/dist/lib/x402/middleware.d.ts +37 -0
  92. package/dist/lib/x402/middleware.d.ts.map +1 -0
  93. package/dist/lib/x402/middleware.js +220 -0
  94. package/dist/lib/x402/middleware.js.map +1 -0
  95. package/dist/types/kite.d.ts +157 -0
  96. package/dist/types/kite.d.ts.map +1 -0
  97. package/dist/types/kite.js +107 -0
  98. package/dist/types/kite.js.map +1 -0
  99. package/dist/types/x402.d.ts +78 -0
  100. package/dist/types/x402.d.ts.map +1 -0
  101. package/dist/types/x402.js +79 -0
  102. package/dist/types/x402.js.map +1 -0
  103. package/docs/AI_AGENT_MCP_MANUAL.md +1029 -0
  104. package/docs/USER_MANUAL.md +603 -0
  105. package/docs/technical-details.html +555 -0
  106. package/lib/bionfs-client.js +2 -0
  107. package/lib/consent-manager.js +2 -0
  108. package/lib/consent-prompt.js +2 -0
  109. package/package.json +9 -3
  110. package/presentation/biofs-x402-kite-presentation.html +813 -0
  111. package/scripts/build_annotator_dictionary.py +1 -0
  112. package/scripts/deploy-clara-nft.js +37 -0
  113. package/test-complete-flow.sh +1 -1
  114. package/test.vcf +1 -0
  115. package/test_23andme.txt +1 -0
  116. package/ADMIN_REGISTER_LAB.md +0 -252
  117. package/ANNOTATOR_RECOMMENDATIONS_API.md +0 -490
  118. package/BIOFS_QUICK_START.md +0 -200
  119. package/BIOFS_TOKENIZE_COMPLETE.md +0 -541
  120. package/BIOFS_V1.2.7_PUBLISHED.md +0 -317
  121. package/BIOFS_V1.2.9_FIXES.md +0 -306
  122. package/BIOFS_V1.3.0_DIRECT_GRANT.md +0 -381
  123. package/BIOFS_V1.3.1_GRANTED_FILES.md +0 -328
  124. package/BIONFS_DEPLOYMENT_GUIDE.md +0 -408
  125. package/BIONFS_MOUNT_INTEGRATION_PLAN.md +0 -415
  126. package/BIONFS_PROTOCOL_SPECIFICATION.md +0 -688
  127. package/BIONFS_SEQUENTIAS_INTEGRATION.md +0 -457
  128. package/BIONFT_GATED_REMOTE_MOUNTING.md +0 -1260
  129. package/BIONFT_NFS_PROTOCOL_ARCHITECTURE.md +0 -583
  130. package/BIOOS_CLI_IMPLEMENTATION_COMPLETE.md +0 -422
  131. package/BIOOS_JOB_MANAGEMENT.md +0 -681
  132. package/BUGFIX_V2.1.3.md +0 -72
  133. package/CHANGELOG_V2.1.0.md +0 -386
  134. package/CHANGELOG_V2.2.0.md +0 -284
  135. package/ENHANCEMENT_DOCUMENTATION.md +0 -218
  136. package/GDPR_BIONFS_CONSENT_ARCHITECTURE.md +0 -798
  137. package/GDPR_BIONFS_IMPLEMENTATION_STATUS.md +0 -462
  138. package/INSTALL_V1.2.7_ON_MAC.md +0 -306
  139. package/LABNFT_BIOFS_INTEGRATION.md +0 -396
  140. package/OPENCRAVAT_ANNOTATORS_REFERENCE.md +0 -340
  141. package/OPENCRAVAT_ANNOTATOR_INTELLIGENCE_COMPLETE.md +0 -479
  142. package/QUICK_START_V2.1.0.md +0 -116
  143. package/RELEASE_SUMMARY_V1.2.7.md +0 -479
  144. package/RELEASE_SUMMARY_V1.3.0.md +0 -324
  145. package/SEQUENTIAS_PROTOCOL_ARCHITECTURE.md +0 -880
  146. package/SEQUENTIA_MIGRATION_GUIDE.md +0 -337
  147. package/SESSION_SUMMARY_DIRECT_GRANT.md +0 -321
  148. package/ULTRATHINK_BIONFS_COMPLETE.md +0 -458
  149. package/WEB3FUSE_LICENSE_TOKEN_ANALYSIS.md +0 -494
  150. package/WHERE_PERMISSIONS_LIVE.md +0 -165
  151. package/config.json +0 -21
  152. package/opencravat_annotators_dictionary.json +0 -2356
  153. package/package.json.working.v1.9.2.20251105_023952 +0 -48
@@ -1,688 +0,0 @@
1
- # 🧬 BioNFS Protocol Specification v1.0
2
-
3
- **Based on IETF NFS v4 Standards** (draft-ietf-nfsv4-internationalization-13)
4
-
5
- ---
6
-
7
- ## 1. Protocol Overview
8
-
9
- **BioNFS** (Biological Network File System) is a blockchain-authenticated network file system protocol designed specifically for genomic data. It extends traditional NFS concepts with:
10
-
11
- - ✅ **Blockchain-native authentication** (Web3 signatures, Story Protocol License Tokens)
12
- - ✅ **Genomics-optimized streaming** (chunk-based delivery for large VCF/BAM/FASTQ files)
13
- - ✅ **License-aware access control** (PIL terms enforcement at protocol level)
14
- - ✅ **GDPR compliance** (audit trail, revocable access)
15
-
16
- ### Key Differences from NFS v4:
17
-
18
- | Feature | NFS v4 | BioNFS |
19
- |---------|--------|--------|
20
- | **Authentication** | Kerberos, GSS-API | Web3 signatures (EIP-191) |
21
- | **File Handles** | Opaque server-generated | IP Asset ID (blockchain address) |
22
- | **Access Control** | POSIX ACLs | Story Protocol License Tokens |
23
- | **String Encoding** | UTF-8 (RFC 3629) | UTF-8 + Ethereum addresses |
24
- | **Session Management** | State management | Blockchain-verified sessions |
25
- | **Internationalization** | Full Unicode support | UTF-8 + hex addresses (0x...) |
26
-
27
- ---
28
-
29
- ## 2. Protocol Architecture
30
-
31
- ### 2.1 Protocol Stack
32
-
33
- ```
34
- ┌─────────────────────────────────────────┐
35
- │ Application Layer (biofs CLI/API) │
36
- └──────────────┬──────────────────────────┘
37
- │
38
- ┌──────────────▼──────────────────────────┐
39
- │ BioNFS Client Library │
40
- │ - Session management │
41
- │ - Web3 signature generation │
42
- │ - Chunk streaming │
43
- └──────────────┬──────────────────────────┘
44
- │
45
- ┌──────────────▼──────────────────────────┐
46
- │ Transport Layer │
47
- │ - HTTP/2 (primary) │
48
- │ - gRPC (optional) │
49
- │ - WebSocket (streaming) │
50
- └──────────────┬──────────────────────────┘
51
- │
52
- ┌──────────────▼──────────────────────────┐
53
- │ TLS 1.3 (Encryption) │
54
- └──────────────┬──────────────────────────┘
55
- │
56
- ▼
57
- Network (TCP/IP)
58
- ```
59
-
60
- ### 2.2 Protocol Versioning
61
-
62
- Following IETF NFS v4 guidelines:
63
-
64
- ```
65
- BioNFS Version: MAJOR.MINOR.PATCH
66
- Example: 1.0.0
67
-
68
- MAJOR: Incompatible protocol changes
69
- MINOR: Backward-compatible feature additions
70
- PATCH: Backward-compatible bug fixes
71
- ```
72
-
73
- **Current Version**: `1.0.0` (Initial release)
74
-
75
- ---
76
-
77
- ## 3. String Encoding (Following IETF NFS v4 Section 10)
78
-
79
- ### 3.1 UTF-8 Encoding
80
-
81
- **From IETF NFS v4 Spec**:
82
- > "All strings within the protocol MUST be encoded as UTF-8"
83
-
84
- **BioNFS Extension**:
85
- All strings MUST be UTF-8 encoded, with the following additions:
86
-
87
- 1. **Ethereum Addresses** (0x-prefixed 40-character hex strings)
88
- ```
89
- Example: 0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7
90
- Format: "0x" + [0-9a-fA-F]{40}
91
- ```
92
-
93
- 2. **Filenames** (UTF-8 with genomics extensions)
94
- ```
95
- Allowed: sample_001.vcf, patient-123.bam, exome_R1.fastq.gz
96
- Forbidden: Non-UTF8 bytes, control characters
97
- ```
98
-
99
- 3. **Session Tokens** (base64url-encoded)
100
- ```
101
- Format: "bionfs_" + base64url(signature + timestamp + random)
102
- Example: bionfs_eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
103
- ```
104
-
105
- ### 3.2 Case Sensitivity
106
-
107
- **Following IETF NFS v4 Section 7**:
108
- > "Servers MAY treat canonically equivalent strings as identical"
109
-
110
- **BioNFS Implementation**:
111
- - **Filenames**: Case-sensitive (genomics convention: `sample001.vcf` ≠ `Sample001.VCF`)
112
- - **Ethereum addresses**: Case-insensitive (checksummed addresses optional)
113
- - **IP Asset IDs**: Case-insensitive
114
-
115
- ```python
116
- # Example: These are equivalent
117
- ip_id_1 = "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7"
118
- ip_id_2 = "0xcce14315ee3d6a41596eeb4a2839ee50a8ec59f7"
119
- assert ip_id_1.lower() == ip_id_2.lower() # True
120
- ```
121
-
122
- ---
123
-
124
- ## 4. Authentication Protocol
125
-
126
- ### 4.1 Web3 Signature Authentication
127
-
128
- **Unlike NFS v4 Kerberos**, BioNFS uses Ethereum signature verification:
129
-
130
- ```
131
- Step 1: Client generates signature
132
- message = "BioNFS Access Request\nTimestamp: 1696636800\nNonce: abc123"
133
- signature = wallet.sign(message) # EIP-191 format
134
-
135
- Step 2: Client sends auth request
136
- POST /bionfs/v1/auth
137
- {
138
- "wallet": "0xb3c3a584491b8ca4df45116a1e250098a0d6192d",
139
- "signature": "0x42226a0eeb5ec5a441...",
140
- "timestamp": 1696636800,
141
- "nonce": "abc123"
142
- }
143
-
144
- Step 3: Server verifies signature
145
- recovered = ecrecover(message, signature)
146
- if recovered == wallet:
147
- session = create_session(wallet, expires=86400) # 24 hours
148
- return session_token
149
-
150
- Step 4: Client uses session
151
- GET /bionfs/v1/open/0xCCe1...
152
- Authorization: Bearer bionfs_eyJhbGci...
153
- ```
154
-
155
- ### 4.2 Session Token Format
156
-
157
- ```javascript
158
- {
159
- "token": "bionfs_" + base64url({
160
- "wallet": "0xb3c3a584491b8ca4df45116a1e250098a0d6192d",
161
- "issued_at": 1696636800,
162
- "expires_at": 1696723200, // 24 hours later
163
- "nonce": "abc123",
164
- "signature": "0x42226a0eeb5ec5a441..."
165
- })
166
- }
167
- ```
168
-
169
- ### 4.3 License Token Verification
170
-
171
- **Story Protocol Integration**:
172
-
173
- ```
174
- Step 1: Server discovers user's licenses
175
- licenses = license_tokens.find({
176
- "receiver": wallet,
177
- "status": "active"
178
- })
179
-
180
- Step 2: Build granted file list
181
- granted_files = []
182
- for license in licenses:
183
- bioip = bioip_registry.find({"ip_id": license.ip_id})
184
- granted_files.append(bioip)
185
-
186
- Step 3: Cache in session
187
- session.granted_files = [file.ip_id for file in granted_files]
188
- ```
189
-
190
- ---
191
-
192
- ## 5. File Handles
193
-
194
- **NFS v4 uses opaque server-generated handles**. BioNFS uses **IP Asset IDs** as file handles.
195
-
196
- ### 5.1 File Handle Structure
197
-
198
- ```
199
- Format: IP Asset ID (Ethereum address)
200
- Example: 0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7
201
-
202
- Properties:
203
- - Globally unique (blockchain-guaranteed)
204
- - Persistent (never changes)
205
- - Verifiable (can query Story Protocol)
206
- - Human-readable (unlike opaque NFS handles)
207
- ```
208
-
209
- ### 5.2 Path Resolution
210
-
211
- **BioNFS Path Format**:
212
- ```
213
- /mount_point/<ip_id>/<filename>
214
-
215
- Example:
216
- /mnt/genobank/0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7/55052008714000.deepvariant.vcf
217
-
218
- Breakdown:
219
- /mnt/genobank/ → Mount point
220
- 0xCCe14315... → IP Asset ID (file handle)
221
- 55052008714000...vcf → Original filename
222
- ```
223
-
224
- ---
225
-
226
- ## 6. Protocol Operations
227
-
228
- ### 6.1 AUTHENTICATE
229
-
230
- **Request**:
231
- ```json
232
- {
233
- "version": "1.0.0",
234
- "operation": "AUTHENTICATE",
235
- "params": {
236
- "wallet": "0xb3c3a584491b8ca4df45116a1e250098a0d6192d",
237
- "signature": "0x42226a0eeb5ec5a441...",
238
- "timestamp": 1696636800,
239
- "nonce": "abc123"
240
- }
241
- }
242
- ```
243
-
244
- **Response**:
245
- ```json
246
- {
247
- "status": "success",
248
- "session_token": "bionfs_eyJhbGci...",
249
- "expires_at": 1696723200,
250
- "granted_files": [
251
- "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7",
252
- "0x89224559242246F93479Fc44B0d8a1AFF5950faB"
253
- ]
254
- }
255
- ```
256
-
257
- ### 6.2 OPEN
258
-
259
- **Request**:
260
- ```json
261
- {
262
- "version": "1.0.0",
263
- "operation": "OPEN",
264
- "session": "bionfs_eyJhbGci...",
265
- "params": {
266
- "ip_id": "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7",
267
- "mode": "read"
268
- }
269
- }
270
- ```
271
-
272
- **Response**:
273
- ```json
274
- {
275
- "status": "success",
276
- "file_handle": "fh_abc123",
277
- "file_info": {
278
- "ip_id": "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7",
279
- "filename": "55052008714000.deepvariant.vcf",
280
- "size": 152428800, // 145 MB
281
- "content_type": "text/vcf",
282
- "owner": "0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a",
283
- "license_type": "non-commercial",
284
- "created_at": 1696550400
285
- }
286
- }
287
- ```
288
-
289
- ### 6.3 READ
290
-
291
- **Request**:
292
- ```json
293
- {
294
- "version": "1.0.0",
295
- "operation": "READ",
296
- "session": "bionfs_eyJhbGci...",
297
- "params": {
298
- "file_handle": "fh_abc123",
299
- "offset": 0,
300
- "length": 1048576 // 1 MB chunk
301
- }
302
- }
303
- ```
304
-
305
- **Response** (streaming):
306
- ```
307
- HTTP/2 200 OK
308
- Content-Type: application/octet-stream
309
- Transfer-Encoding: chunked
310
- X-BioNFS-Chunk-Size: 1048576
311
- X-BioNFS-Total-Size: 152428800
312
-
313
- <binary data chunk 1>
314
- <binary data chunk 2>
315
- ...
316
- ```
317
-
318
- ### 6.4 STAT
319
-
320
- **Request**:
321
- ```json
322
- {
323
- "version": "1.0.0",
324
- "operation": "STAT",
325
- "session": "bionfs_eyJhbGci...",
326
- "params": {
327
- "ip_id": "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7"
328
- }
329
- }
330
- ```
331
-
332
- **Response**:
333
- ```json
334
- {
335
- "status": "success",
336
- "file_info": {
337
- "ip_id": "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7",
338
- "filename": "55052008714000.deepvariant.vcf",
339
- "size": 152428800,
340
- "content_type": "text/vcf",
341
- "owner": "0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a",
342
- "license_type": "non-commercial",
343
- "created_at": 1696550400,
344
- "last_accessed": 1696636800,
345
- "md5": "3931d9ff4b23c844e8e8f1e6c1234567"
346
- }
347
- }
348
- ```
349
-
350
- ### 6.5 LIST
351
-
352
- **Request**:
353
- ```json
354
- {
355
- "version": "1.0.0",
356
- "operation": "LIST",
357
- "session": "bionfs_eyJhbGci...",
358
- "params": {
359
- "filter": {
360
- "file_type": "vcf",
361
- "access_level": "granted"
362
- }
363
- }
364
- }
365
- ```
366
-
367
- **Response**:
368
- ```json
369
- {
370
- "status": "success",
371
- "files": [
372
- {
373
- "ip_id": "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7",
374
- "filename": "55052008714000.deepvariant.vcf",
375
- "size": 152428800,
376
- "owner": "0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a",
377
- "access_reason": "license_token_40205"
378
- }
379
- ],
380
- "total_count": 1
381
- }
382
- ```
383
-
384
- ---
385
-
386
- ## 7. Error Handling
387
-
388
- **Following IETF NFS v4 Section 12** (Errors Related to UTF-8):
389
-
390
- ### 7.1 Standard Error Codes
391
-
392
- ```javascript
393
- const BioNFSErrors = {
394
- // Authentication errors (1000-1099)
395
- INVALID_SIGNATURE: {
396
- code: 1001,
397
- message: "Invalid Web3 signature",
398
- http_status: 401
399
- },
400
- SESSION_EXPIRED: {
401
- code: 1002,
402
- message: "Session token expired",
403
- http_status: 401
404
- },
405
-
406
- // Permission errors (1100-1199)
407
- ACCESS_DENIED: {
408
- code: 1101,
409
- message: "Access denied - no license token found",
410
- http_status: 403
411
- },
412
- LICENSE_REVOKED: {
413
- code: 1102,
414
- message: "License token has been revoked",
415
- http_status: 403
416
- },
417
-
418
- // File errors (1200-1299)
419
- FILE_NOT_FOUND: {
420
- code: 1201,
421
- message: "IP Asset not found in registry",
422
- http_status: 404
423
- },
424
- INVALID_IP_ID: {
425
- code: 1202,
426
- message: "Invalid IP Asset ID format",
427
- http_status: 400
428
- },
429
-
430
- // String encoding errors (following NFS v4)
431
- INVALID_UTF8: {
432
- code: 1301,
433
- message: "String contains invalid UTF-8 sequences",
434
- http_status: 400
435
- }
436
- };
437
- ```
438
-
439
- ### 7.2 Error Response Format
440
-
441
- ```json
442
- {
443
- "status": "error",
444
- "error": {
445
- "code": 1101,
446
- "message": "Access denied - no license token found",
447
- "details": {
448
- "ip_id": "0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7",
449
- "wallet": "0xb3c3a584491b8ca4df45116a1e250098a0d6192d",
450
- "reason": "No active license token found for this IP Asset"
451
- }
452
- }
453
- }
454
- ```
455
-
456
- ---
457
-
458
- ## 8. Security Considerations
459
-
460
- **Following IETF NFS v4 Section 14**:
461
-
462
- ### 8.1 Signature Verification
463
-
464
- ```python
465
- def verify_web3_signature(message: str, signature: str, expected_wallet: str) -> bool:
466
- """
467
- Verify EIP-191 signature
468
-
469
- Security considerations:
470
- - Replay attack prevention (timestamp + nonce)
471
- - Message tampering detection (signature verification)
472
- - Wallet spoofing prevention (ecrecover)
473
- """
474
- # Reconstruct signed message
475
- eth_message = f"\x19Ethereum Signed Message:\n{len(message)}{message}"
476
- message_hash = keccak256(eth_message.encode())
477
-
478
- # Recover signer
479
- recovered_wallet = ecrecover(message_hash, signature)
480
-
481
- # Verify
482
- return recovered_wallet.lower() == expected_wallet.lower()
483
- ```
484
-
485
- ### 8.2 Session Security
486
-
487
- ```javascript
488
- // Session token includes:
489
- // 1. Wallet address (cannot be forged)
490
- // 2. Signature (proves wallet ownership)
491
- // 3. Timestamp (prevents replay attacks)
492
- // 4. Nonce (prevents reuse)
493
-
494
- const session = {
495
- wallet: "0xb3c3a584491b8ca4df45116a1e250098a0d6192d",
496
- signature: "0x42226a0eeb5ec5a441...",
497
- timestamp: Date.now(),
498
- nonce: crypto.randomBytes(16).toString('hex'),
499
- expires_at: Date.now() + 86400000 // 24 hours
500
- };
501
- ```
502
-
503
- ### 8.3 License Token Verification
504
-
505
- ```python
506
- def verify_license_access(wallet: str, ip_id: str) -> bool:
507
- """
508
- Verify license token on Story Protocol blockchain
509
-
510
- Security: On-chain verification prevents forged licenses
511
- """
512
- license_token = license_tokens.find_one({
513
- "ip_id": ip_id,
514
- "receiver": wallet,
515
- "status": {"$ne": "revoked"}
516
- })
517
-
518
- if not license_token:
519
- return False
520
-
521
- # Optional: Verify on blockchain (paranoid mode)
522
- on_chain_owner = story_protocol.ownerOf(license_token.license_token_id)
523
- return on_chain_owner.lower() == wallet.lower()
524
- ```
525
-
526
- ---
527
-
528
- ## 9. Internationalization
529
-
530
- **Following IETF NFS v4 Sections 5-8**:
531
-
532
- ### 9.1 UTF-8 Support
533
-
534
- All strings MUST be valid UTF-8. This includes:
535
- - Filenames (e.g., `patient_測試.vcf` ✅)
536
- - User metadata (e.g., `description: "Análisis genómico"` ✅)
537
- - Error messages (localized)
538
-
539
- ### 9.2 Ethereum Address Handling
540
-
541
- ```python
542
- # Addresses are hex strings, not Unicode
543
- # But must be valid UTF-8 for JSON serialization
544
-
545
- def normalize_address(address: str) -> str:
546
- """
547
- Normalize Ethereum address to lowercase
548
-
549
- Following NFS v4 Section 7.2 (case-insensitive comparison)
550
- """
551
- if not address.startswith('0x'):
552
- raise ValueError("Invalid address format")
553
-
554
- if len(address) != 42:
555
- raise ValueError("Invalid address length")
556
-
557
- return address.lower()
558
- ```
559
-
560
- ---
561
-
562
- ## 10. Streaming Protocol
563
-
564
- ### 10.1 Chunked Streaming (HTTP/2)
565
-
566
- ```
567
- Client Request:
568
- GET /bionfs/v1/stream/0xCCe1...
569
- Authorization: Bearer bionfs_eyJhbGci...
570
- Range: bytes=0-1048575
571
-
572
- Server Response:
573
- HTTP/2 200 OK
574
- Content-Type: application/octet-stream
575
- Content-Length: 1048576
576
- X-BioNFS-Chunk: 1/145
577
- X-BioNFS-Total-Chunks: 145
578
-
579
- <1MB binary data>
580
- ```
581
-
582
- ### 10.2 Range Requests (Seek Support)
583
-
584
- ```javascript
585
- // Client can seek to any position in file
586
- const chunk = await bionfs.read({
587
- file_handle: "fh_abc123",
588
- offset: 100000000, // Start at 100MB
589
- length: 1048576 // Read 1MB
590
- });
591
-
592
- // Efficient for VCF files (skip to specific chromosome)
593
- const chr22_chunk = await bionfs.read({
594
- file_handle: "fh_vcf_123",
595
- offset: chr22_offset, // Calculated from VCF index
596
- length: chr22_length
597
- });
598
- ```
599
-
600
- ---
601
-
602
- ## 11. Comparison with IETF NFS v4
603
-
604
- | Aspect | IETF NFS v4 | BioNFS |
605
- |--------|-------------|--------|
606
- | **Authentication** | Kerberos, GSS-API | Web3 signatures (EIP-191) |
607
- | **Authorization** | POSIX ACLs | Story Protocol License Tokens |
608
- | **File Handles** | Opaque (server-generated) | IP Asset IDs (blockchain addresses) |
609
- | **State Management** | Stateful (complex) | Session-based (simple) |
610
- | **Locking** | Full file locking | Read-only (no locking needed) |
611
- | **Write Operations** | Full read/write | Read-only (genomic data immutable) |
612
- | **Caching** | Client-side caching | Minimal caching (always fresh) |
613
- | **Internationalization** | Full UTF-8 (RFC 3629) | UTF-8 + Ethereum addresses |
614
- | **Transport** | RPC over TCP | HTTP/2, WebSocket, gRPC |
615
-
616
- ---
617
-
618
- ## 12. Implementation Roadmap
619
-
620
- ### Phase 1: Core Protocol (Week 1)
621
- - ✅ Protocol specification (this document)
622
- - ✅ Authentication flow (Web3 signatures)
623
- - ✅ Session management
624
- - ✅ Basic file operations (OPEN, READ, STAT, LIST)
625
-
626
- ### Phase 2: Server Implementation (Week 2)
627
- - ✅ FastAPI server
628
- - ✅ MongoDB integration
629
- - ✅ S3 streaming
630
- - ✅ License token verification
631
-
632
- ### Phase 3: Client Library (Week 3)
633
- - ✅ TypeScript client
634
- - ✅ Python client
635
- - ✅ Streaming support
636
- - ✅ CLI integration
637
-
638
- ### Phase 4: FUSE Integration (Week 4)
639
- - ✅ web3fuse updates
640
- - ✅ Mount command
641
- - ✅ Performance optimization
642
- - ✅ Production deployment
643
-
644
- ---
645
-
646
- ## 13. References
647
-
648
- ### 13.1 Normative References
649
-
650
- - **IETF NFS v4**: draft-ietf-nfsv4-internationalization-13
651
- - **UTF-8**: RFC 3629 - UTF-8, a transformation format of ISO 10646
652
- - **EIP-191**: Ethereum Signed Message Standard
653
- - **HTTP/2**: RFC 7540 - Hypertext Transfer Protocol Version 2
654
-
655
- ### 13.2 GenoBank References
656
-
657
- - **Story Protocol**: https://docs.story.foundation
658
- - **BioIP Protocol**: `/production_api/BIOIP_PROTOCOL_DOCUMENTATION.md`
659
- - **GenoBank API**: https://genobank.app/static/Genobank_API_Educational_Guide.html
660
-
661
- ---
662
-
663
- ## 14. Appendix: Protocol Design Rationale
664
-
665
- ### Why Not Pure NFS v4?
666
-
667
- 1. **Genomics-specific**: VCF/BAM files need optimized streaming
668
- 2. **Blockchain-native**: Web3 authentication is more secure than Kerberos
669
- 3. **Immutable data**: No write operations needed (genomic data is read-only)
670
- 4. **Global access**: HTTP/2 works better than RPC over internet
671
-
672
- ### Why Session-Based Instead of Stateless?
673
-
674
- 1. **Performance**: Cache granted files list (avoid repeated blockchain queries)
675
- 2. **UX**: 24-hour sessions better than 1-hour presigned URLs
676
- 3. **Security**: Wallet-bound sessions cannot be transferred
677
-
678
- ### Why IP Asset IDs as File Handles?
679
-
680
- 1. **Globally unique**: Blockchain-guaranteed uniqueness
681
- 2. **Persistent**: Never change (unlike server-generated handles)
682
- 3. **Verifiable**: Can verify ownership on blockchain
683
- 4. **Human-readable**: Easy to debug
684
-
685
- ---
686
-
687
- **This specification follows IETF NFS v4 design principles while adapting them for blockchain-authenticated genomic data access.**
688
-