@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.
- package/CHANGELOG.md +2 -0
- package/LICENSE +37 -0
- package/README.md +2 -1
- package/bin/biofs.js +2 -1
- package/contracts/ClaraJobNFT.sol +101 -0
- package/dist/commands/agent/health.js +1 -1
- package/dist/commands/agent/health.js.map +1 -1
- package/dist/commands/agent/list.d.ts +14 -0
- package/dist/commands/agent/list.d.ts.map +1 -0
- package/dist/commands/agent/list.js +101 -0
- package/dist/commands/agent/list.js.map +1 -0
- package/dist/commands/agent/register.d.ts +18 -0
- package/dist/commands/agent/register.d.ts.map +1 -0
- package/dist/commands/agent/register.js +120 -0
- package/dist/commands/agent/register.js.map +1 -0
- package/dist/commands/agent/status.d.ts +14 -0
- package/dist/commands/agent/status.d.ts.map +1 -0
- package/dist/commands/agent/status.js +151 -0
- package/dist/commands/agent/status.js.map +1 -0
- package/dist/commands/annotate/status.d.ts +11 -0
- package/dist/commands/annotate/status.d.ts.map +1 -0
- package/dist/commands/annotate/status.js +123 -0
- package/dist/commands/annotate/status.js.map +1 -0
- package/dist/commands/annotate/submit.d.ts +23 -0
- package/dist/commands/annotate/submit.d.ts.map +1 -0
- package/dist/commands/annotate/submit.js +296 -0
- package/dist/commands/annotate/submit.js.map +1 -0
- package/dist/commands/family-status.d.ts +12 -0
- package/dist/commands/family-status.d.ts.map +1 -0
- package/dist/commands/family-status.js +220 -0
- package/dist/commands/family-status.js.map +1 -0
- package/dist/commands/job/status.d.ts +1 -0
- package/dist/commands/job/status.d.ts.map +1 -1
- package/dist/commands/job/status.js.map +1 -1
- package/dist/commands/link-clara.d.ts +20 -0
- package/dist/commands/link-clara.d.ts.map +1 -0
- package/dist/commands/link-clara.js +234 -0
- package/dist/commands/link-clara.js.map +1 -0
- package/dist/commands/mount-remote.d.ts +1 -1
- package/dist/commands/mount-remote.js +1 -1
- package/dist/commands/payment/balance.d.ts +12 -0
- package/dist/commands/payment/balance.d.ts.map +1 -0
- package/dist/commands/payment/balance.js +101 -0
- package/dist/commands/payment/balance.js.map +1 -0
- package/dist/commands/payment/faucet.d.ts +11 -0
- package/dist/commands/payment/faucet.d.ts.map +1 -0
- package/dist/commands/payment/faucet.js +92 -0
- package/dist/commands/payment/faucet.js.map +1 -0
- package/dist/commands/payment/history.d.ts +27 -0
- package/dist/commands/payment/history.d.ts.map +1 -0
- package/dist/commands/payment/history.js +162 -0
- package/dist/commands/payment/history.js.map +1 -0
- package/dist/commands/payment/pricing.d.ts +12 -0
- package/dist/commands/payment/pricing.d.ts.map +1 -0
- package/dist/commands/payment/pricing.js +65 -0
- package/dist/commands/payment/pricing.js.map +1 -0
- package/dist/commands/payment/setup.d.ts +25 -0
- package/dist/commands/payment/setup.d.ts.map +1 -0
- package/dist/commands/payment/setup.js +155 -0
- package/dist/commands/payment/setup.js.map +1 -0
- package/dist/commands/tokenize-biosample.d.ts +19 -0
- package/dist/commands/tokenize-biosample.d.ts.map +1 -0
- package/dist/commands/tokenize-biosample.js +253 -0
- package/dist/commands/tokenize-biosample.js.map +1 -0
- package/dist/index.js +281 -13
- package/dist/index.js.map +1 -1
- package/dist/lib/api/bionft-client.d.ts +35 -7
- package/dist/lib/api/bionft-client.d.ts.map +1 -1
- package/dist/lib/api/bionft-client.js +106 -16
- package/dist/lib/api/bionft-client.js.map +1 -1
- package/dist/lib/kite/agent.d.ts +85 -0
- package/dist/lib/kite/agent.d.ts.map +1 -0
- package/dist/lib/kite/agent.js +332 -0
- package/dist/lib/kite/agent.js.map +1 -0
- package/dist/lib/kite/index.d.ts +9 -0
- package/dist/lib/kite/index.d.ts.map +1 -0
- package/dist/lib/kite/index.js +25 -0
- package/dist/lib/kite/index.js.map +1 -0
- package/dist/lib/kite/passport.d.ts +69 -0
- package/dist/lib/kite/passport.d.ts.map +1 -0
- package/dist/lib/kite/passport.js +312 -0
- package/dist/lib/kite/passport.js.map +1 -0
- package/dist/lib/x402/client.d.ts +78 -0
- package/dist/lib/x402/client.d.ts.map +1 -0
- package/dist/lib/x402/client.js +298 -0
- package/dist/lib/x402/client.js.map +1 -0
- package/dist/lib/x402/index.d.ts +9 -0
- package/dist/lib/x402/index.d.ts.map +1 -0
- package/dist/lib/x402/index.js +37 -0
- package/dist/lib/x402/index.js.map +1 -0
- package/dist/lib/x402/middleware.d.ts +37 -0
- package/dist/lib/x402/middleware.d.ts.map +1 -0
- package/dist/lib/x402/middleware.js +220 -0
- package/dist/lib/x402/middleware.js.map +1 -0
- package/dist/types/kite.d.ts +157 -0
- package/dist/types/kite.d.ts.map +1 -0
- package/dist/types/kite.js +107 -0
- package/dist/types/kite.js.map +1 -0
- package/dist/types/x402.d.ts +78 -0
- package/dist/types/x402.d.ts.map +1 -0
- package/dist/types/x402.js +79 -0
- package/dist/types/x402.js.map +1 -0
- package/docs/AI_AGENT_MCP_MANUAL.md +1029 -0
- package/docs/USER_MANUAL.md +603 -0
- package/docs/technical-details.html +555 -0
- package/lib/bionfs-client.js +2 -0
- package/lib/consent-manager.js +2 -0
- package/lib/consent-prompt.js +2 -0
- package/package.json +9 -3
- package/presentation/biofs-x402-kite-presentation.html +813 -0
- package/scripts/build_annotator_dictionary.py +1 -0
- package/scripts/deploy-clara-nft.js +37 -0
- package/test-complete-flow.sh +1 -1
- package/test.vcf +1 -0
- package/test_23andme.txt +1 -0
- package/ADMIN_REGISTER_LAB.md +0 -252
- package/ANNOTATOR_RECOMMENDATIONS_API.md +0 -490
- package/BIOFS_QUICK_START.md +0 -200
- package/BIOFS_TOKENIZE_COMPLETE.md +0 -541
- package/BIOFS_V1.2.7_PUBLISHED.md +0 -317
- package/BIOFS_V1.2.9_FIXES.md +0 -306
- package/BIOFS_V1.3.0_DIRECT_GRANT.md +0 -381
- package/BIOFS_V1.3.1_GRANTED_FILES.md +0 -328
- package/BIONFS_DEPLOYMENT_GUIDE.md +0 -408
- package/BIONFS_MOUNT_INTEGRATION_PLAN.md +0 -415
- package/BIONFS_PROTOCOL_SPECIFICATION.md +0 -688
- package/BIONFS_SEQUENTIAS_INTEGRATION.md +0 -457
- package/BIONFT_GATED_REMOTE_MOUNTING.md +0 -1260
- package/BIONFT_NFS_PROTOCOL_ARCHITECTURE.md +0 -583
- package/BIOOS_CLI_IMPLEMENTATION_COMPLETE.md +0 -422
- package/BIOOS_JOB_MANAGEMENT.md +0 -681
- package/BUGFIX_V2.1.3.md +0 -72
- package/CHANGELOG_V2.1.0.md +0 -386
- package/CHANGELOG_V2.2.0.md +0 -284
- package/ENHANCEMENT_DOCUMENTATION.md +0 -218
- package/GDPR_BIONFS_CONSENT_ARCHITECTURE.md +0 -798
- package/GDPR_BIONFS_IMPLEMENTATION_STATUS.md +0 -462
- package/INSTALL_V1.2.7_ON_MAC.md +0 -306
- package/LABNFT_BIOFS_INTEGRATION.md +0 -396
- package/OPENCRAVAT_ANNOTATORS_REFERENCE.md +0 -340
- package/OPENCRAVAT_ANNOTATOR_INTELLIGENCE_COMPLETE.md +0 -479
- package/QUICK_START_V2.1.0.md +0 -116
- package/RELEASE_SUMMARY_V1.2.7.md +0 -479
- package/RELEASE_SUMMARY_V1.3.0.md +0 -324
- package/SEQUENTIAS_PROTOCOL_ARCHITECTURE.md +0 -880
- package/SEQUENTIA_MIGRATION_GUIDE.md +0 -337
- package/SESSION_SUMMARY_DIRECT_GRANT.md +0 -321
- package/ULTRATHINK_BIONFS_COMPLETE.md +0 -458
- package/WEB3FUSE_LICENSE_TOKEN_ANALYSIS.md +0 -494
- package/WHERE_PERMISSIONS_LIVE.md +0 -165
- package/config.json +0 -21
- package/opencravat_annotators_dictionary.json +0 -2356
- 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
|
-
|