upload.json

{
  "name": "Upload",
  "access": {
    "anon": "Cannot upload attachments.",
    "user": "Can upload in the comment attachment flow; download permissions must be re-validated.",
    "admin": "No standalone public 'upload management console' currently exists.",
    "agent": "No upload capability is currently provided."
  },
  "rules": {
    "comment-attachments-only": "Uploads serve only comment attachments; they are not an independent file space.",
    "permission-and-quota": "Permission and quota checks are required before upload.",
    "three-step-upload": "Web comment attachment uploads follow a three-step flow — create upload session on-site → browser direct upload to S3-compatible pre-signed URL generated by AWS SDK → confirm completion on-site; page CSP must allow the signed storage origin actually used by the upload backend, including AWS S3 virtual-hosted / path-style addresses or compatible backend addresses via custom endpoint configuration.",
    "s3-compatible-backend": "The storage backend operates with AWS SDK S3-compatible configuration; defaults to AWS S3 but allows connecting to compatible backends via custom endpoint.",
    "storage-observability": "Shared S3 helpers record production-safe bounded metrics for storage operation status and duration; metrics identify operation type but do not include bucket names, object keys, signed URLs, filenames, or user IDs.",
    "e2e-local-s3": "E2E tests use a local S3-compatible test endpoint by default; external storage is only used when an available S3 environment is explicitly provided.",
    "download-auth-required": "Downloads must not bypass authorization by obtaining a direct link.",
    "download-signed-url": "/api/uploads/[id]/download only returns a short-lived signed download URL redirect, not a stable long-reusable object direct link."
  },
  "capabilities": {
    "upload-list": {
      "title": "Upload List",
      "auth": "user",
      "web": "stable",
      "rest": {
        "routes": [
          {
            "path": "/api/uploads",
            "returns": "{ maxFileSizeBytes, quotaBytes, uploads: Upload[], usedBytes }",
            "notes": [
              "The same path currently handles both 'read upload quota / history' and 'create upload session' capabilities."
            ]
          }
        ]
      },
      "mcp": "unavailable",
      "display": {
        "fields": [
          "upload.filename",
          "upload.size (formatted bytes)",
          "upload.createdAt",
          "usedBytes",
          "quotaBytes",
          "maxFileSizeBytes"
        ]
      }
    },
    "comment-attachment-upload": {
      "title": "Comment Attachment Upload",
      "auth": "user",
      "web": "stable",
      "rest": {
        "routes": [
          {
            "path": "/api/uploads",
            "method": "POST",
            "returns": "{ key: String, url: String, maxFileSizeBytes: Int, quotaBytes: Int, usedBytes: Int }"
          },
          {
            "path": "/api/uploads/complete",
            "method": "POST",
            "returns": "{ upload: Upload, usedBytes: Int, quotaBytes: Int }"
          }
        ]
      },
      "mcp": "unavailable",
      "display": {
        "fields": [
          "File input",
          "File preview",
          "upload progress indicator",
          "Cancel button"
        ]
      }
    },
    "comment-attachment-download": {
      "title": "Comment Attachment Download",
      "auth": "user",
      "web": "stable",
      "rest": {
        "routes": [
          {
            "path": "/api/uploads/[id]/download",
            "returns": "302 redirect to signed URL",
            "notes": [
              "Validates access permissions before redirecting to a short-lived signed URL."
            ]
          }
        ]
      },
      "mcp": "unavailable",
      "display": {
        "fields": ["attachment filename", "Open/download button"]
      }
    },
    "upload-manage": {
      "title": "Upload Rename & Delete",
      "auth": "user",
      "web": "stable",
      "rest": {
        "routes": [
          {
            "path": "/api/uploads/[id]",
            "method": "PATCH",
            "returns": "{ upload: Upload }",
            "notes": ["Renames one upload owned by the current user."]
          },
          {
            "path": "/api/uploads/[id]",
            "method": "DELETE",
            "returns": "{ deletedId: String, deletedSize: Int }",
            "notes": [
              "Deletes one upload owned by the current user and removes the object from storage."
            ]
          }
        ]
      },
      "mcp": "unavailable",
      "display": {
        "fields": [
          "Rename action",
          "Delete action",
          "Per-upload feedback state"
        ]
      }
    }
  }
}