@@ -8,6 +8,7 @@ license = "MIT"
 
 [workspace.dependencies]
 anyhow = "1"
+async-trait = "0.1"
 axum = { version = "0.8", features = ["macros"] }
 bytes = "1"
 chrono = { version = "0.4", features = ["serde"] }
@@ -23,6 +24,7 @@ opentelemetry-otlp = { version = "0.31", features = ["grpc-tonic"] }
 opentelemetry_sdk = { version = "0.31", features = ["rt-tokio"] }
 prometheus = "0.14"
 reqwest = { version = "0.13", default-features = false, features = ["json", "rustls", "stream"] }
+s3s = "0.13"
 secrecy = "0.8"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 
@@ -24,10 +24,27 @@ Clean JSON API, Beyond bearer-token auth, no XML, no Sig V4. This is what the Ty
 
 ### S3-compatible
 
-Full S3 wire protocol via [`s3s`](https://github.com/s3s-project/s3s) — a hyper middleware that handles S3 routing, request parsing, multipart lifecycle, and error serialization. We implement one `S3` trait backed by the filesystem.
+Full S3 wire protocol via [`s3s`](https://github.com/Nugine/s3s) — a tower service that handles S3 routing, request parsing, multipart lifecycle, and error serialization. We implement one `S3` trait backed by the same filesystem.
 
 S3 "buckets" map directly to Beyond buckets on the filesystem. `CreateBucket` is a `mkdir` + xattr init. `ListBuckets` reads top-level directories.
 
+**Auth — SigV4 mapped to our HMAC scheme.** AWS SDKs always sign with `(access_key_id, secret_access_key)`. We answer s3s's "what's the secret for this access_key?" question by reusing the existing token derivation:
+
+| access_key_id | secret_access_key                                 |
+| ------------- | ------------------------------------------------- |
+| `"root"`      | `OBJECTS_ROOT_TOKEN`                              |
+| `<bucket>`    | `HMAC-SHA256(OBJECTS_ROOT_TOKEN, <bucket>)` (hex) |
+
+So an S3 client using `accessKeyId: "images"` and `secretAccessKey: <hex>` is byte-for-byte equivalent to a REST client sending `Authorization: Bearer <hex>`. Authorization (which buckets a key may touch) is enforced by `S3Access`: `access_key == bucket || access_key == "root"`. The TS SDK exports `deriveS3Credentials(rootToken, bucket)` for symmetry with `deriveToken`.
+
+**Path-style only.** `https://{endpoint}/{bucket}/{key…}`. Virtual-hosted-style is not supported (it would require a wildcard cert per project, and AWS clients support `forcePathStyle: true`).
+
+**Anonymous reads.** Public objects can be GET/HEAD'd without credentials, mirroring the REST surface. Anonymous writes are denied at `S3Access`.
+
+**What we support:** `ListBuckets`, `CreateBucket`, `DeleteBucket`, `HeadBucket`; `PutObject`, `GetObject`, `HeadObject`, `DeleteObject`, `CopyObject`, `ListObjectsV2`; the full multipart five (`CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListMultipartUploads`, `ListParts`). Within those: `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`, `Content-Type`, `x-amz-meta-*`, and `x-amz-acl: public-read | private` (mapped to the same `user.access` xattr the REST surface writes).
+
+**What returns `NotImplemented`:** versioning, lifecycle, replication, CORS-config-via-API, website config, object lock, retention, tagging, presigned URLs, bucket policies, inventory, intelligent-tiering, analytics, encryption configuration, full ACL grants beyond the canned `private` / `public-read`.
+
 ---
 
 ## Storage
@@ -128,7 +145,24 @@ Supported via standard HTTP conditional headers on PUT:
 
 ### Multipart uploads (S3-compat only)
 
-Multipart is not exposed in the native API — streaming handles large uploads directly. The S3-compatible layer supports it for clients that require it. Parts written to `.multipart/{upload_id}/{part_number}`; assembled on `CompleteMultipartUpload` via sequential concatenation → `fsync` → `rename()` → fjall INSERT.
+Multipart is not exposed in the native API — streaming handles large uploads directly. The S3-compatible layer supports it for clients that require it.
+
+**On-disk layout:**
+
+```
+{data_dir}/.multipart/{upload_id}/.meta.json   {bucket, key, content_type, access, user_metadata, init_time_secs}
+{data_dir}/.multipart/{upload_id}/{part_n}     raw part bytes; quoted-MD5 etag in `user.etag` xattr
+```
+
+`CompleteMultipartUpload`: read the meta sidecar → concatenate parts in caller-supplied order to `.tmp/{uuid}` while computing `MD5({part_md5}|{part_md5}|…)` → fsync → set xattrs from meta → atomic `rename()` to `{bucket}/{key}` → fjall INSERT → `rm -rf .multipart/{upload_id}`. Final etag is `"{md5_of_part_md5s}-{N}"` (AWS convention). `AbortMultipartUpload` is `rm -rf .multipart/{upload_id}` (idempotent).
+
+**Crash recovery:**
+
+- Crash mid-`UploadPart` → tmp file in `.tmp/`, GC'd by `gc_temp_files`.
+- Crash after `complete` rename, before `.multipart/{id}` cleanup → orphan dir, GC'd by `gc_multipart_uploads`.
+- Crash before rename → object never appears; abort or GC sweeps it.
+
+The `.multipart/` directory is dot-prefixed so `list_buckets` skips it automatically.
 
 ---
 
@@ -146,6 +180,14 @@ const objects = createObjectsClient();
 // derive a scoped token to hand off to a specific service (HMAC-SHA256, async)
 const imagesToken = await deriveToken(process.env.OBJECTS_ROOT_TOKEN, "images");
 const images = createObjectsClient({ bucket: "images", token: imagesToken });
+
+// the same secret, formatted for any AWS S3 SDK
+import { deriveS3Credentials } from "@beyond.dev/objects";
+const creds = await deriveS3Credentials(
+  process.env.OBJECTS_ROOT_TOKEN,
+  "images",
+);
+// { accessKeyId: "images", secretAccessKey: <hex> }
 ```
 
 **Per-object visibility**, set at write time, inherited from bucket default if absent:
 
@@ -17,6 +17,7 @@ beyond-objects-index = { path = "../index" }
 beyond-objects-storage = { path = "../storage" }
 
 anyhow = { workspace = true }
+async-trait = { workspace = true }
 axum = { workspace = true }
 bytes = { workspace = true }
 chrono = { workspace = true }
@@ -29,6 +30,7 @@ opentelemetry = { workspace = true }
 opentelemetry-otlp = { workspace = true }
 opentelemetry_sdk = { workspace = true }
 prometheus = { workspace = true }
+s3s = { workspace = true }
 secrecy = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
@@ -49,9 +51,18 @@ uuid = { workspace = true }
 tikv-jemallocator = { workspace = true }
 
 [dev-dependencies]
+aws-config = { version = "1", default-features = false, features = ["behavior-version-latest", "rustls", "rt-tokio"] }
+aws-sdk-s3 = { version = "1", default-features = false, features = ["behavior-version-latest", "rustls", "rt-tokio"] }
+aws-smithy-async = { version = "1", features = ["rt-tokio"] }
+aws-smithy-runtime = { version = "1", features = ["client", "connector-hyper-0-14-x", "rt-tokio"] }
+aws-smithy-types = { version = "1", features = ["http-body-1-x"] }
 reqwest = { workspace = true }
 tempfile = { workspace = true }
 
 [[test]]
 name = "rest"
 path = "tests/rest/main.rs"
+
+[[test]]
+name = "s3"
+path = "tests/s3/main.rs"
@@ -71,6 +71,12 @@ pub enum ApiError {
     #[error("range not satisfiable")]
     RangeNotSatisfiable,
 
+    #[error("multipart upload not found: {0}")]
+    UploadNotFound(String),
+
+    #[error("invalid part: {0}")]
+    InvalidPart(String),
+
     #[error("internal error: {0}")]
     Internal(#[from] anyhow::Error),
 }
@@ -91,6 +97,8 @@ impl From<StorageError> for ApiError {
             StorageError::EtagMismatch => Self::EtagMismatch,
             StorageError::InvalidKey(k) => Self::InvalidKey(k),
             StorageError::InvalidValue(v) => Self::BadRequest(v),
+            StorageError::UploadNotFound(id) => Self::UploadNotFound(id),
+            StorageError::InvalidPart(msg) => Self::InvalidPart(msg),
             StorageError::Xattr(msg) => Self::Internal(anyhow::anyhow!("xattr failure: {msg}")),
             StorageError::Io(e) => Self::Internal(anyhow::anyhow!("io: {e}")),
         }
@@ -134,6 +142,10 @@ impl IntoResponse for ApiError {
                 "range_not_satisfiable",
                 self.to_string(),
             ),
+            ApiError::UploadNotFound(_) => {
+                (StatusCode::NOT_FOUND, "upload_not_found", self.to_string())
+            }
+            ApiError::InvalidPart(_) => (StatusCode::BAD_REQUEST, "invalid_part", self.to_string()),
             ApiError::Internal(_) => (
                 StatusCode::INTERNAL_SERVER_ERROR,
                 "internal_error",
 
@@ -4,6 +4,7 @@ pub mod error;
 pub mod metrics;
 pub mod middleware;
 pub mod routes;
+pub mod s3;
 pub mod telemetry;
 pub mod test_support;
 
@@ -67,6 +68,79 @@ impl AppState {
     /// now — kept on AppState so handlers don't need to know whether events are
     /// wired up.
     pub fn publish(&self, _base_url: &str, _bucket: &str, _key: &str) {}
+
+    /// One page of a prefix-paginated listing. Used by both the native REST
+    /// handler and the S3 `ListObjectsV2` handler so they share a single
+    /// scan plus buffered-head implementation. Index entries whose backing
+    /// file disappeared (typically after a crash) are skipped silently;
+    /// startup reconcile drops them on the next boot.
+    pub async fn list_page(
+        &self,
+        bucket: &str,
+        prefix: &str,
+        cursor: Option<&str>,
+        limit: usize,
+    ) -> Result<ListPage, error::ApiError> {
+        use beyond_objects_storage::StorageError;
+        use futures::TryStreamExt;
+        use futures::stream::StreamExt;
+
+        let index = self.index.clone();
+        let bucket_owned = bucket.to_owned();
+        let prefix_owned = prefix.to_owned();
+        let cursor_owned = cursor.map(str::to_owned);
+        let keys = tokio::task::spawn_blocking(move || {
+            index.scan(&bucket_owned, &prefix_owned, cursor_owned.as_deref(), limit)
+        })
+        .await
+        .map_err(|e| error::ApiError::Internal(anyhow::anyhow!("index scan join: {e}")))??;
+
+        let next_cursor = if keys.len() == limit {
+            keys.last().cloned()
+        } else {
+            None
+        };
+
+        let bucket_owned = bucket.to_owned();
+        let items: Vec<ListItem> = futures::stream::iter(keys.into_iter().map(|k| {
+            let storage = self.storage.clone();
+            let b = bucket_owned.clone();
+            async move {
+                match storage.head_object(&b, &k).await {
+                    Ok(info) => Ok(Some(ListItem { key: k, info })),
+                    Err(StorageError::NotFound { .. }) => {
+                        tracing::debug!(
+                            bucket = %b,
+                            key = %k,
+                            "skipping index entry without backing file"
+                        );
+                        Ok::<Option<ListItem>, error::ApiError>(None)
+                    }
+                    Err(e) => Err(error::ApiError::from(e)),
+                }
+            }
+        }))
+        .buffered(64)
+        .try_collect::<Vec<_>>()
+        .await?
+        .into_iter()
+        .flatten()
+        .collect();
+
+        Ok(ListPage { items, next_cursor })
+    }
+}
+
+/// One key+metadata pair returned by `AppState::list_page`. Surface layers
+/// (REST, S3) wrap this into their own response shapes.
+pub struct ListItem {
+    pub key: String,
+    pub info: beyond_objects_storage::ObjectInfo,
+}
+
+pub struct ListPage {
+    pub items: Vec<ListItem>,
+    pub next_cursor: Option<String>,
 }
 
 #[derive(Clone)]
@@ -83,8 +157,14 @@ impl MakeRequestId for MakeRequestUuid {
 /// sit outside the auth boundary; per-resource auth is applied inside
 /// `routes::router`. The `/metrics` endpoint lives on a separate internal-only
 /// listener built via `build_metrics_router`.
+///
+/// The S3-compatible surface is mounted as `fallback_service` so that explicit
+/// `/v1/*`, `/healthz`, and `/v1/openapi.json` routes always win. Any
+/// unmatched URL (e.g. `GET /` for `ListBuckets`, `PUT /{bucket}/{key}` for
+/// `PutObject`) is handed to s3s.
 pub fn build_router(state: AppState) -> Router {
     let openapi = routes::ApiDoc::openapi();
+    let s3_fallback = s3::service(state.clone());
 
     routes::router(state.clone())
         .route(
@@ -96,8 +176,13 @@ pub fn build_router(state: AppState) -> Router {
         )
         .route("/healthz", get(routes::healthz::handler))
         .with_state(state.clone())
+        .fallback_service(
+            ServiceBuilder::new()
+                .layer(DefaultBodyLimit::disable())
+                .service(s3_fallback),
+        )
         .route_layer(from_fn_with_state(state, record_metrics))
-        .layer(DefaultBodyLimit::max(64 * 1024))
+        .route_layer(DefaultBodyLimit::max(64 * 1024))
         .layer(
             ServiceBuilder::new()
                 .layer(SetRequestIdLayer::x_request_id(MakeRequestUuid))
@@ -197,7 +282,7 @@ pub async fn serve(config: Config) -> Result<()> {
         config: Arc::new(config),
         storage,
         index,
-        metrics: Arc::new(metrics::Metrics::new()),
+        metrics: Arc::new(metrics::Metrics::try_new()?),
     };
 
     let app = build_router(state.clone());
@@ -221,17 +306,23 @@ async fn shutdown_signal() {
     use tokio::signal;
 
     let ctrl_c = async {
-        signal::ctrl_c()
-            .await
-            .expect("failed to install Ctrl+C handler");
+        if let Err(e) = signal::ctrl_c().await {
+            tracing::warn!(err = %e, "Ctrl+C handler unavailable; relying on SIGTERM");
+            std::future::pending::<()>().await;
+        }
     };
 
     #[cfg(unix)]
     let terminate = async {
-        signal::unix::signal(signal::unix::SignalKind::terminate())
-            .expect("failed to install SIGTERM handler")
-            .recv()
-            .await;
+        match signal::unix::signal(signal::unix::SignalKind::terminate()) {
+            Ok(mut sig) => {
+                sig.recv().await;
+            }
+            Err(e) => {
+                tracing::warn!(err = %e, "SIGTERM handler unavailable; relying on Ctrl+C");
+                std::future::pending::<()>().await;
+            }
+        }
     };
 
     #[cfg(not(unix))]
 
@@ -7,14 +7,13 @@ pub struct Metrics {
 }
 
 impl Metrics {
-    pub fn new() -> Self {
+    pub fn try_new() -> Result<Self, prometheus::Error> {
         let registry = Registry::new();
 
         let http_requests_total = CounterVec::new(
             Opts::new("http_requests_total", "Total HTTP requests"),
             &["method", "path", "status"],
-        )
-        .expect("valid metric");
+        )?;
 
         let http_request_duration_seconds = HistogramVec::new(
             histogram_opts!(
@@ -23,21 +22,16 @@ impl Metrics {
                 vec![0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5]
             ),
             &["method", "path"],
-        )
-        .expect("valid metric");
+        )?;
 
-        registry
-            .register(Box::new(http_requests_total.clone()))
-            .expect("unique metric");
-        registry
-            .register(Box::new(http_request_duration_seconds.clone()))
-            .expect("unique metric");
+        registry.register(Box::new(http_requests_total.clone()))?;
+        registry.register(Box::new(http_request_duration_seconds.clone()))?;
 
-        Self {
+        Ok(Self {
             http_requests_total,
             http_request_duration_seconds,
             registry,
-        }
+        })
     }
 
     pub fn render(&self) -> Result<String, prometheus::Error> {