{
  "openapi": "3.1.0",
  "info": {
    "title": "TmpFiles Bridge API",
    "version": "4.0.0",
    "description": "A multi-backend, anonymizing Cloudflare Worker upload proxy. The multipart body is streamed upstream so curl -F works as usual, but all client-identifying request metadata is removed before the request leaves the Worker, and all upstream response headers are discarded. Choose a backend with ?backend= (tmpfiles, tflink, gofile) or bring your own HTTPS endpoint. Gofile returns a share page rather than a raw file URL, so data.directUrl is null for that backend.",
    "x-backends": [
      {
        "id": "tmpfiles",
        "name": "TmpFiles.org",
        "endpoint": "https://tmpfiles.org/api/v1/upload",
        "fileField": "file",
        "supportsExpire": true,
        "landingPage": true,
        "directUrl": true,
        "linkType": "page",
        "maxSize": "100 MB",
        "retention": "1 hour default; 60–172800 s via expire",
        "responseExample": {
          "status": "success",
          "data": {
            "url": "https://tmpfiles.org/6136281/test.jpg"
          }
        }
      },
      {
        "id": "tflink",
        "name": "tfLink (tmpfile.link)",
        "endpoint": "https://tmpfile.link/api/upload",
        "fileField": "file",
        "supportsExpire": false,
        "landingPage": false,
        "directUrl": true,
        "linkType": "direct",
        "maxSize": "100 MB",
        "retention": "7 days (anonymous uploads)",
        "responseExample": {
          "downloadLink": "https://d.tmpfile.link/public/2026-01-11/a1b2c3d4/test.jpg",
          "downloadLinkEncoded": "https://d.tmpfile.link/public%2F2026-01-11%2Fa1b2c3d4%2Ftest.jpg",
          "fileName": "test.jpg",
          "size": 204800,
          "type": "image/jpeg",
          "uploadedTo": "public"
        }
      },
      {
        "id": "gofile",
        "name": "Gofile.io",
        "endpoint": "https://upload.gofile.io/uploadfile",
        "fileField": "file",
        "supportsExpire": false,
        "landingPage": true,
        "directUrl": false,
        "linkType": "page",
        "maxSize": "no fixed limit (free tier is temporary)",
        "retention": "temporary for free / guest uploads",
        "region": "auto",
        "note": "Returns a share page, not a raw file URL. guestToken is dropped.",
        "responseExample": {
          "status": "ok",
          "data": {
            "downloadPage": "https://gofile.io/d/x7k2p9Qm",
            "parentFolderCode": "x7k2p9Qm",
            "name": "test.jpg",
            "size": 204800,
            "mimetype": "image/jpeg"
          }
        }
      },
      {
        "id": "custom",
        "name": "Custom endpoint",
        "endpoint": "X-Upstream-Url header",
        "fileField": "X-File-Field header (default: file)",
        "supportsExpire": false,
        "landingPage": false,
        "directUrl": true,
        "linkType": "direct",
        "maxSize": "backend decides",
        "retention": "backend decides",
        "responseExample": {
          "downloadLink": "https://upload.example.com/files/a1b2c3/test.jpg",
          "fileName": "test.jpg"
        }
      }
    ],
    "x-privacy": [
      {
        "title": "Fixed anonymous User-Agent",
        "detail": "Every proxied upstream subrequest carries exactly one UA: Anonymous-Upload-Client. No version, no OS, no browser, no client hint. Your real UA is never read or forwarded."
      },
      {
        "title": "Upstream never sees your IP",
        "detail": "The request is re-issued by the Worker, so the backend sees a Cloudflare egress IP. CF-Connecting-IP, X-Forwarded-For, True-Client-IP and similar inbound hints are dropped."
      },
      {
        "title": "Outbound header allowlist",
        "detail": "Only Content-Type (boundary only), Accept: application/json, and the fixed UA are sent. Cookie, Referer, Origin, Accept-Language, Authorization, X-Upstream-Url, X-File-Field, Via and all other inbound headers are dropped. Optional tfLink credentials (X-User-Id / X-Auth-Token) and an optional Gofile account token (Authorization: Bearer) come from Worker secrets only, never from the client."
      },
      {
        "title": "Filename sanitization",
        "detail": "Multipart part headers are rewritten in-stream: directory paths in filename= are stripped. Set ANONYMIZE_FILENAME=random for upload-<hex>.<ext>. X-File-Field renames the file part for custom backends. The Web UI anonymizes the filename before the request even leaves the browser."
      },
      {
        "title": "No token in URLs",
        "detail": "UPLOAD_TOKEN is accepted only via Authorization: Bearer. Query-string tokens are rejected. Custom backend URLs travel in the X-Upstream-Url header, not in the request line."
      },
      {
        "title": "Clean responses, no fingerprint",
        "detail": "No upstream response header is copied: Set-Cookie, CF-Ray, Server, ETag and tracing headers are gone. Upstream JSON is rebuilt through a field allowlist and every URL is validated before it is returned."
      },
      {
        "title": "Gofile guest credentials are discarded",
        "detail": "An anonymous Gofile upload creates a guest account and returns a guestToken. That is an account credential, so the Worker drops it along with parentFolder, md5, createTime and every other unexpected field. Only the validated share page URL, share code, file name, size and mimetype are returned. Gofile has no reliable raw file URL for guest uploads, so data.directUrl is null and data.linkType is \"page\". GOFILE_TOKEN, GOFILE_REGION and GOFILE_ENDPOINT are server-side settings; the client cannot choose them."
      },
      {
        "title": "Custom backends are SSRF-guarded",
        "detail": "HTTPS only, default port, no userinfo, no IP literals, no localhost or reserved suffixes, redirects not followed. Pin CUSTOM_BACKEND_ALLOWLIST to restrict hosts, or set ALLOW_CUSTOM_BACKEND=0 to disable. DNS rebinding cannot be fully prevented from inside a Worker."
      },
      {
        "title": "No logs, no storage, no analytics",
        "detail": "The Worker keeps nothing in memory beyond one request, writes no KV/R2/DO, emits no console output, and never logs filenames, sizes, tokens, backend URLs, timestamps or IPs. Every response is no-store, private."
      },
      {
        "title": "Browser-side hardening",
        "detail": "The UI is served with a fresh per-response CSP nonce, no unsafe-inline scripts, no-referrer, COOP, CORP, Permissions-Policy and frame-ancestors none. connect-src allows https: only for opt-in direct mode."
      },
      {
        "title": "Anonymity is not encryption",
        "detail": "Files are public on the chosen backend until they expire (tmpfiles.org: 1 hour by default; tfLink: 7 days; Gofile: temporary for free/guest uploads). Anyone with the link can download it. Metadata anonymization does not make the content private."
      }
    ],
    "x-config": [
      {
        "key": "UPLOAD_TOKEN",
        "default": "unset",
        "detail": "Require Authorization: Bearer <token> on proxied uploads."
      },
      {
        "key": "CORS_ORIGIN",
        "default": "*",
        "detail": "Pin Access-Control-Allow-Origin and add Vary: Origin."
      },
      {
        "key": "ANONYMIZE_FILENAME",
        "default": "strip",
        "detail": "strip | random | off."
      },
      {
        "key": "ALLOW_CUSTOM_BACKEND",
        "default": "1",
        "detail": "0 disables user-supplied endpoints."
      },
      {
        "key": "CUSTOM_BACKEND_ALLOWLIST",
        "default": "unset",
        "detail": "Comma-separated hosts allowed for custom endpoints."
      },
      {
        "key": "TFLINK_USER_ID / TFLINK_AUTH_TOKEN",
        "default": "unset",
        "detail": "Server-side tfLink authenticated upload credentials."
      },
      {
        "key": "GOFILE_TOKEN",
        "default": "unset",
        "detail": "Server-side Gofile account token, injected as Authorization: Bearer for the gofile backend only."
      },
      {
        "key": "GOFILE_REGION",
        "default": "auto",
        "detail": "Pin an upload region: eu-par, na-phx, na-nyc, ap-sgp, ap-hkg, ap-tyo, ap-syd, sa-sao."
      },
      {
        "key": "GOFILE_ENDPOINT",
        "default": "unset",
        "detail": "Full HTTPS URL override if Gofile moves its upload host. Takes priority over GOFILE_REGION."
      },
      {
        "key": "KEEP_UPSTREAM_BODY",
        "default": "0",
        "detail": "1 = forward raw upstream body (headers still cleaned)."
      },
      {
        "key": "EXPOSE_BRIDGE_HEADERS",
        "default": "0",
        "detail": "1 = add x-bridge-* debug headers."
      }
    ]
  },
  "servers": [
    {
      "url": "https://up.cogpu.com",
      "description": "This Worker"
    }
  ],
  "tags": [
    {
      "name": "Upload",
      "description": "Anonymizing multi-backend upload proxy"
    },
    {
      "name": "Meta",
      "description": "Discovery and health"
    }
  ],
  "paths": {
    "/api/v1/upload": {
      "post": {
        "tags": [
          "Upload"
        ],
        "summary": "Upload a file through a chosen backend",
        "description": "Accepts multipart/form-data, forwards it to the selected backend with a fixed anonymous header set, and returns a unified sanitized JSON result. Alias: POST /api/upload.",
        "operationId": "uploadFile",
        "parameters": [
          {
            "in": "query",
            "name": "backend",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "tmpfiles",
                "tflink",
                "gofile",
                "custom"
              ],
              "default": "tmpfiles"
            },
            "description": "tmpfiles = https://tmpfiles.org/api/v1/upload (default). tflink = https://tmpfile.link/api/upload. gofile = https://upload.gofile.io/uploadfile (returns a share page, no direct URL). custom = use X-Upstream-Url. Aliases: link, tmpfile.link, tmpfiles.org, gofile.io, upload.gofile.io, gf, self."
          },
          {
            "in": "header",
            "name": "X-Upstream-Url",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Full HTTPS endpoint for the custom backend. Presence implies backend=custom. Validated against SSRF rules and CUSTOM_BACKEND_ALLOWLIST. Never forwarded to the upstream."
          },
          {
            "in": "header",
            "name": "X-File-Field",
            "required": false,
            "schema": {
              "type": "string",
              "default": "file"
            },
            "description": "Rename the multipart file part for custom backends (e.g. upfile). Only [A-Za-z0-9_-], max 64 chars. Never forwarded to the upstream."
          },
          {
            "in": "header",
            "name": "Authorization",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer <UPLOAD_TOKEN>, only when the secret is configured. Never send the token in the query string."
          },
          {
            "in": "header",
            "name": "User-Agent",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "IGNORED. Overwritten with the fixed anonymous UA before the upstream request."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file to upload. Max 100 MB on tmpfiles and tfLink; Gofile has no fixed limit. Directory paths in the filename are stripped. Use curl -F \"file=@/path/to/test.jpg;filename=photo.jpg\" to control the published name. Gofile also accepts optional folderId / token form fields, but its account token should be set as the GOFILE_TOKEN secret instead."
                  },
                  "expire": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 172800,
                    "default": 3600,
                    "description": "Seconds until deletion. tmpfiles backend only; ignored by tfLink, gofile and custom backends. The Web UI disables this field for backends that do not support it."
                  }
                }
              },
              "example": {
                "file": "@/path/to/test.jpg",
                "expire": 21600
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload succeeded through the selected backend.",
            "content": {
              "application/json": {
                "examples": {
                  "tmpfiles": {
                    "value": {
                      "status": "success",
                      "backend": "tmpfiles",
                      "data": {
                        "url": "https://tmpfiles.org/6136281/test.jpg",
                        "directUrl": "https://tmpfiles.org/dl/6136281/test.jpg",
                        "linkType": "page"
                      }
                    }
                  },
                  "tflink": {
                    "value": {
                      "status": "success",
                      "backend": "tflink",
                      "data": {
                        "url": "https://d.tmpfile.link/public/2026-01-11/a1b2c3/test.jpg",
                        "directUrl": "https://d.tmpfile.link/public/2026-01-11/a1b2c3/test.jpg",
                        "linkType": "direct",
                        "fileName": "test.jpg",
                        "size": 204800,
                        "type": "image/jpeg"
                      }
                    }
                  },
                  "gofile": {
                    "value": {
                      "status": "success",
                      "backend": "gofile",
                      "data": {
                        "url": "https://gofile.io/d/x7k2p9Qm",
                        "directUrl": null,
                        "linkType": "page",
                        "code": "x7k2p9Qm",
                        "fileName": "test.jpg",
                        "size": 204800,
                        "type": "image/jpeg"
                      }
                    }
                  },
                  "custom": {
                    "value": {
                      "status": "success",
                      "backend": "custom",
                      "data": {
                        "url": "https://upload.example.com/files/a1b2c3/test.jpg",
                        "directUrl": "https://upload.example.com/files/a1b2c3/test.jpg",
                        "linkType": "direct"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing body, or backend=custom without X-Upstream-Url."
          },
          "401": {
            "description": "UPLOAD_TOKEN configured and the bearer token is missing or wrong."
          },
          "403": {
            "description": "Custom backend disabled or host not in CUSTOM_BACKEND_ALLOWLIST."
          },
          "405": {
            "description": "Method not allowed. Only POST is accepted on this path."
          },
          "415": {
            "description": "Content-Type is not multipart/form-data with a valid boundary."
          },
          "502": {
            "description": "Upstream unreachable, redirected, non-JSON, or contained no usable URL."
          }
        }
      }
    },
    "/api/backends": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "List backends and custom-endpoint policy",
        "operationId": "listBackends",
        "responses": {
          "200": {
            "description": "Backend descriptors + custom policy."
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "This OpenAPI document",
        "operationId": "getApiDocs",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON."
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Health check (no client data)",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Service is alive."
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Web UI (upload + backend picker + docs + privacy)",
        "operationId": "getWebUi",
        "responses": {
          "200": {
            "description": "text/html; charset=utf-8, CSP nonce per response."
          }
        }
      }
    }
  }
}