remix 3.0.0-beta.0 → 3.0.0-beta.2

package/src/auth/README.md

@@ -0,0 +1,445 @@
+# auth
+
+Composable browser authentication primitives for Remix. Use this package to verify credentials on your own server, start external OAuth or OIDC redirects, finish provider callbacks, and write an app-owned auth record into the session. Pair it with [`remix/middleware/auth`](https://github.com/remix-run/remix/tree/main/packages/auth-middleware) when later requests need to resolve that session data into the current user and protect routes.
+
+## Features
+
+- Small, composable primitives: `verifyCredentials()`, `startExternalAuth()`, `finishExternalAuth()`, `refreshExternalAuth()`, and `completeAuth()`
+- Built-in provider support for Google, Microsoft, Okta, Auth0, GitHub, Facebook, X, and Atmosphere
+- Module-scope provider configuration for boot-time validation and stable callback URLs
+- App-owned session records so you decide what auth data to persist
+- Shared session completion for credentials and external auth flows
+- Designed to pair with `remix/middleware/auth` for request-time auth resolution and route protection
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+`remix/auth` exposes five primitives:
+
+- `verifyCredentials(provider, context)` parses submitted credentials and returns the authenticated result or `null`
+- `startExternalAuth(provider, context, options?)` stores the in-progress OAuth transaction in the session and returns the provider redirect response
+- `finishExternalAuth(provider, context, options?)` validates the callback, clears the stored transaction, and returns `{ result, returnTo? }`, including any provider tokens in `result.tokens`
+- `refreshExternalAuth(provider, tokens)` exchanges a previously stored `refreshToken` for a fresh provider token bundle when the provider runtime supports refresh
+- `completeAuth(context)` rotates the current session id and returns the session for auth writes
+
+The route owns redirects, flashes, and other app-specific behavior. `remix/auth` owns the protocol work.
+
+## Credentials Auth
+
+Use `createCredentialsAuthProvider()` when your own server can verify submitted credentials directly, such as email/password logins.
+
+```ts
+import { auth, Auth, createSessionAuthScheme, requireAuth } from 'remix/middleware/auth'
+import { completeAuth, createCredentialsAuthProvider, verifyCredentials } from 'remix/auth'
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/router'
+import { formData } from 'remix/middleware/form-data'
+import { form, route } from 'remix/routes'
+import type { GoodAuth } from 'remix/middleware/auth'
+import { redirect } from 'remix/response/redirect'
+import { Session } from 'remix/session'
+import { session } from 'remix/middleware/session'
+import { createCookieSessionStorage } from 'remix/session-storage/cookie'
+
+let sessionCookie = createCookie('__session', {
+  secrets: [env.SESSION_SECRET],
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',
+  path: '/',
+})
+
+let sessionStorage = createCookieSessionStorage()
+
+let routes = route({
+  auth: {
+    session: {
+      login: form('/login'),
+      logout: { method: 'POST', pattern: '/logout' },
+    },
+  },
+  app: {
+    dashboard: '/dashboard',
+  },
+})
+
+let passwordProvider = createCredentialsAuthProvider({
+  parse(context) {
+    let formData = context.get(FormData)
+    if (formData == null) {
+      throw new Error('Expected formData() middleware before verifyCredentials()')
+    }
+
+    return {
+      email: String(formData.get('email') ?? ''),
+      password: String(formData.get('password') ?? ''),
+    }
+  },
+  async verify({ email, password }) {
+    return users.verifyPassword(email, password)
+  },
+})
+
+let router = createRouter({
+  middleware: [
+    session(sessionCookie, sessionStorage),
+    formData(),
+    auth({
+      schemes: [
+        createSessionAuthScheme({
+          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.auth.session.login.index, () => new Response('Login page'))
+
+router.post(routes.auth.session.login.action, async (context) => {
+  let user = await verifyCredentials(passwordProvider, context)
+
+  if (user == null) {
+    return redirect(routes.auth.session.login.index.href())
+  }
+
+  let session = completeAuth(context)
+  session.set('auth', { userId: user.id })
+
+  return redirect(routes.app.dashboard.href())
+})
+
+router.post(routes.auth.session.logout, ({ get }) => {
+  let session = get(Session)
+  session.unset('auth')
+  session.regenerateId(true)
+  return redirect(routes.auth.session.login.index.href())
+})
+
+router.get(routes.app.dashboard, {
+  middleware: [requireAuth()],
+  handler(context) {
+    let auth = context.get(Auth) as GoodAuth<{ id: string; email: string }>
+
+    return Response.json({
+      id: auth.identity.id,
+      email: auth.identity.email,
+      method: auth.method,
+    })
+  },
+})
+```
+
+## External Auth
+
+Starting from the same `session()`, `auth()`, and `createSessionAuthScheme()` setup as the credentials example above, you can add a Google login flow like this. The provider is created once at module scope, and the routes compose `startExternalAuth()`, `finishExternalAuth()`, and `completeAuth()` directly.
+
+```ts
+import { auth, Auth, createSessionAuthScheme, requireAuth } from 'remix/middleware/auth'
+import {
+  completeAuth,
+  createGoogleAuthProvider,
+  finishExternalAuth,
+  refreshExternalAuth,
+  startExternalAuth,
+} from 'remix/auth'
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/router'
+import { route } from 'remix/routes'
+import type { GoodAuth } from 'remix/middleware/auth'
+import { redirect } from 'remix/response/redirect'
+import { session } from 'remix/middleware/session'
+import { createCookieSessionStorage } from 'remix/session-storage/cookie'
+
+let sessionCookie = createCookie('__session', {
+  secrets: [env.SESSION_SECRET],
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',
+  path: '/',
+})
+
+let sessionStorage = createCookieSessionStorage()
+
+let routes = route({
+  auth: {
+    session: {
+      login: '/login',
+    },
+    google: {
+      login: '/login/google',
+      callback: '/auth/google/callback',
+    },
+  },
+  app: {
+    dashboard: '/dashboard',
+  },
+})
+
+let googleProvider = createGoogleAuthProvider({
+  clientId: env.GOOGLE_CLIENT_ID,
+  clientSecret: env.GOOGLE_CLIENT_SECRET,
+  redirectUri: new URL(routes.auth.google.callback.href(), env.APP_ORIGIN),
+  authorizationParams: {
+    access_type: 'offline',
+    prompt: 'consent',
+  },
+})
+
+let router = createRouter({
+  middleware: [
+    session(sessionCookie, sessionStorage),
+    auth({
+      schemes: [
+        createSessionAuthScheme({
+          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.auth.session.login, () => {
+  return new Response(`<a href="${routes.auth.google.login.href()}">Login with Google</a>`, {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+    },
+  })
+})
+
+router.get(routes.auth.google.login, (context) =>
+  startExternalAuth(googleProvider, context, {
+    returnTo: context.url.searchParams.get('returnTo'),
+  }),
+)
+
+router.get(routes.auth.google.callback, async (context) => {
+  let { result, returnTo } = await finishExternalAuth(googleProvider, context)
+
+  let user = await users.upsertFromGoogle(result.profile)
+  await persistProviderTokens(user.id, result.tokens)
+
+  let session = completeAuth(context)
+  session.set('auth', { userId: user.id })
+
+  return redirect(returnTo ?? routes.app.dashboard.href())
+})
+
+async function getGoogleAccessToken(userId: string) {
+  let tokens = await readStoredProviderTokens(userId)
+  if (tokens == null) {
+    return null
+  }
+
+  if (tokens.expiresAt != null && tokens.expiresAt.getTime() <= Date.now()) {
+    tokens = (await refreshExternalAuth(googleProvider, tokens)).tokens
+    await persistProviderTokens(userId, tokens)
+  }
+
+  return tokens.accessToken
+}
+
+router.get(routes.app.dashboard, {
+  middleware: [requireAuth()],
+  handler(context) {
+    let auth = context.get(Auth) as GoodAuth<{ id: string; email: string | null }>
+
+    return Response.json({
+      id: auth.identity.id,
+      email: auth.identity.email,
+      method: auth.method,
+    })
+  },
+})
+```
+
+A typical external auth flow looks like this:
+
+1. Create the provider once at module scope. For Atmosphere, call `provider.prepare(handleOrDid)` only when starting the login flow.
+2. Call `startExternalAuth()` from the login route.
+3. Call `finishExternalAuth()` from the callback route.
+4. Persist any provider tokens you want to reuse later.
+5. Call `completeAuth(context)` and write your auth record into the returned session.
+6. On a later follow-up request, load the stored provider tokens, refresh them with `refreshExternalAuth()` only if needed, then save the refreshed bundle back to storage.
+7. Return your own redirect or other response.
+
+## Built-in External Auth Providers
+
+When one of the built-in providers matches your auth provider, start there. Google, Microsoft, Okta, and Auth0 use the shared OIDC runtime. GitHub, Facebook, X, and Atmosphere use built-in custom OAuth flows.
+
+```ts
+import {
+  createAuth0AuthProvider,
+  createAtmosphereAuthProvider,
+  createFacebookAuthProvider,
+  createGitHubAuthProvider,
+  createGoogleAuthProvider,
+  createMicrosoftAuthProvider,
+  createOktaAuthProvider,
+  createXAuthProvider,
+} from 'remix/auth'
+
+let auth0Provider = createAuth0AuthProvider({
+  domain: env.AUTH0_DOMAIN,
+  clientId: env.AUTH0_CLIENT_ID,
+  clientSecret: env.AUTH0_CLIENT_SECRET,
+  redirectUri: new URL('/auth/auth0/callback', env.APP_ORIGIN),
+})
+
+let atmosphereProvider = createAtmosphereAuthProvider({
+  clientId: new URL('/oauth/client-metadata.json', env.APP_ORIGIN),
+  redirectUri: new URL('/auth/atmosphere/callback', env.APP_ORIGIN),
+  sessionSecret: env.SESSION_SECRET,
+})
+
+let facebookProvider = createFacebookAuthProvider({
+  clientId: env.FACEBOOK_CLIENT_ID,
+  clientSecret: env.FACEBOOK_CLIENT_SECRET,
+  redirectUri: new URL('/auth/facebook/callback', env.APP_ORIGIN),
+})
+
+let githubProvider = createGitHubAuthProvider({
+  clientId: env.GITHUB_CLIENT_ID,
+  clientSecret: env.GITHUB_CLIENT_SECRET,
+  redirectUri: new URL('/auth/github/callback', env.APP_ORIGIN),
+})
+
+let googleProvider = createGoogleAuthProvider({
+  clientId: env.GOOGLE_CLIENT_ID,
+  clientSecret: env.GOOGLE_CLIENT_SECRET,
+  redirectUri: new URL('/auth/google/callback', env.APP_ORIGIN),
+})
+
+let microsoftProvider = createMicrosoftAuthProvider({
+  tenant: 'organizations',
+  clientId: env.MICROSOFT_CLIENT_ID,
+  clientSecret: env.MICROSOFT_CLIENT_SECRET,
+  redirectUri: new URL('/auth/microsoft/callback', env.APP_ORIGIN),
+})
+
+let oktaProvider = createOktaAuthProvider({
+  issuer: env.OKTA_ISSUER,
+  clientId: env.OKTA_CLIENT_ID,
+  clientSecret: env.OKTA_CLIENT_SECRET,
+  redirectUri: new URL('/auth/okta/callback', env.APP_ORIGIN),
+})
+
+let xProvider = createXAuthProvider({
+  clientId: env.X_CLIENT_ID,
+  clientSecret: env.X_CLIENT_SECRET,
+  redirectUri: new URL('/auth/x/callback', env.APP_ORIGIN),
+})
+```
+
+Notes:
+
+- OIDC providers use discovery by default at `/.well-known/openid-configuration`
+- Pass `metadata` when you want to skip discovery or `discoveryUrl` when the metadata document lives elsewhere
+- Default OIDC scopes are `openid profile email`
+- `createGoogleAuthProvider()` uses the same OIDC runtime with Google's published endpoints wired in directly, so it does not need a discovery request
+- `createMicrosoftAuthProvider()` adds the `tenant` option and builds the issuer from it
+- `createOktaAuthProvider()` expects the full Okta issuer URL, usually something like `https://example.okta.com/oauth2/default`
+- `createAuth0AuthProvider()` expects your Auth0 domain and derives the issuer URL for you
+- `createAtmosphereAuthProvider()` returns a module-scope provider with `prepare(handleOrDid)` for request-time atproto account discovery before `startExternalAuth()`
+- Atmosphere callback routes pass the module-scope provider directly to `finishExternalAuth()`; the original handle or DID is stored in the sealed OAuth transaction state
+- `createAtmosphereAuthProvider()` requires `sessionSecret` and seals the in-flight account, authorization server, nonce, and DPoP key state into the existing OAuth transaction stored in your app session, so you do not need a separate file or database store for the redirect step
+- `createAtmosphereAuthProvider()` returns DPoP-bound token material in `result.tokens`, including `accessToken`, `refreshToken`, authorization server refresh details, and `dpop` JWK state for follow-up DPoP-signed requests
+- `refreshExternalAuth()` supports built-in OIDC providers, X, and Atmosphere when the stored token bundle includes a refresh token
+- Providers only return refresh tokens when configured to request offline access, such as `authorizationParams: { access_type: 'offline' }` for Google or adding `offline.access` to X scopes
+- Use `mapProfile()` with `createOIDCAuthProvider()` when you want `result.profile` to have an app-specific type before it reaches your route code
+
+Default scopes for OAuth providers that don't use OIDC discovery:
+
+- GitHub: `read:user user:email`
+- Facebook: `public_profile email`
+- X: `tweet.read users.read`
+
+Pass `scopes` if you need a different set for a provider.
+
+## Custom Auth Providers
+
+Use `createOIDCAuthProvider()` directly for custom external auth providers. This is the extension point for providers that support OpenID Connect discovery, authorization code flow, and a userinfo endpoint. Reach for a custom OAuth provider implementation only when the provider does not support OIDC.
+
+```ts
+import {
+  completeAuth,
+  createOIDCAuthProvider,
+  finishExternalAuth,
+  startExternalAuth,
+} from 'remix/auth'
+import { redirect } from 'remix/response/redirect'
+
+let companyProvider = createOIDCAuthProvider({
+  name: 'company',
+  issuer: 'https://sso.acme.com',
+  clientId: 'acme-web',
+  clientSecret: 'acme-web-secret',
+  redirectUri: new URL('/auth/company/callback', 'https://app.acme.com'),
+  authorizationParams: {
+    prompt: 'login',
+  },
+  mapProfile({ claims }) {
+    return {
+      id: claims.sub,
+      email: claims.email ?? null,
+      name: claims.name ?? claims.preferred_username ?? 'Unknown user',
+    }
+  },
+})
+
+router.get('/login/company', (context) =>
+  startExternalAuth(companyProvider, context, {
+    returnTo: context.url.searchParams.get('returnTo'),
+  }),
+)
+
+router.get('/auth/company/callback', async (context) => {
+  let { result, returnTo } = await finishExternalAuth(companyProvider, context)
+
+  let user = await users.upsertFromCompanySSO(result.profile)
+  let session = completeAuth(context)
+  session.set('auth', { userId: user.id })
+
+  return redirect(returnTo ?? '/dashboard')
+})
+```
+
+## Related Packages
+
+- [`auth-middleware`](https://github.com/remix-run/remix/tree/main/packages/auth-middleware) - Request authentication and route protection helpers
+- [`form-data-middleware`](https://github.com/remix-run/remix/tree/main/packages/form-data-middleware) - Form body parsing for `createCredentialsAuthProvider()` routes
+- [`session-middleware`](https://github.com/remix-run/remix/tree/main/packages/session-middleware) - Request-scoped session loading and persistence
+- [`session`](https://github.com/remix-run/remix/tree/main/packages/session) - Session data model and storage backends
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router and middleware runtime
+
+## Related Work
+
+- [OAuth 2.0](https://oauth.net/2/)
+- [RFC 7636: PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
+- [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)
+- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

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)