@remix-run/cli 0.1.0 → 0.2.0

package/bootstrap/.agents/skills/remix/references/auth-and-sessions.md

@@ -0,0 +1,420 @@
+# Authentication and Sessions
+
+## What This Covers
+
+How to remember things about a browser between requests and how to identify a user. Read this when
+the task involves:
+
+- Storing per-browser state across requests (login, cart, "I have submitted this form")
+- Adding a credentials login flow or an OAuth provider
+- Protecting routes with `requireAuth()` or stacking authorization checks
+- Reading or writing `Session`, `Auth`, or other identity-related context values
+- Logging in, logging out, or rotating session IDs
+
+For raw cookies that are not session-backed (theme, locale, dismissed-banner), see
+`createCookie` in this file plus the broader `Package Map` in `SKILL.md`.
+
+## Sessions vs Plain Cookies
+
+Reach for `remix/session` when state is sensitive, must be tamper-resistant, or represents the
+identity of a request: who is logged in, which form a browser already submitted, what items are in
+a cart. Sessions sign or encrypt their backing cookie with a server-held secret and give you a
+typed `Session` object you can `get`, `set`, `flash`, `unset`, and `regenerateId`.
+
+Reach for `remix/cookie` directly when the browser is allowed to carry the value and the server
+does not need session semantics. This often means preferences (theme, locale, dismissed banner),
+but a signed cookie can also be fine for small low-risk values where you truly only need one
+cookie-shaped fact and do not need `Session` helpers.
+
+If a malicious user editing the value would be a bug, or if the value needs server-managed
+lifecycle, reach for a session.
+
+### Quick chooser
+
+| Need                                                                | Best fit        | Why                                                |
+| ------------------------------------------------------------------- | --------------- | -------------------------------------------------- |
+| Theme, locale, dismissed banner                                     | `remix/cookie`  | Browser-controlled preference                      |
+| Small signed hint with minimal lifecycle                            | `remix/cookie`  | One value, no `Session` helpers needed             |
+| "This browser already submitted", cart, flash messages, login state | `remix/session` | Tamper-sensitive, server-managed per-browser state |
+| "One real person only", ownership, durable identity                 | account/auth    | Cookies or sessions alone do not prove personhood  |
+
+## Session Setup
+
+### Create a session cookie
+
+```typescript
+import { createCookie } from 'remix/cookie'
+
+let sessionSecret = process.env.SESSION_SECRET
+if (!sessionSecret && process.env.NODE_ENV !== 'test') {
+  throw new Error('SESSION_SECRET is required')
+}
+
+export let sessionCookie = createCookie('session', {
+  secrets: [sessionSecret ?? 'test-only-secret'],
+  httpOnly: true,
+  sameSite: 'Lax',
+  secure: process.env.NODE_ENV === 'production',
+  maxAge: 2592000, // 30 days
+  path: '/',
+})
+```
+
+The cookie should always be `httpOnly`, default to `sameSite: 'Lax'`, and be `secure` in
+production. Demo defaults like `'s3cr3t'` are fine in tests but should never reach production —
+fail fast when the secret is missing.
+
+### Create session storage
+
+```typescript
+// Filesystem storage
+import { createFsSessionStorage } from 'remix/session/fs-storage'
+export let sessionStorage = createFsSessionStorage('./tmp/sessions')
+
+// Memory storage (for tests)
+import { createMemorySessionStorage } from 'remix/session/memory-storage'
+export let sessionStorage = createMemorySessionStorage()
+```
+
+### Add session middleware
+
+```typescript
+import { session } from 'remix/session-middleware'
+
+let router = createRouter({
+  middleware: [
+    session(sessionCookie, sessionStorage),
+    // ... other middleware
+  ],
+})
+```
+
+### Using sessions in handlers
+
+```typescript
+import { Session } from 'remix/session'
+
+async function handler({ get }) {
+  let session = get(Session)
+
+  // Read
+  let userId = session.get('userId')
+
+  // Write
+  session.set('userId', 42)
+
+  // Flash (read once, then cleared)
+  session.flash('message', 'Settings saved!')
+  let message = session.get('message') // returns and clears
+
+  // Remove a key
+  session.unset('userId')
+
+  // Regenerate session ID (after login/logout)
+  session.regenerateId(true)
+}
+```
+
+### Sessions for non-auth state
+
+Sessions are not just for login. They are the right place to store any tamper-sensitive
+per-browser fact: which form a browser already submitted, how many free actions are left in a
+trial, which feature flags a tester opted into, what items are in a cart.
+
+```typescript
+async function submit({ get }) {
+  let session = get(Session)
+  if (session.get('hasSubmitted')) {
+    return render(<AlreadySubmittedPage />, { status: 409 })
+  }
+
+  let parsed = s.parseSafe(submitSchema, get(FormData))
+  if (!parsed.success) {
+    return render(<SubmitPage errors={parsed.issues} />, { status: 400 })
+  }
+
+  await saveSubmission(parsed.value)
+  session.set('hasSubmitted', true)
+  session.flash('message', 'Thanks for submitting!')
+
+  return redirect(routes.thanks.href())
+}
+```
+
+Notice that there is no manual `Set-Cookie` plumbing in the action — the session middleware handles
+that, and the handler returns an ordinary `Response`. Per-browser state enforced this way is still
+bypassable by clearing cookies; if the guarantee needs to survive that, you also need an account
+(see auth providers below).
+
+## Auth Middleware
+
+### Basic setup
+
+```typescript
+import { auth, createSessionAuthScheme } from 'remix/auth-middleware'
+import { Session } from 'remix/session'
+import { Database } from 'remix/data-table'
+
+export function loadAuth() {
+  return auth({
+    schemes: [
+      createSessionAuthScheme({
+        read(session) {
+          let data = session.get('auth')
+          return data ?? null
+        },
+        async verify(value, context) {
+          let db = context.get(Database)
+          return (await db.find(users, value.userId)) ?? null
+        },
+        invalidate(session) {
+          session.unset('auth')
+        },
+      }),
+    ],
+  })
+}
+```
+
+### Reading auth state
+
+```typescript
+import { Auth } from 'remix/auth-middleware'
+
+function handler({ get }) {
+  let auth = get(Auth)
+
+  if (auth.ok) {
+    // User is authenticated
+    let user = auth.identity
+  }
+}
+```
+
+## Credentials Auth
+
+### Define a credentials provider
+
+```typescript
+import { createCredentialsAuthProvider, verifyCredentials, completeAuth } from 'remix/auth'
+import * as s from 'remix/data-schema'
+import * as f from 'remix/data-schema/form-data'
+
+let loginSchema = f.object({
+  email: f.field(s.defaulted(s.string(), '')),
+  password: f.field(s.defaulted(s.string(), '')),
+})
+
+export let passwordProvider = createCredentialsAuthProvider({
+  parse(context) {
+    let formData = context.get(FormData)
+    return s.parse(loginSchema, formData)
+  },
+  async verify({ email, password }, context) {
+    let db = context.get(Database)
+    let user = await db.findOne(users, { where: { email } })
+    if (!user || !(await verifyPassword(password, user.password_hash))) {
+      return null
+    }
+    return user
+  },
+})
+```
+
+### Login action
+
+```typescript
+import { verifyCredentials, completeAuth } from 'remix/auth'
+import { redirect } from 'remix/response/redirect'
+
+async action(context) {
+  let user = await verifyCredentials(passwordProvider, context)
+
+  if (user == null) {
+    let session = context.get(Session)
+    session.flash('error', 'Invalid email or password.')
+    return redirect(routes.auth.login.href())
+  }
+
+  let session = completeAuth(context)
+  session.set('auth', { userId: user.id })
+
+  return redirect(routes.home.href())
+},
+```
+
+### Logout action
+
+```typescript
+import { Session } from 'remix/session'
+import { redirect } from 'remix/response/redirect'
+
+function logout(context) {
+  let session = context.get(Session)
+  session.unset('auth')
+  session.regenerateId(true)
+  return redirect(routes.home.href())
+}
+```
+
+## OAuth / External Auth
+
+### Create providers
+
+```typescript
+import {
+  createAtmosphereAuthProvider,
+  createGoogleAuthProvider,
+  createGitHubAuthProvider,
+  startExternalAuth,
+  finishExternalAuth,
+  completeAuth,
+  refreshExternalAuth,
+} from 'remix/auth'
+
+let googleProvider = createGoogleAuthProvider({
+  clientId: process.env.GOOGLE_CLIENT_ID,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+  redirectUri: new URL(routes.auth.google.callback.href(), origin),
+})
+
+let githubProvider = createGitHubAuthProvider({
+  clientId: process.env.GITHUB_CLIENT_ID,
+  clientSecret: process.env.GITHUB_CLIENT_SECRET,
+  redirectUri: new URL(routes.auth.github.callback.href(), origin),
+})
+
+let atmosphereSessionSecret = process.env.ATMOSPHERE_SESSION_SECRET
+if (!atmosphereSessionSecret && process.env.NODE_ENV !== 'test') {
+  throw new Error('ATMOSPHERE_SESSION_SECRET is required')
+}
+
+let atmosphereProvider = createAtmosphereAuthProvider({
+  clientId: 'https://app.example.com/oauth/client-metadata.json',
+  redirectUri: new URL(routes.auth.atmosphere.callback.href(), origin),
+  sessionSecret: atmosphereSessionSecret ?? 'test-only-secret',
+})
+```
+
+For Atmosphere-compatible atproto OAuth, create the provider once, call
+`atmosphereProvider.prepare(handleOrDid)` before `startExternalAuth(...)`, then pass the same
+module-scope provider to `finishExternalAuth(...)` and `refreshExternalAuth(...)`.
+
+### OAuth controller
+
+```typescript
+export default {
+  actions: {
+    // GET /auth/google — redirect to Google
+    async index(context) {
+      return await startExternalAuth(googleProvider, context, {
+        returnTo: context.url.searchParams.get('returnTo'),
+      })
+    },
+
+    // GET /auth/google/callback — handle redirect back
+    async callback(context) {
+      let { result, returnTo } = await finishExternalAuth(googleProvider, context)
+
+      let db = context.get(Database)
+      let { user, authAccount } = await resolveExternalAuth(db, result)
+
+      let session = completeAuth(context)
+      session.set('auth', {
+        userId: user.id,
+        loginMethod: result.provider,
+        authAccountId: authAccount.id,
+      })
+
+      return redirect(returnTo ?? routes.account.href())
+    },
+  },
+} satisfies Controller<typeof routes.auth.google>
+```
+
+### Refresh stored provider tokens
+
+Use `refreshExternalAuth(provider, tokens)` when an app has stored OAuth/OIDC tokens and needs a
+fresh access token from a refresh token. Built-in OIDC providers, X, and Atmosphere support
+refresh-token exchange. If the provider does not rotate the refresh token, the refreshed bundle
+preserves the current one.
+
+```typescript
+async function refreshGoogleTokens({ get }) {
+  let db = get(Database)
+  let account = await db.findOne(authAccounts, { where: { provider: 'google' } })
+  if (!account) return null
+
+  let refreshed = await refreshExternalAuth(googleProvider, account.tokens)
+  await db.update(authAccounts, account.id, { tokens: refreshed.tokens })
+
+  return refreshed.tokens
+}
+```
+
+## Protecting Routes
+
+### Controller-level protection
+
+Apply `requireAuth()` to an entire controller subtree:
+
+```typescript
+import { requireAuth } from 'remix/auth-middleware'
+
+export default {
+  middleware: [requireAuth()],
+  actions: {
+    index() {
+      /* guaranteed authenticated */
+    },
+    settings: settingsController,
+  },
+} satisfies Controller<typeof routes.account>
+```
+
+### Stacking middleware
+
+Combine auth checks with role checks:
+
+```typescript
+export default {
+  middleware: [requireAuth(), requireAdmin()],
+  actions: {
+    index() {
+      /* requires auth + admin */
+    },
+  },
+} satisfies Controller<typeof routes.admin>
+```
+
+### Action-level protection
+
+Apply middleware to a single route:
+
+```typescript
+import { Auth, requireAuth } from 'remix/auth-middleware'
+
+router.get(routes.account, {
+  middleware: [requireAuth()],
+  handler(context) {
+    let auth = context.get(Auth)
+    return render(<AccountPage identity={auth.identity} />)
+  },
+})
+```
+
+### Redirect on auth failure
+
+```typescript
+import { requireAuth } from 'remix/auth-middleware'
+import { redirect } from 'remix/response/redirect'
+
+export function requireAuthRedirect() {
+  return requireAuth({
+    onFailure(context) {
+      let returnTo = encodeURIComponent(context.url.pathname)
+      return redirect(routes.auth.login.href() + `?returnTo=${returnTo}`, 303)
+    },
+  })
+}
+```

package/bootstrap/.agents/skills/remix/references/component-model.md

@@ -0,0 +1,282 @@
+# Component Model
+
+## What This Covers
+
+How a Remix Component is shaped and how its state, lifecycle, and updates behave. Read this when
+the task involves:
+
+- Writing a component (`handle` plus render function)
+- Managing component-local state, derived values, or post-render DOM work
+- Using `handle.props`, `handle.update()`, `handle.queueTask()`, `handle.signal`, `handle.id`, or
+  `handle.context`
+- Listening to global events with cleanup tied to the component lifecycle
+
+For host-element behavior (event handlers, styles, refs, animations), see
+`mixins-styling-events.md`. For browser hydration, frames, and navigation, see
+`hydration-frames-navigation.md`.
+
+## Phases
+
+A component has two phases:
+
+1. **Setup phase** — runs once when the component is created
+2. **Render phase** — returned function runs on initial render and every update
+
+```tsx
+import { on, type Handle } from 'remix/ui'
+
+function Counter(handle: Handle<{ initialCount?: number; label: string }>) {
+  let count = handle.props.initialCount ?? 0
+
+  return () => (
+    <button
+      mix={on('click', () => {
+        count++
+        handle.update()
+      })}
+    >
+      {handle.props.label}: {count}
+    </button>
+  )
+}
+```
+
+## Props
+
+Components receive all JSX props through `handle.props`. The object identity is stable for the
+component lifetime, and its values are updated before each render. Put initialization inputs on
+normal JSX props and read them from `handle.props`:
+
+```tsx
+function Timer(handle: Handle<{ initialSeconds: number; paused?: boolean }>) {
+  let seconds = handle.props.initialSeconds
+
+  return () => <div>Time remaining: {seconds}s</div>
+}
+
+// Usage: <Timer initialSeconds={60} paused={false} />
+```
+
+Because `handle.props` is stable, destructuring `let { props } = handle` is safe when helpers need
+to read current values later. Destructuring individual prop values is only a snapshot; prefer
+`handle.props.name` inside callbacks and render output when values can change.
+
+## State Rules
+
+- Keep state in setup scope as plain JavaScript variables.
+- Store only what affects rendering. Derive computed values in render.
+- Do not mirror input state unless you truly need controlled behavior.
+- Do work in event handlers, not in render. Use the handler scope for transient state.
+
+```tsx
+// Derive computed values in render
+function TodoList(handle: Handle) {
+  let todos: Array<{ text: string; completed: boolean }> = []
+
+  return () => {
+    let completedCount = todos.filter((t) => t.completed).length
+    return <div>Completed: {completedCount}</div>
+  }
+}
+```
+
+## Handle API
+
+### `handle.update()`
+
+Schedules a rerender. Returns a promise that resolves with an `AbortSignal` after the update
+completes. Await it when you need the updated DOM before follow-up work:
+
+```tsx
+on('click', async () => {
+  isPlaying = true
+  let signal = await handle.update()
+  // DOM is now updated, safe to focus or measure
+  stopButton.focus()
+})
+```
+
+### `handle.queueTask(task)`
+
+Schedules a task to run after the next update. The task receives an `AbortSignal` that aborts when
+the component re-renders or is removed. Use for post-render DOM work, reactive data loading, or
+hydration-sensitive setup:
+
+```tsx
+let data = null
+let requestedUrl: string | null = null
+
+// Post-render DOM work in an event handler
+on('click', () => {
+  showDetails = true
+  handle.update()
+  handle.queueTask(() => {
+    detailsSection.scrollIntoView({ behavior: 'smooth' })
+  })
+})
+
+// Reactive data loading keyed by props.url
+return () => {
+  if (requestedUrl !== handle.props.url) {
+    let nextUrl = handle.props.url
+    requestedUrl = nextUrl
+    data = null
+
+    handle.queueTask(async (signal) => {
+      let response = await fetch(nextUrl, { signal })
+      let json = await response.json()
+      if (signal.aborted || requestedUrl !== nextUrl) return
+      data = json
+      handle.update()
+    })
+  }
+
+  return <div>{data ?? 'Loading...'}</div>
+}
+```
+
+Avoid creating intermediate state just to trigger `queueTask`. Do the work directly in the handler
+or the queued task.
+
+### `handle.signal`
+
+An `AbortSignal` aborted when the component disconnects. Use for cleanup:
+
+```tsx
+function Clock(handle: Handle) {
+  let interval = setInterval(handle.update, 1000)
+  handle.signal.addEventListener('abort', () => clearInterval(interval))
+
+  return () => <span>{new Date().toString()}</span>
+}
+```
+
+### `handle.id`
+
+Stable identifier per component instance. Useful for `htmlFor`, `aria-owns`, etc.:
+
+```tsx
+function LabeledInput(handle: Handle) {
+  return () => (
+    <div>
+      <label htmlFor={handle.id}>Name</label>
+      <input id={handle.id} type="text" />
+    </div>
+  )
+}
+```
+
+### `handle.frame` and `handle.frames`
+
+Frame-aware behavior for client entries rendered inside frames:
+
+- `handle.frame.reload()` — reload the containing frame
+- `handle.frame.src` — the URL of the containing frame
+- `handle.frames.top` — the root frame (the whole page)
+- `handle.frames.top.reload()` — reload the entire page/frame tree
+- `handle.frames.get(name)` — look up a named frame; returns `FrameHandle | undefined`
+
+```tsx
+function RefreshButton(handle: Handle) {
+  return () => <button mix={on('click', () => handle.frame.reload())}>Refresh</button>
+}
+```
+
+### `handle.context`
+
+Context for ancestor/descendant communication. See the context section below.
+
+## Context
+
+Use `handle.context.set()` to provide values and `handle.context.get(Provider)` to consume them.
+`set()` does **not** trigger updates — call `handle.update()` if the tree needs to rerender.
+
+```tsx
+function ThemeProvider(handle: Handle<{ children?: RemixNode }, { theme: 'light' | 'dark' }>) {
+  let theme: 'light' | 'dark' = 'light'
+  handle.context.set({ theme })
+
+  return () => (
+    <div>
+      <button
+        mix={on('click', () => {
+          theme = theme === 'light' ? 'dark' : 'light'
+          handle.context.set({ theme })
+          handle.update()
+        })}
+      >
+        Toggle
+      </button>
+      {handle.props.children}
+    </div>
+  )
+}
+
+function ThemedContent(handle: Handle) {
+  let { theme } = handle.context.get(ThemeProvider)
+  return () => <div>Current theme: {theme}</div>
+}
+```
+
+For granular updates without re-rendering the full subtree, use `TypedEventTarget`:
+
+```tsx
+import { TypedEventTarget, addEventListeners } from 'remix/ui'
+
+class Theme extends TypedEventTarget<{ change: Event }> {
+  #value: 'light' | 'dark' = 'light'
+  get value() {
+    return this.#value
+  }
+  setValue(value: 'light' | 'dark') {
+    this.#value = value
+    this.dispatchEvent(new Event('change'))
+  }
+}
+
+function ThemeProvider(handle: Handle<{ children?: RemixNode }, Theme>) {
+  let theme = new Theme()
+  handle.context.set(theme)
+
+  return () => (
+    <div>
+      <button mix={on('click', () => theme.setValue(theme.value === 'light' ? 'dark' : 'light'))}>
+        Toggle
+      </button>
+      {handle.props.children}
+    </div>
+  )
+}
+
+function ThemedContent(handle: Handle) {
+  let theme = handle.context.get(ThemeProvider)
+  addEventListeners(theme, handle.signal, {
+    change() {
+      handle.update()
+    },
+  })
+  return () => <div>Theme: {theme.value}</div>
+}
+```
+
+## Global Events
+
+Use `addEventListeners(target, handle.signal, listeners)` to listen to global targets with
+automatic cleanup when the component disconnects:
+
+```tsx
+import { addEventListeners, type Handle } from 'remix/ui'
+
+function ResizeTracker(handle: Handle) {
+  let width = window.innerWidth
+
+  addEventListeners(window, handle.signal, {
+    resize() {
+      width = window.innerWidth
+      handle.update()
+    },
+  })
+
+  return () => <div>{width}</div>
+}
+```