λgitsite

~ober/jerboa-drive

Imported from ~/mine/jerboa-drive

download snapshot

about

# jerboa-drive

`jdrive` is a Jerboa-native, client-side encrypted drive backed by an
S3-compatible object store. The remote service sees opaque encrypted objects;
profile configuration and wrapped key material stay under `~/.jdrive` by
default.

The project currently supports one storage backend: S3.

## Quick start

Build the dependencies pinned in `dependency-lock.tsv`, then inspect the CLI:

```sh
make deps
make run ARGS='help'
```

Create a profile using the normal AWS credential chain:

```sh
export AWS_PROFILE=personal
export AWS_REGION=us-east-1

make run ARGS='s3 init --profile default --bucket my-private-bucket'
make run ARGS='s3 profile-status --profile default'
```

The initializer reads `JDRIVE_VAULT_PASSWORD` automatically, or prompts when
the variable is unset. `--vault-password-env NAME` remains available for a
differently named secret variable. Use a unique, high-entropy password and do
not store it in the repository.

Upload, inspect, and restore data:

```sh
make run ARGS='s3 cp notes.txt jd:/notes.txt'
make run ARGS='s3 ls jd:/'
make run ARGS='s3 cat jd:/notes.txt'
make run ARGS='s3 get jd:/notes.txt restored-notes.txt'
make run ARGS='s3 sync -v ./photos jd:/photos --delete'
```

Run `jdrive help` for all commands and options. See
[the user guide](docs/user-guide.md) for profile, sync, range-read, YubiKey,
and packaging details.

## Configuration

The main environment variables are:

- `AWS_PROFILE`, `AWS_REGION`, `AWS_DEFAULT_REGION`, and the standard AWS
  credential variables used by `jerboa-aws`.
- `JDRIVE_S3_BUCKET`, `JDRIVE_S3_PREFIX`, `JDRIVE_S3_ENDPOINT`, and
  `JDRIVE_S3_PATH_STYLE` for the object-store target.
- `JDRIVE_PROFILE` and `JDRIVE_STATE_DIR` for local profile selection.

Endpoint overrides make MinIO and other S3-compatible services usable. Path
style can be enabled with `--path-style` or `JDRIVE_S3_PATH_STYLE=1`.

Remote paths use the short `jd:` prefix: `jd:photos` and `jd:/photos` both
address `/photos`. The older `jdrive:` prefix remains compatible. Sync `-v`
prints progress to stderr.

## Storage and encryption

Each profile has a local configuration document and encrypted key vault. Drive
manifests, file records, and chunk records are authenticated and encrypted
before upload. Large files use independently authenticated chunks, enabling
bounded-memory transfer and range reads. Manifest generations are recorded
locally so rollback or tampering is rejected.

The implementation uses `jerboa-crypto` for OpenSSL-backed primitives,
`jerboa-aws` for SigV4/S3 requests, and `jerboa-yubikey` for optional PIV-backed
unlock material. The detailed trust boundaries are in
[the security model](docs/security-model.md).

## Development

```sh
make test
make security
make binary
make bundle
```

On macOS and other non-Linux platforms, `make binary` is the canonical
pre-commit build. Linux release CI uses the repository's static pipeline.
`make bundle` produces `dist/jerboa-drive-<os>-<arch>.tar.gz`; run the packaged
`jdrive` launcher rather than the internal binary directly.

The local integration test is opt-in because it creates and removes objects in
a real bucket:

```sh
make s3-integration
```

Use only a disposable test prefix and review the test's required environment
before enabling it.

## Repository layout

- `jdrive/cli.ss` — command parsing and dispatch.
- `jdrive/s3/config.ss` — S3 target configuration.
- `jdrive/s3/drive.ss` — profile vault, encrypted manifests, transfers, sync,
  and object operations.
- `test/test-all.ss` — local crypto, manifest, path, and vault tests.
- `support/` — reproducible build, native bundle, and launcher hardening.
- `scripts/` — security and release-evidence checks.

Dependencies are fetched at locked commits into the ignored `.deps/`
directory. Build files never depend on adjacent source checkouts.

## Release policy

`VERSION` is authoritative. Every pull request must advance it and keep package
metadata and user-visible output synchronized. Changes are merged only through
a reviewed Forgejo pull request.

recent commits