README.md

metadata

title: img-proxy
emoji: 🖼️
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

MangaDex Image/Auth Proxy

Two small proxies for projects that need MangaDex data in a browser, README renderer, or hosted automation.

• image/ is an Express image proxy for MangaDex covers. It is meant for Hugging Face Spaces and other Docker hosts.
• image/cloudflare-worker/ is the same cover proxy as a Cloudflare Worker.
• auth/ is a Cloudflare Worker CORS proxy for MangaDex OAuth/API setup flows.

The root Dockerfile runs the image proxy, so this repository can be used directly as a Docker Hugging Face Space.

Why This Exists

MangaDex does not add CORS headers for third-party websites. If a browser app calls MangaDex directly, the browser may block the response even when MangaDex returned data correctly.

Cover images can also behave differently inside markdown previews because the preview site sends its own Referer and image request headers. The image proxy requests MangaDex covers with browser-like headers and then serves the image from your own domain with permissive cross-origin headers.

Use a proxy you control for auth. The auth proxy sees the request body while generating tokens.

Project Layout

mangadex-image-auth-proxy/
├─ Dockerfile
├─ README.md
├─ auth/
│  ├─ README.md
│  ├─ package-lock.json
│  ├─ package.json
│  ├─ tsconfig.json
│  ├─ worker.ts
│  └─ wrangler.toml
└─ image/
   ├─ Dockerfile
   ├─ README.md
   ├─ cloudflare-worker/
   ├─ package-lock.json
   ├─ package.json
   └─ server.js

Deploy Image Proxy On Hugging Face

1. Create a new Hugging Face Space.
2. Select Docker as the Space SDK.
3. Upload or push this repository.
4. Hugging Face builds the root Dockerfile.
5. The image proxy listens on port 7860.

Example proxy URL after deployment:

https://your-space.hf.space/covers/<manga-id>/<cover-file>.256.jpg

The proxy fetches:

https://uploads.mangadex.org/covers/<manga-id>/<cover-file>.256.jpg

For MAL-ReadmeList / mangadex-readlist, use:

cover_proxy_url: "https://your-space.hf.space${path}"

Deploy Image Proxy On Cloudflare

If you prefer a Worker instead of Hugging Face:

cd image/cloudflare-worker
npm install
npm run deploy

Then use:

cover_proxy_url: "https://your-worker.example${path}"

If your image format already uses https://mangadex.org/covers/..., the proxy still accepts the full URL and strips the MangaDex domain before fetching from uploads.mangadex.org.

Image Proxy Local Test

cd image
npm install
npm start

Open:

http://localhost:7860/covers/<manga-id>/<cover-file>.256.jpg

You can also pass a full URL through url:

http://localhost:7860/?url=https://uploads.mangadex.org/covers/<manga-id>/<cover-file>.256.jpg

Deploy Auth Proxy On Cloudflare

The auth proxy is a Cloudflare Worker. It is mainly useful for a plain HTML setup wizard that needs to call MangaDex OAuth from the browser.

cd auth
npm install
npm run deploy

Example usage:

https://your-worker.example/https://auth.mangadex.org/realms/mangadex/protocol/openid-connect/token

For a setup wizard CORS proxy value:

https://your-worker.example/

The worker preserves application/x-www-form-urlencoded request bodies, which is required for MangaDex OAuth token requests.

Auth Proxy Local Test

cd auth
npm install
npm run dev

Then send a token request through the local Worker URL using placeholder values:

curl "http://localhost:8787/https://auth.mangadex.org/realms/mangadex/protocol/openid-connect/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Do not commit real credentials, refresh tokens, or .dev.vars.

Security Notes

• The auth proxy can see usernames, passwords, client secrets, access tokens, and refresh tokens if you send them through it.
• Deploy your own auth proxy. Do not send MangaDex credentials through a random public CORS proxy.
• The image proxy is lower risk because it only requests public image paths, but it is still a public endpoint.
• Keep the image proxy path-based if possible: https://your-space.hf.space${path}.
• Keep the auth proxy limited to setup/testing. GitHub Actions should use stored secrets directly, not the browser proxy.

Recommended ReadmeList Settings

For cover images:

cover_url_format: "https://uploads.mangadex.org/covers/${mangaId}/${coverFileName}.256.jpg"
cover_proxy_url: "https://your-space.hf.space${path}"

For a browser setup wizard:

https://your-auth-worker.example/

Publish To GitHub

From this folder:

git init
git add .
git commit -m "Initial MangaDex auth and image proxies"
git branch -M main
git remote add origin https://github.com/gamersindo1223/mangadex-image-auth-proxy.git
git push -u origin main

Create the GitHub repository first if it does not exist yet.