feat(portal): implement object download functionality (ceph) (#990)

* feat(portal): add object download BFF endpoint with progress streaming

* docs(bff): document object download BFF procedures

* feat(portal): add object download to ObjectsTableView

* fix(portal): add PortalProvider to ObjectsTableView tests

* feat(portal): add row-click preview and download for object files

* fix(portal): update ObjectsTableView tests for anchor-based preview/download

* docs(bff): document downloadObject content-type resolution

* fix(portal): use plain identifiers in Lingui message interpolations

* chore(core): add missing translations

* test(portal): add schema validation tests for object storage types

* chore(core): create a changeset

* fix(portal): track downloads and previews per-row to support concurrent transfers

* fix(portal): prevent version rows from using the object-only download path

* fix(portal): emit mapped progress error for every download failure path

* fix(portal): clear the 30s wait timer once progress arrives

* fix(portal): restrict browser preview to non-scriptable content types

* docs(bff): fix misleading resolveMimeFromKey comment

* docs(bff): update preview whitelist doc to match tightened MIME set

* chore(core): update changeset description

* fix(portal): restore mocks between tests and cover progress subscription

Author: mark-karnaukh-extern-sap

.changeset/eight-corners-fail.md

@@ -0,0 +1,10 @@
+---
+"@cobaltcore-dev/aurora": minor
+---
+
+Add object download and preview for Ceph object storage, bringing Ceph to parity with the existing Swift capability.
+
+- Stream downloads through the BFF (`downloadObject`) with live progress tracking via `watchDownloadProgress`. Multiple downloads/previews can be in flight at once, each tracked and reported independently.
+- Row-click on an object previews it in a new browser tab when the type is safely renderable (images excluding SVG, video, audio, PDF, and plain text); everything else downloads directly. Scriptable types (HTML, JSON, XML, SVG) are intentionally excluded from preview since they can execute active content when opened from a blob URL.
+- New context-menu **Download** action always forces a file save, regardless of type.
+- The BFF resolves a reliable MIME type from the object key extension when S3/Ceph reports a generic or incorrect `Content-Type` (e.g. the `binary/octet-stream` default, or values set by some upload tools), so files preview correctly even without proper upload metadata.

packages/aurora/docs/009_ceph_s3_bff.md

@@ -165,7 +165,9 @@ storage.ceph
   │   ├── createFolder()    → { success: boolean }
   │   ├── copy()            → { success: boolean, etag?: string }
   │   ├── move()            → { success: boolean, etag?: string }
-  │   └── updateMetadata()  → { success: boolean }
+  │   ├── updateMetadata()  → { success: boolean }
+  │   ├── downloadObject()       → AsyncIterable<{ chunk, downloaded, total, contentType?, filename? }>
+  │   └── watchDownloadProgress() → AsyncIterable<{ downloaded, total, percent }>  (subscription)
   └── versioning
       ├── getStatus()         → { status: 'Enabled' | 'Suspended' | 'Unversioned' }
       ├── setStatus()         → { success: boolean }
@@ -854,6 +856,127 @@ await trpc.storage.ceph.objects.updateMetadata.mutate({
 
 ---
 
+#### `downloadObject`
+
+Downloads an object by streaming its content through the BFF as base64-encoded chunks via a tRPC async iterable (S3 `GetObjectCommand`). The server never buffers the whole object in memory, and per-chunk progress is published so a concurrent `watchDownloadProgress` subscription can drive a progress bar. This is a **direct stream** — no presigned/temporary URLs are issued.
+
+**Input:**
+
+```typescript
+{
+  project_id: string,
+  containerName: string,
+  objectKey: string,
+  filename: string,    // Suggested download filename (echoed in the first chunk)
+  downloadId: string   // Client-computed "<bucket>:<objectKey>:<uuid>" correlating
+                       // the stream with a watchDownloadProgress subscription
+}
+```
+
+**Output:** an async iterable yielding chunks:
+
+```typescript
+{
+  chunk: string,         // base64-encoded Uint8Array slice of the object
+  downloaded: number,    // cumulative bytes streamed so far
+  total: number,         // total object size in bytes (0 if unknown)
+  contentType?: string,  // present only in the first chunk
+  filename?: string      // present only in the first chunk
+}
+```
+
+**Example:**
+
+```typescript
+const downloadId = `${bucket}:${objectKey}:${crypto.randomUUID()}`
+
+const iterable = await trpc.storage.ceph.objects.downloadObject.mutate({
+  project_id: "abc123",
+  containerName: "my-bucket",
+  objectKey: "documents/report.pdf",
+  filename: "report.pdf",
+  downloadId,
+})
+
+const parts: Uint8Array[] = []
+let contentType = "application/octet-stream"
+for await (const { chunk, contentType: ct } of iterable) {
+  if (ct) contentType = ct
+  parts.push(Uint8Array.from(atob(chunk), (c) => c.charCodeAt(0)))
+}
+const blob = new Blob(parts, { type: contentType })
+// → wrap in an object URL and trigger an <a download>
+```
+
+**Notes:**
+
+- Each chunk is base64-encoded because tRPC's iterable transport is JSON/SSE-based and yielded values must be JSON-serializable.
+- `contentType` and `filename` are sent only in the first chunk to avoid repetition.
+- Progress is scoped by `project_id`, so a user can never observe another tenant's transfer.
+- An empty object yields no chunks (the loop simply never runs).
+
+**Content-Type resolution:**
+
+S3/Ceph often can't be trusted to report a useful `Content-Type` — RGW defaults to `binary/octet-stream` when none was set on upload, and some upload tools store an unrelated type (e.g. `application/x-www-form-urlencoded`). Since the raw stored value directly determines whether the frontend can preview a file inline vs. must force a download, `downloadObject` resolves the type as follows before yielding the first chunk:
+
+1. If the object key has a recognized extension (`.jpg`, `.pdf`, `.txt`, `.png`, etc.), the MIME type is derived from that extension and takes priority over whatever S3 returned.
+2. Otherwise (unknown or missing extension — e.g. a UUID-style key), the `ContentType` from the S3 `GetObjectCommand` response is used as-is, falling back to `application/octet-stream` if absent.
+
+This means the `contentType` yielded in the first chunk may differ from the object's stored `Content-Type` in S3. Consumers that need the _raw_ stored value (rather than the resolved/display value) should call `getDetails` instead, which returns the S3 metadata unmodified.
+
+The Ceph frontend (`ObjectsTableView`) uses this resolved `contentType` to decide row-click behavior: safe browser-previewable types (passive media `image/*` excluding `image/svg+xml`, `video/*`, `audio/*`, plus `application/pdf` and `text/plain`) open in a new tab; everything else downloads. The context-menu **Download** action always forces a download regardless of type.
+
+---
+
+#### `watchDownloadProgress`
+
+Subscribes to live progress for an in-flight download identified by `downloadId`. Open this **before** calling `downloadObject` so no early events are missed; a snapshot of current progress is emitted immediately for late subscribers.
+
+**Input:**
+
+```typescript
+{
+  project_id: string,
+  downloadId: string   // Same id passed to downloadObject
+}
+```
+
+**Output:** an async iterable (subscription) yielding progress:
+
+```typescript
+{
+  downloaded: number,  // cumulative bytes streamed
+  total: number,       // total object size in bytes (0 if unknown)
+  percent: number      // 0–100 (0 when total is unknown)
+}
+```
+
+**Example:**
+
+```typescript
+const downloadId = `${bucket}:${objectKey}:${crypto.randomUUID()}`
+
+trpc.storage.ceph.objects.watchDownloadProgress.subscribe(
+  { project_id: "abc123", downloadId },
+  { onData: ({ percent }) => setProgress(percent) }
+)
+
+await trpc.storage.ceph.objects.downloadObject.mutate({
+  project_id: "abc123",
+  containerName: "my-bucket",
+  objectKey: "documents/report.pdf",
+  filename: "report.pdf",
+  downloadId,
+})
+```
+
+**Notes:**
+
+- The subscription completes when the download finishes and re-throws if the download errors.
+- If no events arrive within 30 s (e.g. the download finished before the subscription opened), it ends gracefully rather than hanging.
+
+---
+
 ### Versioning (`storage.ceph.versioning`)
 
 Bucket versioning allows keeping multiple variants of objects in the same bucket, enabling recovery from accidental deletions and overwrites.
@@ -1531,17 +1654,17 @@ console.log("Old credential deleted")
 
 ## Comparison: Ceph S3 vs. Swift
 
-| Feature              | Ceph S3 (this BFF)                | Swift BFF                              |
-| -------------------- | --------------------------------- | -------------------------------------- |
-| **Authentication**   | EC2 credentials (access + secret) | Keystone token                         |
-| **API Style**        | S3-compatible (AWS SDK)           | OpenStack Swift API                    |
-| **Bucket/Container** | S3 buckets                        | Swift containers                       |
-| **Object Hierarchy** | `delimiter` + `prefix`            | `delimiter` + `prefix`                 |
-| **Metadata**         | User metadata via `x-amz-meta-`   | Custom headers via `X-Object-Meta-`    |
-| **Large Objects**    | Multipart uploads                 | Static/Dynamic Large Objects (SLO/DLO) |
-| **Uploads**          | (Not yet implemented)             | `octetInputParser` streaming           |
-| **Downloads**        | (Not yet implemented)             | Async iterable base64 chunks           |
-| **Temporary URLs**   | Presigned URLs (not yet impl)     | HMAC-SHA256 signed temp URLs           |
+| Feature              | Ceph S3 (this BFF)                        | Swift BFF                              |
+| -------------------- | ----------------------------------------- | -------------------------------------- |
+| **Authentication**   | EC2 credentials (access + secret)         | Keystone token                         |
+| **API Style**        | S3-compatible (AWS SDK)                   | OpenStack Swift API                    |
+| **Bucket/Container** | S3 buckets                                | Swift containers                       |
+| **Object Hierarchy** | `delimiter` + `prefix`                    | `delimiter` + `prefix`                 |
+| **Metadata**         | User metadata via `x-amz-meta-`           | Custom headers via `X-Object-Meta-`    |
+| **Large Objects**    | Multipart uploads                         | Static/Dynamic Large Objects (SLO/DLO) |
+| **Uploads**          | (Not yet implemented)                     | `octetInputParser` streaming           |
+| **Downloads**        | Async iterable base64 chunks (+ progress) | Async iterable base64 chunks           |
+| **Temporary URLs**   | Presigned URLs (not yet impl)             | HMAC-SHA256 signed temp URLs           |
 
 **When to use which?**
 
@@ -1564,8 +1687,8 @@ Both can coexist — Ceph RGW supports **both Swift and S3 APIs** on the same cl
 
 2. **Object Upload/Download**
    - Upload object (`PutObjectCommand`)
-   - Download object (`GetObjectCommand`)
-   - Streaming upload/download via tRPC (similar to Swift BFF `uploadObject`/`downloadObject`)
+   - ~~Download object (`GetObjectCommand`)~~ ✅ Implemented — streamed through the BFF as a tRPC async iterable, with a `watchDownloadProgress` subscription for progress
+   - Streaming upload via tRPC (similar to Swift BFF `uploadObject`)
    - Multipart uploads for large files
 
 3. **Object Manipulation**
@@ -1790,7 +1913,7 @@ openstack endpoint list --service ceph
 
 ## Next Steps
 
-1. **Implement object upload/download** — streaming via `octetInputParser` / async iterables (similar to Swift BFF)
+1. **Implement object upload** — streaming via `octetInputParser` (download already implemented via async-iterable streaming with progress tracking)
 2. **Add presigned URL generation** — allow direct client → Ceph transfers for large files
 3. ~~**Implement bucket management**~~ ✅ Completed — create, delete, empty buckets
 4. **Add credential caching** — reduce Keystone API calls

packages/aurora/src/client/routes/_auth/projects/$projectId/storage/-components/Ceph/Objects/ObjectBrowserView.tsx

@@ -38,6 +38,7 @@ import {
   getObjectMoveErrorToast,
   getObjectMetadataUpdatedToast,
   getObjectMetadataUpdateErrorToast,
+  getObjectDownloadErrorToast,
 } from "./ObjectToastNotifications"
 import { encodePrefix, decodePrefix } from "../../utils/prefixEncoding"
 
@@ -564,6 +565,10 @@ export function ObjectBrowserView({ bucketName }: ObjectBrowserViewProps) {
             const { message, ...options } = getObjectMetadataUpdateErrorToast(objectKey, errorMessage)
             toast.error(message, options)
           }}
+          onDownloadError={(objectKey, errorMessage) => {
+            const { message, ...options } = getObjectDownloadErrorToast(objectKey, errorMessage)
+            toast.error(message, options)
+          }}
         />
       )}
 

packages/aurora/src/client/routes/_auth/projects/$projectId/storage/-components/Ceph/Objects/ObjectToastNotifications.test.tsx

@@ -13,6 +13,7 @@ import {
   getObjectMoveErrorToast,
   getObjectMetadataUpdatedToast,
   getObjectMetadataUpdateErrorToast,
+  getObjectDownloadErrorToast,
   getVersionRestoredToast,
   getVersionRestoreErrorToast,
   getVersionDeletedToast,
@@ -156,6 +157,22 @@ describe("ObjectToastNotifications", () => {
     })
   })
 
+  // ── Object download ──────────────────────────────────────────────────────────
+
+  describe("getObjectDownloadErrorToast", () => {
+    it("renders correct error content", () => {
+      renderNotification(getObjectDownloadErrorToast("documents/file.txt", "Network error"))
+      expect(screen.getByText("Failed to Download Object")).toBeInTheDocument()
+      expect(screen.getByText(/Could not download/)).toBeInTheDocument()
+      expect(screen.getByText(/Network error/)).toBeInTheDocument()
+    })
+
+    it("extracts the display name from a nested object key", () => {
+      renderNotification(getObjectDownloadErrorToast("documents/reports/Q1.pdf", "err"))
+      expect(screen.getByText(/Q1\.pdf/)).toBeInTheDocument()
+    })
+  })
+
   // ── Notification configuration ───────────────────────────────────────────────
 
   describe("Notification configuration", () => {
@@ -171,6 +188,7 @@ describe("ObjectToastNotifications", () => {
         getObjectMoveErrorToast("a.txt", "err"),
         getObjectMetadataUpdatedToast("a.txt"),
         getObjectMetadataUpdateErrorToast("a.txt", "err"),
+        getObjectDownloadErrorToast("a.txt", "err"),
         getVersionRestoredToast("a.txt"),
         getVersionRestoreErrorToast("a.txt", "err"),
         getVersionDeletedToast("a.txt"),

packages/aurora/src/client/routes/_auth/projects/$projectId/storage/-components/Ceph/Objects/ObjectToastNotifications.tsx

@@ -144,6 +144,23 @@ export const getObjectMetadataUpdateErrorToast = (
   }
 }
 
+// ── Object download ────────────────────────────────────────────────────────────
+
+export const getObjectDownloadErrorToast = (
+  objectKey: string,
+  errorMessage: string
+): { message: ReactNode } & NotificationOptions => {
+  const displayName = objectKey.split("/").filter(Boolean).pop() ?? objectKey
+  return {
+    message: <Trans>Failed to Download Object</Trans>,
+    description: (
+      <Trans>
+        Could not download "{displayName}": {errorMessage}
+      </Trans>
+    ),
+  }
+}
+
 // ── Version restore ────────────────────────────────────────────────────────
 
 export const getVersionRestoredToast = (objectKey: string): { message: ReactNode } & NotificationOptions => {