@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.
- package/CHANGELOG.md +76 -0
- package/README.md +556 -201
- package/dist/commands/alias.d.ts +9 -0
- package/dist/commands/alias.d.ts.map +1 -0
- package/dist/commands/alias.js +56 -0
- package/dist/commands/alias.js.map +1 -0
- package/dist/commands/bionft/revoke.d.ts +6 -0
- package/dist/commands/bionft/revoke.d.ts.map +1 -0
- package/dist/commands/bionft/revoke.js +74 -0
- package/dist/commands/bionft/revoke.js.map +1 -0
- package/dist/commands/bionft/status.d.ts +2 -0
- package/dist/commands/bionft/status.d.ts.map +1 -0
- package/dist/commands/bionft/status.js +45 -0
- package/dist/commands/bionft/status.js.map +1 -0
- package/dist/commands/bionft/view.d.ts +5 -0
- package/dist/commands/bionft/view.d.ts.map +1 -0
- package/dist/commands/bionft/view.js +127 -0
- package/dist/commands/bionft/view.js.map +1 -0
- package/dist/commands/cred/issue.d.ts +12 -0
- package/dist/commands/cred/issue.d.ts.map +1 -0
- package/dist/commands/cred/issue.js +95 -0
- package/dist/commands/cred/issue.js.map +1 -0
- package/dist/commands/cred/lib.d.ts +23 -0
- package/dist/commands/cred/lib.d.ts.map +1 -0
- package/dist/commands/cred/lib.js +95 -0
- package/dist/commands/cred/lib.js.map +1 -0
- package/dist/commands/cred/list.d.ts +7 -0
- package/dist/commands/cred/list.d.ts.map +1 -0
- package/dist/commands/cred/list.js +65 -0
- package/dist/commands/cred/list.js.map +1 -0
- package/dist/commands/cred/revoke.d.ts +6 -0
- package/dist/commands/cred/revoke.d.ts.map +1 -0
- package/dist/commands/cred/revoke.js +60 -0
- package/dist/commands/cred/revoke.js.map +1 -0
- package/dist/commands/cred/status.d.ts +5 -0
- package/dist/commands/cred/status.d.ts.map +1 -0
- package/dist/commands/cred/status.js +41 -0
- package/dist/commands/cred/status.js.map +1 -0
- package/dist/commands/htsget.d.ts +8 -0
- package/dist/commands/htsget.d.ts.map +1 -0
- package/dist/commands/htsget.js +43 -0
- package/dist/commands/htsget.js.map +1 -0
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +15 -0
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/pipe.d.ts +8 -0
- package/dist/commands/pipe.d.ts.map +1 -0
- package/dist/commands/pipe.js +76 -0
- package/dist/commands/pipe.js.map +1 -0
- package/dist/commands/stream.d.ts +9 -0
- package/dist/commands/stream.d.ts.map +1 -0
- package/dist/commands/stream.js +58 -0
- package/dist/commands/stream.js.map +1 -0
- package/dist/commands/upload-fastq.d.ts +10 -0
- package/dist/commands/upload-fastq.d.ts.map +1 -0
- package/dist/commands/upload-fastq.js +60 -0
- package/dist/commands/upload-fastq.js.map +1 -0
- package/dist/commands/vault/mount.d.ts +8 -0
- package/dist/commands/vault/mount.d.ts.map +1 -0
- package/dist/commands/vault/mount.js +136 -0
- package/dist/commands/vault/mount.js.map +1 -0
- package/dist/commands/vault/setup.d.ts +6 -0
- package/dist/commands/vault/setup.d.ts.map +1 -0
- package/dist/commands/vault/setup.js +160 -0
- package/dist/commands/vault/setup.js.map +1 -0
- package/dist/commands/vault/status.d.ts +4 -0
- package/dist/commands/vault/status.d.ts.map +1 -0
- package/dist/commands/vault/status.js +97 -0
- package/dist/commands/vault/status.js.map +1 -0
- package/dist/commands/vault/unmount.d.ts +6 -0
- package/dist/commands/vault/unmount.d.ts.map +1 -0
- package/dist/commands/vault/unmount.js +90 -0
- package/dist/commands/vault/unmount.js.map +1 -0
- package/dist/index.js +354 -23
- package/dist/index.js.map +1 -1
- package/dist/lib/aliases/store.d.ts +7 -0
- package/dist/lib/aliases/store.d.ts.map +1 -0
- package/dist/lib/aliases/store.js +83 -0
- package/dist/lib/aliases/store.js.map +1 -0
- package/dist/lib/auth/server.d.ts.map +1 -1
- package/dist/lib/auth/server.js +21 -2
- package/dist/lib/auth/server.js.map +1 -1
- package/dist/lib/bionft/BioAssetVault.abi.json +1104 -0
- package/dist/lib/bionft/BioNFTCredentials.abi.json +1235 -0
- package/dist/lib/bionft/client.d.ts +45 -0
- package/dist/lib/bionft/client.d.ts.map +1 -0
- package/dist/lib/bionft/client.js +219 -0
- package/dist/lib/bionft/client.js.map +1 -0
- package/dist/lib/htsget/client.d.ts +54 -0
- package/dist/lib/htsget/client.d.ts.map +1 -0
- package/dist/lib/htsget/client.js +76 -0
- package/dist/lib/htsget/client.js.map +1 -0
- package/dist/utils/errorReporter.d.ts +6 -0
- package/dist/utils/errorReporter.d.ts.map +1 -1
- package/dist/utils/errorReporter.js +53 -0
- package/dist/utils/errorReporter.js.map +1 -1
- package/package.json +4 -4
- package/dist/commands/access-sequentia.d.ts +0 -35
- package/dist/commands/access-sequentia.d.ts.map +0 -1
- package/dist/commands/access-sequentia.js +0 -256
- package/dist/commands/access-sequentia.js.map +0 -1
- package/dist/commands/biofiles-sequentia.d.ts +0 -21
- package/dist/commands/biofiles-sequentia.d.ts.map +0 -1
- package/dist/commands/biofiles-sequentia.js +0 -238
- package/dist/commands/biofiles-sequentia.js.map +0 -1
- package/dist/commands/download-sequentia.d.ts +0 -19
- package/dist/commands/download-sequentia.d.ts.map +0 -1
- package/dist/commands/download-sequentia.js +0 -159
- package/dist/commands/download-sequentia.js.map +0 -1
- package/dist/commands/researcher/register.d.ts +0 -24
- package/dist/commands/researcher/register.d.ts.map +0 -1
- package/dist/commands/researcher/register.js +0 -192
- package/dist/commands/researcher/register.js.map +0 -1
- package/dist/commands/researcher/status.d.ts +0 -24
- package/dist/commands/researcher/status.d.ts.map +0 -1
- package/dist/commands/researcher/status.js +0 -235
- package/dist/commands/researcher/status.js.map +0 -1
- package/dist/commands/researcher/verify.d.ts +0 -24
- package/dist/commands/researcher/verify.d.ts.map +0 -1
- package/dist/commands/researcher/verify.js +0 -167
- package/dist/commands/researcher/verify.js.map +0 -1
- package/dist/commands/share-sequentia.d.ts +0 -21
- package/dist/commands/share-sequentia.d.ts.map +0 -1
- package/dist/commands/share-sequentia.js +0 -161
- package/dist/commands/share-sequentia.js.map +0 -1
- package/dist/commands/tokenize-sequentia.d.ts +0 -21
- package/dist/commands/tokenize-sequentia.d.ts.map +0 -1
- package/dist/commands/tokenize-sequentia.js +0 -191
- package/dist/commands/tokenize-sequentia.js.map +0 -1
- package/dist/commands/verify-sequentia.d.ts +0 -18
- package/dist/commands/verify-sequentia.d.ts.map +0 -1
- package/dist/commands/verify-sequentia.js +0 -150
- package/dist/commands/verify-sequentia.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,201 +1,556 @@
|
|
|
1
|
-
# BioFS
|
|
2
|
-
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
#
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
#
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
#
|
|
58
|
-
biofs
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
#
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
#
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
biofs
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
#
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
#
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
##
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
#
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/@genobank/biofs)
|
|
9
|
+
[](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)
|