Post-quantum secure object storage. y2qd is a REST daemon that encrypts every object at rest using ML-KEM-768 key encapsulation and AES-256-GCM, with token-based session authentication, per-bucket access control, and optional post-quantum TLS.
Early development - APIs and on-disk formats may change.
- Documentation
- Features
- Workspace
- Getting Started
- CLI (
y2q) - Load Benchmarking (
y2q-warp) - FUSE Mount (
y2q-fuse) - Configuration
- API Reference
- Object Data Security
- Development
- SECURITY.md - every security mechanism in one place: encryption at rest, key hierarchy, auth/authorization, TLS, and guarded memory (with platform differences called out explicitly)
- docs/architecture.md - system design, encryption envelope (v4 chunked, v3 read-only legacy), storage backends, metadata index, sessions, authorization, S3 gateway
- docs/configuration.md - full config reference: every field, default, TLS, and override syntax
- docs/operations.md - first run, user/role/ACL management, TLS, backup/recovery, runbook
- docs/api.md - complete HTTP API reference: routes, authorization model, schemas, error codes, examples
- docs/search.md - label search query language: operators, regex, grammar, examples
- Post-quantum encryption at rest - each object is encapsulated against an ML-KEM-768 public key; content is encrypted with AES-256-GCM via the pure-Rust aes-gcm crate (hardware AES-NI/NEON accelerated where available, portable to any architecture Rust supports). There is no unauthenticated passthrough - unrecognized or legacy data is rejected outright
- Streaming chunked envelope - objects are encrypted in configurable plaintext chunks (default 4 MiB), so multi-GiB PUTs stream without buffering and
RangeGETs decrypt only the covering chunks - Post-quantum TLS (optional) - native rustls listener offering the X25519MLKEM768 hybrid key exchange;
require_pq_kexcan refuse any client that won't negotiate it; optional mutual TLS via a client CA bundle - Argon2id-protected secret key - the ML-KEM private key is never stored in plaintext; it is wrapped under each user's password and, at rest during an active session, held as sealed ciphertext in guarded memory (Linux; see SECURITY.md)
- Guarded session memory (Linux only) - session identity keys, bucket keys, passwords, and bearer tokens are never plaintext at rest: they're AES-256-GCM ciphertext under a process-ephemeral key living in a locked, non-dumpable page; the daemon also refuses core dumps and same-uid debugger attach. Falls back to a much weaker
Zeroizing-only scheme on macOS/Windows - see SECURITY.md - Token-based session auth - Bearer tokens with configurable TTL, per-account lockout after repeated failures, and a bounded number of refreshes per token (
auth.max_refreshes, default 0 = refresh disabled) so a leaked token can't be extended indefinitely - Bucket ownership, ACLs, and global roles - new buckets are private to their creator; per-bucket grants (read/write/writeonly/admin) plus account-wide roles (admin/user/readonly/writeonly/auditor/disabled). Disable with
auth.enforce_authorization = falsefor single-user deployments - Dual storage backends - portable filesystem backend (all platforms); optional Linux io_uring fast path (kernel >= 5.6); both use the same on-disk
.objformat and are fully cross-compatible - Encrypted, fast listing - embedded redb metadata index, itself encrypted at rest under a key derived from the node key (operator-supplied, or unlocked from a TPM/FIDO2 device registry); auto-rebuilt on startup; can be triggered manually
- Best-effort mode with background flusher - skip per-PUT fsyncs for throughput; a background task drains the dirty queue on a configurable interval
- Custom object labels - attach arbitrary key/value metadata to objects via
X-Y2Q-<label>request headers on PUT; query them with the label search language - S3-compatible gateway (optional) - a second listener (
[s3] enabled = true) speaking AWS SigV4/S3 REST semantics (multipart upload, ranged GET, tagging, delimiter listings). Access uses temporary credentials minted over the authenticated REST API; every S3 request re-resolves the owning session, so logout/expiry/revocation take effect on the S3 surface immediately, mid-transfer included - see docs/api.md#s3-gateway - Prometheus metrics + live trace - Prometheus scrape endpoint; a server-sent-events trace stream (
y2q admin trace) of every request - Structured observability - per-request IDs (
X-Request-ID), INFO/ERROR log events on every request, configurable log format (textorjson) - OpenAPI reference - raw OpenAPI 3 document at
/api-docs/openapi.json(when metrics are exposed)
| Crate | Binary | Purpose |
|---|---|---|
y2qd |
y2qd |
HTTP REST daemon |
y2q-core |
- | Crypto, storage backends, metadata index |
y2q-behavior |
- | Trait-only behavioral contract mirroring y2q-core (I/O, crypto, storage, index), no implementations |
y2q-cli |
y2q |
Client CLI and TUI |
y2q-client |
- | HTTP client library |
y2q-config |
- | Shared config types |
y2q-warp |
y2q-warp |
Load benchmarking tool |
y2q-fuse |
y2q-fuse |
FUSE filesystem driver (mount a store as a directory tree) |
- Rust toolchain (stable, edition 2024)
- Linux kernel >= 5.6 if using the
uringbackend (not required forfilesystem)
cargo build --release -p y2qdThe io_uring backend is always compiled on Linux (no feature flag). On non-Linux
targets it is simply absent, and selecting storage.backend = "uring" at runtime
returns an error - a standard cargo build works everywhere.
On first startup, y2qd generates an ML-KEM-768 keypair and writes a one-time root password to initial-root-password in the keystore directory ([crypto] keystore_dir). The file is created mode 0600. The password is not printed and is not written to the log. The file is UTF-8, one trailing newline per line:
username: root
password: <url-safe-base64>
This file is written exactly once. Stdout and stderr only name the path. Move the file somewhere safe and delete it, then use the password to log in and create additional users. There is no recovery path if you lose it before adding a second user.
./target/release/y2qd --config config.tomlCLI flags:
| Flag | Default | Purpose |
|---|---|---|
--config <path> |
config.toml |
Path to configuration file |
--set KEY=VALUE |
- | Override a config value, e.g. --set server.port=9090 |
Build images locally with make:
make image # y2q:latest - minimal Chainguard runtime (filesystem + uring both compiled in)Run with rootless podman:
podman run \
--network=host \
--userns=keep-id \
--user $(id -u):$(id -g) \
-v /path/to/config.toml:/etc/y2q/config.toml:ro \
-v /path/to/data:/var/lib/y2q/data \
-v /path/to/keys:/var/lib/y2q/keys \
y2q:latest--network=host gives the container direct access to the host network stack - required for rootless podman to expose a port without NAT.
--userns=keep-id maps your host UID into the container unchanged so bind-mounted directories are writable.
The keys directory holds secrets: create it 0700 (mkdir -m 0700 /path/to/keys). A bind-mounted host keys dir replaces the image's 0700 one, so it must be chmod 0700.
The image ships a default config at /etc/y2q/config.toml with base_path = "/var/lib/y2q/data" and keystore_dir = "/var/lib/y2q/keys". Mount your own config over it or override individual values with environment variables (Y2QD_SECTION__KEY=value).
All three binaries (y2qd, y2q, y2q-warp) are present in the image. The entrypoint is y2qd; override to run the others:
podman run --entrypoint y2q --network=host ... y2q:latest ls prod/The root password is not printed. On first run it is written once to initial-root-password in the keystore directory (mode 0600) on the keys volume. Move that file somewhere safe and delete it; do not look for it in container logs.
Build the client:
cargo build --release -p y2q-cli
# or install y2q + y2qd + y2q-warp into ~/.cargo/bin:
make install-localAdd a server alias and log in:
y2q alias set prod https://y2qd.example --user alice
y2q login prodAliases live in ~/.config/y2q/config.toml; cached session tokens in ~/.local/share/y2q/tokens.toml. y2q alias export/import move alias sets between machines as TOML. Paths use alias/bucket/key syntax. An alias URL must be http:// or https://; alias set and alias import reject anything else (an import with any invalid entry saves nothing).
For a self-signed dev endpoint, add --insecure (per alias or per command), or trust a CA bundle with --ca-cert <pem>. For mutual TLS, add --client-cert/--client-key to the alias.
y2q cp report.pdf prod/documents/reports/q1.pdf # upload one file
tar czf - /etc | y2q pipe prod/backups/etc.tar.gz # upload from stdin
y2q cp prod/documents/reports/q1.pdf ./q1.pdf # download to a file
y2q cat prod/documents/reports/q1.pdf | less # download to stdout
y2q mv prod/a/old.txt prod/a/new.txt # rename (copy then delete source)Recursive directory upload (preserves the local tree as remote key paths) and glob patterns:
y2q cp -r ./photos prod/media/photos/
y2q cp '*.log' prod/logs/host1/ # shell-quote so y2q does the expansionAttach labels, or trade durability for speed:
y2q cp notes.txt prod/docs/notes.txt --label project=y2q --label env=prod
y2q cp big.bin prod/data/big.bin --sync best-effort # skip fsyncy2q ls prod/ # list buckets
y2q ls prod/documents/ # list objects in a bucket
y2q ls prod/documents/ --all # auto-paginate
y2q stat prod/documents/q1.pdf # object metadata
y2q head prod/logs/app.log -c 4096 # first N bytes to stdout
y2q get prod/big.bin ./big.bin --range 0-1023 # ranged download
y2q du prod/photos/ --depth 2 # disk usage grouped by prefix
y2q tree prod/media/ --depth 3 # directory tree
y2q find prod/logs/ --name '*.log' --size +10Mi --older-than 7dy2q get (and cp/mv from a remote path to a local one) downloads into a hidden .y2q-part-* file next to the destination (or in the system temp dir if the destination's directory isn't writable) and moves it into place only after the whole transfer succeeds, so a failed download (missing key, bad range, network error) never touches an existing local file. The replacement keeps the file's permission bits but not its owner/group, hard links or extended attributes, and needs room for the old and new copies at once. Output to /dev/stdout and other special files is written directly. If y2q is killed or interrupted (including Ctrl+C), the leftover .y2q-part-* file is not cleaned up; delete it.
Boolean query over labels. Operators: == != =~ (regex) ^= (prefix) $= (suffix); combine with and/or/not and parentheses.
y2q search prod/photos --query 'env == prod and tier != test'
y2q search prod/ --query 'team =~ "infra|sre" and name ^= log-' # all buckets
y2q --json search prod/photos --query 'owner == alice' # JSON outputalias/ searches every bucket; alias/bucket/prefix narrows by bucket and key prefix. Full reference: docs/search.md.
y2q mb prod/archive # create a bucket
y2q rb prod/archive --force # remove a bucket and all its objects
y2q tag set prod/a/x.bin team=infra env=prod # set object tags (labels)
y2q tag ls prod/a/x.bin
y2q quota set prod/archive --size 50g # per-bucket size quota
y2q quota info prod/archiveattribute is an alias of tag (same label store); encrypt records a bucket's informational default-SSE marker.
y2q rm prod/documents/old.txt
y2q rm 'prod/logs/host1/*.log' # glob; prompts before deleting many
y2q rm 'prod/logs/host1/*.log' --force # -f skips the prompty2q diff ./local prod/backup/ # report what differs
y2q mirror ./local prod/backup/ --overwrite --remove # rsync-style one-way sync# users + global roles
y2q admin user add prod bob --role user
y2q admin user ls prod
y2q admin user role prod bob readonly # admin|user|readonly|writeonly|auditor|disabled
y2q admin user rm prod bob
# per-bucket ownership + ACLs
y2q admin acl get prod photos
y2q admin acl grant prod photos bob write # read|write|admin
y2q admin acl revoke prod photos bob
y2q admin acl chown prod photos alice
# index rebuild + stale write locks
y2q admin rebuild start prod
y2q admin rebuild status prod
y2q admin locks ls prod --older-than 30m
y2q admin locks clear prod --older-than 30my2q admin trace prod # stream every request hitting the server
y2q admin trace prod --errors # only status >= 400
y2q watch prod/uploads/ # stream PUT/DELETE/GET/HEAD events under a prefixtrace shows timestamp, method, path, colour-coded status, latency, and payload sizes:
12:34:56.123 PUT /bucket/key 200 42.1ms 1.2 KiB^ 4.0 KiB v
12:34:58.400 DELETE /bucket/missing 404 0.8ms -^ - v
Ctrl-C disconnects; the server has zero overhead when no client is attached.
y2q ping prod # repeated liveness probes
y2q ready prod # single readiness check; non-zero exit if not readyy2q tui # interactive file explorer
y2q # same (default when no subcommand is given)y2q completions fish > ~/.config/fish/completions/y2q.fish
y2q completions zsh > "${fpath[1]}/_y2q"
y2q completions bash > /etc/bash_completion.d/y2qSupported shells: bash, zsh, fish, powershell, elvish.
| Flag | Short | Env | Effect |
|---|---|---|---|
--json |
-j |
Y2Q_OUTPUT |
Output as JSON |
--verbose |
-v |
- | Increase log verbosity (repeatable) |
--quiet |
-q |
- | Silence transfer progress and success lines of put/cp/get/pipe/mv/rm/mirror; warnings and errors still print |
--no-color |
- | NO_COLOR |
Disable ANSI colors |
--debug |
- | - | Maximum verbosity |
--insecure |
- | - | Skip TLS cert verification (dev/staging only) |
--ca-cert <path> |
- | - | Trust this PEM CA bundle for this invocation |
--config <path> |
- | - | Override config file location |
RUST_LOG, if set, overrides the log verbosity set by --verbose/--quiet/--debug only; -q also independently suppresses transfer progress/success lines of put/cp/get/pipe/mv/rm/mirror, and the password-on-command-line warning is not tracing-based so it always prints (see docs/configuration.md#logging).
y2q-warp runs timed workloads against a live y2qd server, records per-operation latencies to a compressed CSV, and shows a live ratatui dashboard. The first positional argument is the alias (server profile), followed by the workload subcommand.
cargo build --release -p y2q-warp# Single-operation benchmarks (alias first, then the workload)
y2q-warp prod put --duration 5m --concurrent 8 --obj-size 4MiB
y2q-warp prod get --duration 5m --concurrent 8 --objects 1000
y2q-warp prod stat --duration 5m --concurrent 16
y2q-warp prod delete --duration 2m
y2q-warp prod list --duration 1m
# Mixed workload (GET 45% / PUT 15% / DELETE 25% / STAT 15%)
y2q-warp prod mixed --duration 10m --concurrent 16
# Pre-seed objects without timing, then run a read benchmark
y2q-warp prod prepare --objects 5000 --obj-size 1MiB
y2q-warp prod get --duration 5m --no-cleanup
y2q-warp prod cleanup
# Variable-size objects
y2q-warp prod put --obj-size-min 64KiB --obj-size-max 16MiBThe alias is node 0; add extra contact endpoints with repeatable --node URLs. Workers round-robin across all nodes. Because sessions are node-local, a multi-node run needs a password (--password or Y2QWARP_PASSWORD) to log into each extra node:
Y2QWARP_PASSWORD=$PW y2q-warp prod mixed \
--node http://localhost:8081 --node http://localhost:8082 \
--node http://localhost:8083 --node http://localhost:8084 \
--duration 60s --concurrent 32The live TUI and the post-run summary both break results down per contact node.
y2q-warp analyze warp-mixed-*.csv.zst
y2q-warp analyze warp-put-*.csv.zst --op PUT --skip 5sOutputs a per-operation summary table (throughput in MiB/s and ops/s, p50/p90/p99 latency, total ops, error count) plus a per-node breakdown when the run fanned across more than one endpoint.
y2q-warp logs to stderr via RUST_LOG (no config file, no -v flag); unset, only error-level events print. See docs/configuration.md#logging.
Mounts a y2q store at a local directory using FUSE, so any program can read and write objects as ordinary files. Linux and macOS. Linux requires libfuse3 (or libfuse2 - it falls back to fusermount if fusermount3 isn't found). macOS requires macFUSE (brew install --cask macfuse); on Apple Silicon you may need to enable the third-party kernel extension in System Settings (or use the kext-free FSKit backend on macOS 26+).
cargo build --release -p y2q-fuse
# or: make install-local (installs y2q, y2qd, y2q-warp, y2q-fuse to ~/.cargo/bin)Log in first, then mount - the alias must already have a valid cached token (y2q login <alias>):
y2q login prod
y2q-fuse --alias prod /mnt/y2qBy default every bucket appears as a top-level directory. Restrict the mount to one bucket (bucket becomes the root) with --bucket:
y2q-fuse --alias prod --bucket photos /mnt/photosUnmount with Ctrl+C, SIGTERM, or manually: fusermount3 -u /mnt/y2q on Linux, umount /mnt/y2q (or diskutil unmount /mnt/y2q) on macOS. The session token is refreshed in the background ~60 seconds before expiry for as long as the mount is alive.
| Flag | Effect |
|---|---|
--alias <NAME> |
Server alias to use (required) |
--config <PATH> |
Config file path (default: platform config dir) |
--bucket <BUCKET> |
Mount a single bucket as the filesystem root; default is all buckets |
--read-only |
Disable all write operations |
--allow-other |
Allow other users to access the mount; requires user_allow_other in /etc/fuse.conf. Without --allow-other-gid, every local user gets read access to every file (mode 0644/0755), not just the intended one |
--allow-other-gid <GID> |
Used with --allow-other: restrict the extra access it grants to group GID (mode 0640/0750, group-owned by GID) instead of every local user |
Overwriting a file with > / O_TRUNC, truncate(2) and ftruncate(2) take effect: the new content is written to the server on close/flush, and readers see it after the close. A truncate with no open handle rewrites the whole object (labels are preserved). File and directory permissions and ownership are fixed: chmod/chown to anything other than the synthetic mode (0644, or 0640 with --allow-other-gid; directories 0755, or 0750 with --allow-other-gid) and the mount's owner/group fail with EPERM, while values equal to the synthetic ones are accepted as no-ops. Tools that request a different mode or owner (for example cp -p, cross-filesystem mv, install -m, install -d under --allow-other-gid, or tar -x and rsync -a run as root, which chown by default) may print permission errors. This was not verified against each tool's exact behaviour. Timestamp changes (touch) are accepted but not stored.
y2q-fuse logs to stderr via RUST_LOG, defaulting to warn when unset. See docs/configuration.md#logging.
config.default.toml in the repo root documents every knob with inline comments. Required fields (no compiled-in default): server.host, server.port, storage.base_path, crypto.keystore_dir, and a node key source: an operator-supplied key (crypto.node_key_file or Y2QD_NODE_KEY; never auto-generated by the daemon) or, on a --features devices Linux build, a device registry at <keystore_dir>/devices.json created by y2q admin device init. Key sections:
[server]
host = "127.0.0.1"
port = 8080
max_body_bytes = 268435456 # 256 MiB upload limit
unauthenticated_metrics = false # expose /metrics/prometheus and /api-docs/openapi.json without auth (else NOT served)
[server.tls]
enabled = false
# cert_path = "/etc/y2q/tls/fullchain.pem"
# key_path = "/etc/y2q/tls/privkey.pem"
# client_ca_path = "/etc/y2q/tls/client-ca.pem" # require mutual TLS
require_pq_kex = true # offer ONLY X25519MLKEM768; refuse classic-only clients
[storage]
base_path = "/var/lib/y2q/data" # required
backend = "filesystem" # "filesystem" or "uring" (Linux only)
default_sync = "durable" # "durable" (fsync) or "best-effort"
sync_flush_interval_secs = 5
sync_flush_limit = 64
[crypto]
keystore_dir = "/var/lib/y2q/keys" # required; keep separate from base_path
node_key_file = "/run/secrets/y2q-node-key" # or set Y2QD_NODE_KEY, or register devices (`y2q admin device init`); one source is required
envelope_chunk_size_bytes = 4194304 # 4 MiB plaintext chunks (current write format: v4)
[crypto.argon2]
m_cost_kib = 65536 # 64 MiB
t_cost = 3
p_cost = 4
[auth]
default_ttl_seconds = 3600
max_ttl_seconds = 86400
max_failed_logins = 10
lockout_seconds = 900
enforce_authorization = true # bucket ownership/ACLs + global admin role
max_refreshes = 0 # times a token may be refreshed; 0 (default) disables refresh entirely
[s3] # optional S3-compatible gateway; disabled by default
enabled = false
host = "127.0.0.1"
port = 9000
region = "y2q" # must match what S3 clients are configured with
[observability]
log_filter = "info" # RUST_LOG syntax; RUST_LOG env var takes precedence
log_format = "text" # "text" or "json"Environment variables override any config file value: prefix the dotted key with Y2QD_ and use __ (two underscores) as the section separator - e.g. Y2QD_SERVER__PORT=9090, Y2QD_OBSERVABILITY__LOG_FORMAT=json. Full schema: docs/configuration.md.
All authenticated routes require Authorization: Bearer <token>. Authorization (bucket ownership, ACLs, global roles) is enforced when auth.enforce_authorization = true (default); see the authorization model.
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST |
/api/v1/auth/login |
No | Obtain a Bearer token |
POST |
/api/v1/auth/refresh |
Yes | Extend session TTL (old token revoked); rejected with 403 past auth.max_refreshes (default 0 = disabled) |
POST |
/api/v1/auth/logout |
Yes | Revoke the current token |
POST |
/api/v1/auth/password |
Yes | Change password |
PUT |
/api/v1/users/add |
Admin | Create a user (optional role) |
GET |
/api/v1/users |
Admin/auditor | List users |
PUT |
/api/v1/users/{user}/role |
Admin | Change a user's global role |
DELETE |
/api/v1/users/{user} |
Admin | Delete a user |
POST |
/api/v1/users/{user}/reset-identity |
Admin | Reset a forgotten password (restores login, not bucket access) |
POST |
/api/v1/personas |
Yes | Add a duress persona (extra password, own credential slot) |
DELETE |
/api/v1/personas/{slot} |
Yes | Overwrite a persona slot with a fresh decoy |
GET |
/api/v1/personas/me |
Yes | The calling session's own slot/role (never the duress flag) |
POST/DELETE |
/api/v1/personas/{slot}/grant |
Yes | Share/revoke your current bucket access with your own other persona |
POST |
/api/v1/s3/credentials |
Yes | Mint a temporary S3 SigV4 credential bound to the caller's session |
GET |
/api/v1/s3/credentials |
Yes | List the caller's own live S3 credentials (never returns a secret) |
DELETE |
/api/v1/s3/credentials/{access_key_id} |
Yes | Revoke one of the caller's own S3 credentials |
Object keys may contain /. Use /{bucket}/{key} where {key} is the full path after the bucket name.
| Method | Path | Auth | Purpose |
|---|---|---|---|
PUT |
/{bucket}/{key} |
write | Store an object (encrypted) |
GET |
/{bucket}/{key} |
read | Retrieve an object (decrypted; supports Range) |
HEAD |
/{bucket}/{key} |
read | Object metadata only |
PATCH |
/{bucket}/{key} |
write | Edit object labels/tags |
DELETE |
/{bucket}/{key} |
write | Delete an object |
PUT |
/{bucket}/ |
write | Create a bucket (caller becomes owner) |
DELETE |
/{bucket}/ |
admin | Remove a bucket and its objects |
GET/PUT |
/api/v1/buckets/{bucket}/config |
read/admin | Read or set bucket config (quota, default-SSE marker) |
GET/PUT |
/api/v1/buckets/{bucket}/acl |
owner/admin | Read or set bucket owner + grants |
Custom labels on PUT: include X-Y2Q-<label>: <value> headers (repeatable). X-Y2Q-Sync: best-effort overrides per-request durability. Range: bytes=N-M on GET returns 206 for chunked and plaintext objects.
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/ |
Yes | List visible non-empty buckets |
GET |
/{bucket}/ |
read | List objects in a bucket (?prefix=, ?after=, ?limit=) |
GET |
/api/v1/search |
read | Find objects by a label query (?q= required, ?bucket=) |
A second listener ([s3] enabled = true, off by default, default port 9000) speaks AWS SigV4/S3 REST semantics - PutObject/GetObject/HeadObject/DeleteObject/CopyObject, bucket create/delete/list, ListObjectsV2, DeleteObjects, object tagging, and full multipart upload - on top of the same storage/crypto/authorization stack as the native API above. There is no password auth on this listener: mint a temporary access key id / secret access key pair via POST /api/v1/s3/credentials (table above) on either listener, then sign requests with SigV4 against [s3] region. Every S3 request re-resolves the owning session (SessionStore::get_active), and a credential's expiry is always clamped to its session's - logout, expiry, and revocation kill S3 access immediately, including mid-transfer. Full reference: docs/api.md#s3-gateway.
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST/GET |
/api/v1/rebuild |
admin / admin+auditor | Start / poll a metadata index rebuild |
GET/DELETE |
/api/v1/locks |
admin+auditor / admin | List / force-release stale in-flight write locks |
GET |
/api/v1/trace |
admin+auditor | Server-sent-events stream of every request |
GET |
/metrics/prometheus |
Gated | Prometheus scrape endpoint |
GET |
/api-docs/openapi.json |
Gated | Raw OpenAPI 3 document |
Both are served only when server.unauthenticated_metrics = true, and then without auth. With the default false neither is registered at all.
y2qd protects not just the object contents but the information about the data - sizes, names, labels, and the listing index. Every layer below is enforced by default (TLS and authorization are opt-in via config). Full design and threat model: docs/architecture.md.
| What is protected | How | Where |
|---|---|---|
| Object contents | Per-object ML-KEM-768 encapsulation -> HKDF-SHA256 -> AES-256-GCM content key, bound to the object's (bucket, key) address and its bucket's current key epoch. Plaintext is sealed in independent chunks (each its own AEAD frame). Nothing is decryptable without the target bucket's epoch secret key, itself sealed individually to every authorized grantee's identity; a ciphertext valid for one object fails to decrypt under a different object's address - copying one object's on-disk envelope onto another object's storage location does not grant access to it. |
crypto/envelope.rs |
| Tamper / integrity | The AEAD tag authenticates every chunk; almost the entire fixed envelope header is bound as AAD (everything except plaintext_len, which is only known after streaming completes), so altering any other header field invalidates the tag. Two non-cryptographic XXH3-64 checksums (of the plaintext, and of the on-disk envelope, both computed incrementally with no read-back) catch accidental corruption and replica divergence - not tamper detection, which is the AEAD tag's job. |
envelope.rs |
| Identity secret keys at rest | Every account carries four fixed credential slots (real or decoy, byte-shape identical). Each slot's ML-KEM-768 identity secret key is Argon2id-wrapped under its own password; once unwrapped on login it is held for the session's whole lifetime (bounded by auth.max_ttl_seconds) as AES-256-GCM ciphertext under a process-ephemeral, guarded-memory key (Linux) - plaintext exists only transiently, inside a locked buffer, for the duration of a single operation. There is no idle-drop knob, because there is no process-wide key left to drop. |
crypto/kdf.rs, auth/session.rs, secmem.rs |
| Bucket secret keys at rest | Each bucket has its own ML-KEM-768 keypair per retained key epoch; its secret is wrapped under a bucket wrap key sealed individually to every authorized grantee's identity - not a single deployment-wide key. A session's resolved bucket keys are cached the same way as its identity key: sealed, not plaintext. Global admin/auditor roles hold no bucket key material at all: visibility follows the crypto grant, not the role. |
crypto/seal.rs |
| Object metadata at rest | The per-object metadata blob (labels, timestamps, checksums, the cleartext key) embedded in each .obj is encrypted with AES-256-GCM under an Object Metadata Key derived from the node key (operator-supplied, or device-unlocked; never a user password) - not stored in the clear. The AEAD is additionally bound to the object's opaque on-disk id via AAD: a metadata blob copied onto a different object's storage location fails to decrypt there, the same anti-relocation property as the object envelope above. |
crypto/node_keys.rs |
| Listing index at rest | The whole redb metadata index is encrypted (per-4 KiB-block AES-256-GCM, block index bound as AAD) under an Index File Key derived from the node key. It is resident for the daemon's whole lifetime - the daemon cannot serve anything without the node key, so there is nothing to idle-drop. | storage/index.rs |
| File and bucket names | On-disk directory and file names are irreversible keyed HMAC-SHA256 under a path key derived from the node key, so the storage tree leaks neither bucket names nor object keys to anyone who can read the directory. | storage/filesystem.rs |
| Object size | Plaintext length is rounded up with Padmé padding before encryption, so the on-disk size leaks at most O(log log n) bits about the true size (<~12% overhead). The exact size lives only in the encrypted metadata. | envelope.rs (padme_len) |
| Data in transit | Optional native TLS ([server.tls]) via rustls, restrictable to the X25519MLKEM768 post-quantum hybrid group (require_pq_kex), with optional mutual TLS. |
tls.rs |
| Access | Bucket ownership + per-bucket ACLs + global roles (when auth.enforce_authorization = true); a bucket you have no relationship to is hidden (404, never 403) so existence cannot be probed. |
authz.rs |
| Session tokens | Only SHA-256(token) is held in memory - the plaintext token itself is guarded-memory ciphertext, never persisted, and a daemon restart invalidates every session. Repeated failed logins lock the account behind a response-time floor. |
auth/session.rs |
| S3 gateway credentials | Temporary access-key/secret pairs (POST /api/v1/s3/credentials) bound to token_hash at mint time, expiry clamped to min(requested, session.expires_at), secret sealed the same way as identity keys. Every S3 request re-resolves the owning session before trusting the credential, so logout/expiry/revocation apply on the S3 surface too, including mid-transfer. |
s3/state.rs, s3/auth.rs |
| Memory disclosure (Linux only)* | A core dump, swap page, same-uid ptrace//proc/<pid>/mem read, or an idle VM snapshot yields no session identity keys, bucket keys, passwords, or bearer tokens - they're sealed ciphertext under a process-ephemeral key in locked, non-dumpable pages; the daemon also sets PR_SET_DUMPABLE=0/RLIMIT_CORE=0 and refuses to start if guarded memory itself is unavailable (override: [server] allow_unprotected_memory). |
secmem.rs, SECURITY.md |
| Duress passwords | Up to three additional passwords per account (POST /api/v1/personas), each unlocking a fully separate identity with its own bucket grants and an optional flag that silently switches every other live session on the account over to this persona on login, in place - deniable under coercion, no revocation, no silent alarm. |
docs/operations.md#duress-personas |
* Guarded memory is Linux-only. On macOS/Windows, secmem falls back to a Zeroizing-backed scheme with none of the above - plaintext sits in ordinary, swappable, dumpable heap the whole session. See SECURITY.md.
What it does not defend against: a live memory read timed to a request actually in flight (guarded memory closes idle disclosure, not a read mid-operation), object body plaintext in ordinary heap, a leaked Bearer token until it expires or is revoked, and traffic analysis when TLS is disabled. See the full threat model and SECURITY.md for the complete boundary.
Root on the live host and device unlock: a root attacker on a running host reads in-flight object-body plaintext from ordinary heap, and can invoke the TPM unseal. With a device registry, use the socket-activated key helper (y2q-keyd.socket + y2q-keyd@.service, y2qd --key-serve; root arms with y2q-keyarm before each start) so a compromised daemon uid holds only one transient NK copy from boot and gets neither RMK, the TPM, nor the ability to forge devices.json, and cannot re-fetch without a root-armed authorization; the legacy in-process mode (empty [crypto.devices] key_agent_socket) is weaker. The principal exposure is the software-only away time-box: a copy of a medium taken while an away grant was live stays openable with the token (and PIN, if uv_required) regardless of not_after_unix. Guarded memory is required by default: the daemon refuses to start without memfd_secret unless [server] allow_unprotected_memory is set. See SECURITY.md.
make build # debug build, all workspace crates
make test # run all tests
make clippy # lint (warnings as errors)
make fmt # format
make check # fmt-check + clippy + test (CI gate)
make install-local # install y2q + y2qd + y2q-warp into ~/.cargo/binRequired after any code change (CI gate): cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, cargo build --all-targets --all-features, then make check. Run make help for all targets including per-binary builds, release builds, and image targets.