corsport

🚀 CORSPort

A simple JavaScript CORS solution using hidden iframe proxy. Make cross-origin requests without server configuration—just add a port.html on the target domain.

✨ Features

• Simple API - Just use corsport.fetch() instead of fetch()
• Explicit control - You decide which requests to proxy
• Zero server configuration - No backend changes needed
• Standard Response API - Returns native Response objects
• TypeScript support - Full type definitions included
• Tiny - Only 2.5 KB minified

🧩 How It Works

Your App → corsport.fetch(url) → Hidden iframe → Same-origin fetch() → Response

CORSPort creates a hidden iframe on the target domain that performs same-origin requests (bypassing CORS).

📦 Installation

npm install corsport

Or via CDN:

<script type="module">
  import * as corsport from 'https://unpkg.com/corsport/dist/corsport.min.js';
</script>

🚀 Quick Start

1. Generate port.html

npx corsport init

Upload the generated port.html to your target domain.

2. Use in your app

import * as corsport from 'corsport';

// Configure once
await corsport.configure({
  portUrl: 'https://api.example.com/port.html',
});

// Use corsport.fetch() for cross-origin requests
const response = await corsport.fetch('https://api.example.com/users');
const data = await response.json();

📖 API

corsport.configure(config)

await corsport.configure({
  portUrl: string,    // Required: URL of port.html
  timeout?: number,   // Optional: Request timeout (default: 30000)
  debug?: boolean     // Optional: Enable logging (default: false)
});

corsport.fetch(url, options)

Same API as native fetch():

// GET
const response = await corsport.fetch('https://api.example.com/users');

// POST
const response = await corsport.fetch('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'John' }),
});

// With authorization
const response = await corsport.fetch('https://api.example.com/data', {
  headers: { Authorization: 'Bearer token' },
});

🔒 Security

Security Audit ✅

CORSPort has passed comprehensive security auditing:

• ✅ Zero vulnerabilities - No critical, high, or moderate issues
• ✅ Zero dependencies - No supply chain attack risk
• ✅ ESLint security checks - All passed
• ✅ npm audit - Clean report
• ✅ TypeScript strict mode - Full type safety

📄 View Full Security Audit Report

Configuration

Configure port.html security settings:

const CONFIG = {
  allowedOrigins: ['https://your-app.com'], // Required
  allowedPaths: ['/api/'], // Optional
  maxBodySize: 10 * 1024 * 1024, // 10MB
  debug: false, // Set to false in production
};

Best Practices:

• ✅ Always set allowedOrigins (never use ['*'] in production)
• ✅ Use HTTPS in production
• ✅ Limit allowedPaths to specific endpoints
• ✅ Set reasonable maxBodySize
• ✅ Disable debug mode in production
• ✅ Monitor access logs regularly

Security Features:

• 🛡️ Origin whitelist validation
• 🔒 MessageChannel isolation
• ⚡ Request size limits
• 🚫 XSS/CSRF/Injection protection
• 🔐 Bearer token support

🧪 Demo

pnpm install
pnpm dev

Open http://localhost:8080/demo/app/

🌐 Browser Support

• Chrome 91+
• Firefox 89+
• Safari 14+
• Edge 91+

📝 License

MIT - see LICENSE file

🤝 Contributing

• Fork the repository
• Create a feature branch
• Run pnpm check && pnpm format
• Submit a pull request

Full documentation: GitHub