Aegiro

Local-only encrypted vault for macOS
_{Argon2id • Chunk AEAD v1 (AES-GCM / ChaCha20-Poly1305) • Post-quantum key protection}

Quick Start • Protection Modes • Docs Map • Build

---

What Is This?

Aegiro is a local-first encrypted vault system for macOS:

• CLI + app workflows for encrypted vault operations
• AGVT v1 storage format with chunked encrypted file data
• APFS disk encryption support with recovery bundles
• Portable USB container flow for non-APFS filesystems
• Non-APFS USB file packing into .agvt via usb-vault-pack

---

Format Status

• Active on-disk format is AGVT v1 (sequential header/wrap/index/manifest/chunk-map/chunk-area layout).
• Read/write paths use v1 chunk key/AAD labels (AEGIRO-FILE-KEY-V1, AEGIRO-CHUNK-V1) with header version = 1 and chunk AEAD id 1.
• New chunk writes prefer AES-GCM on all architectures; ChaCha20-Poly1305 remains supported for fallback and compatibility with existing vault data.
• Reader paths retain legacy compatibility for vaults marked with chunk AEAD id 2, including mixed legacy/v1 chunk domains in existing vault data.

---

Protection Modes

Mode	Commands	Best for	Notes
APFS volume encryption	apfs-volume-encrypt / apfs-volume-decrypt	Dedicated APFS external drives	In-place APFS encryption using diskutil
Portable encrypted container	usb-container-create / usb-container-open / usb-container-close	exFAT/FAT/NTFS/APFS USB drives	Encrypted APFS sparsebundle stored on host filesystem
Non-APFS file-level vault packing	usb-vault-pack	Existing non-APFS USB media	Packs user files into AGVT vault file (data.agvt)

---

Quick Start

# Build package
bash scripts/build.sh
./dist/aegiro-cli --version

# Create a vault
./dist/aegiro-cli create --vault ~/AegiroVaults/alpha.agvt --passphrase "<pass>"

# Import files
./dist/aegiro-cli import --vault ~/AegiroVaults/alpha.agvt --passphrase "<pass>" ~/Downloads/file.pdf

# Batch import in one run (faster than repeated one-file imports)
./dist/aegiro-cli import --vault ~/AegiroVaults/alpha.agvt --passphrase "<pass>" \
  ~/Downloads/file-a.pdf ~/Downloads/file-b.pdf ~/Desktop/notes.txt

# List and export
./dist/aegiro-cli list --vault ~/AegiroVaults/alpha.agvt --passphrase "<pass>"
./dist/aegiro-cli export --vault ~/AegiroVaults/alpha.agvt --passphrase "<pass>" --out ~/Recovered
# Export keeps logical paths under --out (avoids duplicate filename collisions)
# Imported logical paths are stored as relative paths (not absolute host paths).

# Whole-folder packing (recommended for folder/USB workflows)
./dist/aegiro-cli usb-vault-pack --source ~/MyFolder --vault ~/AegiroVaults/data.agvt --passphrase "<pass>"

---

Core CLI

create, import, delete, lock, unlock, list, export, preview
backup, restore, verify, status, doctor, scan, shred
apfs-volume-encrypt, apfs-volume-decrypt
usb-container-create, usb-container-open, usb-container-close
usb-vault-pack

Use ./dist/aegiro-cli --help for full options.

---

Build

brew install liboqs argon2 openssl@3
bash scripts/build.sh

Outputs:

• dist/aegiro-cli
• dist/aegiro-cli-macos-arm64.tar.gz

Build app bundles for both Apple Silicon and Intel (plus universal app):

# Apple Silicon deps
brew install liboqs argon2 openssl@3

# Intel deps (required on Apple Silicon hosts for x86_64 build)
arch -x86_64 /usr/local/bin/brew install liboqs argon2 openssl@3

# Generate app icon (.icns) from your artwork
bash scripts/generate-app-icon.sh --source assets/aegiro-banner.png --overwrite

# Build arm64 + x86_64 + universal app bundle
bash scripts/build-app-universal.sh --configuration release --ad-hoc

# Package the universal app as a styled DMG
# (if omitted, script auto-uses assets/dmg-background.png or assets/aegiro-banner.png when present)
bash scripts/package-dmg.sh \
  --app dist/Aegiro.app \
  --output dist/Aegiro.dmg \
  --background assets/aegiro-banner.png \
  --overwrite

Outputs:

• dist/Aegiro-arm64.app
• dist/Aegiro-x86_64.app
• dist/Aegiro.app (universal)
• dist/Aegiro.dmg

If assets/AppIcon.icns exists, app build scripts include it in the app bundle automatically. scripts/package-dmg.sh sets Finder window/icon positions so users see a drag-to-Applications layout.

---

Docs Map

Jump between project markdown pages:

• Encryption Scheme Paper (Implementation)
• USB Encryption Schematics
• USB Encryption Diagrams
• Documentation Index
• Repository Structure
• App UI Design
• macOS File Associations
• Ownership & Usage
• Agent Workflow Rules

---

Notes

• Default file-count limit per vault: 1,000 (AEGIRO_MAX_FILES_PER_VAULT to override).
• Non-APFS metadata paths are skipped in USB user-data flow.
• Prefer batched imports in one command; repeated small imports are slower because each run rewrites vault metadata/chunk map.
• Export preserves logical paths under the output directory by default.
• Chunk encryption uses per-file derived keys and opaque chunk-map file IDs (no plaintext file paths in chunk map).
• All encryption workflows are local; no telemetry endpoints are used by default.

---

License

This project uses a custom source-available license in LICENSE.txt.

• External contributions and pull requests are accepted.
• Contribution workflow and requirements are in CONTRIBUTING.md.
• Redistribution or republication (including App Store listings and DMG/binary distribution) is not allowed.
• Full terms and ownership boundaries are defined in LICENSE.txt and docs/legal/OWNERSHIP.md.