@genobank/biofs 2.6.2 → 3.0.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 (133) hide show
  1. package/CHANGELOG.md +76 -0
  2. package/README.md +556 -201
  3. package/dist/commands/alias.d.ts +9 -0
  4. package/dist/commands/alias.d.ts.map +1 -0
  5. package/dist/commands/alias.js +56 -0
  6. package/dist/commands/alias.js.map +1 -0
  7. package/dist/commands/bionft/revoke.d.ts +6 -0
  8. package/dist/commands/bionft/revoke.d.ts.map +1 -0
  9. package/dist/commands/bionft/revoke.js +74 -0
  10. package/dist/commands/bionft/revoke.js.map +1 -0
  11. package/dist/commands/bionft/status.d.ts +2 -0
  12. package/dist/commands/bionft/status.d.ts.map +1 -0
  13. package/dist/commands/bionft/status.js +45 -0
  14. package/dist/commands/bionft/status.js.map +1 -0
  15. package/dist/commands/bionft/view.d.ts +5 -0
  16. package/dist/commands/bionft/view.d.ts.map +1 -0
  17. package/dist/commands/bionft/view.js +127 -0
  18. package/dist/commands/bionft/view.js.map +1 -0
  19. package/dist/commands/cred/issue.d.ts +12 -0
  20. package/dist/commands/cred/issue.d.ts.map +1 -0
  21. package/dist/commands/cred/issue.js +95 -0
  22. package/dist/commands/cred/issue.js.map +1 -0
  23. package/dist/commands/cred/lib.d.ts +23 -0
  24. package/dist/commands/cred/lib.d.ts.map +1 -0
  25. package/dist/commands/cred/lib.js +95 -0
  26. package/dist/commands/cred/lib.js.map +1 -0
  27. package/dist/commands/cred/list.d.ts +7 -0
  28. package/dist/commands/cred/list.d.ts.map +1 -0
  29. package/dist/commands/cred/list.js +65 -0
  30. package/dist/commands/cred/list.js.map +1 -0
  31. package/dist/commands/cred/revoke.d.ts +6 -0
  32. package/dist/commands/cred/revoke.d.ts.map +1 -0
  33. package/dist/commands/cred/revoke.js +60 -0
  34. package/dist/commands/cred/revoke.js.map +1 -0
  35. package/dist/commands/cred/status.d.ts +5 -0
  36. package/dist/commands/cred/status.d.ts.map +1 -0
  37. package/dist/commands/cred/status.js +41 -0
  38. package/dist/commands/cred/status.js.map +1 -0
  39. package/dist/commands/htsget.d.ts +8 -0
  40. package/dist/commands/htsget.d.ts.map +1 -0
  41. package/dist/commands/htsget.js +43 -0
  42. package/dist/commands/htsget.js.map +1 -0
  43. package/dist/commands/login.d.ts.map +1 -1
  44. package/dist/commands/login.js +15 -0
  45. package/dist/commands/login.js.map +1 -1
  46. package/dist/commands/pipe.d.ts +8 -0
  47. package/dist/commands/pipe.d.ts.map +1 -0
  48. package/dist/commands/pipe.js +76 -0
  49. package/dist/commands/pipe.js.map +1 -0
  50. package/dist/commands/stream.d.ts +9 -0
  51. package/dist/commands/stream.d.ts.map +1 -0
  52. package/dist/commands/stream.js +58 -0
  53. package/dist/commands/stream.js.map +1 -0
  54. package/dist/commands/upload-fastq.d.ts +10 -0
  55. package/dist/commands/upload-fastq.d.ts.map +1 -0
  56. package/dist/commands/upload-fastq.js +60 -0
  57. package/dist/commands/upload-fastq.js.map +1 -0
  58. package/dist/commands/vault/mount.d.ts +8 -0
  59. package/dist/commands/vault/mount.d.ts.map +1 -0
  60. package/dist/commands/vault/mount.js +136 -0
  61. package/dist/commands/vault/mount.js.map +1 -0
  62. package/dist/commands/vault/setup.d.ts +6 -0
  63. package/dist/commands/vault/setup.d.ts.map +1 -0
  64. package/dist/commands/vault/setup.js +160 -0
  65. package/dist/commands/vault/setup.js.map +1 -0
  66. package/dist/commands/vault/status.d.ts +4 -0
  67. package/dist/commands/vault/status.d.ts.map +1 -0
  68. package/dist/commands/vault/status.js +97 -0
  69. package/dist/commands/vault/status.js.map +1 -0
  70. package/dist/commands/vault/unmount.d.ts +6 -0
  71. package/dist/commands/vault/unmount.d.ts.map +1 -0
  72. package/dist/commands/vault/unmount.js +90 -0
  73. package/dist/commands/vault/unmount.js.map +1 -0
  74. package/dist/index.js +354 -23
  75. package/dist/index.js.map +1 -1
  76. package/dist/lib/aliases/store.d.ts +7 -0
  77. package/dist/lib/aliases/store.d.ts.map +1 -0
  78. package/dist/lib/aliases/store.js +83 -0
  79. package/dist/lib/aliases/store.js.map +1 -0
  80. package/dist/lib/auth/server.d.ts.map +1 -1
  81. package/dist/lib/auth/server.js +21 -2
  82. package/dist/lib/auth/server.js.map +1 -1
  83. package/dist/lib/bionft/BioAssetVault.abi.json +1104 -0
  84. package/dist/lib/bionft/BioNFTCredentials.abi.json +1235 -0
  85. package/dist/lib/bionft/client.d.ts +45 -0
  86. package/dist/lib/bionft/client.d.ts.map +1 -0
  87. package/dist/lib/bionft/client.js +219 -0
  88. package/dist/lib/bionft/client.js.map +1 -0
  89. package/dist/lib/htsget/client.d.ts +54 -0
  90. package/dist/lib/htsget/client.d.ts.map +1 -0
  91. package/dist/lib/htsget/client.js +76 -0
  92. package/dist/lib/htsget/client.js.map +1 -0
  93. package/dist/utils/errorReporter.d.ts +6 -0
  94. package/dist/utils/errorReporter.d.ts.map +1 -1
  95. package/dist/utils/errorReporter.js +53 -0
  96. package/dist/utils/errorReporter.js.map +1 -1
  97. package/package.json +4 -4
  98. package/dist/commands/access-sequentia.d.ts +0 -35
  99. package/dist/commands/access-sequentia.d.ts.map +0 -1
  100. package/dist/commands/access-sequentia.js +0 -256
  101. package/dist/commands/access-sequentia.js.map +0 -1
  102. package/dist/commands/biofiles-sequentia.d.ts +0 -21
  103. package/dist/commands/biofiles-sequentia.d.ts.map +0 -1
  104. package/dist/commands/biofiles-sequentia.js +0 -238
  105. package/dist/commands/biofiles-sequentia.js.map +0 -1
  106. package/dist/commands/download-sequentia.d.ts +0 -19
  107. package/dist/commands/download-sequentia.d.ts.map +0 -1
  108. package/dist/commands/download-sequentia.js +0 -159
  109. package/dist/commands/download-sequentia.js.map +0 -1
  110. package/dist/commands/researcher/register.d.ts +0 -24
  111. package/dist/commands/researcher/register.d.ts.map +0 -1
  112. package/dist/commands/researcher/register.js +0 -192
  113. package/dist/commands/researcher/register.js.map +0 -1
  114. package/dist/commands/researcher/status.d.ts +0 -24
  115. package/dist/commands/researcher/status.d.ts.map +0 -1
  116. package/dist/commands/researcher/status.js +0 -235
  117. package/dist/commands/researcher/status.js.map +0 -1
  118. package/dist/commands/researcher/verify.d.ts +0 -24
  119. package/dist/commands/researcher/verify.d.ts.map +0 -1
  120. package/dist/commands/researcher/verify.js +0 -167
  121. package/dist/commands/researcher/verify.js.map +0 -1
  122. package/dist/commands/share-sequentia.d.ts +0 -21
  123. package/dist/commands/share-sequentia.d.ts.map +0 -1
  124. package/dist/commands/share-sequentia.js +0 -161
  125. package/dist/commands/share-sequentia.js.map +0 -1
  126. package/dist/commands/tokenize-sequentia.d.ts +0 -21
  127. package/dist/commands/tokenize-sequentia.d.ts.map +0 -1
  128. package/dist/commands/tokenize-sequentia.js +0 -191
  129. package/dist/commands/tokenize-sequentia.js.map +0 -1
  130. package/dist/commands/verify-sequentia.d.ts +0 -18
  131. package/dist/commands/verify-sequentia.d.ts.map +0 -1
  132. package/dist/commands/verify-sequentia.js +0 -150
  133. package/dist/commands/verify-sequentia.js.map +0 -1
package/README.md CHANGED
@@ -1,201 +1,556 @@
1
- # BioFS - GenoBank.io CLI
2
-
3
- **BioFS** by GenoBank.io - Command-line interface to manage your BioNFTs and BioFiles from the terminal.
4
-
5
- ## Features
6
-
7
- - 🔐 **Web3 Authentication**: Secure wallet-based authentication
8
- - 📁 **File Discovery**: List all your BioFiles from S3 and Story Protocol
9
- - 📥 **Download Files**: Download by BioCID or filename with progress bars
10
- - 📤 **Upload Files**: Upload genomic data with optional NFT tokenization
11
- - 🗂️ **NFS Mount Support**: Mount BioNFT-gated files as true filesystem (NEW in v2.0!)
12
- - 🤖 **BioOS Job Management**: Run research pipelines with natural language prompts
13
- - ⛓️ **Story Protocol Integration**: Track IP asset lineage across workflows
14
- - 🔗 **BioCID Resolution**: Universal file identifier system
15
- - 🎨 **Beautiful Output**: Color-coded, formatted terminal output
16
-
17
- ## Installation
18
-
19
- ```bash
20
- # Install globally
21
- npm install -g @genobank/biofs
22
-
23
- # Or run locally
24
- cd /home/ubuntu/genobank-cli
25
- npm install
26
- npm run build
27
- npm link
28
- ```
29
-
30
- ## Quick Start
31
-
32
- ### 1. Authenticate
33
-
34
- ```bash
35
- biofs login
36
- # Browser opens for Web3 authentication
37
- # ✅ Authenticated as: 0x5f5a...d19a
38
- ```
39
-
40
- ### 2. List Your Files
41
-
42
- ```bash
43
- biofs files
44
- # 📁 Your BioFiles (12 files)
45
- # Shows all files from S3 and Story Protocol
46
- ```
47
-
48
- ### 3. Download a File
49
-
50
- ```bash
51
- # By filename
52
- biofs download my-genome.vcf
53
-
54
- # By BioCID
55
- biofs download biocid://0x5f5a.../vcf/my-genome.vcf
56
-
57
- # To specific location
58
- biofs download my-genome.vcf ~/analysis/
59
- ```
60
-
61
- ### 4. Upload a File
62
-
63
- ```bash
64
- # Simple upload
65
- biofs upload ~/data/sample.vcf
66
-
67
- # Upload and mint as NFT
68
- biofs upload ~/data/sample.vcf --tokenize
69
-
70
- # Upload with file type
71
- biofs upload ~/data/reads.fastq.gz --type fastq
72
- ```
73
-
74
- ### 5. Mount Files as Filesystem (NEW in v2.0!)
75
-
76
- ```bash
77
- # Mount all granted files via NFS
78
- biofs mount /mnt/genomics --method nfs
79
-
80
- # Mount specific BioCID
81
- biofs mount /mnt/sample --method nfs --biocid biocid://0x.../bioip/0x...
82
-
83
- # Use standard bioinformatics tools
84
- bcftools view /mnt/genomics/sample.vcf | head -20
85
- igv /mnt/genomics/sample.vcf
86
-
87
- # Unmount when done
88
- biofs umount /mnt/genomics
89
-
90
- # Traditional copy method (downloads files)
91
- biofs mount /mnt/genomics --method copy
92
- ```
93
-
94
- **Requirements for NFS mount:**
95
- - BioNFS server installed: `cd /home/ubuntu/bionfs && make install`
96
- - NFS client: `sudo apt-get install nfs-common`
97
- - Root access for system mount
98
-
99
- ## Commands
100
-
101
- ### Authentication
102
-
103
- - `biofs login` - Authenticate with Web3 wallet
104
- - `biofs logout` - Clear stored credentials
105
- - `biofs whoami` - Show current authenticated wallet
106
-
107
- ### File Management
108
-
109
- - `biofs files [--filter <type>] [--source <source>]` - List BioFiles
110
- - `biofs download <file> [destination]` - Download file
111
- - `biofs upload <file> [--tokenize]` - Upload file
112
- - `biofs mount <mountpoint> [--method nfs|copy] [--biocid <biocid>]` - Mount files as filesystem
113
- - `biofs umount <mountpoint> [--force]` - Unmount filesystem
114
-
115
- ### BioOS Job Management
116
-
117
- - `biofs job create "<prompt>" <file>` - Create research job from natural language
118
- - `biofs job status <job_id> [--watch]` - Check job execution status
119
- - `biofs job results <job_id>` - Get job results with download URLs
120
- - `biofs job list [--status <status>]` - List all your research jobs
121
- - `biofs job pipelines` - List available pipeline templates
122
-
123
- **Quick Example:**
124
- ```bash
125
- # List available pipelines
126
- biofs job pipelines
127
-
128
- # Create annotation job
129
- biofs job create "Annotate VCF with rare coding variants" sample.vcf --pipeline vcf_annotation
130
-
131
- # Watch progress in real-time
132
- biofs job status <job_id> --watch
133
-
134
- # Download results
135
- biofs job results <job_id>
136
- ```
137
-
138
- 📚 **Full Documentation**: [BIOOS_JOB_MANAGEMENT.md](BIOOS_JOB_MANAGEMENT.md)
139
-
140
- ## BioCID Format
141
-
142
- BioCID is a universal identifier for genomic files:
143
-
144
- ```
145
- biocid://<wallet>/<type>/<identifier>
146
-
147
- Example:
148
- biocid://0x5f5a60eaef242c0d51a21c703f520347b96ed19a/vcf/hereditary-cancer-2024.vcf
149
- ```
150
-
151
- ## Configuration
152
-
153
- Configuration is stored in `~/.genobank/`:
154
-
155
- - `credentials.json` - Encrypted authentication (0600 permissions)
156
- - `config.json` - User preferences
157
- - `cache/` - Cached file metadata
158
- - `logs/` - Operation logs
159
-
160
- ## Security
161
-
162
- - Credentials are stored with 0600 permissions (owner read/write only)
163
- - Signatures are never logged or displayed
164
- - Auto-expiry after 30 days
165
- - Secure deletion on logout (overwrite before delete)
166
-
167
- ## Development
168
-
169
- ```bash
170
- # Clone repository
171
- git clone https://github.com/genobank/genobank-cli.git
172
- cd genobank-cli
173
-
174
- # Install dependencies
175
- npm install
176
-
177
- # Build TypeScript
178
- npm run build
179
-
180
- # Run locally
181
- npm run dev -- login
182
-
183
- # Link for global use
184
- npm link
185
- ```
186
-
187
- ## Environment Variables
188
-
189
- - `DEBUG=1` - Enable debug logging
190
- - `NO_COLOR=1` - Disable colored output
191
-
192
- ## Support
193
-
194
- - **API Docs**: https://genobank.app/static/Genobank_API_Educational_Guide.html
195
- - **GitHub**: https://github.com/genobank
196
- - **Email**: support@genobank.io
197
-
198
- ## License
199
-
200
- AGPL-3.0 © GenoBank.io
201
-
1
+ # BioFS — GenoBank.io CLI
2
+
3
+ > **BioNFT-gated genomic data, meet standard bioinformatics tools.**
4
+ > Stream, view, mount, and analyze consent-gated VCFs / BAMs / FASTQs with
5
+ > `bcftools`, `samtools`, `pysam`, `IGV`, and every tool you already use —
6
+ > no FUSE install, no kext, no data copy.
7
+
8
+ [![npm version](https://img.shields.io/npm/v/@genobank/biofs.svg)](https://www.npmjs.com/package/@genobank/biofs)
9
+ [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL_3.0-blue.svg)](LICENSE)
10
+
11
+ ---
12
+
13
+ ## What you can do in 30 seconds
14
+
15
+ ```bash
16
+ npm install -g @genobank/biofs # once
17
+ biofs login # browser pops up, sign with your wallet
18
+ biofs files # see what's accessible to you
19
+ biofs stream <ip_id> | bcftools stats - # live-analyze a VCF you own
20
+ ```
21
+
22
+ That's it. BioNFT ownership is verified on every request; revocation is immediate;
23
+ nothing ever hits your disk unless you ask for it.
24
+
25
+ ---
26
+
27
+ ## Table of contents
28
+
29
+ - [Install](#install)
30
+ - [Authentication](#authentication)
31
+ - [Discover your BioIPs](#discover-your-bioips)
32
+ - [Streaming & analysis — NEW in v2.7](#streaming--analysis--new-in-v27)
33
+ - [Downloads](#downloads)
34
+ - [Mounting as a filesystem](#mounting-as-a-filesystem)
35
+ - [Uploading & tokenization](#uploading--tokenization)
36
+ - [Access control & sharing](#access-control--sharing)
37
+ - [Running research jobs (BioOS)](#running-research-jobs-bioos)
38
+ - [BioContext manifests](#biocontext-manifests)
39
+ - [Aliases — never type hex again](#aliases--never-type-hex-again)
40
+ - [BioCID format](#biocid-format)
41
+ - [Configuration](#configuration)
42
+ - [Troubleshooting](#troubleshooting)
43
+ - [Security model](#security-model)
44
+ - [Development](#development)
45
+ - [License](#license)
46
+
47
+ ---
48
+
49
+ ## Install
50
+
51
+ **Requires:** Node.js 18+ (uses built-in `fetch`).
52
+
53
+ ```bash
54
+ # Globally (recommended)
55
+ npm install -g @genobank/biofs
56
+
57
+ # Verify
58
+ biofs --version # → 2.7.1
59
+ ```
60
+
61
+ Optional but highly recommended for researchers:
62
+
63
+ ```bash
64
+ # macOS
65
+ brew install bcftools samtools htslib
66
+
67
+ # Debian / Ubuntu
68
+ sudo apt-get install bcftools samtools tabix
69
+ ```
70
+
71
+ The CLI works without these; they unlock `biofs pipe` and `biofs view`
72
+ filesystem-level integration.
73
+
74
+ ---
75
+
76
+ ## Authentication
77
+
78
+ ```bash
79
+ biofs login
80
+ # Browser opens → MetaMask / Magic Link → sign "I want to proceed"
81
+ # ✅ Authenticated as: 0x5f5a60…Ed19a
82
+ ```
83
+
84
+ Credentials live at `~/.biofs/credentials.json` (0600, owner-only). The
85
+ signature is an EIP-191 `personal_sign` of the string `"I want to proceed"`
86
+ — re-usable by the CLI for the next ~30 days before you need to re-sign.
87
+
88
+ ```bash
89
+ biofs whoami # show current wallet
90
+ biofs logout # clear cached credentials (securely overwrites then deletes)
91
+ ```
92
+
93
+ ---
94
+
95
+ ## Discover your BioIPs
96
+
97
+ ```bash
98
+ biofs files # full table of everything you can access
99
+ biofs files --filter vcf # only VCFs
100
+ biofs files --source story # only Story Protocol IP Assets
101
+ biofs files --source avalanche # only Avalanche-side biosamples
102
+ ```
103
+
104
+ Each row shows the BioCID, ip_id, filename, owner, license status, and
105
+ storage backend (S3 / GCS / Story / Avalanche).
106
+
107
+ ---
108
+
109
+ ## Streaming & analysis — NEW in v2.7
110
+
111
+ This is what most Mac / Linux researchers will use daily. Zero setup;
112
+ pipes cleanly into the tools you already have.
113
+
114
+ ### `biofs stream` — raw bytes to stdout
115
+
116
+ ```bash
117
+ biofs stream 0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7 | bcftools stats -
118
+ biofs stream my-wes | bcftools view -H - | head
119
+ biofs stream my-bam | samtools view -c - # count reads
120
+ biofs stream my-wes | python - <<'PY'
121
+ import pysam, sys
122
+ for v in pysam.VariantFile(sys.stdin):
123
+ print(v.chrom, v.pos, v.ref, v.alts)
124
+ PY
125
+ ```
126
+
127
+ Flags:
128
+ - `--kind variants|reads` force the htsget datatype (default: auto-detect from filename)
129
+ - `--htsget-url <url>` override the endpoint (default: `https://htsget.genobank.app`)
130
+
131
+ ### `biofs pipe` — auto-pipe into the right tool
132
+
133
+ Detects the file format from the registered filename and pipes the
134
+ stream straight into `bcftools view` (VCF) or `samtools view` (BAM).
135
+ Everything after `--` is passed through to the tool.
136
+
137
+ ```bash
138
+ biofs pipe my-wes -- -H # bcftools view -H
139
+ biofs pipe my-wes -- -r chr17 # region filter (client-side)
140
+ biofs pipe my-wes -- -s SAMPLE01 # single sample
141
+ biofs pipe my-bam -- -b | samtools sort # chain
142
+ ```
143
+
144
+ ### `biofs view` — print file content (not piped to a tool)
145
+
146
+ For small files (DTC TXT, CSV, JSON, metadata). Respects GDPR "Right to
147
+ Access" audit logging server-side.
148
+
149
+ ```bash
150
+ biofs view my-dtc --lines 50
151
+ biofs view my-report.json --format pretty
152
+ ```
153
+
154
+ ### `biofs htsget` — low-level GA4GH htsget (debugging)
155
+
156
+ ```bash
157
+ biofs htsget service-info
158
+ biofs htsget ticket variants my-wes # raw ticket JSON
159
+ biofs htsget ticket reads my-bam
160
+ ```
161
+
162
+ Endpoint: `https://htsget.genobank.app` (GA4GH v1.2 compliant).
163
+ Auth: `Authorization: Bearer <signature>` (same signature as `biofs login`).
164
+
165
+ ---
166
+
167
+ ## Downloads
168
+
169
+ When you want the file on disk (not streaming):
170
+
171
+ ```bash
172
+ biofs download my-wes # to ./55052008714000.deepvariant.vcf
173
+ biofs download my-wes ~/analysis/ # into a directory
174
+ biofs download my-wes /tmp/sample.vcf # exact path
175
+ biofs download --force my-wes # overwrite existing
176
+ ```
177
+
178
+ Downloads verify BioNFT ownership on every request and log access for
179
+ GDPR Article 15 (Right to Access). Large files show a progress bar; use
180
+ `--quiet` / `-q` to silence.
181
+
182
+ GDPR-compliant variant (explicit consent prompt):
183
+
184
+ ```bash
185
+ biofs download-with-consent my-wes
186
+ ```
187
+
188
+ ---
189
+
190
+ ## Mounting as a filesystem
191
+
192
+ Three methods, pick based on your platform and use case:
193
+
194
+ | Method | When to use | Requires |
195
+ |---|---|---|
196
+ | `copy` | Simple local work on a small set of files | nothing |
197
+ | `nfs` | Full filesystem semantics on Linux / macOS | BioNFS server + NFS client |
198
+ | `fuse` | **Recommended** for native Unix tool access | `biofs-fuse` binary + FUSE / macFUSE |
199
+
200
+ ```bash
201
+ # 1. Copy method — downloads files on demand, read/write
202
+ biofs mount /mnt/bio --method copy
203
+
204
+ # 2. NFS method — live mount via bionfs server
205
+ biofs mount /mnt/bio --method nfs --biocid biocid://v1/sequentia/IPA/0x…/0x…
206
+
207
+ # 3. FUSE method — Rust-backed driver, lowest latency, xattrs exposed
208
+ biofs mount /mnt/bio --method fuse --biocid biocid://v1/sequentia/IPA/0x…/0x…
209
+
210
+ # Once mounted, use any Unix tool
211
+ ls -la /mnt/bio/
212
+ bcftools view /mnt/bio/sample.vcf | head
213
+ igv /mnt/bio/sample.vcf
214
+ cat /mnt/bio/.status # FUSE-only: consent + owner info
215
+
216
+ # Unmount
217
+ biofs umount /mnt/bio
218
+ ```
219
+
220
+ **FUSE installation:**
221
+
222
+ - **macOS:** `brew install --cask macfuse` (first time needs kext approval + restart) **or** `brew install --cask fuse-t` (no reboot)
223
+ - **Linux:** `sudo apt install fuse3 libfuse3-dev`
224
+ - **biofs-fuse binary:** `git clone github.com/Genobank/biofs-fuse && cd biofs-fuse && cargo build --release`
225
+
226
+ See [biofs-fuse README](https://github.com/Genobank/biofs-fuse) for full setup.
227
+
228
+ **Remote mount on a GPU agent** (for running pipelines on a separate machine):
229
+
230
+ ```bash
231
+ biofs mount-remote <biosample_id> --agent <agent_wallet>
232
+ ```
233
+
234
+ ---
235
+
236
+ ## Uploading & tokenization
237
+
238
+ Simple upload:
239
+
240
+ ```bash
241
+ biofs upload ~/data/sample.vcf # to your BioFS S3
242
+ biofs upload ~/data/reads.fastq.gz --type fastq # force file type
243
+ ```
244
+
245
+ Upload + tokenize as BioNFT:
246
+
247
+ ```bash
248
+ biofs tokenize file ~/data/sample.vcf # VCF → BioIP NFT
249
+ biofs tokenize biosample <biosample_serial> # whole biosample
250
+ biofs tokenize fastqs <biosample_serial> # just the FASTQs
251
+ ```
252
+
253
+ Options:
254
+ - `--title "..."` custom NFT title (default: AI-generated from content)
255
+ - `--description "..."` custom description
256
+ - `--license {commercial,non-commercial,exclusive,public-good,gdpr-research,ai-training,clinical-use,pharma-research,family-inheritance}` — see [Dual PIL architecture](#dual-pil-architecture) below
257
+ - `--no-ai` skip AI classification
258
+ - `--quiet` no interactive prompts (for scripting)
259
+
260
+ **Dual PIL architecture** (license values for `--license`):
261
+ - **Story Protocol PIL** (permanent, `non-commercial`, `commercial`, `exclusive`, `public-good`)
262
+ - **Sequentia BioPIL** (revocable, GDPR-compliant, `gdpr-research`, `ai-training`, `clinical-use`, `pharma-research`, `family-inheritance`)
263
+
264
+ ---
265
+
266
+ ## Access control & sharing
267
+
268
+ ```bash
269
+ # Request access to someone else's BioIP
270
+ biofs access request <ip_id> --message "needed for chr17 study"
271
+
272
+ # Grant access (as the owner, to a requester)
273
+ biofs access grant <request_id> <receiver_wallet>
274
+
275
+ # Revoke access you previously granted
276
+ biofs access revoke <request_id>
277
+
278
+ # Revoke your own biosample consent (GDPR Article 17 — Right to Erasure)
279
+ # Note: triggers off-chain S3 deletion via the BioRouter event listener.
280
+ biofs access revoke-consent <biocid>
281
+
282
+ # See who has access to what
283
+ biofs access list # access you've granted
284
+ biofs shares # full permission graph (by you + to you)
285
+
286
+ # Ad-hoc share
287
+ biofs share <biocid_or_filename> --to <receiver_wallet> --license <license_type>
288
+
289
+ # Check a specific wallet's access to a BioCID
290
+ biofs access check <biocid> --wallet 0x…
291
+ ```
292
+
293
+ ---
294
+
295
+ ## Running research jobs (BioOS)
296
+
297
+ Natural-language research workflows against your BioIPs:
298
+
299
+ ```bash
300
+ biofs job pipelines # list available pipelines
301
+ biofs job create "Annotate VCF with rare coding variants" sample.vcf \
302
+ --pipeline vcf_annotation
303
+ biofs job status <job_id> --watch # live progress
304
+ biofs job results <job_id> # download result URLs
305
+ biofs job list --status running # your job queue
306
+ ```
307
+
308
+ Run results are themselves tokenizable as derivative BioNFTs — the
309
+ ClaraJobNFT contract links each job output back to the source BioIP so
310
+ you get auditable lineage.
311
+
312
+ Quick annotation wrapper:
313
+
314
+ ```bash
315
+ biofs annotate my-wes # OpenCRAVAT with default annotators
316
+ biofs annotate my-wes --annotators clinvar,cosmic # pick specific ones
317
+ ```
318
+
319
+ **Agent health** — check if your GPU compute agent is ready:
320
+
321
+ ```bash
322
+ biofs agent-health
323
+ ```
324
+
325
+ ---
326
+
327
+ ## BioContext manifests
328
+
329
+ EIP-712-signed `.bionft` manifests let you bundle multiple BioIPs into
330
+ a single signed context for research group sharing, clinical trials,
331
+ or consortium data-use agreements.
332
+
333
+ ```bash
334
+ biofs context create --out consortium.bionft \
335
+ --include <biocid1> --include <biocid2>
336
+
337
+ biofs context publish consortium.bionft # pin to IPFS + Sequentia
338
+ biofs context verify consortium.bionft # check signatures + revocations
339
+ biofs context revoke consortium.bionft # propagate revocation
340
+ ```
341
+
342
+ ---
343
+
344
+ ## Aliases — never type hex again
345
+
346
+ Local shortcuts stored at `~/.biofs/aliases.json`:
347
+
348
+ ```bash
349
+ biofs alias my-wes 0xCCe14315eE3D6a41596EeB4a2839eE50A8ec59f7
350
+ biofs alias my-bam 0x9a3E6aEb78363C0b8E240Cc19803d9fe626381C4
351
+ biofs alias --list
352
+
353
+ biofs stream my-wes | bcftools stats - # works everywhere
354
+ biofs pipe my-wes -- -r chr17
355
+ biofs view my-wes
356
+ biofs download my-wes /tmp/
357
+
358
+ biofs alias --remove my-wes
359
+ ```
360
+
361
+ Aliases only resolve on non-hex, non-BioCID inputs — real `ip_id` values
362
+ (`0x…`) and `biocid://` URLs always pass through untouched, so aliases
363
+ can never shadow real identifiers.
364
+
365
+ ---
366
+
367
+ ## BioCID format
368
+
369
+ BioCID is the universal genomic-file identifier used across GenoBank:
370
+
371
+ ```
372
+ biocid://v1/<chain>/IPA/<collection_address>/<token_id>[/<filename>]
373
+ ```
374
+
375
+ Examples:
376
+
377
+ ```
378
+ biocid://v1/sequentia/IPA/0x29853ed299B8FBBe16568840F3Bb2A8E40dc7401/0xCCe14315…
379
+ biocid://v1/story/IPA/0x29853ed299B8FBBe16568840F3Bb2A8E40dc7401/42/sample.bam
380
+ biocid://v1/aeneid/IPA/0x…/99/reads.fastq.gz
381
+ ```
382
+
383
+ - **`<chain>`** — `sequentia` (primary, GDPR-revocable) or `story` / `aeneid` (Story Protocol mainnet / testnet)
384
+ - **`IPA`** — literal, marks this as an Intellectual-Property-Asset reference
385
+ - **`<collection_address>`** — the SPG/ERC-721 collection contract
386
+ - **`<token_id>`** — the NFT token id (matches the `ip_id` for on-chain lookups)
387
+ - **`<filename>`** — optional; disambiguates multi-file BioNFTs
388
+
389
+ Every `biofs` command accepts an `ip_id` (`0x…`), a full BioCID URL,
390
+ or a local alias.
391
+
392
+ ---
393
+
394
+ ## Configuration
395
+
396
+ Files under `~/.biofs/`:
397
+
398
+ | Path | Contents | Mode |
399
+ |---|---|---|
400
+ | `credentials.json` | Signed auth token | `0600` (owner-only) |
401
+ | `aliases.json` | Your local ip_id shortcuts | `0644` |
402
+ | `config.json` | User preferences | `0644` |
403
+ | `cache/` | Per-request metadata cache | |
404
+ | `logs/` | Operation logs | |
405
+
406
+ ### Environment variables
407
+
408
+ | Var | Default | Purpose |
409
+ |---|---|---|
410
+ | `BIOFS_HTSGET_URL` | `https://htsget.genobank.app` | Override htsget endpoint |
411
+ | `BIOFS_API_URL` | `https://bioip.genobank.app` | Override BioIP API endpoint |
412
+ | `BIOFS_SIGNATURE` | (from `credentials.json`) | Supply signature directly (CI/Docker) |
413
+ | `BIOFS_ALIASES` | `~/.biofs/aliases.json` | Override aliases file path |
414
+ | `DEBUG` | — | `DEBUG=1` enables verbose logging |
415
+ | `NO_COLOR` | — | `NO_COLOR=1` disables ANSI colors |
416
+
417
+ ---
418
+
419
+ ## Troubleshooting
420
+
421
+ ### `ENOENT: no such file or directory, open '~/.biofs/credentials.json'`
422
+
423
+ You're not logged in. Run `biofs login`.
424
+
425
+ ### `Signature rejected` / `Expected 65 bytes, got 4`
426
+
427
+ Your cached signature expired. `biofs logout && biofs login`.
428
+
429
+ ### `htsget NotFound: no BioIP with id …`
430
+
431
+ The ip_id doesn't match anything your wallet can access. Check:
432
+
433
+ ```bash
434
+ biofs files | grep <first 10 chars of ip_id>
435
+ biofs access list # requests pending approval?
436
+ ```
437
+
438
+ ### `htsget 401 Unauthorized` / `403 Forbidden`
439
+
440
+ Consent for that BioIP has been revoked, or your access license expired.
441
+ Check with the owner or run `biofs access request <ip_id>` again.
442
+
443
+ ### `bcftools: htsget:// Protocol not supported`
444
+
445
+ Homebrew's default `htslib` ships without htsget compiled in. **Use
446
+ `biofs stream … | bcftools …` instead** — same effect, the CLI does the
447
+ ticket dance for you and pipes raw bytes in.
448
+
449
+ ### Mount fails: `mount_macfuse: the file system is not available`
450
+
451
+ macFUSE kernel extension not loaded. Either:
452
+ - **One-time approval + reboot:** `sudo kmutil load -p /Library/Filesystems/macfuse.fs/Contents/Extensions/14/macfuse.kext`, then System Settings → Privacy & Security → "Allow Benjamin Fleischer" → restart.
453
+ - **No reboot (recommended):** `brew install --cask fuse-t` — drop-in replacement.
454
+
455
+ ### Cloudflare `error code: 1010` on direct `curl`
456
+
457
+ Cloudflare blocks unknown User-Agents. The CLI sends `biofs/2.7.x
458
+ (+https://genobank.io)` automatically. If you're rolling your own script,
459
+ set a real User-Agent:
460
+
461
+ ```bash
462
+ curl -A 'mytool/1.0' -H "Authorization: Bearer $SIG" https://htsget.genobank.app/…
463
+ ```
464
+
465
+ ### `biofs` runs but shows an older version
466
+
467
+ Global installs can shadow each other. Check:
468
+
469
+ ```bash
470
+ which -a biofs # all matches on PATH
471
+ biofs --version # what's actually running
472
+ npm uninstall -g @genobank/biofs # remove
473
+ npm install -g @genobank/biofs@latest
474
+ ```
475
+
476
+ ### Get a full diagnostic report
477
+
478
+ ```bash
479
+ biofs report > biofs-diagnostic.txt
480
+ ```
481
+
482
+ Sends nothing over the network. Includes Node version, install path, auth
483
+ status, endpoint reachability, mount tool availability, and version drift
484
+ info. Attach to any support email.
485
+
486
+ ---
487
+
488
+ ## Security model
489
+
490
+ - **Authentication**: EIP-191 `personal_sign` of `"I want to proceed"`. No passwords, no private keys ever leave your device.
491
+ - **Credentials on disk**: `~/.biofs/credentials.json` is `0600` (owner read/write only). Signatures are never logged or displayed.
492
+ - **Re-verification**: every `stream`, `pipe`, `download`, `mount`, `view` request is gated by a fresh Bearer-auth check against the BioNFT registry on every call — revocation takes effect immediately.
493
+ - **Bearer token in URL?** Only when unavoidable (e.g., signed S3/GCS presigned URLs). Those URLs expire in 1 hour.
494
+ - **Cloudflare TLS** terminates at the edge using the `*.genobank.app` wildcard cert (Google Trust Services).
495
+ - **GDPR**: Sequentia BioPIL supports Article 17 (Right to Erasure) via `biofs access revoke-consent` — triggers server-side S3 deletion. Story Protocol PIL licenses are **permanent** by design; don't use them for personally-identifiable data.
496
+ - **Auto-expiry**: cached credentials rotate every ~30 days.
497
+ - **Secure deletion**: `biofs logout` overwrites credentials before unlinking.
498
+
499
+ ---
500
+
501
+ ## Development
502
+
503
+ ```bash
504
+ git clone git@github.com:Genobank/biofs-cli.git
505
+ cd biofs-cli
506
+ npm install
507
+ npm run build # tsc → dist/
508
+ npm run dev -- stream my-wes # run TypeScript directly
509
+ npm test # jest
510
+ npm link # global `biofs` → this checkout
511
+ ```
512
+
513
+ Architecture:
514
+
515
+ ```
516
+ src/
517
+ ├── index.ts # commander entry + command registration
518
+ ├── commands/ # one file per top-level command
519
+ │ ├── stream.ts # htsget stream → stdout
520
+ │ ├── pipe.ts # stream → bcftools/samtools view
521
+ │ ├── alias.ts # local shortcuts
522
+ │ ├── htsget.ts # low-level GA4GH endpoints
523
+ │ ├── mount.ts # {copy|nfs|fuse} dispatcher
524
+ │ └── …
525
+ ├── lib/
526
+ │ ├── api/client.ts # GenoBankAPIClient (singleton)
527
+ │ ├── auth/ # login + credentials
528
+ │ ├── htsget/client.ts # ticket fetcher
529
+ │ ├── aliases/store.ts # ~/.biofs/aliases.json
530
+ │ ├── biofiles/ # resolver + downloader
531
+ │ ├── context/ # .bionft manifest
532
+ │ └── …
533
+ └── types/ # shared type definitions
534
+ ```
535
+
536
+ Pull requests welcome. Code of conduct in `CONTRIBUTING.md`.
537
+
538
+ ---
539
+
540
+ ## License
541
+
542
+ **AGPL-3.0-or-later** © GenoBank.io
543
+
544
+ If you deploy a modified version of BioFS as a service, you must make
545
+ your source available under the same license. See [`LICENSE`](LICENSE)
546
+ for the full text.
547
+
548
+ ---
549
+
550
+ ## Support
551
+
552
+ - **Web**: <https://genobank.app/biofs>
553
+ - **Docs**: <https://genobank.app/static/Genobank_API_Educational_Guide.html>
554
+ - **GitHub**: <https://github.com/Genobank/biofs-cli>
555
+ - **Security**: [security@genobank.io](mailto:security@genobank.io)
556
+ - **General**: [support@genobank.io](mailto:support@genobank.io)