fix: improve CORS proxy handling and update documentation for certificate fetching

2026-02-20 16:07:21 +05:30
parent 832e28aaca
commit e6c8eaf23c
4 changed files with 732 additions and 516 deletions
--- a/docs/self-hosting/cors-proxy.md
+++ b/docs/self-hosting/cors-proxy.md
@@ -2,6 +2,8 @@

 The digital signature tool uses a CORS proxy to fetch issuer certificates from external Certificate Authorities (CAs). This is necessary because many CA servers don't include CORS headers in their responses, which prevents direct browser-based fetching.

+Additionally, many CA servers serve certificates over plain HTTP. When your BentoPDF instance is hosted over HTTPS, browsers block these HTTP requests (mixed content policy). The CORS proxy resolves both issues by routing requests through an HTTPS endpoint with proper headers.
+
 ## How It Works

 When signing a PDF with a certificate:
@@ -13,35 +15,64 @@ When signing a PDF with a certificate:

 ## Self-Hosting the CORS Proxy

-If you're self-hosting BentoPDF, you'll need to deploy your own CORS proxy.
+If you're self-hosting BentoPDF, you'll need to deploy your own CORS proxy for digital signatures to work with certificates that require chain fetching.

 ### Option 1: Cloudflare Workers (Recommended)

 1. **Install Wrangler CLI**:
+
   ```bash
   npm install -g wrangler
   ```

 2. **Login to Cloudflare**:
+
   ```bash
   wrangler login
   ```

-3. **Deploy the proxy**:
+3. **Clone BentoPDF and update allowed origins**:
+
+   ```bash
+   git clone https://github.com/alam00000/bentopdf.git
+   cd bentopdf/cloudflare
+   ```
+
+   Open `cors-proxy-worker.js` and change the `ALLOWED_ORIGINS` array to your domain:
+
+   ```js
+   const ALLOWED_ORIGINS = [
+     'https://your-domain.com',
+     'https://www.your-domain.com',
+   ];
+   ```
+
+   ::: warning Important
+   Without this change, the proxy will reject all requests from your site with a **403 Forbidden** error. The default only allows requests from `bentopdf.com`.
+   :::
+
+4. **Deploy the proxy**:
+
   ```bash
-   cd cloudflare
   wrangler deploy
   ```

-4. **Update your environment**:
-   Create a `.env` or set in your hosting platform:
-   ```
-   VITE_CORS_PROXY_URL=https://your-worker-name.your-subdomain.workers.dev
+   Note your worker URL (e.g., `https://bentopdf-cors-proxy.your-subdomain.workers.dev`).
+
+5. **Rebuild BentoPDF with the proxy URL**:
+
+   If using Docker:
+
+   ```bash
+   docker build \
+     --build-arg VITE_CORS_PROXY_URL="https://your-worker.workers.dev" \
+     -t your-bentopdf .
   ```

-5. **Rebuild BentoPDF**:
+   If building from source:
+
   ```bash
-   npm run build
+   VITE_CORS_PROXY_URL=https://your-worker.workers.dev npm run build
   ```

 ### Option 2: Custom Backend Proxy
@@ -51,27 +82,28 @@ You can also create your own proxy endpoint. The requirements are:
 1. Accept GET requests with a `url` query parameter
 2. Fetch the URL from your server (no CORS restrictions server-side)
 3. Return the response with these headers:
-   - `Access-Control-Allow-Origin: *` (or your specific origin)
+   - `Access-Control-Allow-Origin: https://your-domain.com`
   - `Access-Control-Allow-Methods: GET, OPTIONS`
-   - `Content-Type: application/x-x509-ca-cert`
+   - `X-Content-Type-Options: nosniff`

 Example Express.js implementation:

 ```javascript
 app.get('/api/cert-proxy', async (req, res) => {
  const targetUrl = req.query.url;
-  
+
  // Validate it's a certificate URL
  if (!isValidCertUrl(targetUrl)) {
    return res.status(400).json({ error: 'Invalid URL' });
  }
-  
+
  try {
    const response = await fetch(targetUrl);
    const data = await response.arrayBuffer();
-    
-    res.set('Access-Control-Allow-Origin', '*');
-    res.set('Content-Type', 'application/x-x509-ca-cert');
+
+    res.set('Access-Control-Allow-Origin', 'https://your-domain.com');
+    res.set('Content-Type', 'application/octet-stream');
+    res.set('X-Content-Type-Options', 'nosniff');
    res.send(Buffer.from(data));
  } catch (error) {
    res.status(500).json({ error: 'Proxy error' });
@@ -83,9 +115,15 @@ app.get('/api/cert-proxy', async (req, res) => {

 The included Cloudflare Worker has several security measures:

- **URL Validation**: Only allows certificate-related URLs (`.crt`, `.cer`, `.pem`, `/certs/`, `/ocsp`, `/crl`)
- **Blocked Domains**: Prevents access to localhost and private IP ranges
- **HTTP Methods**: Only allows GET requests
+| Feature                 | Description                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| **Origin Validation**   | Only allows requests from domains listed in `ALLOWED_ORIGINS`                          |
+| **URL Restrictions**    | Only allows certificate URLs (`.crt`, `.cer`, `.pem`, `/certs/`, `/ocsp`, `/crl`)      |
+| **Private IP Blocking** | Blocks IPv4/IPv6 private ranges, link-local, loopback, decimal IPs, and cloud metadata |
+| **Content-Type Safety** | Only returns safe certificate MIME types, blocks upstream content-type injection       |
+| **File Size Limit**     | Streams response with 10MB limit, aborts mid-download if exceeded                      |
+| **Rate Limiting**       | 60 requests per IP per minute (requires KV)                                            |
+| **HMAC Signatures**     | Optional client-side signing (deters casual abuse)                                     |

 ## Disabling the Proxy

@@ -95,22 +133,39 @@ If you don't want to use a CORS proxy, set the environment variable to an empty
 VITE_CORS_PROXY_URL=
 ```

-**Note**: Without the proxy, signing with certificates that require external chain fetching (like FNMT or some corporate CAs) will fail.
+**Note**: Without the proxy, signing with certificates that require external chain fetching (like FNMT or some corporate CAs) will fail with a "Failed to fetch" error.

 ## Troubleshooting

-### "Failed to fetch certificate chain" Error
+### "Signing error: TypeError: Failed to fetch"

-1. Check that your CORS proxy is deployed and accessible
-2. Verify the `VITE_CORS_PROXY_URL` is correctly set
-3. Test the proxy directly:
-   ```bash
-   curl "https://your-proxy.workers.dev?url=https://www.cert.fnmt.es/certs/ACUSU.crt"
-   ```
+This usually means either:
+
+1. **No CORS proxy configured** — Set `VITE_CORS_PROXY_URL` and rebuild
+2. **Mixed content blocked** — Your site is HTTPS but the certificate's issuer URL is HTTP. The CORS proxy resolves this.
+3. **CORS proxy rejecting your origin** — Check that your domain is in the `ALLOWED_ORIGINS` array in `cors-proxy-worker.js`
+
+### "403 Forbidden" from the proxy
+
+Your domain is not in the `ALLOWED_ORIGINS` list. Edit `cors-proxy-worker.js`:
+
+```js
+const ALLOWED_ORIGINS = ['https://your-domain.com'];
+```
+
+Then redeploy: `npx wrangler deploy`
+
+### Testing the proxy
+
+```bash
+curl -H "Origin: https://your-domain.com" \
+  "https://your-proxy.workers.dev?url=http://www.cert.fnmt.es/certs/ACUSU.crt"
+```

 ### Certificates That Work Without Proxy

 Some certificates include the full chain in the P12/PFX file and don't require external fetching:
+
 - Self-signed certificates
 - Some commercial CAs that bundle intermediate certificates
 - Certificates you've manually assembled with the full chain