FragSeal

FragSeal is a secure single-file backup CLI. It splits a file into chunks, encrypts each chunk in the C++ cryptography layer, uploads them through an object storage backend, and records the backup in a TOML manifest.

The public surface is intentionally storage- and backup-oriented:

• fragseal upload
• fragseal download
• manifest.toml

Compatibility

Host	Build / Run mode
macOS 26+	Native CLI binary
macOS 14+	Backdeploy bundle (also runs on 26+)
Linux	Build and test on a Linux host or Docker container

Install

Prebuilt binaries are published for each release: GitHub Releases

Choose the asset for your host (<tag> example: v0.1.4):

Host	Asset
macOS 26+	fragseal-<tag>-macos-26-universal.tar.gz
macOS 14+	fragseal-<tag>-macos-14-universal.tar.gz
Linux x86_64	fragseal-<tag>-linux-x86_64.tar.gz
Linux arm64	fragseal-<tag>-linux-arm64.tar.gz

For single-binary assets (macOS 26+ and Linux):

TAG=v0.1.4
tar -xzf "fragseal-${TAG}-linux-x86_64.tar.gz"
sudo install -m 755 fragseal-linux-x86_64/fragseal /usr/local/bin/fragseal
fragseal --help

For macOS 14+ backdeploy bundle:

TAG=v0.1.4
tar -xzf "fragseal-${TAG}-macos-14-universal.tar.gz"
cd fragseal-macos-14-universal
./fragseal --help

Keep the Frameworks/ directory next to fragseal in the backdeploy bundle.

Build with Bazel

Install Bazel or Bazelisk.

Common commands:

make build
make build PRODUCT=framework
make build PLATFORM=macos RUNTIME=backdeploy
make build PLATFORM=linux
make test
make project

make test runs both the core test suite and a CLI artifact functional test for the selected host/runtime.

Useful direct Bazel targets:

bazel build //FragSeal:fragseal
bazel build //FragSeal:universal_fragseal
bazel build //FragSealCore:FragSealCore

make project generates FragSeal.xcodeproj.

Runtime requirements

• OpenSSL is optional. When available, FragSeal enables modern crypto modes (aes-256-gcm, chacha20-poly1305).
• On Apple platforms, CommonCrypto is always used for legacy-aes-128-cbc restore compatibility.
• none mode requires no crypto runtime dependencies.
• Linux builds also require libxml2 headers for the AWS/Smithy XML stack.
• For S3 uploads/downloads, standard AWS credential resolution is used.
• For non-interactive runs, set FRAGSEAL_PASSPHRASE.

Linux packages:

sudo apt-get install -y libssl-dev libxml2-dev pkg-config clang lldb lld

If OpenSSL is present but the runtime library is in a non-standard location, provide:

OPENSSL_LIB=/absolute/path/to/libcrypto make test

Usage

USAGE: fragseal <subcommand>

SUBCOMMANDS:
  upload      Encrypt, chunk, and upload a file
  download    Restore a file from a TOML manifest

Upload to local storage:

fragseal upload \
  --input archive.bin \
  --manifest backup.toml \
  --storage-uri file:///tmp/fragseal

Upload to S3:

fragseal upload \
  --input archive.bin \
  --manifest backup.toml \
  --storage-uri s3://my-bucket/backups \
  --region us-east-1 \
  --algorithm aes-256-gcm

Restore:

fragseal download \
  --manifest backup.toml \
  --output restored.bin

Passphrase input:

• Interactive TTY: prompt securely
• Non-interactive: FRAGSEAL_PASSPHRASE=...
• none mode: no passphrase required
• When --algorithm is omitted, FragSeal prompts on interactive terminals; non-interactive runs should pass --algorithm explicitly.

Manifest format

FragSeal writes TOML manifests with storage, encryption, and chunk metadata. nonce/iv live in the manifest, not in chunk payload prefixes.

version = 1

[backup]
id = "uuid"
source_name = "archive.bin"
created_at = "2026-03-07T12:00:00Z"
chunk_size = 67108864
original_size = 123456789
original_sha256 = "hex"

[storage]
backend = "s3"
bucket = "my-bucket"
region = "us-east-1"
prefix = "backups/<backup-id>"

[encryption]
# encrypted backups include mode/kdf/salt/iterations/wrapped_key

[[chunks]]
index = 0
object_key = "backups/<backup-id>/chunks/00000000.bin"
offset = 0
plaintext_size = 67108864
ciphertext_size = 67108880
sha256 = "hex"
nonce = "base64"

Supported encryption modes:

• none (plaintext chunks, no crypto dependency)
• aes-256-gcm
• chacha20-poly1305
• legacy-aes-128-cbc (read-only restore compatibility)

Test fixtures

Framework tests use deterministic backup fixtures under FragSealCoreTests/Resources.

Generate or refresh them with:

make resources

The fixture generator now creates:

• legacy_plaintext.bin
• legacy_chunk_0.bin
• legacy_chunk_1.bin

These fixtures are used for legacy restore compatibility tests only.

Test matrix

Host-native commands:

make test
make build PRODUCT=cli PLATFORM=macos RUNTIME=backdeploy
make build PRODUCT=cli PLATFORM=linux

On macOS, Linux validation can be run through Docker:

docker compose run --rm --entrypoint /bin/bash swift-linux -lc 'make build PLATFORM=linux'
docker compose run --rm --entrypoint /bin/bash swift-linux -lc 'make test PLATFORM=linux'

If the repo is mounted as a linked Git worktree, copy it to a temp directory inside the container before running Bazel so the .git indirection stays valid.

VS Code setup (bis)

This project uses bis as a dev dependency for VS Code / SourceKit-LSP integration.

Compile commands

Generate (or refresh) compile_commands.json for Go-to-definition, hover docs, and the Show Swift Interface for Clang Header task:

bazel run //.bis:refresh_compile_commands

Re-run this whenever you add or change Bazel targets.

Debugger

launch.json is not tracked because the binary path is architecture-specific. Create .vscode/launch.json with the path that matches your host:

{
    "configurations": [
        {
            "debuggerRoot": "${workspaceFolder}",
            "name": "Launch",
            "preLaunchTask": "${config:bis.pre_launch_task_name}",
            "program": "${workspaceFolder}/bazel-out/<cpu>-fastbuild/bin/FragSeal/fragseal",
            "request": "launch",
            "sourcePath": "${workspaceFolder}",
            "type": "lldb-dap"
        },
        {
            "debuggerRoot": "${workspaceFolder}",
            "name": "Attach",
            "program": "${workspaceFolder}/bazel-out/<cpu>-fastbuild/bin/FragSeal/fragseal",
            "request": "attach",
            "sourcePath": "${workspaceFolder}",
            "type": "lldb-dap"
        }
    ],
    "version": "2.0.0"
}

Replace <cpu> with your host CPU string. You can find it by running:

bazel build //FragSeal:fragseal && ls bazel-out/ | grep fastbuild

Common values: darwin_arm64, darwin_x86_64, k8.

Show Swift Interface for Clang Header

Mixed C++/Swift modules expose their C++ API to Swift via Clang modules. The Show Swift Interface for Clang Header task synthesizes the Swift view of a given .hpp header — useful for checking argument labels, type mappings, and Span<T> wrappers generated by SafeInteropWrappers.

Usage:

1. Open any .hpp file from an include/ directory.
2. Run Tasks: Run Task → Show Swift Interface for Clang Header (⇧⌘P → Tasks: Run Task).
3. The synthesized interface opens in a new editor tab as /tmp/<header>.swiftinterface.

compile_commands.json must be up to date (see Compile commands above). The script reads it to find which Clang module owns the header and what compiler flags to pass to swift-synthesize-interface.

Backdeploy note

To validate backdeploy behavior on macOS (including 26+), run the backdeploy bundle produced by:

make build PLATFORM=macos RUNTIME=backdeploy
./bazel-bin/FragSeal/fragseal_backdeploy

On macOS 26+, prefer the native binary for normal use; use backdeploy only for compatibility validation.