chore: import upstream snapshot with attribution

application/api/user/artifacts/__init__.py

@@ -0,0 +1,5 @@
+"""Artifacts module."""
+
+from .routes import artifacts_ns
+
+__all__ = ["artifacts_ns"]

application/api/user/artifacts/authz.py

@@ -0,0 +1,168 @@
+"""Parent-derived authorization helpers for artifact access."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from flask import request
+
+from application.storage.db.repositories.agents import AgentsRepository
+from application.storage.db.repositories.artifacts import ArtifactsRepository
+from application.storage.db.repositories.conversations import ConversationsRepository
+from application.storage.db.repositories.shared_conversations import (
+    SharedConversationsRepository,
+)
+from application.storage.db.repositories.workflow_runs import WorkflowRunsRepository
+from application.storage.db.session import db_readonly
+
+
+@dataclass(frozen=True)
+class Principal:
+    """The resolved caller of an artifact route.
+
+    A decoded JWT is a full *owner* session (``agent_id`` is ``None``). An
+    ``api_key`` is a low-trust, publicly-distributed *agent* credential -- it is
+    embedded client-side in the widget and accepted from the query string -- so
+    it resolves to the owning ``user_id`` but stays **agent-scoped**: it may reach
+    an artifact only when the request also carries that artifact's parent
+    ``conversation_id`` (the unguessable per-visitor secret), confining it to a
+    single conversation rather than the agent's whole corpus, and may not perform
+    mutating operations.
+    """
+
+    user_id: Optional[str] = None
+    agent_id: Optional[str] = None
+
+    @property
+    def is_agent_scoped(self) -> bool:
+        """True for an api_key (agent) principal that must be confined to its agent."""
+        return self.agent_id is not None
+
+
+def resolve_principal() -> Principal:
+    """Resolve the caller to a :class:`Principal`.
+
+    Priority: a decoded JWT (owner session) first, then an ``api_key`` query/form
+    param (agent-scoped). An unresolvable caller yields an anonymous principal
+    (both fields ``None``) that only a valid ``share_token`` can authorize.
+    """
+    decoded_token = getattr(request, "decoded_token", None)
+    if decoded_token:
+        return Principal(user_id=decoded_token.get("sub"))
+
+    api_key = request.args.get("api_key") or request.form.get("api_key")
+    if api_key:
+        with db_readonly() as conn:
+            agent = AgentsRepository(conn).find_by_key(api_key)
+        if agent and agent.get("user_id") and agent.get("id"):
+            return Principal(user_id=str(agent["user_id"]), agent_id=str(agent["id"]))
+    return Principal()
+
+
+def _shared_row_for(conn, conversation_id, share_token):
+    """Return the shared_conversations row iff share_token grants this conversation, else None."""
+    if not share_token:
+        return None
+    shared = SharedConversationsRepository(conn).find_by_uuid(share_token)
+    if shared and str(shared.get("conversation_id")) == str(conversation_id):
+        return shared
+    return None
+
+
+def user_can_access_conversation(
+    conn, conversation_id: str, user_id: Optional[str], share_token: Optional[str]
+) -> bool:
+    """Allow if the caller owns/shares the conversation, or holds a valid share token.
+
+    Conversation-level gate only. Reuses ``ConversationsRepository.get`` (owner OR
+    ``shared_with``) so artifact access tracks message access, and honours a valid
+    share token. A share-token caller reaches the conversation here but must still
+    be snapshot-scoped per-artifact by the caller (see ``authorize_artifact``): a
+    valid token does NOT imply access to every artifact in the conversation.
+    """
+    if user_id:
+        if ConversationsRepository(conn).get(conversation_id, user_id) is not None:
+            return True
+    return _shared_row_for(conn, conversation_id, share_token) is not None
+
+
+def authorize_artifact(conn, artifact: dict, principal: Principal) -> bool:
+    """Authorize a READ of ``artifact`` for ``principal``; missing parent fails closed.
+
+    A low-trust agent api_key is confined to a single conversation it proves by
+    carrying that artifact's parent ``conversation_id`` query param (owner match +
+    matching conversation + agent scope) and never inherits share-link access. A
+    JWT owner or ``shared_with`` collaborator gets full access to every artifact of
+    the parent; a share-token holder is confined to the shared ``first_n_queries``
+    snapshot (an artifact whose ``message_id`` is outside it, or NULL, is denied).
+    """
+    if principal.is_agent_scoped:
+        # An agent key is not the owner's session and is embedded in public widget
+        # JS, so require the artifact to belong to the owner AND the request to
+        # carry the parent conversation_id (the unguessable per-visitor secret):
+        # the key alone, without that id, cannot download a known artifact.
+        if str(artifact.get("user_id")) != str(principal.user_id):
+            return False
+        req_conv = request.args.get("conversation_id")
+        parent = artifact.get("conversation_id")
+        if not req_conv or parent is None or str(parent) != str(req_conv):
+            return False
+        return ArtifactsRepository(conn).artifact_in_agent_scope(
+            str(artifact.get("id")), str(principal.agent_id)
+        )
+
+    conversation_id = artifact.get("conversation_id")
+    workflow_run_id = artifact.get("workflow_run_id")
+    share_token = request.args.get("share_token")
+
+    if conversation_id is not None:
+        # Owner or shared_with collaborator: full access to every artifact.
+        if principal.user_id and ConversationsRepository(conn).get(
+            str(conversation_id), principal.user_id
+        ) is not None:
+            return True
+        # Share-token holder: only artifacts inside the shared first_n_queries snapshot.
+        shared = _shared_row_for(conn, str(conversation_id), share_token)
+        if shared is None:
+            return False
+        message_id = artifact.get("message_id")
+        if not message_id:
+            return False
+        first_n = int(shared.get("first_n_queries") or 0)
+        return ConversationsRepository(conn).message_in_first_n(
+            str(conversation_id), str(message_id), first_n
+        )
+    if workflow_run_id is not None:
+        if not principal.user_id:
+            return False
+        run = WorkflowRunsRepository(conn).get(str(workflow_run_id))
+        return run is not None and run.get("user_id") == principal.user_id
+    # No parent row reachable -> deny (e.g. deleted conversation/run).
+    return False
+
+
+def authorize_artifact_write(conn, artifact: dict, principal: Principal) -> bool:
+    """Authorize a *mutating* artifact operation (e.g. delete / restore).
+
+    Stricter than :func:`authorize_artifact`: a write requires an authenticated
+    *owner* of the parent. Low-trust agent api_keys, share links, and
+    ``shared_with`` collaborators inherit read/download access only, so an
+    agent-scoped, anonymous, or share-token-only caller is denied -- they can read
+    an artifact but never mutate it.
+    """
+    if principal.is_agent_scoped or not principal.user_id:
+        return False
+    conversation_id = artifact.get("conversation_id")
+    workflow_run_id = artifact.get("workflow_run_id")
+
+    if conversation_id is not None:
+        return (
+            ConversationsRepository(conn).get_owned(str(conversation_id), principal.user_id)
+            is not None
+        )
+    if workflow_run_id is not None:
+        run = WorkflowRunsRepository(conn).get(str(workflow_run_id))
+        return run is not None and run.get("user_id") == principal.user_id
+    # No parent row reachable -> deny (e.g. deleted conversation/run).
+    return False

application/api/user/artifacts/routes.py

@@ -0,0 +1,402 @@
+"""Artifact metadata and download routes (parent-derived authz)."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from flask import (
+    Response,
+    current_app,
+    jsonify,
+    make_response,
+    redirect,
+    request,
+    stream_with_context,
+)
+from flask_restx import Namespace, Resource
+
+from application.api import api
+from application.api.user.artifacts.authz import (
+    _shared_row_for,
+    authorize_artifact,
+    authorize_artifact_write,
+    resolve_principal,
+    user_can_access_conversation,
+)
+from application.core.settings import settings
+from application.storage.db.base_repository import looks_like_uuid
+from application.storage.db.repositories.artifacts import ArtifactsRepository
+from application.storage.db.repositories.conversations import ConversationsRepository
+from application.storage.db.repositories.workflow_runs import WorkflowRunsRepository
+from application.storage.db.session import db_readonly, db_session
+from application.storage.storage_creator import StorageCreator
+
+artifacts_ns = Namespace("artifacts", description="Artifact operations", path="/api")
+
+# Presigned-URL TTL for private S3 artifact downloads (seconds).
+_PRESIGNED_URL_TTL = 300
+
+
+_ARTIFACT_URL_ENVELOPE_MIME = "application/vnd.docsgpt.artifact-url+json"
+
+
+def _sanitize_header_filename(filename: Optional[str], fallback: str) -> str:
+    """Strip CRLF / quotes from a display filename for a Content-Disposition header."""
+    if not filename:
+        return fallback
+    cleaned = re.sub(r'[\r\n"]', "", str(filename)).strip()
+    return cleaned or fallback
+
+
+def _artifact_summary(artifact: dict) -> dict:
+    """Project an artifact identity row to its API metadata shape (owner id withheld)."""
+    return {
+        "id": str(artifact.get("id")),
+        "conversation_id": (str(artifact["conversation_id"]) if artifact.get("conversation_id") is not None else None),
+        "workflow_run_id": (str(artifact["workflow_run_id"]) if artifact.get("workflow_run_id") is not None else None),
+        "message_id": (str(artifact["message_id"]) if artifact.get("message_id") is not None else None),
+        "kind": artifact.get("kind"),
+        "title": artifact.get("title"),
+        "metadata": artifact.get("metadata"),
+        "current_version": artifact.get("current_version"),
+        "created_at": _iso(artifact.get("created_at")),
+        "updated_at": _iso(artifact.get("updated_at")),
+    }
+
+
+def _version_summary(version: dict, *, include_spec: bool = False) -> dict:
+    """Project a version row to its API metadata shape (storage_path withheld)."""
+    out = {
+        "version": version.get("version"),
+        "mime_type": version.get("mime_type"),
+        "filename": version.get("filename"),
+        "size": version.get("size"),
+        "sha256": version.get("sha256"),
+        "preview_text": version.get("preview_text"),
+        "produced_by": version.get("produced_by"),
+        "created_at": _iso(version.get("created_at")),
+    }
+    if include_spec:
+        out["spec"] = version.get("spec")
+    return out
+
+
+def _iso(value):
+    """ISO-format a datetime, passing through other values unchanged."""
+    return value.isoformat() if hasattr(value, "isoformat") else value
+
+
+@artifacts_ns.route("/artifacts")
+class ListArtifacts(Resource):
+    @api.doc(description="List artifacts for a conversation, workflow run, or the caller")
+    def get(self):
+        principal = resolve_principal()
+        user_id = principal.user_id
+        conversation_id = request.args.get("conversation_id")
+        workflow_run_id = request.args.get("workflow_run_id")
+        share_token = request.args.get("share_token")
+
+        if not user_id and not share_token:
+            return make_response(jsonify({"success": False, "message": "Authentication required"}), 401)
+
+        # Gate UUID-shape before any CAST(:id AS uuid) reaches the repo, so a
+        # malformed id is rejected cleanly instead of poisoning the transaction.
+        if conversation_id and not looks_like_uuid(conversation_id):
+            return make_response(jsonify({"success": False, "message": "Invalid conversation_id"}), 400)
+        if workflow_run_id and not looks_like_uuid(workflow_run_id):
+            return make_response(jsonify({"success": False, "message": "Invalid workflow_run_id"}), 400)
+
+        try:
+            with db_readonly() as conn:
+                repo = ArtifactsRepository(conn)
+                if principal.is_agent_scoped:
+                    # A low-trust agent api_key is embedded in public widget JS and
+                    # shared by every anonymous visitor, so it may NOT enumerate the
+                    # agent's artifacts. The unguessable conversation_id (UUIDv4) is
+                    # the only per-visitor secret: require it as a bearer capability
+                    # and scope the query to it. Workflow runs are not agent-scoped,
+                    # so reject that filter.
+                    if workflow_run_id:
+                        return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                    if not conversation_id:
+                        return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                    rows = repo.list_artifacts_for_agent(principal.agent_id, user_id, conversation_id=conversation_id)
+                elif conversation_id:
+                    if not user_can_access_conversation(conn, conversation_id, user_id, share_token):
+                        return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                    rows = repo.list_artifacts(conversation_id=conversation_id)
+                    # Owner / shared_with collaborator sees every artifact; a
+                    # share-token caller is confined to the shared first_n_queries
+                    # snapshot (drop artifacts whose message is outside it or NULL).
+                    conv_repo = ConversationsRepository(conn)
+                    is_owner = bool(user_id and conv_repo.get(conversation_id, user_id) is not None)
+                    if not is_owner:
+                        shared = _shared_row_for(conn, conversation_id, share_token)
+                        first_n = int(shared.get("first_n_queries") or 0) if shared else 0
+                        snapshot_ids = conv_repo.first_n_message_ids(conversation_id, first_n)
+                        rows = [
+                            r
+                            for r in rows
+                            if r.get("message_id") is not None and str(r.get("message_id")) in snapshot_ids
+                        ]
+                elif workflow_run_id:
+                    run = WorkflowRunsRepository(conn).get(workflow_run_id)
+                    if run is None or run.get("user_id") != user_id:
+                        return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                    rows = repo.list_artifacts(workflow_run_id=workflow_run_id)
+                else:
+                    if not user_id:
+                        return make_response(
+                            jsonify({"success": False, "message": "Authentication required"}),
+                            401,
+                        )
+                    rows = repo.list_artifacts(user_id=user_id)
+
+            return make_response(
+                jsonify({"success": True, "artifacts": [_artifact_summary(r) for r in rows]}),
+                200,
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error listing artifacts: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+
+
+@artifacts_ns.route("/artifacts/<artifact_id>")
+class GetArtifact(Resource):
+    @api.doc(description="Get an artifact's metadata, version list, and current spec")
+    def get(self, artifact_id: str):
+        if not looks_like_uuid(artifact_id):
+            return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+        principal = resolve_principal()
+        try:
+            with db_readonly() as conn:
+                repo = ArtifactsRepository(conn)
+                artifact = repo.get_artifact(artifact_id)
+                if artifact is None:
+                    return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+                if not authorize_artifact(conn, artifact, principal):
+                    return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                versions = repo.list_versions(artifact_id)
+                current = repo.get_version(artifact_id, artifact.get("current_version"))
+
+            payload = _artifact_summary(artifact)
+            payload["versions"] = [_version_summary(v) for v in versions]
+            payload["spec"] = current.get("spec") if current else None
+            return make_response(jsonify({"success": True, "artifact": payload}), 200)
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving artifact: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+
+    @api.doc(description="Delete an artifact and all its versions (owner only)")
+    def delete(self, artifact_id: str):
+        if not looks_like_uuid(artifact_id):
+            return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+        principal = resolve_principal()
+        try:
+            with db_session() as conn:
+                repo = ArtifactsRepository(conn)
+                artifact = repo.get_artifact(artifact_id)
+                if artifact is None:
+                    return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+                # Delete is a WRITE: only the parent owner may delete; share
+                # links / read-only collaborators are denied (read access only).
+                if not authorize_artifact_write(conn, artifact, principal):
+                    return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                storage_paths = repo.delete_artifact(artifact_id)
+            # Reap the bytes best-effort AFTER the row delete commits.
+            _reap_storage(storage_paths)
+            return make_response(jsonify({"success": True}), 200)
+        except Exception as err:
+            current_app.logger.error(f"Error deleting artifact: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 500)
+
+
+def _reap_storage(paths: list) -> None:
+    """Best-effort delete artifact bytes after the DB rows are gone; never raises."""
+    if not paths:
+        return
+    try:
+        storage = StorageCreator.get_storage()
+    except Exception:
+        current_app.logger.warning("artifact delete: storage unavailable", exc_info=True)
+        return
+    for path in paths:
+        try:
+            storage.delete_file(path)
+        except Exception:
+            current_app.logger.warning("artifact delete: failed to delete bytes %s", path, exc_info=True)
+
+
+@artifacts_ns.route("/artifacts/<artifact_id>/versions/<int:version>")
+class GetArtifactVersion(Resource):
+    @api.doc(description="Get a single artifact version's metadata and spec")
+    def get(self, artifact_id: str, version: int):
+        if not looks_like_uuid(artifact_id):
+            return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+        principal = resolve_principal()
+        try:
+            with db_readonly() as conn:
+                repo = ArtifactsRepository(conn)
+                artifact = repo.get_artifact(artifact_id)
+                if artifact is None:
+                    return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+                if not authorize_artifact(conn, artifact, principal):
+                    return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                version_row = repo.get_version(artifact_id, version)
+            if version_row is None:
+                return make_response(jsonify({"success": False, "message": "Version not found"}), 404)
+            return make_response(
+                jsonify({"success": True, "version": _version_summary(version_row, include_spec=True)}),
+                200,
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving artifact version: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+
+
+@artifacts_ns.route("/artifacts/<artifact_id>/download")
+class DownloadArtifact(Resource):
+    @api.doc(description="Download an artifact's bytes (302 to a presigned URL on S3)")
+    def get(self, artifact_id: str):
+        if not looks_like_uuid(artifact_id):
+            return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+        principal = resolve_principal()
+        version_arg = request.args.get("version")
+        try:
+            with db_readonly() as conn:
+                repo = ArtifactsRepository(conn)
+                artifact = repo.get_artifact(artifact_id)
+                if artifact is None:
+                    return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+                if not authorize_artifact(conn, artifact, principal):
+                    return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                version = artifact.get("current_version")
+                if version_arg is not None:
+                    try:
+                        version = int(version_arg)
+                    except ValueError:
+                        return make_response(jsonify({"success": False, "message": "Invalid version"}), 400)
+                version_row = repo.get_version(artifact_id, version)
+
+            if version_row is None:
+                return make_response(jsonify({"success": False, "message": "Version not found"}), 404)
+            # The object key is derived only from the stored path, never client input.
+            storage_path = version_row.get("storage_path")
+            if not storage_path:
+                return make_response(jsonify({"success": False, "message": "No file for this version"}), 404)
+
+            filename = _sanitize_header_filename(version_row.get("filename"), f"artifact-{artifact_id}")
+            mime_type = version_row.get("mime_type") or "application/octet-stream"
+            storage = StorageCreator.get_storage()
+
+            # With URL_STRATEGY=="s3" the contract is to hand back a presigned
+            # URL. If the active backend can't mint one, that's a config error:
+            # surface a 500 rather than silently proxying bytes from a backend
+            # the operator expected to be off the hot path.
+            if getattr(settings, "URL_STRATEGY", "backend") == "s3":
+                try:
+                    url = storage.generate_presigned_url(storage_path, expires_in=_PRESIGNED_URL_TTL)
+                except NotImplementedError:
+                    current_app.logger.error(
+                        "URL_STRATEGY=s3 but %s cannot mint presigned URLs",
+                        type(storage).__name__,
+                    )
+                    return make_response(
+                        jsonify({"success": False, "message": "Storage misconfigured"}),
+                        500,
+                    )
+                # A 302 to a cross-origin S3 URL can't be read by the app's authed
+                # fetch (the bucket has no CORS grant for the app origin). When the
+                # client opts in via ?disposition=url (or Accept: application/json)
+                # hand the presigned URL back as JSON so it can navigate to it
+                # top-level (no CORS). Default stays a 302 so nothing else breaks.
+                if request.args.get("disposition") == "url" or (
+                    "application/json" in request.headers.get("Accept", "")
+                ):
+                    resp = make_response(jsonify({"success": True, "url": url}), 200)
+                    # Tag the envelope with a distinctive media type so the client
+                    # keys off a server-set signal, not the JSON body shape. A
+                    # ``data`` artifact whose bytes happen to be
+                    # ``{"success":true,"url":"..."}`` is streamed under the backend
+                    # strategy with its own (``application/json``) content-type and
+                    # can never carry this vendor type, so it can't be mistaken for a
+                    # redirect (open-redirect gadget). Content-Type is CORS-safelisted,
+                    # so this stays readable cross-origin without expose-headers.
+                    resp.headers["Content-Type"] = _ARTIFACT_URL_ENVELOPE_MIME
+                    return resp
+                return redirect(url, code=302)
+
+            # Stream the bytes in chunks instead of buffering the whole object in
+            # worker memory (artifacts can be many MB); close the handle when done.
+            file_obj = storage.get_file(storage_path)
+
+            def _stream():
+                try:
+                    for chunk in iter(lambda: file_obj.read(65536), b""):
+                        yield chunk
+                finally:
+                    close = getattr(file_obj, "close", None)
+                    if callable(close):
+                        close()
+
+            return Response(
+                stream_with_context(_stream()),
+                mimetype=mime_type,
+                headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+            )
+        except FileNotFoundError:
+            return make_response(jsonify({"success": False, "message": "File not found"}), 404)
+        except Exception as err:
+            current_app.logger.error(f"Error downloading artifact: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+
+
+@artifacts_ns.route("/artifacts/<artifact_id>/restore")
+class RestoreArtifact(Resource):
+    @api.doc(description="Restore a prior version by appending it as the new current version")
+    def post(self, artifact_id: str):
+        if not looks_like_uuid(artifact_id):
+            return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+        principal = resolve_principal()
+        data = request.get_json(silent=True) or {}
+        target_version = data.get("version")
+        if target_version is None:
+            return make_response(jsonify({"success": False, "message": "Missing version"}), 400)
+        try:
+            target_version = int(target_version)
+        except (ValueError, TypeError):
+            return make_response(jsonify({"success": False, "message": "Invalid version"}), 400)
+
+        try:
+            with db_session() as conn:
+                repo = ArtifactsRepository(conn)
+                artifact = repo.get_artifact(artifact_id)
+                if artifact is None:
+                    return make_response(jsonify({"success": False, "message": "Artifact not found"}), 404)
+                # Restore is a WRITE (it appends a new current version); share
+                # links / shared_with collaborators inherit read access only, so
+                # gate on the stricter owner-required write check.
+                if not authorize_artifact_write(conn, artifact, principal):
+                    return make_response(jsonify({"success": False, "message": "Forbidden"}), 403)
+                source = repo.get_version(artifact_id, target_version)
+                if source is None:
+                    return make_response(jsonify({"success": False, "message": "Version not found"}), 404)
+                new_version = repo.append_version(
+                    artifact_id,
+                    mime_type=source.get("mime_type"),
+                    filename=source.get("filename"),
+                    storage_path=source.get("storage_path"),
+                    size=source.get("size"),
+                    sha256=source.get("sha256"),
+                    spec=source.get("spec"),
+                    preview_text=source.get("preview_text"),
+                    produced_by=source.get("produced_by"),
+                )
+            return make_response(
+                jsonify({"success": True, "version": _version_summary(new_version, include_spec=True)}),
+                200,
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error restoring artifact: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)