hanna/fabrica

feat(blob): S3-compatible object storage for uploads

6b2bf21 · hanna committed on 2026-07-26

Add a `blob` crate exposing a `BlobStore` over the local filesystem or an
S3-compatible object store (AWS S3, MinIO, Cloudflare R2, Backblaze B2, …),
selected by `storage.backend = "local" | "s3"`. The `[storage.s3]` section
carries bucket, region, endpoint, credentials, path-style, and key-prefix, so
non-AWS stores work too. Bare git repos always stay local.

The S3 HTTP client is wired explicitly with the aws-lc-rs rustls provider so the
default (ring-based) client is never linked, keeping `ring` out of the tree and
the license gate green. Keys are namespaced and validated against traversal;
the local backend preserves the historical on-disk layout (no migration).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +549 −21

Cargo.toml +15 −0

crates/blob/Cargo.toml +24 −0

crates/blob/src/lib.rs +562 −0

crates/config/src/lib.rs +65 −3

crates/config/src/types.rs +56 −1

docs/decisions.md +28 −0

fabrica.example.toml +15 −1

 config = { path = "crates/config" }
 store = { path = "crates/store" }
 model = { path = "crates/model" }
+blob = { path = "crates/blob" }
 git = { path = "crates/git" }
 highlight = { path = "crates/highlight" }
 auth = { path = "crates/auth" }
 ] }
 # SSH server (default features: aws-lc-rs backend, no ring; re-exports ssh-key).
 russh = "0.62"
+# S3-compatible object storage for uploads (avatars, release assets, LFS).
+# aws-lc-rs crypto (already in the tree via russh) so `ring` stays out and the
+# license gate holds; see docs/decisions.md. Manual client config (static creds,
+# custom endpoint) avoids the heavier aws-config credential-provider chain.
+aws-sdk-s3 = { version = "1", default-features = false, features = [
+    "behavior-version-latest",
+    "rt-tokio",
+] }
+# The HTTP client is wired explicitly with the aws-lc-rs rustls provider so the
+# default (ring-based) client is never pulled in — keeping `ring` out of the tree.
+aws-smithy-http-client = { version = "1", default-features = false, features = [
+    "rustls-aws-lc",
+] }
+bytes = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt", "json"] }

+[package]
+name = "blob"
+description = "Upload storage over the local filesystem or an S3-compatible object store."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+publish.workspace = true
+[dependencies]
+config = { workspace = true }
+tokio = { workspace = true }
+thiserror = { workspace = true }
+aws-sdk-s3 = { workspace = true }
+aws-smithy-http-client = { workspace = true }
+bytes = { workspace = true }
+[dev-dependencies]
+tempfile = { workspace = true }
+[lints]
+workspace = true

 pub use crate::secret::{REDACTED, Secret};
 pub use crate::types::{
     Auth, Captcha, CaptchaProvider, Config, Database, DefaultVisibility, Git, Instance, Log,
-    LogFormat, LogLevel, Mail, MailBackend, MailEncryption, Search, Server, Ssh, Storage, Ui,
+    LogFormat, LogLevel, Mail, MailBackend, MailEncryption, S3, Search, Server, Ssh, Storage,
+    StorageBackend, Ui,
 };
 /// System-wide configuration path, the lowest-priority file source.
         errors.push("instance.default_branch must not be empty".to_string());
+    }
-    // Storage directories must exist or be creatable.
+    // Storage directories must exist or be creatable. The bare repositories are
+    // always local; the LFS directory is only used by the local upload backend.
     check_dir_creatable("storage.data_dir", &config.storage.data_dir, &mut errors);
     check_dir_creatable("storage.repo_dir", &config.storage.repo_dir, &mut errors);
-    check_dir_creatable("storage.lfs_dir", &config.storage.lfs_dir, &mut errors);
+    if config.storage.backend == StorageBackend::Local {
+        check_dir_creatable("storage.lfs_dir", &config.storage.lfs_dir, &mut errors);
+    }
+    // The S3 backend needs a bucket and credentials.
+    if config.storage.backend == StorageBackend::S3 {
+        match &config.storage.s3 {
+            None => errors.push(
+                "storage.backend is \"s3\" but the [storage.s3] section is missing".to_string(),
+            ),
+            Some(s3) => {
+                if s3.bucket.trim().is_empty() {
+                    errors.push("storage.s3.bucket must not be empty".to_string());
+                }
+                if s3.access_key_id.trim().is_empty() {
+                    errors.push("storage.s3.access_key_id must not be empty".to_string());
+                }
+                if s3.secret_access_key.expose().trim().is_empty() {
+                    errors.push("storage.s3.secret_access_key must not be empty".to_string());
+                }
+            }
+        }
+    }
     // SMTP delivery needs a host and a from address.
     if config.mail.backend == MailBackend::Smtp {
+    }
     #[test]
+    fn s3_backend_without_config_is_rejected() {
+        let err = from_toml("[storage]\nbackend = \"s3\"\n").unwrap_err();
+        match err {
+            ConfigError::Invalid(msg) => assert!(msg.contains("[storage.s3]"), "{msg}"),
+            other => panic!("expected Invalid, got {other:?}"),
+        }
+    }
+    #[test]
+    fn s3_backend_with_config_validates() {
+        let loaded = from_toml(
+            "[storage]\nbackend = \"s3\"\n\n[storage.s3]\nbucket = \"b\"\n\
+             access_key_id = \"k\"\nsecret_access_key = \"s\"\nendpoint = \"https://s3.example.com\"\n\
+             region = \"auto\"\npath_style = true\nprefix = \"fabrica/\"\n",
+        )
+        .unwrap();
+        let s3 = loaded.config.storage.s3.as_ref().unwrap();
+        assert_eq!(s3.bucket, "b");
+        assert_eq!(s3.region, "auto");
+        assert!(s3.path_style);
+        assert_eq!(s3.prefix, "fabrica/");
+        assert_eq!(s3.endpoint.as_deref(), Some("https://s3.example.com"));
+    }
+    #[test]
+    fn s3_backend_with_empty_bucket_is_rejected() {
+        let err = from_toml(
+            "[storage]\nbackend = \"s3\"\n\n[storage.s3]\nbucket = \"\"\n\
+             access_key_id = \"k\"\nsecret_access_key = \"s\"\n",
+        )
+        .unwrap_err();
+        match err {
+            ConfigError::Invalid(msg) => assert!(msg.contains("storage.s3.bucket"), "{msg}"),
+            other => panic!("expected Invalid, got {other:?}"),
+        }
+    }
+    #[test]
     fn smtp_without_host_is_rejected() {
         let err = from_toml("[mail]\nbackend = \"smtp\"\n").unwrap_err();
         match err {

+    }
+}
-/// `[storage]` — on-disk locations.
+/// `[storage]` — on-disk locations and the blob backend for uploads.
+///
+/// Bare repositories always live on local disk (git needs filesystem access);
+/// only user uploads — avatars, release assets, and LFS objects — may be routed
+/// to S3-compatible object storage by setting `backend = "s3"`.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Storage {
     /// Directory holding the bare repositories, sharded by id prefix.
     pub repo_dir: PathBuf,
     /// Directory holding git-LFS objects, content-addressed by their sha256 oid.
+    /// Used only by the `local` backend.
     pub lfs_dir: PathBuf,
+    /// Where uploads (avatars, release assets, LFS objects) are stored.
+    #[serde(default)]
+    pub backend: StorageBackend,
+    /// S3-compatible object storage settings, required when `backend = "s3"`.
+    #[serde(default)]
+    pub s3: Option<S3>,
+}
 impl Default for Storage {
             data_dir: PathBuf::from("/var/lib/fabrica"),
             repo_dir: PathBuf::from("/var/lib/fabrica/repos"),
             lfs_dir: PathBuf::from("/var/lib/fabrica/lfs"),
+            backend: StorageBackend::Local,
+            s3: None,
+        }
+    }
+}
+/// The upload storage backend.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StorageBackend {
+    /// Store uploads on the local filesystem (the default).
+    #[default]
+    Local,
+    /// Store uploads in an S3-compatible object store.
+    S3,
+}
+/// `[storage.s3]` — S3-compatible object storage. Works with AWS S3, `MinIO`,
+/// Cloudflare R2, Backblaze B2, and other implementations.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct S3 {
+    /// The bucket that holds all uploads.
+    pub bucket: String,
+    /// The region (e.g. `us-east-1`); many S3-compatible stores accept `auto`.
+    #[serde(default = "default_region")]
+    pub region: String,
+    /// A custom endpoint URL for non-AWS stores (`MinIO`, R2, …). Omit for AWS S3.
+    #[serde(default)]
+    pub endpoint: Option<String>,
+    /// The access key id.
+    pub access_key_id: String,
+    /// The secret access key.
+    pub secret_access_key: Secret,
+    /// Use path-style addressing (`endpoint/bucket/key`) rather than virtual-host
+    /// style. Required by most non-AWS stores such as `MinIO`.
+    #[serde(default)]
+    pub path_style: bool,
+    /// An optional key prefix prepended to every object (e.g. `fabrica/`).
+    #[serde(default)]
+    pub prefix: String,
+}
+/// The default S3 region when unspecified.
+fn default_region() -> String {
+    "us-east-1".to_string()
+}
 /// `[database]` — connection settings.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]

 The add handler reuses `git::parse_public_key` for validation and fingerprinting and rejects a
 duplicate fingerprint; delete is ownership-checked against `keys_by_user`. This closes the last
 account-settings gap (§19) so key management no longer requires shell access.
+## 2026-07-26 — Optional S3 object storage for uploads (aws-sdk-s3, aws-lc-rs)
+**Decision:** Add an optional S3-compatible backend for the three kinds of *uploads* — user
+avatars, release assets, and git-LFS objects — behind a new `blob` crate exposing a `BlobStore`
+enum with `Local` and `S3` variants. Bare git repositories are **not** included: git needs direct
+filesystem access, so `storage.repo_dir` is always local. Selected by `storage.backend =
+"local" | "s3"` (default `local`, so existing installs are unaffected) with a `[storage.s3]`
+section (`bucket`, `region`, `endpoint`, `access_key_id`, `secret_access_key`, `path_style`,
+`prefix`). The endpoint + path-style knobs make it work with MinIO, Cloudflare R2, Backblaze B2,
+and other S3-compatible stores, not just AWS.
+**Client:** `aws-sdk-s3` with a **manually constructed** config (static credentials, custom
+endpoint) rather than `aws-config`'s credential-provider chain, keeping the dependency surface and
+startup work small. The default HTTPS client (`default-https-client`) pulls `ring`, which the
+license gate forbids; instead the HTTP client is wired explicitly via `aws-smithy-http-client`
+with the `rustls-aws-lc` feature and `tls::Provider::Rustls(CryptoMode::AwsLc)`, so the crypto
+provider is **aws-lc-rs** — already in the tree via russh and already on the license allow-list —
+and `ring` never enters the graph (`cargo deny check licenses` stays green).
+**Streaming:** LFS and release-asset uploads still stream to a **local scratch file** under
+`data_dir/tmp` (LFS) / `data_dir/releases/tmp` (assets) so the sha256 (LFS) and size are computed
+before the object is servable; the verified temp file is then handed to `BlobStore::put_file`,
+which renames it into place (local) or uploads it and removes the temp (S3). Downloads stream
+straight from the backend (`open` returns size + an `AsyncRead`). Keys are namespaced
+(`avatars/`, `releases/`, `lfs/{shard}`) and validated against path traversal. The local backend
+preserves the historical on-disk layout (`data_dir/avatars`, `data_dir/releases`, `lfs_dir`), so
+no migration is needed to stay on local disk.

 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 [[package]]
+name = "aws-credential-types"
+version = "1.2.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b01c9521fa01558f750d183c8c68c81b0155b9d193a4ba7f84c36bd1b6d04a06"
+dependencies = [
+ "aws-smithy-async",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "zeroize",
+]
+[[package]]
 name = "aws-lc-rs"
 version = "1.17.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "00bdb5da18dac48ca2cc7cd4a98e533e8635a58e2361d13a1a4ee3888e0d72f1"
 dependencies = [
  "aws-lc-sys",
- "untrusted",
+ "untrusted 0.7.1",
  "zeroize",
+]
+]
 [[package]]
+name = "aws-runtime"
+version = "1.5.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce527fb7e53ba9626fc47824f25e256250556c40d8f81d27dd92aa38239d632"
+dependencies = [
+ "aws-credential-types",
+ "aws-sigv4",
+ "aws-smithy-async",
+ "aws-smithy-eventstream",
+ "aws-smithy-http",
+ "aws-smithy-runtime",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "aws-types",
+ "bytes",
+ "fastrand",
+ "http 0.2.12",
+ "http-body 0.4.6",
+ "percent-encoding",
+ "pin-project-lite",
+ "tracing",
+ "uuid",
+]
+[[package]]
+name = "aws-sdk-s3"
+version = "1.96.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e25d24de44b34dcdd5182ac4e4c6f07bcec2661c505acef94c0d293b65505fe"
+dependencies = [
+ "aws-credential-types",
+ "aws-runtime",
+ "aws-sigv4",
+ "aws-smithy-async",
+ "aws-smithy-checksums",
+ "aws-smithy-eventstream",
+ "aws-smithy-http",
+ "aws-smithy-json",
+ "aws-smithy-runtime",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "aws-smithy-xml",
+ "aws-types",
+ "bytes",
+ "fastrand",
+ "hex",
+ "hmac 0.12.1",
+ "http 0.2.12",
+ "http 1.4.2",
+ "http-body 0.4.6",
+ "lru",
+ "percent-encoding",
+ "regex-lite",
+ "sha2 0.10.9",
+ "tracing",
+ "url",
+]
+[[package]]
+name = "aws-sigv4"
+version = "1.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c35452ec3f001e1f2f6db107b6373f1f48f05ec63ba2c5c9fa91f07dad32af11"
+dependencies = [
+ "aws-credential-types",
+ "aws-smithy-eventstream",
+ "aws-smithy-http",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "bytes",
+ "form_urlencoded",
+ "hex",
+ "hmac 0.12.1",
+ "http 0.2.12",
+ "http 1.4.2",
+ "percent-encoding",
+ "sha2 0.10.9",
+ "time",
+ "tracing",
+]
+[[package]]
+name = "aws-smithy-async"
+version = "1.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "127fcfad33b7dfc531141fda7e1c402ac65f88aca5511a4d31e2e3d2cd01ce9c"
+dependencies = [
+ "futures-util",
+ "pin-project-lite",
+ "tokio",
+]
+[[package]]
+name = "aws-smithy-checksums"
+version = "0.63.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95bd108f7b3563598e4dc7b62e1388c9982324a2abd622442167012690184591"
+dependencies = [
+ "aws-smithy-http",
+ "aws-smithy-types",
+ "bytes",
+ "crc-fast",
+ "hex",
+ "http 0.2.12",
+ "http-body 0.4.6",
+ "md-5 0.10.6",
+ "pin-project-lite",
+ "sha1 0.10.7",
+ "sha2 0.10.9",
+ "tracing",
+]
+[[package]]
+name = "aws-smithy-eventstream"
+version = "0.60.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e29a304f8319781a39808847efb39561351b1bb76e933da7aa90232673638658"
+dependencies = [
+ "aws-smithy-types",
+ "bytes",
+ "crc32fast",
+]
+[[package]]
+name = "aws-smithy-http"
+version = "0.62.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "445d5d720c99eed0b4aa674ed00d835d9b1427dd73e04adaf2f94c6b2d6f9fca"
+dependencies = [
+ "aws-smithy-eventstream",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "bytes",
+ "bytes-utils",
+ "futures-core",
+ "futures-util",
+ "http 0.2.12",
+ "http 1.4.2",
+ "http-body 0.4.6",
+ "percent-encoding",
+ "pin-project-lite",
+ "pin-utils",
+ "tracing",
+]
+[[package]]
+name = "aws-smithy-http-client"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "623254723e8dfd535f566ee7b2381645f8981da086b5c4aa26c0c41582bb1d2c"
+dependencies = [
+ "aws-smithy-async",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "h2",
+ "http 1.4.2",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "pin-project-lite",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-pki-types",
+ "tokio",
+ "tokio-rustls",
+ "tower",
+ "tracing",
+]
+[[package]]
+name = "aws-smithy-json"
+version = "0.61.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2db31f727935fc63c6eeae8b37b438847639ec330a9161ece694efba257e0c54"
+dependencies = [
+ "aws-smithy-types",
+]
+[[package]]
+name = "aws-smithy-observability"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d1881b1ea6d313f9890710d65c158bdab6fb08c91ea825f74c1c8c357baf4cc"
+dependencies = [
+ "aws-smithy-runtime-api",
+]
+[[package]]
+name = "aws-smithy-runtime"
+version = "1.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bbe9d018d646b96c7be063dd07987849862b0e6d07c778aad7d93d1be6c1ef0"
+dependencies = [
+ "aws-smithy-async",
+ "aws-smithy-http",
+ "aws-smithy-observability",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "bytes",
+ "fastrand",
+ "http 0.2.12",
+ "http 1.4.2",
+ "http-body 0.4.6",
+ "http-body 1.1.0",
+ "pin-project-lite",
+ "pin-utils",
+ "tokio",
+ "tracing",
+]
+[[package]]
+name = "aws-smithy-runtime-api"
+version = "1.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec7204f9fd94749a7c53b26da1b961b4ac36bf070ef1e0b94bb09f79d4f6c193"
+dependencies = [
+ "aws-smithy-async",
+ "aws-smithy-types",
+ "bytes",
+ "http 0.2.12",
+ "http 1.4.2",
+ "pin-project-lite",
+ "tokio",
+ "tracing",
+ "zeroize",
+]
+[[package]]
+name = "aws-smithy-types"
+version = "1.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25f535879a207fce0db74b679cfc3e91a3159c8144d717d55f5832aea9eef46e"
+dependencies = [
+ "base64-simd",
+ "bytes",
+ "bytes-utils",
+ "futures-core",
+ "http 0.2.12",
+ "http 1.4.2",
+ "http-body 0.4.6",
+ "http-body 1.1.0",
+ "http-body-util",
+ "itoa",
+ "num-integer",
+ "pin-project-lite",
+ "pin-utils",
+ "ryu",
+ "serde",
+ "time",
+ "tokio",
+ "tokio-util",
+]
+[[package]]
+name = "aws-smithy-xml"
+version = "0.60.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eab77cdd036b11056d2a30a7af7b775789fb024bf216acc13884c6c97752ae56"
+dependencies = [
+ "xmlparser",
+]
+[[package]]
+name = "aws-types"
+version = "1.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d79fb68e3d7fe5d4833ea34dc87d2e97d26d3086cb3da660bb6b1f76d98680b6"
+dependencies = [
+ "aws-credential-types",
+ "aws-smithy-async",
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "rustc_version",
+ "tracing",
+]
+[[package]]
 name = "axum"
 version = "0.8.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "bytes",
  "form_urlencoded",
  "futures-util",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "http-body-util",
  "hyper",
  "hyper-util",
 dependencies = [
  "bytes",
  "futures-core",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "http-body-util",
  "mime",
  "pin-project-lite",
  "cookie",
  "futures-core",
  "futures-util",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "http-body-util",
  "mime",
  "pin-project-lite",
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 [[package]]
+name = "base64-simd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "339abbe78e73178762e23bea9dfd08e697eb3f3301cd4be981c0f78ba5859195"
+dependencies = [
+ "outref",
+ "vsimd",
+]
+[[package]]
 name = "base64ct"
 version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "blob"
+version = "0.1.0"
+dependencies = [
+ "aws-sdk-s3",
+ "aws-smithy-http-client",
+ "bytes",
+ "config",
+ "tempfile",
+ "thiserror 2.0.19",
+ "tokio",
+]
+[[package]]
 name = "block-buffer"
 version = "0.10.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 [[package]]
+name = "bytes-utils"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dafe3a8757b027e2be6e4e5601ed563c55989fcf1546e933c66c8eb3a058d35"
+dependencies = [
+ "bytes",
+ "either",
+]
+[[package]]
 name = "bzip2"
 version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
 [[package]]
+name = "crc-fast"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ddc2d09feefeee8bd78101665bd8645637828fa9317f9f292496dbbd8c65ff3"
+dependencies = [
+ "crc",
+ "digest 0.10.7",
+ "rand 0.9.5",
+ "regex",
+ "rustversion",
+]
+[[package]]
 name = "crc24"
 version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 [[package]]
 name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+[[package]]
+name = "foldhash"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+]
 [[package]]
+name = "h2"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http 1.4.2",
+ "indexmap",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "allocator-api2",
+ "equivalent",
+ "foldhash 0.1.5",
+]
+[[package]]
 name = "hashbrown"
 version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "allocator-api2",
  "equivalent",
- "foldhash",
+ "foldhash 0.2.0",
+]
 [[package]]
 [[package]]
 name = "http"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "601cbb57e577e2f5ef5be8e7b83f0f63994f25aa94d673e54a92d5c516d101f1"
+dependencies = [
+ "bytes",
+ "fnv",
+ "itoa",
+]
+[[package]]
+name = "http"
 version = "1.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
 [[package]]
 name = "http-body"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ceab25649e9960c0311ea418d17bee82c0dcec1bd053b5f9a66e265a693bed2"
+dependencies = [
+ "bytes",
+ "http 0.2.12",
+ "pin-project-lite",
+]
+[[package]]
+name = "http-body"
 version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
 dependencies = [
  "bytes",
- "http",
+ "http 1.4.2",
+]
 [[package]]
 dependencies = [
  "bytes",
  "futures-core",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "pin-project-lite",
+]
  "bytes",
  "futures-channel",
  "futures-core",
- "http",
+ "h2",
- "http-body",
+ "http 1.4.2",
+ "http-body 1.1.0",
  "httparse",
  "httpdate",
  "itoa",
+]
 [[package]]
+name = "hyper-rustls"
+version = "0.27.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
+dependencies = [
+ "http 1.4.2",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "rustls-native-certs",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+]
+[[package]]
 name = "hyper-tls"
 version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "bytes",
  "futures-channel",
  "futures-util",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "hyper",
  "ipnet",
  "libc",
 checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 [[package]]
+name = "lru"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38"
+dependencies = [
+ "hashbrown 0.15.5",
+]
+[[package]]
 name = "mail"
 version = "0.1.0"
 dependencies = [
 checksum = "8156733e27020ea5c684db5beac5d1d611e1272ab17901a49466294b84fc217e"
 dependencies = [
  "axum-core",
- "http",
+ "http 1.4.2",
  "itoa",
  "maud_macros",
+]
  "bytes",
  "encoding_rs",
  "futures-util",
- "http",
+ "http 1.4.2",
  "httparse",
  "memchr",
  "mime",
+]
 [[package]]
+name = "outref"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e"
+[[package]]
 name = "p256"
 version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 [[package]]
+name = "pin-utils"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
+[[package]]
 name = "pkcs1"
 version = "0.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "regex-lite"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cab834c73d247e67f4fae452806d17d3c7501756d98c8808d7c9c7aa7d18f973"
+[[package]]
 name = "regex-syntax"
 version = "0.8.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "base64",
  "bytes",
  "futures-core",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "http-body-util",
  "hyper",
  "hyper-tls",
+]
 [[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted 0.9.0",
+ "windows-sys 0.52.0",
+]
+[[package]]
 name = "ripemd"
 version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "rustls"
+version = "0.23.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
+dependencies = [
+ "aws-lc-rs",
+ "once_cell",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+[[package]]
 name = "rustls-pki-types"
 version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "rustls-webpki"
+version = "0.103.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+dependencies = [
+ "aws-lc-rs",
+ "ring",
+ "rustls-pki-types",
+ "untrusted 0.9.0",
+]
+[[package]]
 name = "rustversion"
 version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+]
 [[package]]
+name = "tokio-rustls"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+[[package]]
 name = "tokio-stream"
 version = "0.1.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "bytes",
  "futures-core",
  "futures-sink",
+ "libc",
  "pin-project-lite",
  "tokio",
+]
  "bytes",
  "futures-core",
  "futures-util",
- "http",
+ "http 1.4.2",
- "http-body",
+ "http-body 1.1.0",
  "pin-project-lite",
  "tokio",
  "tokio-util",
 checksum = "a156c684c91ea7d62626509bce3cb4e1d9ed5c4d978f7b4352658f96a4c26b4a"
 [[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+[[package]]
 name = "url"
 version = "2.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 [[package]]
+name = "vsimd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64"
+[[package]]
 name = "walkdir"
 version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "axum",
  "axum-extra",
  "base64",
+ "blob",
  "comrak",
  "config",
  "flate2",
 [[package]]
 name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+[[package]]
+name = "windows-sys"
 version = "0.59.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+]
 [[package]]
+name = "xmlparser"
+version = "0.13.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66fee0b777b0f5ac1c69bb06d361268faafa61cd4682ae064a171c16c433e9e4"
+[[package]]
 name = "yansi"
 version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! Upload storage: one abstraction over the local filesystem and S3-compatible
+//! object stores.
+//!
+//! Bare git repositories always live on local disk (git needs filesystem
+//! access); only *uploads* — user avatars, release assets, and git-LFS objects —
+//! flow through here, so an operator can offload them to S3, `MinIO`, R2, or any
+//! compatible store by setting `storage.backend = "s3"`.
+//!
+//! Objects are addressed by a [`Namespace`] plus a key. The local backend maps a
+//! namespace to its on-disk directory (preserving the historical layout); the S3
+//! backend maps it to a key prefix. Keys are validated to forbid path traversal.
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use config::{S3, Storage, StorageBackend};
+use tokio::io::{AsyncRead, AsyncWriteExt as _};
+/// A logical group of uploads, mapped to a directory (local) or key prefix (S3).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Namespace {
+    /// User profile avatars, keyed by user id.
+    Avatars,
+    /// Release asset files, keyed by asset id.
+    Releases,
+    /// git-LFS objects, keyed by their sharded sha256 oid.
+    Lfs,
+}
+impl Namespace {
+    /// The directory / key-prefix segment for this namespace.
+    fn segment(self) -> &'static str {
+        match self {
+            Namespace::Avatars => "avatars",
+            Namespace::Releases => "releases",
+            Namespace::Lfs => "lfs",
+        }
+    }
+}
+/// Errors from the blob store.
+#[derive(Debug, thiserror::Error)]
+pub enum BlobError {
+    /// A local filesystem error.
+    #[error("blob io error: {0}")]
+    Io(#[from] std::io::Error),
+    /// An object-store (S3) error, stringified from the SDK.
+    #[error("object store error: {0}")]
+    Backend(String),
+    /// The key contained an empty, `.`, `..`, or absolute segment.
+    #[error("invalid object key")]
+    InvalidKey,
+    /// `backend = "s3"` without a `[storage.s3]` section.
+    #[error("s3 backend requires the [storage.s3] configuration")]
+    MissingS3Config,
+}
+/// A readable object: its byte length plus an async reader over its contents.
+pub struct BlobRead {
+    /// The object's size in bytes.
+    pub size: u64,
+    /// A streaming reader over the object.
+    pub reader: Pin<Box<dyn AsyncRead + Send>>,
+}
+/// The upload store, over either the local filesystem or an S3-compatible store.
+#[derive(Clone)]
+pub enum BlobStore {
+    /// Local filesystem backend.
+    Local(LocalStore),
+    /// S3-compatible object-store backend.
+    S3(S3Store),
+}
+/// The local filesystem backend: one root directory per namespace.
+#[derive(Clone)]
+pub struct LocalStore {
+    avatars: PathBuf,
+    releases: PathBuf,
+    lfs: PathBuf,
+}
+/// The S3-compatible backend.
+#[derive(Clone)]
+pub struct S3Store {
+    client: aws_sdk_s3::Client,
+    bucket: String,
+    prefix: String,
+}
+impl BlobStore {
+    /// Build the store described by `[storage]`. The local backend reuses the
+    /// existing on-disk directories; the S3 backend builds a client from
+    /// `[storage.s3]` with static credentials and the configured endpoint.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`BlobError::MissingS3Config`] if `backend = "s3"` but no
+    /// `[storage.s3]` section is present.
+    pub fn from_config(storage: &Storage) -> Result<Self, BlobError> {
+        match storage.backend {
+            StorageBackend::Local => Ok(BlobStore::Local(LocalStore {
+                avatars: storage.data_dir.join("avatars"),
+                releases: storage.data_dir.join("releases"),
+                lfs: storage.lfs_dir.clone(),
+            })),
+            StorageBackend::S3 => {
+                let s3 = storage.s3.as_ref().ok_or(BlobError::MissingS3Config)?;
+                Ok(BlobStore::S3(S3Store {
+                    client: build_s3_client(s3),
+                    bucket: s3.bucket.clone(),
+                    prefix: s3.prefix.clone(),
+                }))
+            }
+        }
+    }
+    /// Move the file at `src` into the store at `(namespace, key)`, consuming it
+    /// (the source is removed on success). Streams for the S3 backend.
+    ///
+    /// # Errors
+    ///
+    /// [`BlobError::InvalidKey`] for an unsafe key; otherwise a backend error.
+    pub async fn put_file(
+        &self,
+        namespace: Namespace,
+        key: &str,
+        src: &Path,
+        content_type: &str,
+    ) -> Result<(), BlobError> {
+        check_key(key)?;
+        match self {
+            BlobStore::Local(local) => {
+                move_in(src, &local.path(namespace, key)).await?;
+                Ok(())
+            }
+            BlobStore::S3(s3) => {
+                let body = aws_sdk_s3::primitives::ByteStream::from_path(src)
+                    .await
+                    .map_err(|e| BlobError::Backend(e.to_string()))?;
+                s3.client
+                    .put_object()
+                    .bucket(&s3.bucket)
+                    .key(s3.key(namespace, key))
+                    .content_type(content_type)
+                    .body(body)
+                    .send()
+                    .await
+                    .map_err(|e| BlobError::Backend(e.to_string()))?;
+                tokio::fs::remove_file(src).await?;
+                Ok(())
+            }
+        }
+    }
+    /// Store `bytes` at `(namespace, key)`, replacing any existing object.
+    ///
+    /// # Errors
+    ///
+    /// [`BlobError::InvalidKey`] for an unsafe key; otherwise a backend error.
+    pub async fn put_bytes(
+        &self,
+        namespace: Namespace,
+        key: &str,
+        bytes: Vec<u8>,
+        content_type: &str,
+    ) -> Result<(), BlobError> {
+        check_key(key)?;
+        match self {
+            BlobStore::Local(local) => {
+                let path = local.path(namespace, key);
+                if let Some(parent) = path.parent() {
+                    tokio::fs::create_dir_all(parent).await?;
+                }
+                let mut file = tokio::fs::File::create(&path).await?;
+                file.write_all(&bytes).await?;
+                file.flush().await?;
+                Ok(())
+            }
+            BlobStore::S3(s3) => {
+                s3.client
+                    .put_object()
+                    .bucket(&s3.bucket)
+                    .key(s3.key(namespace, key))
+                    .content_type(content_type)
+                    .body(bytes.into())
+                    .send()
+                    .await
+                    .map_err(|e| BlobError::Backend(e.to_string()))?;
+                Ok(())
+            }
+        }
+    }
+    /// Read an entire object into memory, or `None` if it does not exist.
+    ///
+    /// # Errors
+    ///
+    /// [`BlobError::InvalidKey`] for an unsafe key; otherwise a backend error.
+    pub async fn get_bytes(
+        &self,
+        namespace: Namespace,
+        key: &str,
+    ) -> Result<Option<Vec<u8>>, BlobError> {
+        check_key(key)?;
+        match self {
+            BlobStore::Local(local) => match tokio::fs::read(local.path(namespace, key)).await {
+                Ok(bytes) => Ok(Some(bytes)),
+                Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
+                Err(e) => Err(e.into()),
+            },
+            BlobStore::S3(s3) => match s3
+                .client
+                .get_object()
+                .bucket(&s3.bucket)
+                .key(s3.key(namespace, key))
+                .send()
+                .await
+            {
+                Ok(resp) => {
+                    let data = resp
+                        .body
+                        .collect()
+                        .await
+                        .map_err(|e| BlobError::Backend(e.to_string()))?;
+                    Ok(Some(data.to_vec()))
+                }
+                Err(e) => {
+                    let svc = e.into_service_error();
+                    if svc.is_no_such_key() {
+                        Ok(None)
+                    } else {
+                        Err(BlobError::Backend(svc.to_string()))
+                    }
+                }
+            },
+        }
+    }
+    /// Open an object for streaming, or `None` if it does not exist.
+    ///
+    /// # Errors
+    ///
+    /// [`BlobError::InvalidKey`] for an unsafe key; otherwise a backend error.
+    pub async fn open(
+        &self,
+        namespace: Namespace,
+        key: &str,
+    ) -> Result<Option<BlobRead>, BlobError> {
+        check_key(key)?;
+        match self {
+            BlobStore::Local(local) => {
+                match tokio::fs::File::open(local.path(namespace, key)).await {
+                    Ok(file) => {
+                        let size = file.metadata().await?.len();
+                        Ok(Some(BlobRead {
+                            size,
+                            reader: Box::pin(file),
+                        }))
+                    }
+                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
+                    Err(e) => Err(e.into()),
+                }
+            }
+            BlobStore::S3(s3) => match s3
+                .client
+                .get_object()
+                .bucket(&s3.bucket)
+                .key(s3.key(namespace, key))
+                .send()
+                .await
+            {
+                Ok(resp) => {
+                    let size = u64::try_from(resp.content_length().unwrap_or(0)).unwrap_or(0);
+                    Ok(Some(BlobRead {
+                        size,
+                        reader: Box::pin(resp.body.into_async_read()),
+                    }))
+                }
+                Err(e) => {
+                    let svc = e.into_service_error();
+                    if svc.is_no_such_key() {
+                        Ok(None)
+                    } else {
+                        Err(BlobError::Backend(svc.to_string()))
+                    }
+                }
+            },
+        }
+    }
+    /// Delete an object. Missing objects are not an error (idempotent).
+    ///
+    /// # Errors
+    ///
+    /// [`BlobError::InvalidKey`] for an unsafe key; otherwise a backend error.
+    pub async fn delete(&self, namespace: Namespace, key: &str) -> Result<(), BlobError> {
+        check_key(key)?;
+        match self {
+            BlobStore::Local(local) => {
+                match tokio::fs::remove_file(local.path(namespace, key)).await {
+                    Ok(()) => Ok(()),
+                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+                    Err(e) => Err(e.into()),
+                }
+            }
+            BlobStore::S3(s3) => {
+                s3.client
+                    .delete_object()
+                    .bucket(&s3.bucket)
+                    .key(s3.key(namespace, key))
+                    .send()
+                    .await
+                    .map_err(|e| BlobError::Backend(e.to_string()))?;
+                Ok(())
+            }
+        }
+    }
+    /// Whether an object exists.
+    ///
+    /// # Errors
+    ///
+    /// [`BlobError::InvalidKey`] for an unsafe key; otherwise a backend error.
+    pub async fn exists(&self, namespace: Namespace, key: &str) -> Result<bool, BlobError> {
+        check_key(key)?;
+        match self {
+            BlobStore::Local(local) => Ok(tokio::fs::try_exists(local.path(namespace, key)).await?),
+            BlobStore::S3(s3) => match s3
+                .client
+                .head_object()
+                .bucket(&s3.bucket)
+                .key(s3.key(namespace, key))
+                .send()
+                .await
+            {
+                Ok(_) => Ok(true),
+                Err(e) => {
+                    let svc = e.into_service_error();
+                    if svc.is_not_found() {
+                        Ok(false)
+                    } else {
+                        Err(BlobError::Backend(svc.to_string()))
+                    }
+                }
+            },
+        }
+    }
+}
+impl LocalStore {
+    /// The on-disk path for `(namespace, key)`.
+    fn path(&self, namespace: Namespace, key: &str) -> PathBuf {
+        let root = match namespace {
+            Namespace::Avatars => &self.avatars,
+            Namespace::Releases => &self.releases,
+            Namespace::Lfs => &self.lfs,
+        };
+        root.join(key)
+    }
+}
+impl S3Store {
+    /// The object key for `(namespace, key)`: `{prefix}{segment}/{key}`.
+    fn key(&self, namespace: Namespace, key: &str) -> String {
+        format!("{}{}/{}", self.prefix, namespace.segment(), key)
+    }
+}
+/// Build an S3 client from static credentials and the configured endpoint. The
+/// HTTP client is wired explicitly with the aws-lc-rs rustls provider so the
+/// default (ring-based) client is never linked.
+fn build_s3_client(s3: &S3) -> aws_sdk_s3::Client {
+    use aws_sdk_s3::config::{BehaviorVersion, Credentials, Region};
+    use aws_smithy_http_client::{Builder as HttpBuilder, tls};
+    let http = HttpBuilder::new()
+        .tls_provider(tls::Provider::Rustls(
+            tls::rustls_provider::CryptoMode::AwsLc,
+        ))
+        .build_https();
+    let credentials = Credentials::new(
+        s3.access_key_id.clone(),
+        s3.secret_access_key.expose().to_string(),
+        None,
+        None,
+        "fabrica-config",
+    );
+    let mut builder = aws_sdk_s3::Config::builder()
+        .behavior_version(BehaviorVersion::latest())
+        .http_client(http)
+        .region(Region::new(s3.region.clone()))
+        .credentials_provider(credentials)
+        .force_path_style(s3.path_style);
+    if let Some(endpoint) = &s3.endpoint {
+        builder = builder.endpoint_url(endpoint);
+    }
+    aws_sdk_s3::Client::from_conf(builder.build())
+}
+/// Move `src` to `dest`, creating parent directories, with a copy fallback if the
+/// two live on different filesystems (rename fails with `EXDEV`).
+async fn move_in(src: &Path, dest: &Path) -> std::io::Result<()> {
+    if let Some(parent) = dest.parent() {
+        tokio::fs::create_dir_all(parent).await?;
+    }
+    if tokio::fs::rename(src, dest).await.is_ok() {
+        return Ok(());
+    }
+    tokio::fs::copy(src, dest).await?;
+    tokio::fs::remove_file(src).await
+}
+/// Reject keys that could escape the namespace root: empty, absolute, or with a
+/// `.`/`..`/empty path segment.
+fn check_key(key: &str) -> Result<(), BlobError> {
+    if key.is_empty()
+        || key.starts_with('/')
+        || key
+            .split('/')
+            .any(|seg| seg.is_empty() || seg == "." || seg == "..")
+    {
+        return Err(BlobError::InvalidKey);
+    }
+    Ok(())
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use config::{Storage, StorageBackend};
+    use tokio::io::AsyncReadExt as _;
+    use super::*;
+    fn local_store(dir: &Path) -> BlobStore {
+        let storage = Storage {
+            data_dir: dir.to_path_buf(),
+            repo_dir: dir.join("repos"),
+            lfs_dir: dir.join("lfs"),
+            backend: StorageBackend::Local,
+            s3: None,
+        };
+        BlobStore::from_config(&storage).unwrap()
+    }
+    #[tokio::test]
+    async fn local_round_trip() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = local_store(dir.path());
+        // Missing object.
+        assert!(!store.exists(Namespace::Avatars, "u1").await.unwrap());
+        assert!(
+            store
+                .get_bytes(Namespace::Avatars, "u1")
+                .await
+                .unwrap()
+                .is_none()
+        );
+        assert!(
+            store
+                .open(Namespace::Avatars, "u1")
+                .await
+                .unwrap()
+                .is_none()
+        );
+        // put_bytes / get_bytes / exists.
+        store
+            .put_bytes(Namespace::Avatars, "u1", b"hello".to_vec(), "image/png")
+            .await
+            .unwrap();
+        assert!(store.exists(Namespace::Avatars, "u1").await.unwrap());
+        assert_eq!(
+            store
+                .get_bytes(Namespace::Avatars, "u1")
+                .await
+                .unwrap()
+                .unwrap(),
+            b"hello"
+        );
+        // open streams the same bytes with the right size.
+        let mut read = store.open(Namespace::Avatars, "u1").await.unwrap().unwrap();
+        assert_eq!(read.size, 5);
+        let mut buf = Vec::new();
+        read.reader.read_to_end(&mut buf).await.unwrap();
+        assert_eq!(buf, b"hello");
+        // delete is idempotent.
+        store.delete(Namespace::Avatars, "u1").await.unwrap();
+        store.delete(Namespace::Avatars, "u1").await.unwrap();
+        assert!(!store.exists(Namespace::Avatars, "u1").await.unwrap());
+    }
+    #[tokio::test]
+    async fn put_file_consumes_source_and_shards_lfs_keys() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = local_store(dir.path());
+        let src = dir.path().join("scratch.bin");
+        tokio::fs::write(&src, b"payload").await.unwrap();
+        // A sharded LFS key nests into subdirectories.
+        store
+            .put_file(
+                Namespace::Lfs,
+                "ab/cd/abcdef",
+                &src,
+                "application/octet-stream",
+            )
+            .await
+            .unwrap();
+        assert!(
+            !tokio::fs::try_exists(&src).await.unwrap(),
+            "source moved in"
+        );
+        assert_eq!(
+            store
+                .get_bytes(Namespace::Lfs, "ab/cd/abcdef")
+                .await
+                .unwrap()
+                .unwrap(),
+            b"payload"
+        );
+        assert!(dir.path().join("lfs/ab/cd/abcdef").exists());
+    }
+    #[test]
+    fn key_traversal_is_rejected() {
+        assert!(matches!(check_key(""), Err(BlobError::InvalidKey)));
+        assert!(matches!(
+            check_key("/etc/passwd"),
+            Err(BlobError::InvalidKey)
+        ));
+        assert!(matches!(check_key("a/../b"), Err(BlobError::InvalidKey)));
+        assert!(matches!(check_key("a//b"), Err(BlobError::InvalidKey)));
+        assert!(check_key("ab/cd/abcdef").is_ok());
+        assert!(check_key("01H0000000000000000000").is_ok());
+    }
+    #[tokio::test]
+    async fn missing_s3_config_is_an_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let storage = Storage {
+            data_dir: dir.path().to_path_buf(),
+            repo_dir: dir.path().join("repos"),
+            lfs_dir: dir.path().join("lfs"),
+            backend: StorageBackend::S3,
+            s3: None,
+        };
+        assert!(matches!(
+            BlobStore::from_config(&storage),
+            Err(BlobError::MissingS3Config)
+        ));
+    }
+}

 [storage]
 data_dir = "/var/lib/fabrica"        # secrets, host key, SQLite db, scratch
 repo_dir = "/var/lib/fabrica/repos"  # bare repos, sharded by id prefix
-lfs_dir  = "/var/lib/fabrica/lfs"    # git-LFS objects, content-addressed by sha256
+lfs_dir  = "/var/lib/fabrica/lfs"    # git-LFS objects (local backend only)
+# Where uploads (avatars, release assets, LFS objects) live. Bare repos are
+# always local — only uploads may be offloaded to S3.
+backend  = "local"                   # "local" (default) or "s3"
+# S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, Backblaze B2, …).
+# Required when backend = "s3".
+# [storage.s3]
+# bucket            = "fabrica"
+# region            = "us-east-1"    # many non-AWS stores accept "auto"
+# endpoint          = "https://<account>.r2.cloudflarestorage.com"  # omit for AWS
+# access_key_id     = "..."
+# secret_access_key = "..."
+# path_style        = false          # true for MinIO and most non-AWS stores
+# prefix            = ""             # optional key prefix, e.g. "fabrica/"
 [database]
 url             = "sqlite:///var/lib/fabrica/fabrica.db"