# Br Cors Public Client

> Configure better-route 0.5.0 CORS and preflight support for public REST clients. Use when adding CorsMiddleware, CorsPolicy, Router::options(), Authorization or Idempotency-Key cross-origin requests, credentialed browser clients, app clients, OPTIONS routes, or debugging failed REST preflight requests.

- Skill: `aibot88/br-cors-public-client` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aibot88/br-cors-public-client`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aibot88/br-cors-public-client/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: aibot88 (https://skillmd.com/u/aibot88)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/aibot88/br-cors-public-client

---


# better-route: CORS and preflight

Use explicit CORS policy for browser or embedded clients. Do not rely on incidental WordPress defaults when the API needs `Authorization`, `Idempotency-Key`, `If-Match`, `X-Request-ID`, or credentials.

## Global middleware

```php
use BetterRoute\Middleware\Cors\CorsMiddleware;
use BetterRoute\Middleware\Cors\CorsPolicy;

$cors = new CorsMiddleware(new CorsPolicy(
    allowedOrigins: ['https://app.example.com'],
    allowCredentials: true
));

$router->middleware([$cors]);
```

Default allowed headers include:

- `Authorization`
- `Content-Type`
- `Idempotency-Key`
- `If-Match`
- `If-None-Match`
- `X-Request-ID`
- `X-WP-Nonce`

Default exposed headers include `ETag`, `Idempotency-Replayed`, `X-RateLimit-*`, and `X-Request-ID`.

## Explicit preflight route

`CorsMiddleware` can short-circuit `OPTIONS` requests, but the router must register an `OPTIONS` route for that path when WordPress would not otherwise dispatch it.

```php
$router->options('/account/payment-methods', static fn () => null)
    ->middleware([$cors]);
```

`Router::options()` is public by default in 0.5.0. Do not attach business handlers to preflight routes.

## Rules

- Prefer an origin allowlist. Use `*` only for non-credentialed public APIs.
- If `allowCredentials: true`, do not return wildcard origin; `CorsPolicy` echoes the allowed request origin.
- Put CORS early in the middleware list so errors and short-circuits still get headers where possible.
- Keep allowed headers aligned with actual client needs; add custom headers deliberately.
- Keep CORS separate from authentication. CORS says which browser origins may call; auth says who the caller is.

## Source refs

- `libraries/better-route/src/Middleware/Cors/CorsMiddleware.php`
- `libraries/better-route/src/Middleware/Cors/CorsPolicy.php`
- `libraries/better-route/src/Router/Router.php`
- `libraries/better-route/tests/BuiltInMiddlewareTest.php`
- `libraries/better-route/tests/RouterPipelineTest.php`