@netlify/agent-runner-cli 2.16.0-server.2 → 2.16.0

package/dist/skills/netlify-identity/SKILL.md

@@ -1,682 +1,360 @@
 ---
 name: netlify-identity
-description: Use whenever the task involves authentication, signups, logins, password recovery, user accounts, role-based access control, OAuth providers, protected routes, protecting Netlify Functions, server-side auth in SSR frameworks, or Netlify Identity. Always use `@netlify/identity`. Never use `netlify-identity-widget` or `gotrue-js` as they are deprecated. Make sure to always run `node scripts/enable.cjs` located in this skill's directory after implementing Netlify Identity.
+description: Add user authentication to a Netlify site with @netlify/identity, covering 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, accepting user invites, assigning roles at signup, customizing Identity emails, or finding out why a specific user can't sign up or log in. 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).
-
-## Enable Feature
-
-After implementing Netlify Identity, you **must** run the enable script to activate the feature on the deploy. The script
-is located in this skill's `scripts/` directory:
-
-```bash
-node scripts/enable.cjs
-```
-
-**NEVER use `netlify-identity-widget` or `gotrue-js`. Always use `@netlify/identity`.** It provides a unified, headless
-TypeScript API that works in both browser and server contexts (Netlify Functions, Edge Functions, SSR frameworks). It
-replaces all previous Identity client libraries.
-
-## 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 enabled on the site when you run the enable script above. Default settings:
-
-- **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.
-
-For local development, use `netlify dev` so the Identity endpoint is available.
+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).
 
-## Quick Start
+> **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.
 
-Log in from the browser:
-
-```typescript
-import { login, getUser } from '@netlify/identity'
+> **Identity config is dashboard-only. There is no public API for Identity settings.** Never curl `api.netlify.com` to flip or read Identity settings, never read tokens from local Netlify config, and never probe undocumented endpoints. The one exception is reading the site's `identity_instance_id` and a single user's account with the lookup described under Additional requirements. Configure Identity at `https://app.netlify.com/projects/{site_name}/identity`. Enable it using this skill's `scripts/enable.cjs`, as described under Additional requirements.
 
-const user = await login('jane@example.com', 'password123')
-console.log(`Hello, ${user.name}`)
-
-// Later, check auth state
-const currentUser = await getUser()
-```
-
-Protect a Netlify Function:
-
-```typescript
-// netlify/functions/protected.mts
-import { getUser } from '@netlify/identity'
-import type { Context } from '@netlify/functions'
-
-export default async (req: Request, context: Context) => {
-  const user = await getUser()
-  if (!user) return new Response('Unauthorized', { status: 401 })
-  return Response.json({ id: user.id, email: user.email })
-}
-```
+> **Never build a from-scratch OAuth flow alongside Identity.** No provider app registration in code, no `client_id`/`secret` in source, and no custom callback token exchange. Use `oauthLogin()` + `handleAuthCallback()`. Raw OAuth beside Identity is the most common source of rework.
 
-## Error Handling
+## Client auth (browser)
 
-`@netlify/identity` throws two error classes:
+```ts
+import { signup, login, logout, getUser, oauthLogin, handleAuthCallback } from '@netlify/identity'
 
-- **`AuthError`** - Thrown by auth operations (login, signup, logout, etc.). Has `message`, optional `status` (HTTP
-  status code from GoTrue), and optional `cause` (original error).
-- **`MissingIdentityError`** - Thrown when Identity is not configured in the current environment (site doesn't have
-  Identity enabled, or not running via `netlify dev`).
+// Register — confirmation email sent by default (unless autoconfirm is on)
+const user = await signup('jane@example.com', 'securepassword', { full_name: 'Jane Doe' })
 
-`getUser()` and `isAuthenticated()` never throw - they return `null` and `false` respectively on failure.
+// Log in / out
+await login('jane@example.com', 'securepassword')
+await logout()
 
-### Try/Catch Pattern
+// Current user or null
+const current = await getUser()
+if (current) console.log(`Logged in as ${current.email}`)
 
-```typescript
-import { login, AuthError, MissingIdentityError } from '@netlify/identity'
-
-try {
-  const user = await login(email, password)
-} catch (error) {
-  if (error instanceof MissingIdentityError) {
-    // Identity not configured - show setup instructions
-    showError('Identity is not enabled on this site.')
-    return
-  }
-  if (error instanceof AuthError) {
-    switch (error.status) {
-      case 401:
-        showError('Invalid email or password.')
-        break
-      case 403:
-        showError('Signups are not allowed for this site.')
-        break
-      case 422:
-        showError('Invalid input. Check your email and password.')
-        break
-      case 404:
-        showError('User not found.')
-        break
-      default:
-        showError(error.message)
-    }
-    return
-  }
-  throw error
-}
+// External provider — redirects the browser; provider is one of
+// 'google' | 'github' | 'gitlab' | 'bitbucket'
+oauthLogin('github')
 ```
 
-### Common Status Codes
+> **`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.
 
-| 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 |
+> **Invites are NOT logged in by `handleAuthCallback()`.** For an invite it returns `type === 'invite'` with the token in `result.token` and `result.user === null`. The account does not exist yet. You must collect a password and call `acceptInvite(result.token, password)`. If you skip this step, invited users never get an account.
 
-## Authentication Flows
+```ts
+import { handleAuthCallback, acceptInvite } from '@netlify/identity'
 
-### Login
-
-```typescript
-import { login, AuthError } from '@netlify/identity'
-
-let loading = false
-
-async function handleLogin(email: string, password: string) {
-  loading = true
-  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)
-    }
-  } finally {
-    loading = false
-  }
+const result = await handleAuthCallback() // falsy if no token in URL hash
+if (result?.type === 'invite' && result.token) {
+  // Invited user has no account yet. Ask them to choose a password first.
+  const password = (document.getElementById('password') as HTMLInputElement).value
+  const user = await acceptInvite(result.token, password)
+  console.log('Account created:', user.email)
+} else if (result) {
+  // OAuth, email confirmation, recovery, or email change
+  console.log(result.type, result.user?.email)
 }
 ```
 
-### Signup
+For recovery tokens you can call `recoverPassword()` directly instead. Refresh a session with `refreshSession()`.
 
-After signup, check `user.emailVerified` to determine if the user was auto-confirmed (logged in immediately) or needs
-to confirm their email first.
+Don't hard-code which providers exist. Call `getSettings()` at startup and render the signup form and OAuth buttons from what it returns.
 
-```typescript
-import { signup, AuthError } from '@netlify/identity'
-
-async function handleSignup(email: string, password: string, name: string) {
-  try {
-    const user = await signup(email, password, { full_name: name })
-    if (user.emailVerified) {
-      // Autoconfirm is ON - user is logged in
-      showSuccess('Account created. You are now logged in.')
-    } else {
-      // Autoconfirm is OFF - confirmation email sent, user is NOT logged in
-      showSuccess('Check your email to confirm your account.')
-    }
-  } catch (error) {
-    if (error instanceof AuthError) {
-      showError(error.status === 403 ? 'Signups are not allowed.' : error.message)
-    }
-  }
-}
-```
+## Server-side auth (Netlify Functions & Edge Functions)
 
-When autoconfirm is off, the confirmation email contains a link that redirects the user back to the site with
-`#confirmation_token=<token>` in the URL hash. `handleAuthCallback()` processes this automatically - it calls
-`confirmEmail()` under the hood, logs the user in, and returns `{ type: 'confirmation', user }`. This is why
-`handleAuthCallback()` must be called on page load (see the OAuth section below for the full switch).
+Server-side `getUser()`/`login()`/`admin.*` require modern **v2 functions** (`export default`). The v1 `export { handler }` form is not supported.
 
-### OAuth
-
-OAuth is a two-step flow: `oauthLogin(provider)` redirects away from the site, then `handleAuthCallback()` processes
-the redirect when the user returns.
-
-```typescript
-import { oauthLogin } from '@netlify/identity'
-
-// Step 1: Redirect to OAuth provider (this navigates away - never returns)
-function handleOAuthClick(provider: 'google' | 'github' | 'gitlab' | 'bitbucket') {
-  oauthLogin(provider)
-}
-```
-
-```typescript
-import { handleAuthCallback, AuthError } from '@netlify/identity'
-
-// Step 2: Process the redirect on page load
-async function processCallback() {
-  try {
-    const result = await handleAuthCallback()
-    if (!result) return // No callback hash present - 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)
-    }
-  }
-}
-```
+`getUser()` works in both runtimes. **`admin.*` runs ONLY in Netlify Functions. It does not run in the browser or in Edge Functions.**
 
-Always call `handleAuthCallback()` on page load in any app that uses OAuth, password recovery, invites, or email
-confirmation. It handles all callback types via the URL hash.
-
-### Password Recovery
-
-Three-step flow: request recovery email, handle the callback, then set a new password.
-
-```typescript
-import { requestPasswordRecovery, handleAuthCallback, updateUser, AuthError } from '@netlify/identity'
-
-// Step 1: Send recovery email
-async function handleForgotPassword(email: string) {
-  try {
-    await requestPasswordRecovery(email)
-    showSuccess('Check your email for a password reset link.')
-  } catch (error) {
-    if (error instanceof AuthError) showError(error.message)
-  }
-}
-
-// Step 2: handleAuthCallback() returns { type: 'recovery', user } - show password reset form
-// (See the handleAuthCallback switch above)
-
-// Step 3: Set new password
-async function handlePasswordReset(newPassword: string) {
-  try {
-    await updateUser({ password: newPassword })
-    showSuccess('Password updated.')
-  } catch (error) {
-    if (error instanceof AuthError) showError(error.message)
-  }
-}
-```
-
-Note: The recovery callback fires a `'recovery'` auth event, not `'login'`. The user is authenticated but should be
-prompted to set a new password before navigating away.
-
-### Invite Acceptance
-
-When a user clicks an invite link, `handleAuthCallback()` returns `{ type: 'invite', user: null, token }`. Use the
-token to accept the invite and set a password.
-
-```typescript
-import { acceptInvite, AuthError } from '@netlify/identity'
-
-async function handleAcceptInvite(token: string, password: string) {
-  try {
-    const user = await acceptInvite(token, password)
-    showSuccess(`Welcome, ${user.email}! Your account is ready.`)
-  } catch (error) {
-    if (error instanceof AuthError) showError(error.message)
-  }
-}
-```
-
-### Email Change
-
-When a user verifies an email change, `handleAuthCallback()` returns `{ type: 'email_change', user }`. This requires an
-active browser session - the user must be logged in when clicking the verification link.
-
-```typescript
-import { verifyEmailChange, AuthError } from '@netlify/identity'
-
-// If you need to verify programmatically with a token:
-async function handleEmailChangeVerification(token: string) {
-  try {
-    const user = await verifyEmailChange(token)
-    showSuccess(`Email updated to ${user.email}`)
-  } catch (error) {
-    if (error instanceof AuthError) showError(error.message)
-  }
-}
-```
-
-### Session Hydration
-
-`hydrateSession()` bridges server-set cookies to the browser session. Call it on page load when using server-side login
-(e.g., login inside a Netlify Function followed by a redirect).
-
-```typescript
-import { hydrateSession } from '@netlify/identity'
+```ts
+// netlify/functions/me.ts — verify user
+import { getUser } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
 
-// On page load
-const user = await hydrateSession()
-if (user) {
-  // Browser session is now in sync with server-set cookies
+export default async (req: Request, context: Context) => {
+  const user = await getUser()
+  if (!user) return new Response('Unauthorized', { status: 401 })
+  return Response.json({ id: user.id, email: user.email })
 }
 ```
 
-Note: `getUser()` auto-hydrates from the `nf_jwt` cookie if no browser session exists, so explicit `hydrateSession()`
-is only needed when you want to restore the full session (including token refresh timers) after a server-side login.
-
-## Auth Events
-
-Subscribe to auth state changes with `onAuthChange`. Returns an unsubscribe function. No-op on server.
-
-```typescript
-import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'
-
-const unsubscribe = onAuthChange((event, user) => {
-  switch (event) {
-    case AUTH_EVENTS.LOGIN:
-      console.log('User logged in:', user?.email)
-      break
-    case AUTH_EVENTS.LOGOUT:
-      console.log('User logged out')
-      break
-    case AUTH_EVENTS.TOKEN_REFRESH:
-      // Token auto-refreshed in background
-      break
-    case AUTH_EVENTS.USER_UPDATED:
-      console.log('User profile updated:', user?.email)
-      break
-    case AUTH_EVENTS.RECOVERY:
-      // Recovery token processed - prompt for new password
-      console.log('Password recovery initiated')
-      break
-  }
-})
-
-// Later: unsubscribe()
-```
-
-Auth events are automatically detected across browser tabs via the storage event listener - no extra setup needed.
-
-## Settings-Driven UI
-
-Fetch the project's Identity settings to conditionally render signup forms and OAuth buttons.
-
-```typescript
-import { getSettings } from '@netlify/identity'
+The Edge Function form is identical but imports `Context` from `@netlify/edge-functions`.
 
-const settings = await getSettings()
-// settings.autoconfirm - boolean, whether email confirmation is skipped
-// settings.disableSignup - boolean, whether registration is closed
-// settings.providers - Record<AuthProvider, boolean>, e.g. { google: true, github: true, ... }
+### Role checks
 
-// Conditionally render signup
-if (!settings.disableSignup) {
-  showSignupForm()
-}
+```ts
+// netlify/functions/admin-users.ts
+import { getUser, admin } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
 
-// Conditionally render OAuth buttons
-for (const [provider, enabled] of Object.entries(settings.providers)) {
-  if (enabled) {
-    showOAuthButton(provider)
-  }
+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 })
 }
 ```
 
-## Full API Reference
-
-For the complete API reference - all function signatures, type definitions, OAuth helpers, admin operations, session
-management, auth events, and framework-specific integration examples - read the package README:
-
-```
-node_modules/@netlify/identity/README.md
-```
-
-The README is shipped with the npm package and is always in sync with the installed version.
-
-## SSR Integration Patterns
+### CSRF: required for server-side auth endpoints
 
-For SSR frameworks, the recommended pattern is:
+> 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.
 
-- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
-- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
-
-Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The
-server reads the cookie on the next request.
-
-The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these
-require the Netlify Functions runtime to set cookies. After a server-side mutation, use a full page navigation so the
-browser sends the new cookie.
-
-Always use `window.location.href` (not framework router navigation) after server-side auth mutations in Next.js,
-TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions return real HTTP responses.
-
-## Netlify SSO Users (`context.user`)
-
-Netlify Identity is for your site's own end users. Separately, on private projects and sites protected by Netlify team
-login, Netlify Functions, Edge Functions, and Netlify Server code can read the Netlify team member who signed in through
-Netlify's SSO from the request context as `context.user` (`id`, `email`, `expiresAt`). Netlify verifies the visitor at
-the edge and sets it itself, so it can't be spoofed with request headers.
-
-Use `context.user` instead of Netlify Identity when the only people who should reach the site are members of the
-Netlify team (internal dashboards, audit logs, approval workflows): there is no signup, login UI, or `@netlify/identity`
-setup to build, and you don't run the enable script for it. Use `getUser()` from `@netlify/identity` when the site has
-its own user accounts.
-
-```typescript
-// netlify/functions/whoami.mts
+```ts
+// netlify/functions/login.ts
+import { login, verifyRequestOrigin } from '@netlify/identity'
 import type { Context } from '@netlify/functions'
 
 export default async (req: Request, context: Context) => {
-  if (!context.user) return new Response('Unauthorized', { status: 401 })
-  return Response.json({ id: context.user.id, email: context.user.email })
+  verifyRequestOrigin(req)
+  const { email, password } = await req.json()
+  await login(email, password)
+  return new Response(null, { status: 302, headers: { Location: '/dashboard' } })
 }
 ```
 
-See the [changelog post](https://www.netlify.com/changelog/2026-10-07-context-user-in-functions/), and the
-**netlify-functions**, **netlify-edge-functions**, and **netlify-server** skills for runtime-specific details.
+## Identity event functions
 
-## Identity Event Functions
+The platform calls your handler when an Identity event occurs. Export a default object with a method per event. File: `netlify/functions/identity.mts`.
 
-Subscribe to Identity lifecycle events by exporting an object whose properties are named event handlers. See the
-**netlify-functions** skill for the full event-handler pattern.
+> 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`.
 
-**Available identity handlers:**
-
-| Handler | Trigger |
+| Handler | Fires when |
 |---|---|
-| `userValidate` | A user attempts to sign up. Can deny the signup. |
-| `userSignup` | A user completes signup. Can deny or mutate. |
-| `userLogin` | A user logs in. Can deny or mutate. |
-| `userModified` | A user's profile is updated. Can deny or mutate. |
-| `userDeleted` | A user is deleted. Notification only. |
-
-Each handler receives a typed event with a parsed `user` object (camelCase fields: `appMetadata`, `userMetadata`,
-`confirmedAt`, etc.).
+| `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). |
 
-### Example: Assign Default Role on Signup
-
-Return `{ user: ... }` to substitute the user record before it's persisted.
+Event `user` fields are camelCase (`appMetadata`, `userMetadata`, `confirmedAt`).
 
 ```typescript
-// netlify/functions/identity.mts
-import type { UserSignupEvent } from '@netlify/functions'
+// netlify/functions/identity.mts — deny a signup
+import type { UserValidateEvent } from "@netlify/functions"
 
 export default {
-  userSignup(event: UserSignupEvent) {
-    return {
-      user: {
-        ...event.user,
-        appMetadata: {
-          ...event.user.appMetadata,
-          roles: ['member'],
-        },
-      },
-    }
+  userValidate(event: UserValidateEvent) {
+    if (!event.user.email?.endsWith("@example.com")) return event.deny()
   },
 }
 ```
 
-### Deny an Action
-
-Call `event.deny()` to reject a signup, login, validation, or modification. The end user receives a 401. Do NOT throw —
-`event.deny()` is the canonical denial mechanism and does not produce an error in observability.
-
 ```typescript
-import type { UserValidateEvent } from '@netlify/functions'
+// netlify/functions/identity.mts — assign roles at signup
+import type { UserSignupEvent } from "@netlify/functions"
 
 export default {
-  userValidate(event: UserValidateEvent) {
-    if (!event.user.email?.endsWith('@example.com')) {
-      return event.deny()
-    }
+  userSignup(event: UserSignupEvent) {
+    return { user: { ...event.user, appMetadata: { ...event.user.appMetadata, roles: ["member"] } } }
   },
 }
 ```
 
-If multiple functions subscribe to the same event, the first to call `event.deny()` aborts the chain.
-
-For bulk user management or role changes outside lifecycle events, use the `admin` API instead of Identity event functions.
-
-**Legacy filename convention:** The previous syntax — files named `identity-validate.ts`, `identity-signup.ts`, or
-`identity-login.ts` (with a `-background` suffix for background mode), exporting `handler` and signaling denial via a
-non-2xx response — still works. New functions should prefer the typed handler syntax above.
-
-## Roles and Authorization
+- `event.deny()` rejects the action. The end user gets a `401`, and no error appears in observability. The first handler to call it aborts the chain, and later subscribers are not invoked. Legacy filename functions signal denial with a non-2xx `Response` instead.
+- Return `{ user: {...} }` to modify the record before it is persisted. This is the 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 }`. The action completes immediately and the handler runs asynchronously.
 
-### First Admin User
+## Roles & the JWT
 
-The first admin user cannot be created through code alone. You must direct the user to set it up through the Netlify UI:
+- `user.roles` is read from `app_metadata.roles` and carried in the JWT (cookie `nf_jwt`; refresh via `nf_refresh`).
+- `user_metadata` holds the user-editable profile (`full_name`, `email`). `app_metadata` holds app data, including `roles`, and is not user-editable.
 
-1. Go to **Identity** in the project sidebar in the Netlify dashboard
-2. Click **Invite users** and enter the admin user's email address
-3. After the user accepts the invite, click the user in the Identity list to open their detail page
-4. In the **Roles** field, add the `admin` role and save
+> **Role changes are NOT immediate.** They take effect on next login or token refresh. Changing roles does not invalidate the current JWT. Force a refresh with `refreshSession()`.
 
-Once the first admin exists, subsequent users can be managed programmatically using Identity event functions (e.g., assigning roles in the `userSignup` handler) or role-based redirects.
+Set roles for existing users via `admin.updateUser()` in a Netlify Function. Set them at signup via the `userSignup` event handler above.
 
-### Metadata Types
+Deep guides for SSR/session hydration and authorization live in `references/advanced-patterns.md` and `references/authorization-and-sessions.md`.
 
-- **`app_metadata.roles`** - Server-controlled. Only settable via the Netlify UI, admin API, or Identity event functions.
-  Do not allow users to set their own roles.
-- **`user_metadata`** - User-controlled. Users can update this via `updateUser({ data: { ... } })`.
+## CDN-edge RBAC (redirect rules)
 
-### Role-Based Redirects
+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.**
 
-Use `netlify.toml` to restrict paths by role:
+`_redirects`:
+```
+/admin/*  /admin/:splat  200!  Role=admin
+/admin/*  /login         401!
+# Multiple roles chained with commas:
+/private/* /private/:splat 200! Role=editor,admin
+```
 
+`netlify.toml`:
 ```toml
 [[redirects]]
   from = "/admin/*"
   to = "/admin/:splat"
+  force = true
   status = 200
-  conditions = { Role = ["admin"] }
-
-[[redirects]]
-  from = "/admin/*"
-  to = "/"
-  status = 302
+  conditions = {Role = ["editor", "admin"]}
 ```
 
-Rules are evaluated top-to-bottom. The first redirect matches users with the `admin` role; everyone else falls through
-to the second rule and is redirected away.
+Use redirect rules for path-based gating. Use function-based `user.roles` checks for custom authorization logic.
 
-**How it works:** The `nf_jwt` cookie is read by the CDN to evaluate `conditions = { Role = [...] }`. Without this
-cookie, role-based redirects will not work.
+## Configuration (dashboard-only)
 
-## Common Errors & Solutions
+Base: `https://app.netlify.com/projects/{site_name}/identity`. Enable Identity using this skill's `scripts/enable.cjs`, as described under Additional requirements. Identity requires HTTPS, so set up SSL before integrating on a custom domain.
 
-### "Signups not allowed for this instance" (403)
+- **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 a client ID and secret, and enter them **in the Netlify settings UI**, not in code.
+- **Invitations** (`?tab=users`): enter addresses to send invites. The link carries `invite_token`. Complete it with `handleAuthCallback()` + `acceptInvite(token, password)` as shown above.
+- **Password recovery**: on the user page, use **Send reset password email**. The link carries `recovery_token`.
 
-**Cause:** Registration is set to Invite only.
+### Emails (Pro plans or higher)
 
-**Fix:**
+The default sender is `no-reply@netlify.com`. A custom SMTP sender and custom templates both require **Pro plans or higher**.
 
-1. Change to Open in **Project configuration > Identity**
-2. Or invite users from the Identity tab in the Netlify UI
+Template variables (Go syntax): `{{ .Email }}`, `{{ .NewEmail }}` (email-change only), `{{ .SiteURL }}`, `{{ .ConfirmationURL }}`, `{{ .Token }}`.
 
-```typescript
-if (error instanceof AuthError && error.status === 403) {
-  showError('Signups are disabled. Contact the site admin for an invite.')
-}
+Custom-link hash fragments per action:
 ```
-
-### Invalid credentials (401)
-
-**Cause:** Wrong email or password on login.
-
-**Fix:** Show a user-facing error and let the user retry. Do not reveal whether the email or password was wrong.
-
-```typescript
-if (error instanceof AuthError && error.status === 401) {
-  showError('Invalid email or password.')
-}
+{{ .SiteURL }}/path/#invite_token={{ .Token }}
+{{ .SiteURL }}/path/#confirmation_token={{ .Token }}
+{{ .SiteURL }}/path/#recovery_token={{ .Token }}
+{{ .SiteURL }}/path/#email_change_token={{ .Token }}
 ```
 
-### "Email not confirmed"
-
-**Cause:** User tries to log in before confirming their email (autoconfirm is off).
-
-**Fix:** Tell the user to check their inbox. Optionally provide a way to resend the confirmation email via `signup()`
-with the same credentials.
-
-### "Token expired" / 401 on API calls
+Custom template constraints:
+- Inline CSS only.
+- Absolute image links.
+- **No `<html>`/`<head>`/`<body>` tags.**
+- Ensure your build doesn't alter Go template variables.
+
+### Audit log (Pro plans or higher)
+
+`?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`.
+
+## External JWT providers (Enterprise)
+
+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 path: Netlify Identity uses `app_metadata.roles`; an external provider uses `app_metadata.authorization.roles`. For a custom path, contact support.
+- The JWT header must be `{"alg": "HS256", "typ": "JWT"}` (HS256 required). The 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 settings override team-level defaults.
+
+## On failure — stop, don't guess
+
+If callbacks 404, `/.netlify/identity/*` is unreachable, or an OAuth flow never returns:
+1. Surface the error.
+2. Give the dashboard URL (`https://app.netlify.com/projects/{site_name}/identity`).
+3. Name the setting to check (registration preference, external provider config, confirmation/autoconfirm).
+4. Then stop. Do not invent recovery commands.
+
+Remember: Identity does not work under `netlify dev`. Confirm you are testing on a deploy.
+
+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. Restricting who can view the whole project uses [project visibility](https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility) or [Password Protection](https://docs.netlify.com/manage/security/secure-access-to-sites/password-protection), not Identity.
+
+<!-- gap: getSettings() signature/return shape is not documented in the intermediate. -->
+<!-- gap: handleAuthCallback() result.type strings other than 'invite' are not enumerated. -->
+
+<!-- system: agent-context/identity/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
+# Netlify house rules (identity)
+
+These are org conventions, not docs facts — merged into the rendered skill by
+ctx-gen and never generated. Owned by the skills maintainer.
+
+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. The one exception is reading the site's
+   `identity_instance_id` and a single user's account with the lookup described
+   under Additional requirements.
+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.
+10. Before setting up Identity for an internal tool, ask who signs in. If
+    they can already pass the project's Netlify login (a private project or
+    team login protection), the app has a verified user without Identity:
+    read `context.user` in functions and edge functions and skip the second
+    login. Identity is for users outside that Netlify login. The two never
+    merge: `context.user` has no roles or `app_metadata`, and `getUser()`
+    never returns it.
+
+
+## Additional requirements
+
+After implementing Netlify Identity, you MUST run `scripts/enable.cjs` from this skill using Node. Use the absolute path
+to the script and keep the project's directory as your working directory:
 
-**Cause:** Stale access token.
-
-**Fix:**
-
-1. Always use `getUser()` before authenticated requests - it auto-hydrates from cookies
-2. In the browser, the library auto-refreshes tokens via `startTokenRefresh()`
-3. On the server, call `refreshSession()` in middleware to handle near-expiry tokens
-
-```typescript
-const newToken = await refreshSession()
-if (newToken) {
-  // Token was refreshed - retry the request
-}
+```bash
+node /absolute/path/to/netlify-identity/scripts/enable.cjs
 ```
 
-### Identity event function not triggering
-
-**Cause:** Export shape does not match the expected pattern.
-
-**Fix:**
-
-1. Use the typed handler syntax: default export an object with `userSignup`, `userLogin`, `userValidate`, `userModified`,
-   or `userDeleted` methods
-2. Place the function in `netlify/functions/` with `.mts` or `.mjs` extension
-3. If using the legacy filename convention, verify the filename matches the event exactly (`identity-signup.mts`,
-   `identity-validate.mts`, or `identity-login.mts`) and that the file exports a named `handler`
-
-### `MissingIdentityError`
+Replace the example path with the installed location of this skill. The script creates
+`.netlify/features/netlify-identity` in the project's repository. The deployment workflow uses that marker to request
+Identity enablement before deploying. Do not ask the user to enable Identity in the Netlify UI. Registration settings,
+external providers, and other Identity configuration can still be managed in the dashboard.
 
-**Cause:** Identity is not configured in the current environment.
+### Look up one user's account
 
-**Fix:**
+When the user reports that a specific person can't sign up or log in, read that person's Identity account with the
+Netlify API before guessing. You can look up one user by email or by ID. Listing users, searching, changing users, and
+the Identity audit log are not available to you; those calls return 401 or 404.
 
-1. Ensure Identity is enabled on the project
-2. Use `netlify dev` for local development so the Identity endpoint is available
+`$SITE_ID` is the project ID from your instructions. First read the project's Identity instance ID from the
+`identity_instance_id` field of the site object into `IDENTITY_ID`. If it prints `null`, Identity is not enabled on the
+project; stop here.
 
-```typescript
-if (error instanceof MissingIdentityError) {
-  showError('Identity is not enabled. Run "netlify dev" or enable Identity in project settings.')
-}
+```bash
+IDENTITY_ID=$(curl -s -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" "https://api.netlify.com/api/v1/sites/$SITE_ID" \
+  | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).identity_instance_id')
+echo "$IDENTITY_ID"
 ```
 
-### `AuthError` on server - missing Netlify runtime
-
-**Cause:** Server-side `login()`, `signup()`, or `logout()` require the Netlify Functions runtime to set cookies.
-
-**Fix:**
+Look up by email (matching ignores case and trailing spaces; partial emails return 404):
 
-1. Deploy to Netlify to use server-side auth mutations
-2. Or use `netlify dev` for local development
-
-### "User not found" after OAuth login
-
-**Cause:** OAuth provider is not enabled for the project.
-
-**Fix:**
-
-1. Enable the provider in **Project configuration > Identity > External providers**
-2. Users are created automatically on first OAuth login
-
-### Account operations fail after server-side login
-
-**Cause:** Browser-side session is not bootstrapped from server-set cookies.
-
-**Fix:** Call `hydrateSession()` on page load to bridge server-set cookies to the browser session. Then use
-`updateUser()`, `verifyEmailChange()`, or other account operations.
-
-```typescript
-import { hydrateSession, updateUser } from '@netlify/identity'
-
-// On page load after server-side login
-await hydrateSession()
-
-// Now account operations work
-await updateUser({ data: { full_name: 'Jane' } })
+```bash
+curl -s -X POST -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" -H "Content-Type: application/json" \
+  -d '{"email": "jane@example.com"}' \
+  "https://api.netlify.com/api/v1/sites/$SITE_ID/identity/$IDENTITY_ID/users/lookup"
 ```
 
-### "Email change verification requires an active browser session"
-
-**Cause:** `verifyEmailChange()` was called without an active session. The user must be logged in when clicking the
-email change verification link.
-
-**Fix:** Ensure the user is logged in before processing the `email_change` callback. If the session expired, prompt
-the user to log in first.
-
-### "No user is currently logged in"
+Look up by ID:
 
-**Cause:** An account operation (`updateUser`, `verifyEmailChange`) was called without an authenticated user.
-
-**Fix:** Check `getUser()` before calling account operations. If `null`, redirect to login.
-
-```typescript
-const user = await getUser()
-if (!user) {
-  redirectToLogin()
-  return
-}
-await updateUser({ data: { full_name: 'Jane' } })
+```bash
+curl -s -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" \
+  "https://api.netlify.com/api/v1/sites/$SITE_ID/identity/$IDENTITY_ID/users/$USER_ID"
 ```
 
-### Stale session - user deleted server-side
+Once the site read has returned an `identity_instance_id`, a 404 from these lookups means no user with that email or ID
+exists on this project. The response contains:
 
-**Cause:** `getUser()` returns `null` when the `nf_jwt` cookie is gone but localStorage still has a stale
-session. This happens when a user is deleted via the admin API or Netlify UI.
+| Field                   | What it tells you                                                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `confirmed_at`          | Empty: the user never confirmed their email or accepted their invite, so login fails.                                               |
+| `invited_at`            | Set: the user was invited. With an empty `confirmed_at`, the invite is still pending.                                               |
+| `app_metadata.provider` | `email` for password signups; `google`, `github`, etc. for OAuth. An OAuth user has no password, so the password form rejects them. |
+| `app_metadata.roles`    | Compare with the roles your redirects or code require.                                                                              |
+| `last_sign_in_at`       | When the user last logged in successfully.                                                                                          |
+| `recovery_sent_at`      | When a password reset email was last requested.                                                                                     |
+| `email_change_sent_at`  | When an email change was last requested.                                                                                            |
 
-**Fix:** `getUser()` handles this gracefully - it returns `null` and the stale localStorage entry is ignored. Always
-check for `null` before using the user object.
+These reads don't show whether the login flow in the code works. Check the code and the preview for that.