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

package/src/auth-middleware/README.md

@@ -0,0 +1,246 @@
+# auth-middleware
+
+Request-time authentication and route protection for Remix. Use this package to resolve identity into `context.auth` from sessions, bearer tokens, API keys, or your own schemes. Pair it with [`remix/auth`](https://github.com/remix-run/remix/tree/main/packages/auth) when you need browser login routes that call `verifyCredentials()` or `finishExternalAuth()`, then rotate the session id with `completeAuth()` before writing the auth record.
+
+## Features
+
+- Request auth resolution without mutating request objects
+- Route protection with `requireAuth()` and configurable failure behavior
+- Built-in auth schemes for sessions, bearer tokens, and API keys
+- Ordered fallback across multiple auth schemes
+- Public and private route support with the same resolved auth state
+- Read auth state with `context.auth` (or `context.get(Auth)`)
+- Designed to pair with browser login flows that persist session auth records earlier in the request lifecycle
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+The following example shows the request-time half of a session-backed browser login flow:
+
+- another part of the app has already called `completeAuth()` and written `{ userId }` into the returned session
+- `remix/middleware/auth` reads that value, resolves the current user, and protects the dashboard route
+
+```ts
+import { auth, createSessionAuthScheme, requireAuth } from 'remix/middleware/auth'
+import { createRouter } from 'remix/router'
+import { route } from 'remix/routes'
+import { session } from 'remix/middleware/session'
+
+let routes = route({
+  app: {
+    dashboard: '/dashboard',
+  },
+})
+
+type User = { id: string; email: string }
+
+let router = createRouter({
+  middleware: [
+    session(sessionCookie, sessionStorage),
+    auth({
+      schemes: [
+        createSessionAuthScheme<User, { userId: string }>({
+          read(session) {
+            return session.get('auth') as { userId: string } | null
+          },
+          verify(value) {
+            return users.getById(value.userId)
+          },
+          invalidate(session) {
+            session.unset('auth')
+          },
+        }),
+      ],
+    }),
+  ],
+})
+
+router.get(routes.app.dashboard, {
+  middleware: [requireAuth<User>()],
+  handler(context) {
+    let auth = context.auth
+    if (!auth.ok) {
+      return new Response('Unauthorized', { status: 401 })
+    }
+
+    return Response.json({
+      id: auth.identity.id,
+      email: auth.identity.email,
+      method: auth.method,
+    })
+  },
+})
+```
+
+In this example, `createSessionAuthScheme()` turns a persisted session auth record back into request auth state, `auth()` stores that state at `context.auth` (or `context.get(Auth)`), and `requireAuth()` rejects anonymous requests.
+
+If you need to create the login route, start an OAuth redirect, finish a provider callback, or write the session auth record in the first place, use [`remix/auth`](https://github.com/remix-run/remix/tree/main/packages/auth):
+
+- `verifyCredentials()` for direct credentials flows
+- `startExternalAuth()` and `finishExternalAuth()` for OAuth and OIDC flows
+- `completeAuth()` to rotate the session id before writing the auth record that this package reads later
+
+## Route Protection
+
+This package includes two middlewares:
+
+- `auth()` to resolve auth state and store it in `context.auth` (or `context.get(Auth)`)
+- `requireAuth()` to reject requests that aren't authenticated
+
+That separation is intentional so the same auth resolution can support public routes, API routes, and browser routes with different failure behavior.
+
+`auth()` resolves auth state and stores either `{ ok: true, identity, method }` or `{ ok: false, error? }` in `context.auth`.
+
+Use `requireAuth()` after `auth()` when a route must be authenticated. If `auth()` did not run first, `requireAuth()` throws. Otherwise it returns `401 Unauthorized` by default, or you can replace that with `onFailure(context, auth)` to return JSON, redirects, or any other custom response.
+
+Handlers whose context contract includes `auth()` and `requireAuth<Identity>()` can read `context.auth.identity` without a manual lookup or cast. You can also use `context.get(Auth)`.
+
+Auth challenges are forwarded to `WWW-Authenticate` automatically when the auth failure included a `challenge`, so clients that honor those challenges can react without custom header handling.
+
+## Auth Schemes
+
+An `AuthScheme` is any object with a `name` and an `authenticate(context)` method. The `auth()` middleware tries each scheme in order until one returns a success or failure result. If no scheme returns success or failure, the request is treated as anonymous.
+
+This package ships with three built-in auth schemes:
+
+- `createBearerTokenAuthScheme()` for bearer tokens in the [HTTP `Authorization: Bearer <token>` header](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1)
+- `createAPIAuthScheme()` for API keys in a custom request header
+- `createSessionAuthScheme()` for session-backed auth loaded by [a `session()` middleware](https://github.com/remix-run/remix/tree/main/packages/session-middleware)
+
+## Custom Auth Schemes
+
+If none of the built-in auth schemes match your environment, you can create your own auth scheme easily. A custom scheme usually wraps one auth mechanism behind a small `create*` factory function and returns an `AuthScheme`. For example, apps behind a trusted access proxy can authenticate requests from forwarded identity headers instead of sessions or bearer tokens.
+
+```ts
+import type { RequestContext } from 'remix/router'
+import type { AuthScheme } from 'remix/middleware/auth'
+
+type User = {
+  id: string
+  role: 'admin' | 'user'
+}
+
+function createTrustedProxyAuthScheme(): AuthScheme<User> {
+  return {
+    name: 'trusted-proxy',
+    async authenticate(context: RequestContext) {
+      let email = context.headers.get('X-Forwarded-Email')
+
+      if (email == null) {
+        return
+      }
+
+      let user = await users.getByEmail(email)
+
+      if (user == null) {
+        return {
+          status: 'failure',
+          code: 'invalid_credentials',
+          message: 'Unknown forwarded user',
+        }
+      }
+
+      return {
+        status: 'success',
+        identity: user,
+      }
+    },
+  }
+}
+```
+
+Only use a scheme like this when the app is reachable exclusively through infrastructure you trust to set the headers you rely on. In this case, the `X-Forwarded-Email` header.
+
+`authenticate(context)` can return:
+
+- `null`, `undefined`, or no return value to skip this scheme
+- `{ status: 'success', identity }` to authenticate the request
+- `{ status: 'failure', code?, message?, challenge? }` to stop with an auth error
+
+The scheme `name` becomes `auth.method` when authentication succeeds.
+
+## Simple Auth Cookies
+
+If your app already has an auth cookie and you do not need a session-backed identity lookup, you can use a small custom auth scheme and still rely on `requireAuth()` for route protection.
+
+```ts
+import { auth, requireAuth } from 'remix/middleware/auth'
+import type { AuthScheme } from 'remix/middleware/auth'
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/router'
+import { redirect } from 'remix/response/redirect'
+
+let authCookie = createCookie('__auth', {
+  httpOnly: true,
+  sameSite: 'lax',
+  path: '/',
+})
+
+let authCookieScheme: AuthScheme<'demo-user'> = {
+  name: 'auth-cookie',
+  async authenticate(context) {
+    let value = await authCookie.parse(context.headers.get('Cookie'))
+    if (value !== '1') {
+      return
+    }
+
+    return {
+      status: 'success',
+      identity: 'demo-user',
+    }
+  },
+}
+
+let requireAuthCookie = requireAuth<'demo-user'>({
+  onFailure(context) {
+    let isFrameRequest = context.request.headers.get('X-Remix-Frame') === 'true'
+    if (isFrameRequest) {
+      return new Response('<p>Not authorized</p>', {
+        status: 401,
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+        },
+      })
+    }
+
+    return redirect('/login')
+  },
+})
+
+let router = createRouter({
+  middleware: [
+    auth({
+      schemes: [authCookieScheme],
+    }),
+  ],
+})
+
+router.get('/dashboard', {
+  middleware: [requireAuthCookie],
+  handler() {
+    return new Response('ok')
+  },
+})
+```
+
+This pattern keeps the auth check app-owned. Use [`remix/middleware/session`](https://github.com/remix-run/remix/tree/main/packages/session-middleware) and [`remix/auth`](https://github.com/remix-run/remix/tree/main/packages/auth) when you need server-managed session data, credential verification helpers, or OAuth/OIDC flows.
+
+## Related Packages
+
+- [`auth`](https://github.com/remix-run/remix/tree/main/packages/auth) - Browser auth primitives for credentials, OAuth, and OIDC flows
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router and middleware runtime
+- [`response`](https://github.com/remix-run/remix/tree/main/packages/response) - Response helpers like redirects
+
+## Related Work
+
+- [HTTP Authentication Framework](https://datatracker.ietf.org/doc/html/rfc7235)
+- [OAuth 2.0 Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/cli/README.md

@@ -0,0 +1,182 @@
+# cli
+
+Command-line interface for creating and managing Remix projects.
+
+## Features
+
+- Create new Remix projects with `npx remix@next new` or installed `remix new`
+- Print shell completion scripts with `remix completion`
+- Check project environment and Remix app conventions with `remix doctor`
+- Apply available low-risk project fixes with `remix doctor --fix`
+- Manage the current app database with `remix db`
+- Inspect the current app route tree with `remix routes`
+- Run project tests with `remix test`
+- Configure commands with a static, commented `remix.json` file
+- Print the current Remix version with `remix version`
+- Use the same CLI through the `remix` package or the `remix/cli` API
+- Scaffold a starter app that matches the Remix project layout conventions
+
+## Installation
+
+Use `npx remix@next new <target-dir>` to scaffold a new Remix app. Install `remix` when you want the local `remix` command:
+
+```sh
+npm i remix
+```
+
+## Shell completion
+
+Install bash completion:
+
+```sh
+remix completion bash >> ~/.bashrc
+```
+
+Install zsh completion:
+
+```sh
+remix completion zsh >> ~/.zshrc
+```
+
+## Usage
+
+Use `npx remix@next new my-remix-app` to scaffold a new Remix app. After installing Remix, the equivalent local command is `remix new my-remix-app`.
+
+The rest of the CLI is available through the installed `remix` command:
+
+```sh
+remix new my-remix-app
+remix completion bash >> ~/.bashrc
+remix doctor
+remix doctor --fix
+remix db migrate
+remix db status
+remix db reset --force
+remix routes
+remix routes --table
+remix routes --table --no-headers
+remix test
+remix version
+remix --no-color doctor
+```
+
+You can also run the CLI programmatically:
+
+```ts
+import { runRemix } from 'remix/cli'
+
+await runRemix(['new', 'my-remix-app'])
+await runRemix(['completion', 'bash'])
+await runRemix(['doctor'])
+await runRemix(['doctor', '--fix'])
+await runRemix(['db', 'migrate'])
+await runRemix(['db', 'status'])
+await runRemix(['db', 'reset', '--force'])
+await runRemix(['routes'])
+await runRemix(['routes', '--table'])
+await runRemix(['routes', '--table', '--no-headers'])
+await runRemix(['test'])
+await runRemix(['version'])
+```
+
+Destructive database commands (`remix db wipe` and `remix db reset`) refuse to run without `--force`.
+
+`runRemix()` returns the CLI exit code as a promise.
+
+## Configuration
+
+The CLI loads an optional `remix.json`. The file is parsed as JSONC, so it may contain comments and
+trailing commas. Every top-level field is optional:
+
+```jsonc
+{
+  "$schema": "https://remix.run/schemas/remix.json",
+
+  "db": {
+    "adapter": {
+      "type": "sqlite",
+      "filename": { "env": "DATABASE_URL", "default": "./db/app.sqlite" },
+      "foreignKeys": true,
+      "busyTimeout": 5000,
+    },
+    "migrations": {
+      "directory": "./db/migrations",
+      "journalTable": "data_table_migrations",
+    },
+    "seed": "./db/seed.sql",
+  },
+
+  "doctor": {
+    "strict": true,
+  },
+
+  "test": {
+    // Test discovery
+    "files": ["**/*.test{,.browser,.e2e}.{ts,tsx}"],
+    "browserFiles": ["**/*.test.browser.{ts,tsx}"],
+    "e2eFiles": ["**/*.test.e2e.{ts,tsx}"],
+    "exclude": ["node_modules/**", "dist/**"],
+    "type": ["server", "browser", "e2e"],
+    "only": ["/checkout/i"],
+
+    // Test execution
+    "concurrency": 4,
+    "pool": "forks",
+    "setup": "./test/setup.ts",
+    "watch": false,
+
+    // Playwright
+    "playwright": {
+      "echo": false,
+      "open": false,
+      "configFile": "./playwright.config.ts",
+      "projects": ["chromium", "firefox"],
+    },
+
+    // Output
+    "reporter": "spec",
+    "quiet": false,
+
+    // Coverage
+    "coverage": {
+      "enabled": true,
+      "dir": ".coverage",
+      "include": ["app/**"],
+      "exclude": ["**/*.test.*"],
+      "branches": 80,
+      "functions": 80,
+      "lines": 80,
+      "statements": 80,
+    },
+  },
+}
+```
+
+Explicit command flags and positional arguments override configured values. Repeated flags replace
+configured arrays, while nested Playwright and coverage settings merge by field. Relative paths and
+globs are resolved from the directory containing the config file. Use `remix doctor --no-strict` to
+disable configured strict mode for one run.
+
+`remix db` requires `db.adapter`. Adapters use `type: "sqlite"`, `type: "postgres"`, or
+`type: "mysql"`; PostgreSQL uses `connectionString` and MySQL uses `uri`. A connection value may be
+a string or an object naming an environment variable with an optional default. `db.seed` names a
+SQL file that `remix db seed` and `remix db reset` run against the database. Database flags such as
+`--migrations`, `--seed`, `--journal-table`, and `--connection-env` override the corresponding
+config for one invocation. When no global `--config` is provided, database commands find the
+nearest `remix.json` by walking up from the working directory.
+
+Use the global `--config` option to select another JSONC file. The option itself is resolved from the
+CLI working directory and may appear before or after the command:
+
+```sh
+remix --config ./config/remix.ci.json test
+remix test --config ./config/remix.ci.json
+```
+
+A missing default `remix.json` is ignored. A missing explicitly selected file, malformed JSONC,
+unknown property, or invalid value is reported as a CLI error. The optional `$schema` field enables
+editor completion and validation; it has no runtime effect.
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/compression-middleware/README.md

@@ -0,0 +1,176 @@
+# compression-middleware
+
+Response compression middleware for Remix. It negotiates `br`, `gzip`, and `deflate` from `Accept-Encoding` and applies sensible defaults for when compression is useful.
+
+## Features
+
+- **Encoding Negotiation** - Selects the best supported encoding from `Accept-Encoding`
+- **Compression Guards** - Skips already-compressed responses and range-enabled responses
+- **Size Thresholds** - Configurable minimum response size for compression
+- **MIME Filtering** - Compresses only content types likely to benefit
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [compression()],
+})
+```
+
+The middleware will automatically compress responses for compressible MIME types when:
+
+- The client supports compression (`Accept-Encoding` header with a supported encoding)
+- The response is large enough to benefit from compression (≥1024 bytes if `Content-Length` is present, by default)
+- The response hasn't already been compressed
+- The response doesn't advertise range support (`Accept-Ranges: bytes`)
+
+### Threshold
+
+**Default:** `1024` (only enforced if `Content-Length` is present)
+
+Set the minimum response size in bytes to compress:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      threshold: 2048, // Only compress responses ≥2KB
+    }),
+  ],
+})
+```
+
+### Encodings
+
+**Default:** `['br', 'gzip', 'deflate']`
+
+Customize which compression algorithms to support:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      encodings: ['br', 'gzip'], // Only use Brotli and Gzip
+    }),
+  ],
+})
+```
+
+The `encodings` option can also be a function that receives the response:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      encodings: (response) => {
+        // Use different encodings for server-sent events
+        let contentType = response.headers.get('Content-Type')
+        return contentType?.startsWith('text/event-stream;')
+          ? ['gzip', 'deflate']
+          : ['br', 'gzip', 'deflate']
+      },
+    }),
+  ],
+})
+```
+
+### Filter Media Type
+
+**Default:** Uses `isCompressibleMimeType()` from [`remix/mime`](https://github.com/remix-run/remix/tree/main/packages/mime)
+
+You can customize this behavior with the `filterMediaType` option:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+import { isCompressibleMimeType } from 'remix/mime'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      filterMediaType(mediaType) {
+        // Add a custom media type to the default compressible list
+        return isCompressibleMimeType(mediaType) || mediaType === 'application/vnd.example+data'
+      },
+    }),
+  ],
+})
+```
+
+### Compression Options
+
+**Default:** Uses Node.js defaults for [zlib](https://nodejs.org/api/zlib.html#class-options) and [Brotli](https://nodejs.org/api/zlib.html#class-brotlioptions), with automatic flush handling for server-sent events.
+
+You can pass options options to the underlying Node.js `zlib` and `brotli` compressors for fine-grained control:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+import { zlib } from 'node:zlib'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      zlib: {
+        level: 6,
+      },
+      brotli: {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+        },
+      },
+    }),
+  ],
+})
+```
+
+Like `encodings`, both `zlib` and `brotli` options can also be functions that receive the response:
+
+```ts
+import zlib from 'node:zlib'
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      brotli: (response) => {
+        let contentType = response.headers.get('Content-Type')
+        return {
+          params: {
+            [zlib.constants.BROTLI_PARAM_QUALITY]: contentType?.startsWith('text/html;') ? 4 : 11,
+          },
+        }
+      },
+    }),
+  ],
+})
+```
+
+## Related Packages
+
+- [`remix/router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`remix/mime`](https://github.com/remix-run/remix/tree/main/packages/mime) - MIME type utilities
+- [`remix/response`](https://github.com/remix-run/remix/tree/main/packages/response) - Response helpers
+
+## License
+
+MIT