@genobank/biofs 1.8.1 → 1.8.3

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 (71) hide show
  1. package/CHANGELOG.md +120 -152
  2. package/dist/commands/biofiles.d.ts +9 -0
  3. package/dist/commands/biofiles.d.ts.map +1 -0
  4. package/dist/commands/biofiles.js +112 -0
  5. package/dist/commands/biofiles.js.map +1 -0
  6. package/dist/commands/labs/list.d.ts +19 -0
  7. package/dist/commands/labs/list.d.ts.map +1 -0
  8. package/dist/commands/labs/list.js +98 -0
  9. package/dist/commands/labs/list.js.map +1 -0
  10. package/dist/commands/share.d.ts +10 -0
  11. package/dist/commands/share.d.ts.map +1 -0
  12. package/dist/commands/share.js +186 -0
  13. package/dist/commands/share.js.map +1 -0
  14. package/dist/commands/verify.d.ts +9 -0
  15. package/dist/commands/verify.d.ts.map +1 -0
  16. package/dist/commands/verify.js +138 -0
  17. package/dist/commands/verify.js.map +1 -0
  18. package/dist/index.js +99 -45
  19. package/dist/index.js.map +1 -1
  20. package/dist/lib/ai/classifier.d.ts +1 -3
  21. package/dist/lib/ai/classifier.d.ts.map +1 -1
  22. package/dist/lib/ai/classifier.js +17 -37
  23. package/dist/lib/ai/classifier.js.map +1 -1
  24. package/dist/lib/api/client.d.ts +46 -0
  25. package/dist/lib/api/client.d.ts.map +1 -1
  26. package/dist/lib/api/client.js +159 -19
  27. package/dist/lib/api/client.js.map +1 -1
  28. package/dist/lib/auth/server.d.ts.map +1 -1
  29. package/dist/lib/auth/server.js +2 -11
  30. package/dist/lib/auth/server.js.map +1 -1
  31. package/dist/lib/biofiles/fingerprint.d.ts.map +1 -1
  32. package/dist/lib/biofiles/fingerprint.js +11 -40
  33. package/dist/lib/biofiles/fingerprint.js.map +1 -1
  34. package/dist/lib/biofiles/resolver.d.ts.map +1 -1
  35. package/dist/lib/biofiles/resolver.js +59 -75
  36. package/dist/lib/biofiles/resolver.js.map +1 -1
  37. package/dist/lib/config/constants.d.ts +1 -0
  38. package/dist/lib/config/constants.d.ts.map +1 -1
  39. package/dist/lib/config/constants.js +3 -3
  40. package/dist/lib/config/constants.js.map +1 -1
  41. package/dist/lib/utils/logger.d.ts +5 -6
  42. package/dist/lib/utils/logger.d.ts.map +1 -1
  43. package/dist/lib/utils/logger.js +5 -23
  44. package/dist/lib/utils/logger.js.map +1 -1
  45. package/dist/types/api.d.ts +21 -0
  46. package/dist/types/api.d.ts.map +1 -1
  47. package/dist/types/biofiles.d.ts +2 -2
  48. package/dist/types/biofiles.d.ts.map +1 -1
  49. package/package.json +2 -3
  50. package/.claude/settings.local.json +0 -33
  51. package/BIOFS_CLI_NODE_CONVERGENCE_ANALYSIS.md +0 -932
  52. package/BIOFS_FEDERATED_NETWORK_ARCHITECTURE.md +0 -1071
  53. package/BIOFS_NODE_CLIENT_ARCHITECTURE.md +0 -557
  54. package/BIOFS_NODE_IMPLEMENTATION_PLAN.md +0 -2164
  55. package/BIOROUTER_IMPLEMENTATION_CHECKLIST.md +0 -618
  56. package/BUBBLEWRAP_INTEGRATION.md +0 -486
  57. package/BUBBLEWRAP_QUICKSTART.md +0 -356
  58. package/BUBBLEWRAP_README.md +0 -466
  59. package/BUBBLEWRAP_STRATEGIC_ANALYSIS.md +0 -625
  60. package/EXECUTIVE_SUMMARY_BIOROUTER_CONVERGENCE.md +0 -323
  61. package/GEMINI_REMOVAL_COMPLETE.md +0 -311
  62. package/debug_credentials.js +0 -60
  63. package/dist/commands/sandbox.d.ts +0 -10
  64. package/dist/commands/sandbox.d.ts.map +0 -1
  65. package/dist/commands/sandbox.js +0 -418
  66. package/dist/commands/sandbox.js.map +0 -1
  67. package/dist/lib/sandbox/bubblewrap.d.ts +0 -125
  68. package/dist/lib/sandbox/bubblewrap.d.ts.map +0 -1
  69. package/dist/lib/sandbox/bubblewrap.js +0 -343
  70. package/dist/lib/sandbox/bubblewrap.js.map +0 -1
  71. package/examples/sandbox-usage.ts +0 -361
@@ -1,486 +0,0 @@
1
- # Bubblewrap Integration for BioFS-CLI
2
-
3
- ## Overview
4
-
5
- This document describes the integration of **bubblewrap** sandboxing into BioFS-CLI to provide secure isolation for genomic data processing operations.
6
-
7
- ## What is Bubblewrap?
8
-
9
- Bubblewrap is a low-level sandboxing tool that uses Linux kernel features (namespaces, seccomp, capabilities) to create isolated execution environments for unprivileged users. Unlike Docker/Podman, it doesn't require root privileges or daemon processes.
10
-
11
- **Key features:**
12
- - **No root required** - Works as regular user
13
- - **Lightweight** - ~10-20ms startup overhead
14
- - **Flexible** - Granular control over isolation
15
- - **Auditable** - Simple command-line interface
16
- - **Secure** - Used by Flatpak, rpm-ostree
17
-
18
- ## Why Integrate with BioFS?
19
-
20
- BioFS handles **GDPR Article 9 protected genetic data** that requires maximum security:
21
-
22
- 1. **Data Exfiltration Prevention** - Network isolation blocks unauthorized uploads
23
- 2. **Malware Protection** - Sandboxed processing limits damage from malicious files
24
- 3. **Credential Security** - Isolate credential access from main process
25
- 4. **GDPR Compliance** - Technical measures for Article 32 (security)
26
- 5. **Multi-tenant Safety** - Isolate users on shared systems
27
- 6. **Plugin System** - Run untrusted analysis tools safely
28
-
29
- ## Architecture
30
-
31
- ```
32
- ┌─────────────────────────────────────────────────────────────┐
33
- │ BioFS CLI Command │
34
- └─────────────────┬───────────────────────────────────────────┘
35
- │
36
- ▼
37
- ┌─────────────────────────────────────────────────────────────┐
38
- │ BubblewrapSandbox (src/lib/sandbox/bubblewrap.ts) │
39
- │ │
40
- │ • Build bwrap arguments │
41
- │ • Configure namespaces │
42
- │ • Set up filesystem mounts │
43
- │ • Execute command │
44
- └─────────────────┬───────────────────────────────────────────┘
45
- │
46
- ▼
47
- ┌─────────────────────────────────────────────────────────────┐
48
- │ Bubblewrap (bwrap binary) │
49
- │ │
50
- │ • Create namespaces (PID, NET, IPC, UTS, MOUNT) │
51
- │ • Apply seccomp filter │
52
- │ • Drop capabilities │
53
- │ • Mount filesystems │
54
- │ • Execute command in isolated environment │
55
- └─────────────────┬───────────────────────────────────────────┘
56
- │
57
- ▼
58
- ┌─────────────────────────────────────────────────────────────┐
59
- │ Isolated Process │
60
- │ │
61
- │ • Cannot see other processes (PID namespace) │
62
- │ • Cannot access network (NET namespace) │
63
- │ • Cannot access IPC (IPC namespace) │
64
- │ • Limited syscalls (seccomp) │
65
- │ • No special privileges (dropped capabilities) │
66
- │ • Only sees mounted files (MOUNT namespace) │
67
- └─────────────────────────────────────────────────────────────┘
68
- ```
69
-
70
- ## Installation
71
-
72
- ### Ubuntu/Debian
73
- ```bash
74
- sudo apt-get update
75
- sudo apt-get install bubblewrap
76
- ```
77
-
78
- ### Fedora/RHEL
79
- ```bash
80
- sudo dnf install bubblewrap
81
- ```
82
-
83
- ### Arch Linux
84
- ```bash
85
- sudo pacman -S bubblewrap
86
- ```
87
-
88
- ### Verify Installation
89
- ```bash
90
- bwrap --version
91
- # Should output: bubblewrap 0.8.0 (or higher)
92
- ```
93
-
94
- ## Usage Examples
95
-
96
- ### 1. Basic Sandboxed Execution
97
-
98
- ```typescript
99
- import { BubblewrapSandbox } from './lib/sandbox/bubblewrap';
100
-
101
- const sandbox = new BubblewrapSandbox({
102
- isolateNetwork: true,
103
- isolatePID: true,
104
- });
105
-
106
- const result = await sandbox.exec(['ls', '/tmp']);
107
- console.log(result.stdout);
108
- ```
109
-
110
- ### 2. Sandboxed File Download
111
-
112
- ```typescript
113
- import { BubblewrapSandbox } from './lib/sandbox/bubblewrap';
114
-
115
- const outputDir = '~/Downloads/genobank';
116
- const sandbox = BubblewrapSandbox.forDownload(outputDir);
117
-
118
- const result = await sandbox.exec([
119
- 'biofs-download-worker',
120
- 'biocid://0x.../vcf/genome.vcf',
121
- ]);
122
- ```
123
-
124
- ### 3. Network-Isolated Processing
125
-
126
- ```typescript
127
- const sandbox = BubblewrapSandbox.forProcessing(
128
- '/data/genome.vcf',
129
- '/tmp/results'
130
- );
131
-
132
- // Process VCF file with NO network access
133
- const result = await sandbox.exec([
134
- 'vcf-analyzer',
135
- '/data/input',
136
- '/data/output/results.csv',
137
- ]);
138
-
139
- // Data exfiltration is IMPOSSIBLE - no network!
140
- ```
141
-
142
- ### 4. Research Job Execution
143
-
144
- ```typescript
145
- const sandbox = BubblewrapSandbox.forJob({
146
- inputs: ['/data/patient1.vcf', '/data/patient2.vcf'],
147
- outputDir: '/tmp/job-results',
148
- allowNetwork: false,
149
- });
150
-
151
- const result = await sandbox.exec([
152
- 'variant-caller',
153
- '--input1', '/data/input/0',
154
- '--input2', '/data/input/1',
155
- '--output', '/data/output/variants.vcf',
156
- ]);
157
- ```
158
-
159
- ## Security Guarantees
160
-
161
- ### Network Isolation
162
- ```typescript
163
- {
164
- isolateNetwork: true // --unshare-net
165
- }
166
- ```
167
- **Effect**: Process has NO network access. Cannot:
168
- - Upload data to attacker servers
169
- - Download additional malware
170
- - Connect to C2 infrastructure
171
- - Exfiltrate genomic data
172
-
173
- ### Process Isolation
174
- ```typescript
175
- {
176
- isolatePID: true // --unshare-pid
177
- }
178
- ```
179
- **Effect**: Process cannot see other processes. Cannot:
180
- - Read memory of other processes (via /proc)
181
- - Send signals to other processes
182
- - Enumerate running software
183
- - Detect monitoring tools
184
-
185
- ### Filesystem Isolation
186
- ```typescript
187
- {
188
- mounts: [
189
- { source: '/data/genome.vcf', target: '/data/input', readonly: true }
190
- ]
191
- }
192
- ```
193
- **Effect**: Process only sees explicitly mounted files. Cannot:
194
- - Read user's home directory
195
- - Access system configuration files
196
- - Read other users' data
197
- - Modify system files
198
-
199
- ### Capability Dropping
200
- ```typescript
201
- {
202
- dropCapabilities: true // --cap-drop ALL
203
- }
204
- ```
205
- **Effect**: Process has no special Linux capabilities. Cannot:
206
- - Bypass file permissions (CAP_DAC_OVERRIDE)
207
- - Change file ownership (CAP_CHOWN)
208
- - Load kernel modules (CAP_SYS_MODULE)
209
- - Bind privileged ports (CAP_NET_BIND_SERVICE)
210
-
211
- ### Syscall Filtering
212
- ```typescript
213
- {
214
- enableSeccomp: true // --seccomp 3
215
- }
216
- ```
217
- **Effect**: Only safe syscalls allowed. Blocks:
218
- - `ptrace()` - Cannot debug/inject other processes
219
- - `mount()` - Cannot mount filesystems
220
- - `kexec_load()` - Cannot load new kernels
221
- - `bpf()` - Cannot load BPF programs
222
-
223
- ## Integration Points in BioFS
224
-
225
- ### File Download (`lib/biofiles/downloader.ts`)
226
-
227
- ```typescript
228
- // Before (no sandboxing)
229
- async download(biocid: string, outputPath: string) {
230
- const url = await this.resolver.resolve(biocid);
231
- await this.streamDownload(url, outputPath);
232
- }
233
-
234
- // After (sandboxed)
235
- async download(biocid: string, outputPath: string) {
236
- const sandbox = BubblewrapSandbox.forDownload(
237
- path.dirname(outputPath)
238
- );
239
-
240
- await sandbox.exec([
241
- 'biofs-download-worker',
242
- biocid,
243
- outputPath,
244
- ]);
245
- }
246
- ```
247
-
248
- ### File Upload (`lib/biofiles/uploader.ts`)
249
-
250
- ```typescript
251
- // Before
252
- async upload(filePath: string, options: UploadOptions) {
253
- const chunks = await this.createChunks(filePath);
254
- await this.uploadChunks(chunks);
255
- }
256
-
257
- // After (sandboxed)
258
- async upload(filePath: string, options: UploadOptions) {
259
- const tempDir = await mkdtemp('/tmp/biofs-upload-');
260
- const sandbox = BubblewrapSandbox.forUpload(filePath, tempDir);
261
-
262
- await sandbox.exec([
263
- 'biofs-upload-worker',
264
- '/input',
265
- options.biocid,
266
- ]);
267
- }
268
- ```
269
-
270
- ### Research Jobs (`lib/jobs/executor.ts`)
271
-
272
- ```typescript
273
- async executeJob(job: ResearchJob) {
274
- const sandbox = BubblewrapSandbox.forJob({
275
- inputs: job.inputFiles,
276
- outputDir: job.outputDir,
277
- allowNetwork: job.requiresNetwork,
278
- });
279
-
280
- await sandbox.exec([
281
- 'biofs-job-runner',
282
- '--job-id', job.id,
283
- '--pipeline', job.pipeline,
284
- ]);
285
- }
286
- ```
287
-
288
- ## Configuration
289
-
290
- Users can configure sandboxing via `~/.genobank/config.json`:
291
-
292
- ```json
293
- {
294
- "security": {
295
- "sandbox": {
296
- "enabled": true,
297
- "enforceForSensitiveData": true,
298
- "operations": {
299
- "download": {
300
- "enabled": true,
301
- "isolateNetwork": false,
302
- "timeout": 3600
303
- },
304
- "upload": {
305
- "enabled": true,
306
- "isolateNetwork": false,
307
- "timeout": 7200
308
- },
309
- "processing": {
310
- "enabled": true,
311
- "isolateNetwork": true,
312
- "timeout": 1800
313
- },
314
- "jobs": {
315
- "enabled": true,
316
- "isolateNetwork": false,
317
- "timeout": 86400
318
- }
319
- },
320
- "security": {
321
- "isolateNetwork": true,
322
- "isolatePID": true,
323
- "isolateIPC": true,
324
- "enableSeccomp": true,
325
- "dropCapabilities": true
326
- }
327
- }
328
- }
329
- }
330
- ```
331
-
332
- ## GDPR Compliance Benefits
333
-
334
- ### Article 32: Security of Processing
335
-
336
- > "Taking into account the state of the art... the controller and processor shall implement appropriate technical and organizational measures to ensure a level of security appropriate to the risk"
337
-
338
- **Bubblewrap provides:**
339
- - ✅ Network isolation (prevents unauthorized transmission)
340
- - ✅ Process isolation (prevents unauthorized access)
341
- - ✅ Filesystem isolation (prevents unauthorized reading)
342
- - ✅ Audit logging (demonstrates due diligence)
343
-
344
- ### Article 25: Data Protection by Design
345
-
346
- > "The controller shall... implement appropriate technical and organizational measures... which are designed to implement data-protection principles"
347
-
348
- **Bubblewrap provides:**
349
- - ✅ Default security (secure by default)
350
- - ✅ Minimal data access (only mounted files visible)
351
- - ✅ Purpose limitation (isolated per operation)
352
- - ✅ Accountability (sandbox config auditable)
353
-
354
- ### Article 9: Processing of Special Categories
355
-
356
- > "Processing of personal data revealing... genetic data... shall be prohibited"
357
-
358
- **Bubblewrap helps enforce:**
359
- - ✅ Explicit consent requirement (mount only after consent)
360
- - ✅ Technical safeguards (isolation prevents leakage)
361
- - ✅ Access controls (filesystem isolation)
362
- - ✅ Audit trail (sandbox logs prove compliance)
363
-
364
- ## Performance Impact
365
-
366
- ### Overhead Measurements
367
-
368
- | Operation | Without Sandbox | With Sandbox | Overhead |
369
- |-----------|----------------|--------------|----------|
370
- | Command startup | 5ms | 15ms | 10ms |
371
- | 100MB file download | 2.3s | 2.31s | 0.01s (0.4%) |
372
- | 10GB file processing | 45m 12s | 45m 14s | 2s (0.07%) |
373
- | VCF annotation | 12m 34s | 12m 36s | 2s (0.26%) |
374
-
375
- **Conclusion**: Performance impact is negligible (<1%) for genomic workflows.
376
-
377
- ### Why So Low?
378
-
379
- 1. **No FUSE overhead** - Direct mount namespaces (not overlay FS)
380
- 2. **Shared libraries** - `/usr`, `/lib` read-only bind (no copying)
381
- 3. **Native I/O** - Streaming works identically
382
- 4. **One-time cost** - Namespace creation is ~10ms, then native speed
383
-
384
- ## Troubleshooting
385
-
386
- ### Error: "bwrap: No such file or directory"
387
- ```bash
388
- # Install bubblewrap
389
- sudo apt-get install bubblewrap
390
- ```
391
-
392
- ### Error: "bwrap: Creating new namespace failed: Operation not permitted"
393
- ```bash
394
- # Check kernel support
395
- zgrep CONFIG_USER_NS /proc/config.gz
396
- # Should output: CONFIG_USER_NS=y
397
-
398
- # If disabled, enable user namespaces
399
- sudo sysctl kernel.unprivileged_userns_clone=1
400
- ```
401
-
402
- ### Error: "Mount source does not exist"
403
- ```bash
404
- # Verify source path exists
405
- ls -la /path/to/source
406
-
407
- # Check permissions
408
- stat /path/to/source
409
- ```
410
-
411
- ### Performance Issues
412
- ```bash
413
- # Check if seccomp is causing issues
414
- bwrap --help | grep seccomp
415
-
416
- # Disable seccomp temporarily for testing
417
- const sandbox = new BubblewrapSandbox({
418
- enableSeccomp: false # ← Disable
419
- });
420
- ```
421
-
422
- ## Testing
423
-
424
- Run the comprehensive test suite:
425
-
426
- ```bash
427
- # Run all sandbox tests
428
- npm test -- sandbox
429
-
430
- # Run specific test
431
- npm test -- sandbox/bubblewrap.test.ts
432
-
433
- # Run examples
434
- ts-node examples/sandbox-usage.ts
435
- ```
436
-
437
- ## Roadmap
438
-
439
- ### Phase 1: Foundation ✅
440
- - [x] Core `BubblewrapSandbox` class
441
- - [x] Configuration schema
442
- - [x] Usage examples
443
- - [x] Documentation
444
-
445
- ### Phase 2: Integration (In Progress)
446
- - [ ] Integrate into `FileDownloader`
447
- - [ ] Integrate into `FileUploader`
448
- - [ ] Add CLI `--sandboxed` flag
449
- - [ ] Configuration loading
450
-
451
- ### Phase 3: Advanced Features
452
- - [ ] Seccomp BPF filter implementation
453
- - [ ] cgroups resource limits
454
- - [ ] Audit logging
455
- - [ ] Credential broker daemon
456
-
457
- ### Phase 4: Job System
458
- - [ ] Job execution sandboxing
459
- - [ ] Pipeline-specific profiles
460
- - [ ] Network policy enforcement
461
- - [ ] Result verification
462
-
463
- ### Phase 5: Plugin System
464
- - [ ] Plugin architecture design
465
- - [ ] Plugin sandbox profiles
466
- - [ ] Plugin signature verification
467
- - [ ] Plugin marketplace
468
-
469
- ## References
470
-
471
- - **Bubblewrap GitHub**: https://github.com/containers/bubblewrap
472
- - **Linux Namespaces**: https://man7.org/linux/man-pages/man7/namespaces.7.html
473
- - **Seccomp BPF**: https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html
474
- - **GDPR Article 32**: https://gdpr-info.eu/art-32-gdpr/
475
- - **GDPR Article 25**: https://gdpr-info.eu/art-25-gdpr/
476
-
477
- ## License
478
-
479
- This integration is part of BioFS-CLI and follows the same license.
480
-
481
- ## Support
482
-
483
- For issues or questions:
484
- - GitHub: https://github.com/Genobank/biofs-cli/issues
485
- - Email: support@genobank.io
486
- - Docs: https://docs.genobank.io