remix 3.0.0-beta.0 → 3.0.0-beta.10

package/src/cookie/README.md

@@ -0,0 +1,106 @@
+# cookie
+
+Type-safe cookie parsing and serialization for Remix. It supports secure signing, secret rotation, and complete cookie attribute control.
+
+## Features
+
+- **Secure Cookie Signing:** Built-in cryptographic signing using HMAC-SHA256 to prevent cookie tampering, with support for secret rotation without breaking existing cookies.
+- **Secret Rotation Support:** Seamlessly rotate signing secrets while maintaining backward compatibility with existing cookies.
+- **Web Standards Compliant:** Built on Web Crypto API and standard cookie parsing, making it runtime-agnostic (Node.js, Bun, Deno, Cloudflare Workers).
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```tsx
+import { createCookie } from 'remix/cookie'
+
+let sessionCookie = createCookie('session', {
+  httpOnly: true,
+  secrets: ['s3cret1'],
+  secure: true,
+})
+
+cookie.name // "session"
+cookie.httpOnly // true
+cookie.secure // true
+cookie.signed // true
+
+// Get the value of the "session" cookie from the request's `Cookie` header
+let value = await sessionCookie.parse(request.headers.get('Cookie'))
+
+// Set the value of the cookie in a Response's `Set-Cookie` header
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
+```
+
+### Signing Cookies
+
+This library supports signing cookies, which is useful for ensuring the integrity of the cookie value and preventing tampering. Signing happens automatically when you provide a `secrets` option to the `Cookie` constructor.
+
+Secret rotation is also supported, so you can easily rotate in new secrets without breaking existing cookies.
+
+```tsx
+import { Cookie } from 'remix/cookie'
+
+// Start with a single secret
+let sessionCookie = createCookie('session', {
+  secrets: ['secret1'],
+})
+
+console.log(sessionCookie.signed) // true
+
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
+```
+
+All cookies sent in this scenario will be signed with the secret `secret1`. Later, when it's time to rotate secrets, add a new secret to the beginning of the array and all existing cookies will still be able to be parsed.
+
+```tsx
+let sessionCookie = createCookie('session', {
+  secrets: ['secret2', 'secret1'],
+})
+
+// This works for cookies signed with either secret
+let value = await sessionCookie.parse(request.headers.get('Cookie'))
+
+// Newly serialized cookies will be signed with the new secret
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
+```
+
+### Custom Encoding
+
+By default, cookie values are percent-encoded and wrapped in base64 so arbitrary string values can be safely stored in cookies. This is suitable for most use cases, but you can provide your own functions to customize the encoding and decoding of the cookie value.
+
+```tsx
+let sessionCookie = createCookie('session', {
+  encode: (value) => value.replaceAll(' ', '-'),
+  decode: (value) => value.replaceAll('-', ' '),
+})
+```
+
+Custom `encode` functions are used as the full cookie value codec. Their return values are signed when `secrets` are configured and then serialized as-is, without the default base64 wrapper. This can be useful for viewing the value of cookies in a human-readable format in the browser's developer tools. But you should be sure that the encoded cookie value contains only characters that are [valid in a cookie value](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#attributes) and safe for HTTP headers. Raw Unicode characters should be escaped or encoded by your custom function before they are returned.
+
+## Related Packages
+
+- [`headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Type-safe HTTP header manipulation
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Build HTTP routers using the web fetch API
+- [`node-fetch-server`](https://github.com/remix-run/remix/tree/main/packages/node-fetch-server) - Build HTTP servers on Node.js using the web fetch API
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/cop-middleware/README.md

@@ -0,0 +1,117 @@
+# cop-middleware
+
+Cross-origin protection middleware for Remix. It mirrors Go's `CrossOriginProtection` by rejecting unsafe cross-origin browser requests without synchronizer tokens.
+
+## Features
+
+- **Browser Provenance Checks** - Uses `Sec-Fetch-Site` when present and falls back to `Origin`
+- **Trusted Origins** - Allow specific cross-origin callers by exact origin
+- **Explicit Escape Hatches** - Support insecure bypass patterns for endpoints like webhooks
+- **No Session State** - Does not require synchronizer tokens or server-side CSRF storage
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/router'
+import { cop } from 'remix/middleware/cop'
+
+let router = createRouter({
+  middleware: [cop()],
+})
+```
+
+## Behavior
+
+For unsafe methods (`POST`, `PUT`, `PATCH`, `DELETE`), `cop()` follows the same broad model as Go's `CrossOriginProtection`:
+
+- Allow `Sec-Fetch-Site: same-origin`
+- Allow `Sec-Fetch-Site: none`
+- Reject other `Sec-Fetch-Site` values unless the request matches a trusted origin or insecure bypass
+- If `Sec-Fetch-Site` is missing, compare `Origin` to the request host
+- If both `Sec-Fetch-Site` and `Origin` are missing, allow the request
+
+This middleware is intentionally tokenless. If you cannot guarantee the deployment assumptions behind that model, prefer [`csrf-middleware`](https://github.com/remix-run/remix/tree/main/packages/csrf-middleware).
+
+## Caveats
+
+- `cop()` is a browser-origin guard, not a universal CSRF solution. It is designed for deployments that can rely on modern browser provenance signals and same-origin request handling.
+- If both `Sec-Fetch-Site` and `Origin` are missing on an unsafe request, `cop()` allows the request to continue. This is intentional so older clients and non-browser callers do not fail closed by default.
+- If `Sec-Fetch-Site` is missing, `cop()` only rejects when `Origin` is present and does not match the request host.
+- If you need stronger guarantees for session-backed form workflows, mixed deployment environments, or requests that should not fall through when browser provenance headers are missing, use [`csrf-middleware`](https://github.com/remix-run/remix/tree/main/packages/csrf-middleware) or layer both middlewares together.
+
+## Using with csrf-middleware
+
+You can also layer `cop()` in front of `csrf()` when you want both browser provenance checks and session-backed synchronizer tokens.
+
+```ts
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/router'
+import { createCookieSessionStorage } from 'remix/session-storage/cookie'
+import { session } from 'remix/middleware/session'
+import { cop } from 'remix/middleware/cop'
+import { csrf } from 'remix/middleware/csrf'
+
+let sessionCookie = createCookie('__session', { secrets: ['secret1'] })
+let sessionStorage = createCookieSessionStorage()
+
+let router = createRouter({
+  middleware: [cop(), session(sessionCookie, sessionStorage), csrf()],
+})
+```
+
+In this setup, `cop()` runs first and rejects unsafe cross-origin browser requests early using `Sec-Fetch-Site` and `Origin`. Requests that pass `cop()` continue into `csrf()`, which still enforces synchronizer-token validation and origin checks for the remaining traffic.
+
+## Trusted Origins
+
+```ts
+import { createRouter } from 'remix/router'
+import { cop } from 'remix/middleware/cop'
+
+let router = createRouter({
+  middleware: [
+    cop({
+      trustedOrigins: ['https://admin.example.com'],
+    }),
+  ],
+})
+```
+
+Trusted origins must be exact origin values in the form `scheme://host[:port]`.
+
+## Insecure Bypass Patterns
+
+Bypass patterns intentionally weaken protection for specific endpoints. They support:
+
+- Optional method prefixes, for example `POST /webhooks/{provider}`
+- Exact paths, for example `/healthz`
+- Trailing-slash subtree patterns, for example `/webhooks/`
+- Single-segment wildcards with `{name}`
+- Tail wildcards with `{name...}`
+
+```ts
+import { createRouter } from 'remix/router'
+import { cop } from 'remix/middleware/cop'
+
+let router = createRouter({
+  middleware: [
+    cop({
+      insecureBypassPatterns: ['POST /webhooks/{provider}', '/healthz'],
+    }),
+  ],
+})
+```
+
+## Related Packages
+
+- [`csrf-middleware`](https://github.com/remix-run/remix/tree/main/packages/csrf-middleware) - Session-backed CSRF protection with synchronizer tokens
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/cors-middleware/README.md

@@ -0,0 +1,174 @@
+# cors-middleware
+
+CORS middleware for Remix. It adds standard CORS response headers to Fetch API servers and can either short-circuit preflight requests or pass them through to app-defined `OPTIONS` handlers.
+
+## Features
+
+- **Preflight Handling** - Automatically handles `OPTIONS` preflight requests
+- **Flexible Origin Rules** - Supports static, regex, list, and function-based origin policies
+- **Credential Support** - Supports credentialed requests with spec-safe origin reflection
+- **Header Controls** - Configure allowed and exposed headers, preflight methods, and max age
+- **Private Network Support** - Optionally allow private network preflight requests
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/router'
+import { cors } from 'remix/middleware/cors'
+
+let router = createRouter({
+  middleware: [
+    cors({
+      origin: ['https://app.example.com', 'https://admin.example.com'],
+      credentials: true,
+      exposedHeaders: ['X-Request-Id'],
+    }),
+  ],
+})
+
+router.get('/api/projects', () => {
+  return Response.json([{ id: 'p1', name: 'Remix' }], {
+    headers: {
+      'X-Request-Id': 'req_123',
+    },
+  })
+})
+```
+
+## Origin Policies
+
+`origin` supports:
+
+- `'*'` to allow all origins
+- `string` for a single exact origin
+- `RegExp` for pattern-based matching
+- `Array<string | RegExp>` for multiple exact and pattern matches
+- `true` to reflect the request origin
+- `(origin, context) => boolean | string` for dynamic policies
+
+### Restrict Origins
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      origin: ['https://app.example.com', 'https://admin.example.com'],
+      credentials: true,
+    }),
+  ],
+})
+```
+
+### Dynamic Origin Policies
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      origin(origin, context) {
+        if (context.url.pathname.startsWith('/public/')) {
+          return '*'
+        }
+
+        return origin.endsWith('.trusted.example')
+      },
+    }),
+  ],
+})
+```
+
+## Preflight Behavior
+
+By default, preflight requests are short-circuited with status `204`.
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      methods: ['GET', 'POST', 'PATCH'],
+      allowedHeaders: ['Authorization', 'Content-Type'],
+      maxAge: 600,
+    }),
+  ],
+})
+```
+
+Use a function-based `allowedHeaders` policy when the header allowlist depends on the request:
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      allowedHeaders(request) {
+        let requestedHeaders = request.headers.get('Access-Control-Request-Headers')
+
+        if (requestedHeaders?.includes('x-admin-token')) {
+          return ['Authorization', 'Content-Type', 'X-Admin-Token']
+        }
+
+        return ['Authorization', 'Content-Type']
+      },
+    }),
+  ],
+})
+```
+
+Function-based `allowedHeaders` responses vary on `Access-Control-Request-Headers`, so caches do not reuse a preflight response for a different requested-header set.
+
+Set `preflightContinue: true` to let downstream handlers process preflight requests. Use `preflightStatusCode` when you want short-circuited preflight responses to return a status other than `204`.
+
+## Private Network Preflights
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      allowPrivateNetwork: true,
+    }),
+  ],
+})
+```
+
+When `allowPrivateNetwork` is enabled, the middleware adds `Access-Control-Allow-Private-Network: true` for preflight requests that ask for private network access.
+
+## Expose Response Headers
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      exposedHeaders: ['X-Request-Id', 'X-Trace-Id'],
+    }),
+  ],
+})
+```
+
+## Caveats
+
+- CORS is primarily a browser enforcement mechanism. Disallowed non-preflight requests still reach your handlers unless you add separate request validation.
+- When `credentials: true` is used with `origin: '*'`, the middleware reflects the request origin and adds `Vary: Origin` so the response stays cache-safe.
+- When `allowedHeaders` is a function, preflight responses vary on `Access-Control-Request-Headers` so caches do not reuse a response for a different requested-header set.
+- `preflightContinue` and `preflightStatusCode` only affect how preflight `OPTIONS` requests are handled. They do not change actual request authorization.
+
+## Related Packages
+
+- [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) - Browser-origin protection middleware for unsafe cross-origin requests
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Typed HTTP header utilities
+
+## Related Work
+
+- [MDN: Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+- [Fetch Standard: CORS protocol](https://fetch.spec.whatwg.org/#http-cors-protocol)
+- [expressjs/cors](https://github.com/expressjs/cors)
+- [rack-cors](https://github.com/cyu/rack-cors)
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/csrf-middleware/README.md

@@ -0,0 +1,92 @@
+# csrf-middleware
+
+CSRF protection middleware for Remix. It provides synchronizer-token validation backed by session storage, plus origin checks for unsafe requests.
+
+## Features
+
+- **Session-Backed Tokens** - Creates and persists CSRF tokens in the request session
+- **Flexible Token Extraction** - Reads tokens from headers, form fields, query params, or a custom resolver
+- **Origin Validation** - Validates `Origin`/`Referer` for unsafe methods with customizable policies
+- **Configurable Enforcement** - Control safe methods, token keys, and failure responses
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+This middleware requires [`session-middleware`](https://github.com/remix-run/remix/tree/main/packages/session-middleware) to run before it.
+
+```ts
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/router'
+import { createCookieSessionStorage } from 'remix/session-storage/cookie'
+import { session } from 'remix/middleware/session'
+import { csrf, getCsrfToken } from 'remix/middleware/csrf'
+
+let sessionCookie = createCookie('__session', { secrets: ['secret1'] })
+let sessionStorage = createCookieSessionStorage()
+
+let router = createRouter({
+  middleware: [session(sessionCookie, sessionStorage), csrf()],
+})
+
+router.get('/form', (context) => {
+  let token = getCsrfToken(context)
+
+  return new Response(`
+    <form method="post" action="/submit">
+      <input type="hidden" name="_csrf" value="${token}" />
+      <button type="submit">Submit</button>
+    </form>
+  `)
+})
+```
+
+## Token Sources
+
+By default, `csrf()` checks token values in this order:
+
+1. Request headers: `X-Csrf-Token`, `X-Xsrf-Token`, `Csrf-Token`
+2. Form field: `_csrf` (requires `formData()` middleware to parse request bodies)
+3. Query param: `_csrf`
+
+You can override extraction using `value(context)`.
+
+Headers and form fields are the preferred transports. Query param fallback exists for compatibility, but it is the weakest option because tokens are more likely to be exposed in logs, history, and copied URLs.
+
+## Origin Validation
+
+For unsafe methods (`POST`, `PUT`, `PATCH`, `DELETE`), the middleware validates request origin.
+
+- Default: same-origin validation when `Origin` or `Referer` is present
+- Custom: provide `origin` as string, regex, array, or function
+- Missing origin behavior: controlled by `allowMissingOrigin` (default `true`)
+
+## Caveats
+
+- The synchronizer token is the primary defense in `csrf()`. `Origin` and `Referer` checks are an additional signal, not the only protection.
+- By default, unsafe requests with a valid token still pass when `Origin` and `Referer` are both missing. Set `allowMissingOrigin: false` if your deployment wants to require provenance headers on unsafe requests.
+- Query param tokens are supported for compatibility, but they should not be the default recommendation. Prefer headers or hidden form fields when you control the client.
+- If you want to reject more unsafe requests before token validation, especially when browser provenance headers are available, layer [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) in front of `csrf()`.
+
+## Why This Exists
+
+Modern browsers now provide stronger cross-origin signals like `Sec-Fetch-Site`, and explicit `SameSite=Lax` cookies already block many CSRF attacks. We have considered the lighter, tokenless model used by Go's `CrossOriginProtection`, and we think it is a good fit when a deployment can make all of the guarantees that model depends on.
+
+Remix cannot assume those guarantees for every app. `csrf()` still exists as the conservative option for apps that want synchronizer tokens in addition to origin checks, especially for session-backed HTML form workflows and mixed deployment environments.
+
+If your deployment can guarantee the prerequisites for the tokenless model, this middleware is optional. In that case, [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) may be a better fit.
+
+## Related Packages
+
+- [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) - Middleware for tokenless cross-origin protection using browser provenance headers
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`session-middleware`](https://github.com/remix-run/remix/tree/main/packages/session-middleware) - Session middleware required by `csrf()`
+- [`form-data-middleware`](https://github.com/remix-run/remix/tree/main/packages/form-data-middleware) - Needed for form body token extraction
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)