Update to Netlify

SKILL.md line diff

--- before
+++ after
@@ -1,47 +1,66 @@
 ---
 name: netlify-identity
-description: Use when the task involves authentication, user signups, logins, password recovery, OAuth providers, role-based access control, or protecting routes and functions. Always use `@netlify/identity`. Never use `netlify-identity-widget` or `gotrue-js` — they are deprecated.
+description: Add user authentication to a Netlify site with @netlify/identity — signup/login/logout, Google/GitHub/GitLab/Bitbucket OAuth, server-side getUser() checks, role-based access control, and Identity event functions. Use it when a task involves adding a login or signup form, gating content to members or roles, "auth middleware" or verifying users in Netlify Functions or Edge Functions, handling OAuth or email-confirmation callbacks, assigning roles at signup, or customizing Identity emails. For locking a whole site to your company or employees-only access, use netlify-access-control instead.
 ---
 
 # Netlify Identity
 
-Netlify Identity is a user management service for signups, logins, password recovery, user metadata, and role-based access control. It is built on [GoTrue](https://github.com/netlify/gotrue) and issues JSON Web Tokens (JWTs).
-
-**Always use `@netlify/identity`.** Never use `netlify-identity-widget` or `gotrue-js` — they are deprecated. `@netlify/identity` provides a unified, headless TypeScript API that works in both browser and server contexts (Netlify Functions, Edge Functions, SSR frameworks).
-
-## Setup
+Use `@netlify/identity` (npm). For new projects it replaces the legacy `netlify-identity-widget` and `gotrue-js` — do not reach for those.
 
 ```bash
 npm install @netlify/identity
 ```
 
-Identity is automatically enabled when a deploy created by a Netlify Agent Runner session includes Identity code. Otherwise, it must be manually enabled in the UI. These are the default settings:
+Framework examples (Next.js/Astro/Remix/SvelteKit) and the full API reference are in the [`@netlify/identity` README on npm](https://www.npmjs.com/package/@netlify/identity).
 
-- **Registration** — Open (anyone can sign up). Change to Invite only in **Project configuration > Identity** if needed.
-- **Autoconfirm** — Off (new signups require email confirmation). Enable in **Project configuration > Identity** to skip confirmation during development.
+> **Identity does not run under `netlify dev`.** Test all auth flows on a deploy — Deploy Previews work. Local dev will not complete signup/login/OAuth.
 
-### Local Development
+> **Identity config is dashboard-only — there is no public API.** Never curl `api.netlify.com` to flip or read Identity settings, never read tokens from local Netlify config, never probe undocumented endpoints. Enable and configure Identity at `https://app.netlify.com/projects/{site_name}/identity`.
 
-Identity does **not** currently work with `netlify dev`. You must deploy to Netlify to test Identity features. Use `npx netlify deploy` for preview deploys during development. This limitation may be resolved in a future release.
+> **Never build a from-scratch OAuth flow alongside Identity.** No provider app registration in code, no `client_id`/`secret` in source, no custom callback token exchange. Use `oauthLogin()` + `handleAuthCallback()`. Raw OAuth beside Identity is the most common source of rework.
 
-## Quick Start
+## Client auth (browser)
 
-Log in from the browser:
+```ts
+import { signup, login, logout, getUser, oauthLogin, handleAuthCallback } from '@netlify/identity'
 
-```typescript
-import { login, getUser } from '@netlify/identity'
+// Register — confirmation email sent by default (unless autoconfirm is on)
+const user = await signup('jane@example.com', 'securepassword', { full_name: 'Jane Doe' })
+
+// Log in / out
+await login('jane@example.com', 'securepassword')
+await logout()
 
-const user = await login('user@example.com', '<password>')
-console.log(`Hello, ${user.name}`)
+// Current user or null
+const current = await getUser()
+if (current) console.log(`Logged in as ${current.email}`)
 
-// Later, check auth state
-const currentUser = await getUser()
+// External provider — redirects the browser; provider is one of
+// 'google' | 'github' | 'gitlab' | 'bitbucket'
+oauthLogin('github')
 ```
 
-Protect a Netlify Function:
+> **`handleAuthCallback()` is mandatory on your landing page.** Without it, OAuth redirects, email-confirmation links, password-recovery links, and invite links never complete. Call it on page load:
 
-```typescript
-// netlify/functions/protected.mts
+```ts
+import { handleAuthCallback } from '@netlify/identity'
+
+const result = await handleAuthCallback() // falsy if no token in URL hash
+if (result) console.log(result.type, result.user.email) // confirmation | invite | recovery | email change
+```
+
+Alternatives for a single token type: `recoverPassword()` (recovery), `acceptInvite()` (invite). Refresh a session with `refreshSession()`.
+
+Don't hard-code which providers exist. Call `getSettings()` at startup and render the signup form and OAuth buttons from what it returns.
+
+## Server-side auth (Netlify Functions & Edge Functions)
+
+Server-side `getUser()`/`login()`/`admin.*` require modern **v2 functions** (`export default`). The v1 `export { handler }` form is not supported.
+
+`getUser()` works in both runtimes. **`admin.*` runs ONLY in Netlify Functions — not the browser, not Edge Functions.**
+
+```ts
+// netlify/functions/me.ts — verify user
 import { getUser } from '@netlify/identity'
 import type { Context } from '@netlify/functions'
 
@@ -52,284 +71,197 @@
 }
 ```
 
-## Core API
-
-Import and use headless functions directly:
+Edge Function form is identical but imports `Context` from `@netlify/edge-functions`.
 
-```typescript
-import {
-  getUser,
-  handleAuthCallback,
-  login,
-  logout,
-  signup,
-  oauthLogin,
-  onAuthChange,
-  getSettings,
-} from '@netlify/identity'
-```
+### Role checks
 
-### Login
-
-```typescript
-import { login, AuthError } from '@netlify/identity'
+```ts
+// netlify/functions/admin-users.ts
+import { getUser, admin } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
 
-async function handleLogin(email: string, password: string) {
-  try {
-    const user = await login(email, password)
-    showSuccess(`Welcome back, ${user.name ?? user.email}`)
-  } catch (error) {
-    if (error instanceof AuthError) {
-      showError(error.status === 401 ? 'Invalid email or password.' : error.message)
-    }
-  }
+export default async (req: Request, context: Context) => {
+  const user = await getUser()
+  if (!user) return new Response('Unauthorized', { status: 401 })
+  if (!user.roles.includes('admin')) return new Response('Forbidden', { status: 403 })
+  const users = await admin.listUsers()
+  return Response.json({ users })
 }
 ```
 
-### Signup
+### CSRF: required for server-side auth endpoints
 
-After signup, check `user.emailVerified` to determine if the user was auto-confirmed or needs to confirm their email.
+> Any endpoint that runs `login()`, `signup()`, or `logout()` server-side **must** call `verifyRequestOrigin(req)` at the top of the handler. It throws a 403 on origin mismatch.
 
-```typescript
-import { signup, AuthError } from '@netlify/identity'
+```ts
+// netlify/functions/login.ts
+import { login, verifyRequestOrigin } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
 
-async function handleSignup(email: string, password: string, name: string) {
-  try {
-    const user = await signup(email, password, { full_name: name })
-    if (user.emailVerified) {
-      // Autoconfirm ON — user is logged in immediately
-      showSuccess('Account created. You are now logged in.')
-    } else {
-      // Autoconfirm OFF — confirmation email sent
-      showSuccess('Check your email to confirm your account.')
-    }
-  } catch (error) {
-    if (error instanceof AuthError) {
-      showError(error.status === 403 ? 'Signups are not allowed.' : error.message)
-    }
-  }
+export default async (req: Request, context: Context) => {
+  verifyRequestOrigin(req)
+  const { email, password } = await req.json()
+  await login(email, password)
+  return new Response(null, { status: 302, headers: { Location: '/dashboard' } })
 }
 ```
 
-### Logout
+## Identity event functions
 
-```typescript
-import { logout } from '@netlify/identity'
+The platform calls your handler when an Identity event occurs. Export a default object with a method per event. File: `netlify/functions/identity.mts`.
 
-await logout()
-```
+> Typed handlers (`UserSignupEvent`, `event.deny()`) require `@netlify/functions` ≥ 5.2.0. Older installs must use the legacy filename convention (`identity-signup.ts`, etc.) — see `references/authorization-and-sessions.md`.
 
-### OAuth
+| Handler | Fires when |
+|---|---|
+| `userValidate` | Signup attempt, before account creation. Block bad signups here. |
+| `userSignup` | Signup completes (after email confirmation if enabled). Assign roles, sync, welcome. |
+| `userLogin` | User logs in. Track/last-seen/block. |
+| `userModified` | Profile updated. |
+| `userDeleted` | User deleted (notification only). |
 
-OAuth is a two-step flow: `oauthLogin(provider)` redirects away from the site, then `handleAuthCallback()` processes the redirect when the user returns.
+Event `user` fields are camelCase (`appMetadata`, `userMetadata`, `confirmedAt`).
 
 ```typescript
-import { oauthLogin } from '@netlify/identity'
+// netlify/functions/identity.mts — deny a signup
+import type { UserValidateEvent } from "@netlify/functions"
 
-// Step 1: Redirect to provider (navigates away — never returns)
-function handleOAuthClick(provider: 'google' | 'github' | 'gitlab' | 'bitbucket') {
-  oauthLogin(provider)
+export default {
+  userValidate(event: UserValidateEvent) {
+    if (!event.user.email?.endsWith("@example.com")) return event.deny()
+  },
 }
 ```
 
-Enable providers in **Project configuration > Identity > External providers** before using OAuth.
-
-### Handling Callbacks
-
-Always call `handleAuthCallback()` on page load in any app that uses OAuth, password recovery, invites, or email confirmation. It processes all callback types via the URL hash.
-
 ```typescript
-import { handleAuthCallback, AuthError } from '@netlify/identity'
+// netlify/functions/identity.mts — assign roles at signup
+import type { UserSignupEvent } from "@netlify/functions"
 
-async function processCallback() {
-  try {
-    const result = await handleAuthCallback()
-    if (!result) return // No callback hash — normal page load
-
-    switch (result.type) {
-      case 'oauth':
-        showSuccess(`Logged in as ${result.user?.email}`)
-        break
-      case 'confirmation':
-        showSuccess('Email confirmed. You are now logged in.')
-        break
-      case 'recovery':
-        // User is authenticated but must set a new password
-        showPasswordResetForm(result.user)
-        break
-      case 'invite':
-        // User must set a password to accept the invite
-        showInviteAcceptForm(result.token)
-        break
-      case 'email_change':
-        showSuccess('Email address updated.')
-        break
-    }
-  } catch (error) {
-    if (error instanceof AuthError) showError(error.message)
-  }
+export default {
+  userSignup(event: UserSignupEvent) {
+    return { user: { ...event.user, appMetadata: { ...event.user.appMetadata, roles: ["member"] } } }
+  },
 }
 ```
 
-### Auth State
-
-```typescript
-import { getUser, onAuthChange, AUTH_EVENTS } from '@netlify/identity'
+- `event.deny()` — rejects the action; end user gets `401`, no observability error. First handler to call it aborts the chain; later subscribers are not invoked. (Legacy filename functions signal denial with a non-2xx `Response` instead.)
+- Return `{ user: {...} }` to modify the record before persistence (canonical way to set roles at signup). Roles ride in the JWT, so a role change takes effect on the user's **next login or token refresh, not immediately** — see Roles & the JWT below.
+- Background mode: `export const config: Config = { background: true }` — action completes immediately, handler runs async.
 
-// Check current user (never throws — returns null if not authenticated)
-const user = await getUser()
+## Roles & the JWT
 
-// Subscribe to auth state changes (returns unsubscribe function)
-const unsubscribe = onAuthChange((event, user) => {
-  switch (event) {
-    case AUTH_EVENTS.LOGIN:
-      console.log('Logged in:', user?.email)
-      break
-    case AUTH_EVENTS.LOGOUT:
-      console.log('Logged out')
-      break
-    case AUTH_EVENTS.TOKEN_REFRESH:
-      break
-    case AUTH_EVENTS.USER_UPDATED:
-      console.log('Profile updated:', user?.email)
-      break
-    case AUTH_EVENTS.RECOVERY:
-      console.log('Password recovery initiated')
-      break
-  }
-})
-```
+- `user.roles` is read from `app_metadata.roles`, carried in the JWT (cookie `nf_jwt`; refresh via `nf_refresh`).
+- `user_metadata` — user-editable profile (`full_name`, `email`). `app_metadata` — app data incl. `roles`, not user-editable.
 
-### Settings-Driven UI
+> **Role changes are NOT immediate.** They take effect on next login or token refresh. Changing roles does not invalidate the current JWT. Force it with `refreshSession()`.
 
-Fetch the project's Identity settings to conditionally render signup forms and OAuth buttons.
+Set roles for existing users via `admin.updateUser()` in a Netlify Function; at signup via the `userSignup` event handler above.
 
-```typescript
-import { getSettings } from '@netlify/identity'
+Deep guides for SSR/session hydration and authorization live in `references/advanced-patterns.md` and `references/authorization-and-sessions.md`.
 
-const settings = await getSettings()
-// settings.autoconfirm — boolean
-// settings.disableSignup — boolean
-// settings.providers — Record<AuthProvider, boolean>
+## CDN-edge RBAC (redirect rules)
 
-if (!settings.disableSignup) showSignupForm()
+Enforced at the edge with no origin round trip. A mismatched role gets a 404 unless you add a fallback — **always pair a role-gated rule with a fallback.**
 
-for (const [provider, enabled] of Object.entries(settings.providers)) {
-  if (enabled) showOAuthButton(provider)
-}
+`_redirects`:
+```
+/admin/*  /admin/:splat  200!  Role=admin
+/admin/*  /login         401!
+# Multiple roles chained with commas:
+/private/* /private/:splat 200! Role=editor,admin
 ```
 
-## Minimal React Example
-
-```tsx
-import { useEffect, useState } from 'react'
-import {
-  getUser,
-  handleAuthCallback,
-  login,
-  logout,
-  oauthLogin,
-  onAuthChange,
-} from '@netlify/identity'
-
-function App() {
-  const [user, setUser] = useState(null)
-  const [loading, setLoading] = useState(true)
-
-  useEffect(() => {
-    ;(async () => {
-      await handleAuthCallback()
-      setUser(await getUser())
-      setLoading(false)
-    })()
-    return onAuthChange((_event, currentUser) => setUser(currentUser))
-  }, [])
-
-  const handleLogin = async (email, password) => {
-    const currentUser = await login(email, password)
-    setUser(currentUser)
-  }
-
-  const handleGoogleLogin = () => oauthLogin('google')
-
-  const handleSignOut = async () => {
-    await logout()
-    setUser(null)
-  }
-
-  if (loading) return <p>Loading...</p>
-  // Render login form or user details based on `user` state
-}
+`netlify.toml`:
+```toml
+[[redirects]]
+  from = "/admin/*"
+  to = "/admin/:splat"
+  force = true
+  status = 200
+  conditions = {Role = ["editor", "admin"]}
 ```
 
-## Error Handling
+Use redirect rules for path-based gating; use function-based `user.roles` checks for custom authorization logic.
 
-`@netlify/identity` throws two error classes:
+## Configuration (dashboard-only)
 
-- **`AuthError`** — Thrown by auth operations. Has `message`, optional `status` (HTTP status code), and optional `cause`.
-- **`MissingIdentityError`** — Thrown when Identity is not configured in the current environment.
+Base: `https://app.netlify.com/projects/{site_name}/identity`. Enable with **Enable Identity**. Identity requires HTTPS — set up SSL before integrating on a custom domain.
 
-`getUser()` and `isAuthenticated()` never throw — they return `null` and `false` respectively on failure.
+- **Registration** (`?tab=registration#registration-preferences`): **Open** (default, anyone can sign up) or **Invite only** (all users, including external-provider logins, must be invited first).
+- **Confirmation / autoconfirm** (`?tab=emails#confirmation-template`): check the box to skip email verification.
+- **External providers** (`?tab=registration#external-providers`): Google/GitHub/GitLab/Bitbucket. For branded OAuth (your app name instead of "Netlify Identity"), register your app with the provider, get client ID + secret, and enter them **in the Netlify settings UI** — not in code.
+- **Invitations** (`?tab=users`): enter addresses to send invites; link carries `invite_token`.
+- **Password recovery**: user page → **Send reset password email**; link carries `recovery_token`.
 
-| Status | Meaning |
-|--------|---------|
-| 401 | Invalid credentials or expired token |
-| 403 | Action not allowed (e.g., signups disabled) |
-| 422 | Validation error (e.g., weak password, malformed email) |
-| 404 | User or resource not found |
+### Emails (Pro plans or higher)
 
-## Identity Event Functions
+Default sender is `no-reply@netlify.com`. Custom SMTP sender and custom templates both require **Pro plans or higher**.
 
-Special serverless functions that trigger on Identity lifecycle events. These use the **legacy named `handler` export** (not the modern default export).
+Template variables (Go syntax): `{{ .Email }}`, `{{ .NewEmail }}` (email-change only), `{{ .SiteURL }}`, `{{ .ConfirmationURL }}`, `{{ .Token }}`.
 
-**Event names:** `identity-validate`, `identity-signup`, `identity-login`
+Custom-link hash fragments per action:
+```
+{{ .SiteURL }}/path/#invite_token={{ .Token }}
+{{ .SiteURL }}/path/#confirmation_token={{ .Token }}
+{{ .SiteURL }}/path/#recovery_token={{ .Token }}
+{{ .SiteURL }}/path/#email_change_token={{ .Token }}
+```
 
-```typescript
-// netlify/functions/identity-signup.mts
-import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
+Custom template constraints: inline CSS only; absolute image links; **no `<html>`/`<head>`/`<body>` tags**; ensure your build doesn't alter Go template variables.
 
-const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
-  const { user } = JSON.parse(event.body || '{}')
+### Audit log (Pro plans or higher)
 
-  return {
-    statusCode: 200,
-    body: JSON.stringify({
-      app_metadata: {
-        ...user.app_metadata,
-        roles: ['member'],
-      },
-    }),
-  }
-}
+`?tab=audit-log`. Search with a scoped term: `author:[string]` or `action:[string]`. Action names: `login`, `logout`, `user_signedup`, `user_deleted`, `user_modified`, `token_revoked`, `token_refreshed`, `user_recovery_requested`, `user_invited`.
 
-export { handler }
-```
+## External JWT providers (Enterprise)
 
-The response body replaces `app_metadata` and/or `user_metadata` on the user record — include all fields you want to keep.
+Available on **Enterprise plans**. You may use Netlify Identity OR an external JWT provider — **not both at once**; you cannot authenticate third-party JWTs while Netlify Identity is enabled.
 
-## Roles and Authorization
+- Roles path: Netlify Identity `app_metadata.roles`; external provider `app_metadata.authorization.roles`. Custom path → contact support.
+- JWT header must be `{"alg": "HS256", "typ": "JWT"}` (HS256 required). Payload `exp` is required and must be a future Unix Epoch time.
+- Set the JWT secret at `Project configuration > General > Visitor access > JWT secret`. Project-level overrides team-level defaults.
 
-- **`app_metadata.roles`** — Server-controlled. Only settable via the Netlify UI, admin API, or Identity event functions. Never let users set their own roles.
-- **`user_metadata`** — User-controlled. Users can update via `updateUser({ data: { ... } })`.
+## On failure — stop, don't guess
 
-### Role-Based Redirects
+If callbacks 404, `/.netlify/identity/*` is unreachable, or an OAuth flow never returns: surface the error, the dashboard URL (`https://app.netlify.com/projects/{site_name}/identity`), and the setting to check (registration preference, external provider config, confirmation/autoconfirm). Then stop. Do not invent recovery commands. Remember: Identity does not work under `netlify dev` — confirm you are testing on a deploy.
 
-```toml
-# netlify.toml
-[[redirects]]
-  from = "/admin/*"
-  to = "/admin/:splat"
-  status = 200
-  conditions = { Role = ["admin"] }
+Site-gating requests ("lock this site to my company", employees-only) route to the netlify-access-control skill first — Identity is the app-level user layer only.
 
-[[redirects]]
-  from = "/admin/*"
-  to = "/"
-  status = 302
-```
+<!-- gap: getSettings() is referenced by house rules for provider discovery but its signature/return shape is not documented in the intermediate. -->
 
-Rules are evaluated top-to-bottom. The `nf_jwt` cookie is read by the CDN to evaluate role conditions.
+<!-- system: agent-context/identity/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
+# Netlify house rules (identity)
 
-## Bundled References (Load As Needed)
+These are org conventions, not docs facts — merged into the rendered skill by
+ctx-gen and never generated. Owned by the skills maintainer.
 
-- [Advanced patterns](references/advanced-patterns.md) — password recovery, invite acceptance, email change, session hydration, SSR integration
+1. Deep guides live in this skill: `references/advanced-patterns.md`
+   (SSR/session hydration) and `references/authorization-and-sessions.md`.
+2. Identity does not work under `netlify dev` — test auth flows on deploys
+   (Deploy Previews work).
+3. Identity configuration has no public API — it is dashboard-only. Never curl
+   `api.netlify.com` to flip or inspect Identity settings, never read auth
+   tokens from `~/Library/Preferences/netlify/config.json`, never probe for
+   undocumented endpoints.
+4. On failure (callback 404s, `/.netlify/identity/*` unreachable, OAuth flow
+   doesn't return), surface the error, the dashboard URL, and the setting to
+   check — then stop. Do not invent recovery commands.
+5. Never build a from-scratch third-party OAuth flow when Identity is in play —
+   no provider app registration, no `client_id`/`secret` in code, no custom
+   callback token exchange. Use `oauthLogin()` + `handleAuthCallback()`;
+   raw OAuth beside Identity is the single most common source of rework.
+6. Server-side `getUser()`/`login()`/`admin.*` require modern v2 functions
+   (`export default`) — v1 `export { handler }` is not supported. Typed
+   Identity event handlers (`UserSignupEvent`, `event.deny()`) require
+   `@netlify/functions` ≥ 5.2.0; older installs use the legacy filenames.
+7. Don't hard-code which auth providers exist — call `getSettings()` at
+   startup and render the signup form and OAuth buttons from what it returns.
+8. Site-gating requests ("lock this site to my company", employees-only)
+   route to the netlify-access-control skill first — Identity is the
+   app-level user layer only.
+9. Any answer that assigns or changes roles — at signup, via `admin.*`, or in
+   the dashboard — must say the change takes effect on the user's next login
+   or token refresh, not immediately. Keep that sentence next to the code that
+   sets the role, not only in a separate JWT section: an agent answering a
+   signup question reads the signup example and stops, and it has shipped
+   answers that omit the delay.