feat(upload): add ephemeral key prefix to POST /v1/upload

api/routes/uploader.py

@@ -57,6 +57,15 @@ class UploadRequest(BaseModel):
         description=f"File content as base64-encoded string (max {MAX_UPLOAD_MIB} MiB decoded)",
     )
     content_type: str | None = Field(default=None, max_length=255, description="MIME type (e.g. 'application/pdf')")
+    ephemeral: bool = Field(
+        default=False,
+        description=(
+            "When true, the file is stored under the user's '/ephemeral/' key prefix instead of '/assets/'. "
+            "The prefix marks synthetic, throwaway test inputs (e.g. sandbox-generated data) as distinct from "
+            "durable user attachments under '/assets/'. A 7-day auto-delete lifecycle for these objects is planned "
+            "(tag-based, gated on pipelex storage-provider tag support) but not yet active."
+        ),
+    )
 
 
 class UploadResponse(BaseModel):
@@ -94,7 +103,15 @@ async def upload_file(
         raise_payload_too_large(f"Decoded file exceeds {MAX_UPLOAD_BYTES // (1024 * 1024)} MiB limit")
 
     ext = body.filename.rsplit(".", 1)[-1] if "." in body.filename else "bin"
-    key = f"{user.user_id}/assets/{uuid.uuid4()}.{ext}"
+    # The key must keep `user_id` as its first segment: the storage-URL resolver
+    # (`storage.py::parse_storage_uri`) gates ownership on `segments[0] == requester
+    # user_id`, so ephemeral files stay resolvable by their owner. The '/ephemeral/'
+    # segment separates synthetic, throwaway inputs from durable user attachments
+    # under '/assets/'. A planned 7-day auto-delete lifecycle for ephemeral objects
+    # is tag-based (not prefix-based) precisely because the user_id-first layout
+    # prevents a single S3 prefix rule from matching '*/ephemeral/'.
+    prefix = "ephemeral" if body.ephemeral else "assets"
+    key = f"{user.user_id}/{prefix}/{uuid.uuid4()}.{ext}"
 
     storage = get_storage_provider()
     # Most storage failures surface as a pipelex `StorageError` (a `PipelexError`)

tests/unit/test_uploader.py

@@ -116,6 +116,35 @@ def test_storage_key_uses_authenticated_user_id(self, mocker: MockerFixture, fil
         assert key.startswith(f"{USER_A}/assets/")
         assert key.endswith(f".{expected_ext}")
 
+    def test_default_upload_lands_under_assets_prefix(self, mocker: MockerFixture):
+        """Regression guard: omitting `ephemeral` keeps durable attachments under '/assets/',
+        which the 7-day lifecycle rule must never touch.
+        """
+        user = RequestUser(user_id=USER_A)
+        client, store_mock = _build_client(user, mocker)
+
+        client.post("/upload", json={"filename": "resume.pdf", "data": VALID_B64})
+
+        store_mock.assert_awaited_once()
+        key = store_mock.await_args.kwargs["key"]
+        assert key.startswith(f"{USER_A}/assets/")
+        assert "/ephemeral/" not in key
+
+    def test_ephemeral_upload_lands_under_ephemeral_prefix(self, mocker: MockerFixture):
+        """`ephemeral=true` routes the object under '/ephemeral/', the exact key segment the
+        pipelex-api-infra S3 lifecycle rule filters on for 7-day auto-deletion.
+        """
+        user = RequestUser(user_id=USER_A)
+        client, store_mock = _build_client(user, mocker)
+
+        client.post("/upload", json={"filename": "synthetic.png", "data": VALID_B64, "ephemeral": True})
+
+        store_mock.assert_awaited_once()
+        key = store_mock.await_args.kwargs["key"]
+        assert key.startswith(f"{USER_A}/ephemeral/")
+        assert key.endswith(".png")
+        assert "/assets/" not in key
+
     @pytest.mark.parametrize(
         "backend_error",
         [