BenchVault

Public beta: BenchVault helps LabArchives notebook owners make full-size local backup copies, review them offline, verify preserved attachments, and get a warning if protected local backup files change later.

It is built for labs that need more than a lightweight web export: local access during outages or travel, readable review copies, original attachment preservation, integrity checks, and search that works even when the notebook website is unavailable.

Download the latest beta · Read the Quickstart PDF · Open the documentation site

This build targets the FedRAMP-authorized LabArchives environment used at NIH. The app and user-facing docs use the shorter name LabArchives.

Why Try It

• Full-size backup workflow. BenchVault downloads the full-size LabArchives archive when the signed-in account is allowed to do so.
• Offline read-only viewer. Browse backed-up pages, comments, attachments, and readable search copies without writing anything back to LabArchives.
• Attachment confidence. Check whether reported original files were preserved, then preview common lab formats such as PDF, Office, CSV, FASTA, Sanger traces, Jupyter notebooks, TIFF, ZIP, images, and media.
• Tamper-evidence for local copies. Each successful backup receives local file fingerprints; the viewer warns if protected files change later.
• Optional AI-assisted search. Save an AI API key locally to ask questions over selected backed-up excerpts, with links back to source pages. Local search works without an AI key.

Who It Is For

BenchVault is useful for notebook owners, lab managers, research integrity staff, data stewards, and scientific IT teams who need local review copies of LabArchives notebooks.

At NIH, full-size LabArchives backup is generally owner-only. A notebook may be visible to an account but still fail full-size backup if that account is not the notebook owner.

Try The Demo First

BenchVault ships with a synthetic notebook copy that opens before any LabArchives setup. Use it to evaluate the viewer without credentials.

The demo shows:

• A broad preview gallery: CSV, FASTA, Sanger trace, SnapGene-style DNA, SDF chemistry, PDF, Excel, Jupyter, TIFF, PNG, ZIP, and media attachments.
• A verified local integrity seal and Certify Copy witness-email draft.
• AI-assisted search behavior plus the local fallback search path.

Public Beta Status

macOS is the primary beta target. Windows builds are generated by CI and now include Windows Credential Manager plus disk-space preflight validation. iPadOS builds are generated for signing review and read-only viewer work, but iPadOS backup creation is blocked in this beta because LabArchives .7z extraction still requires desktop archive tooling.

Current macOS beta builds are unsigned and not notarized yet. macOS may say it cannot verify BenchVault.app and may offer to move it to the Trash. Download only from this GitHub repository, compare the release checksum when possible, then use System Settings > Privacy & Security > Open Anyway or Control-click BenchVault.app > Open if you decide to run the beta.

Screenshots

Technical Capabilities

• Prompts for LabArchives credentials on first launch.
• Lets the user choose the local folder for routine backup copies.
• Checks credentials, notebook access, backup folder access, storage space, archive extraction, read-only LabArchives access, search settings, and schedule state before backup starts.
• Shows the result for each notebook: backed up, skipped, or needs review.
• Backs up every notebook the authenticated user owns and can back up through the LabArchives API.
• Uses LabArchives only for sign-in, notebook access lookup, and notebook backup download; it does not add, update, delete, upload, or write content back to LabArchives.
• Keeps the original LabArchives .7z archive for preservation.
• Extracts and indexes notebook pages for local read-only viewing.
• Shows page breadcrumbs, page counts, comment counts, attachment counts, and a compact page outline in the offline reader.
• Writes a separate easy-to-read copy and search data for every successful backup.
• Provides notebook search with local matching by default and optional AI-assisted answers when the user saves an AI API key locally, including filters for text, attachments, comments, exact phrase, and verified backups.
• Recognizes LabArchives attachment families in the viewer, including browser images, text/tabular files, PDFs, Office documents, Jupyter notebooks, SnapGene/sequence files, chemical structure files, media, archives, and unknown custom formats.
• Previews LabArchives-viewable attachment families with visual or domain-specific views where possible: image previews, table previews, sequence viewers, Sanger trace chromatograms, molecule sketches, Jupyter cell cards, spreadsheet table previews, Quick Look thumbnails, format-specific PDF/Office/TIFF/media fallback cards, and structured file lists for packages.
• Shows attachment preservation evidence in the viewer, including original file preservation, LabArchives-viewable status, BenchVault preview status, byte size, and a Copy Original action.
• Verifies reported original attachment files by byte size before marking a notebook backup successful.
• Retries eligible skipped notebooks from the latest run while leaving owner-permission skips as clear owner guidance.
• Records digital fingerprints for each successful backup and warns in the viewer if any protected backup file changes later.
• Exports local audit summaries for backup runs as Markdown, JSON, CSV, and a short external hash record without exposing credentials.
• Offers a skippable Certify Copy action that opens a prepared witness email for a verified local backup-copy fingerprint.
• Ships with a synthetic demo backup so users can try read-only review, attachment previews, Certify Copy, and AI-assisted search with source references before connecting LabArchives.
• Stores LabArchives and AI keys in platform secret storage where available; notebook metadata, schedules, integrity records, and backups stay local or in the user-selected backup folder.
• Supports manual backup plus daily or weekly scheduled backup while the app is open.

Platform Strategy

• macOS is the first target and primary development environment.
• Windows support is started through Flutter and now has GitHub Actions build and prerelease packaging validation.
• iPad support is started through Flutter iOS and now has GitHub Actions unsigned build validation for Apple signing review.
• Shared LabArchives, backup, parsing, and verification logic stays in Dart so platform-specific code remains small.
• Visual styling uses an NIH/HHS-aligned palette: federal blue as the primary action color, gold as a restrained secondary accent, and cool grays for dense notebook review surfaces.

Current status:

Platform	Status
macOS	Native Flutter .app builds, runs, and is packaged by the tag release workflow.
Windows	CI builds and packages a prerelease zip on windows-latest; Credential Manager and disk-space preflight are wired, but real workstation validation and installer signing are still pending.
iPad	CI builds an unsigned iPadOS validation app; full backup creation is blocked in this beta until archive extraction is implemented without desktop tools.

Repository Layout

docs/
  strategic_plan.md
  implementation_limitations.md
  assets/
    benchvault-banner.svg
    screenshots/
  developer/
    labarchives_gov_api_reference.md
  user/
    BenchVault_Quickstart.pdf
    quickstart.md
lib/
  main.dart
  src/
scripts/
test/
tool/

Documentation

• Quickstart PDF
• Quickstart source
• GitHub Pages documentation site
• Trust, safety, and correctness model
• Strategic implementation plan
• Implementation limitations
• Platform release checklist
• LabArchives API working reference
• Release notes
• Documentation index

The original LabArchives API source PDF is intentionally kept local under local_docs/ and is ignored by Git. The compact developer reference is the tracked substitute used during implementation.

Citation And Archiving

BenchVault includes repository metadata for software indexing and release archiving:

• CITATION.cff for GitHub citation support.
• codemeta.json for structured software metadata.
• .zenodo.json so Zenodo can archive releases with useful metadata.
• Zenodo all-versions DOI: 10.5281/zenodo.20329338.

Current Limitations

BenchVault is macOS-first and focused on LabArchives backup/offline viewing. It is not a LabArchives editor, legal certification system, write-once storage system, or background service. Auto backups currently run only while the app is open, readable views simplify some LabArchives formatting, and Windows and iPad support still need real-device/platform validation beyond CI builds. iPad currently targets read-only review of backups already prepared by the desktop app, not creating full LabArchives backups on-device. See the implementation limitations for the full list.

License

Apache-2.0. See LICENSE.

Local-Only Data Rules

• Use paths relative to the project root in tracked files.
• Never commit machine-specific absolute paths.
• Never commit real credentials, tokens, access keys, local auth XML, notebook IDs, downloaded source PDFs, or raw notebook backups.
• Keep local setup files under ignored paths such as local_credentials/, local_docs/, .env.local, or a user-selected backup folder outside the repository.
• Commit placeholder templates only when examples are needed.

Development

flutter analyze
flutter test
flutter build macos
scripts/run_macos_app.sh

Useful helper commands:

python3 scripts/labarchives_auth_flow.py --email your.email@example.gov --open-browser
dart run tool/backup_once.dart
python3 tool/build_quickstart_pdf.py
scripts/release_smoke_check.sh
scripts/package_macos_release.sh <version>
pwsh scripts/package_windows_release.ps1 <version>
scripts/package_ipados_validation.sh <version>

Release automation:

• .github/workflows/ci.yml runs tests, analyzer, safety scans, seeder dry-run, macOS build, Windows build, and unsigned iPadOS build validation on push and pull request.
• .github/workflows/release.yml runs on v* tags, creates or updates the GitHub prerelease, then uploads macOS, Windows, and unsigned iPadOS validation assets with platform-specific checksum files.
• The iPadOS validation zip is a build artifact for signing review. It is not an installable iPad release without Apple Developer signing, provisioning, and distribution through an approved channel.

The synthetic test-notebook seeder is intentionally write-capable and is locked behind a double opt-in so it cannot be run accidentally:

BENCHVAULT_ALLOW_LABARCHIVES_TEST_WRITES=YES_WRITE_SYNTHETIC_TEST_NOTEBOOK \
  python3 scripts/labarchives_seed_bio_test_notebook.py \
  --i-understand-this-writes-to-labarchives-test-notebook

For clean public screenshots, use Open Demo Backup on the setup screen or run the app with demo data:

scripts/run_macos_app.sh --demo