@netlify/agent-runner-cli 1.75.0-alpha.0 → 1.76.0

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

@@ -0,0 +1,329 @@
+---
+name: netlify-identity
+description: Add user authentication with Netlify Identity. Use when implementing signups, logins, password recovery, role-based access control, OAuth providers, or protecting Netlify Functions with user tokens.
+---
+
+# 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).
+
+There are two integration paths:
+
+- **Widget** (`netlify-identity-widget`) — Drop-in UI modal for login, signup, and password recovery. Zero framework
+  dependencies. Best when you want auth working quickly without building custom forms.
+- **gotrue-js** — Programmatic client for full control over authentication flows. Best when you need custom UI or
+  headless auth logic.
+
+Both communicate with the Identity endpoint at `/.netlify/identity` on your site.
+
+## Quick Start
+
+Add the widget CDN script and a menu element for instant auth:
+
+```html
+<script type="text/javascript" src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
+<div data-netlify-identity-menu></div>
+```
+
+Handle logins:
+
+```javascript
+netlifyIdentity.on('login', async (user) => {
+  const jwt = await netlifyIdentity.refresh()
+  await fetch('/.netlify/functions/protected', {
+    headers: { Authorization: `Bearer ${jwt}` },
+  })
+})
+```
+
+### When to Use Widget vs gotrue-js
+
+- **Prefer the widget** when the user wants auth working quickly, doesn't have custom UI requirements, or is building a
+  simple site. It requires minimal code and automatically sets the `nf_jwt` cookie needed for role-based redirects.
+- **Use gotrue-js** when the user needs custom login/signup forms, headless auth, or programmatic control over the auth
+  flow. Pass `setCookie: true` if you need role-based redirects (see below).
+- **Never mix both** in the same page unless accessing `netlifyIdentity.gotrue` for low-level operations while using the
+  widget for UI.
+
+## Setup
+
+Identity is automatically enabled when the deploy includes Identity code. 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.
+
+## Widget (Drop-in UI)
+
+### CDN Script Tag
+
+Include the widget script and add HTML attributes for automatic controls:
+
+```html
+<script type="text/javascript" src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
+
+<!-- Login/Signup menu (shows username + logout when logged in) -->
+<div data-netlify-identity-menu></div>
+
+<!-- Simple button that opens the modal -->
+<div data-netlify-identity-button>Login with Netlify Identity</div>
+```
+
+The widget attaches itself to `window.netlifyIdentity` automatically.
+
+### npm Module
+
+```bash
+npm install netlify-identity-widget
+```
+
+```javascript
+import netlifyIdentity from 'netlify-identity-widget'
+
+netlifyIdentity.init({
+  container: '#netlify-modal', // defaults to document.body
+  locale: 'en',               // language code (en, fr, es, pt, de, etc.)
+  // APIUrl: 'https://your-site.netlify.app/.netlify/identity', // only for non-Netlify hosts
+})
+```
+
+Set `APIUrl` only when the app is served from a different domain than the Identity endpoint (Cordova, Electron, or
+custom domains).
+
+### Events
+
+```javascript
+netlifyIdentity.on('init', (user) => console.log('init', user))
+netlifyIdentity.on('login', (user) => console.log('login', user))
+netlifyIdentity.on('logout', () => console.log('Logged out'))
+netlifyIdentity.on('error', (err) => console.error('Error', err))
+
+netlifyIdentity.off('login')           // unbind all login handlers
+netlifyIdentity.off('login', handler)  // unbind a specific handler
+```
+
+### Key Methods
+
+```javascript
+netlifyIdentity.open()                                // open modal (default tab)
+netlifyIdentity.open('login')                         // open to login tab
+netlifyIdentity.open('signup')                        // open to signup tab
+netlifyIdentity.open('signup', { full_name: 'Jane' }) // pre-fill signup metadata
+netlifyIdentity.close()
+netlifyIdentity.logout()
+const user = netlifyIdentity.currentUser()            // null if not logged in
+const jwt = await netlifyIdentity.refresh()           // refresh the JWT
+const gotrueClient = netlifyIdentity.gotrue           // underlying GoTrue client
+```
+
+## gotrue-js (Programmatic Client)
+
+### Install
+
+```bash
+npm install gotrue-js
+```
+
+### Initialize
+
+```typescript
+import GoTrue from 'gotrue-js'
+
+const auth = new GoTrue({
+  APIUrl: 'https://<your-site>.netlify.app/.netlify/identity',
+  setCookie: false,
+})
+```
+
+`setCookie: true` tells the server to set HttpOnly cookies, which protects tokens from XSS but is required if you need
+role-based redirects without the widget (the CDN reads an `nf_jwt` cookie to evaluate redirect conditions). Use `false`
+when you manage tokens entirely in JavaScript and don't need CDN-level access control.
+
+### Core Methods
+
+```javascript
+// Signup (sends confirmation email if autoconfirm is off)
+const response = await auth.signup(email, password)
+// Pass user_metadata during signup: auth.signup(email, password, { full_name: 'Jane' })
+
+// Confirm email (token from confirmation email URL fragment)
+const user = await auth.confirm(token, true)        // remember = persist session
+
+// Login
+const user = await auth.login(email, password, true) // remember = persist session
+
+// Current user (from localStorage)
+const user = auth.currentUser()
+
+// Get fresh JWT (auto-refreshes if expired; pass true to force)
+const token = await user.jwt()
+
+// Update user
+await user.update({ email: 'new@example.com', password: 'newpassword' })
+await user.update({ data: { full_name: 'Jane Doe' } }) // update user_metadata
+
+// Logout
+await user.logout()
+
+// Password recovery
+await auth.requestPasswordRecovery(email)               // sends recovery email
+const user = await auth.recover(recoveryToken, true)    // remember = persist session
+
+// Check server settings (signup enabled? autoconfirm? OAuth providers?)
+const settings = await auth.settings()
+```
+
+### Error Handling
+
+gotrue-js exports `JSONHTTPError`, `TextHTTPError`, and `HTTPError` for granular error catching. Use `error.json`,
+`error.data`, or `error.status` respectively.
+
+## Token Handling
+
+- Access tokens expire after **1 hour**
+- Both `user.jwt()` (gotrue-js) and `netlifyIdentity.refresh()` (widget) auto-refresh using the refresh token
+- Always call `jwt()` or `refresh()` before authenticated requests — do not cache tokens
+- Send the token as `Authorization: Bearer <token>`
+
+## Roles and Authorization
+
+### Metadata Types
+
+- **`app_metadata.roles`** — Server-controlled. Only settable via the Netlify UI, admin API, or server-side code
+  (Identity event functions, protected functions with admin token). Do not allow users to set their own roles.
+- **`user_metadata`** — User-controlled. Users can update this via `user.update({ data: { ... } })`.
+
+### Role-Based Redirects
+
+Use `netlify.toml` to restrict paths by role:
+
+```toml
+[[redirects]]
+  from = "/admin/*"
+  to = "/admin/:splat"
+  status = 200
+  conditions = { Role = ["admin"] }
+
+[[redirects]]
+  from = "/admin/*"
+  to = "/"
+  status = 302
+```
+
+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.
+
+**How it works:** The widget sets an `nf_jwt` cookie that the CDN reads to evaluate `conditions = { Role = [...] }`.
+Without this cookie, role-based redirects will not work. If using gotrue-js instead of the widget, pass
+`setCookie: true` when initializing GoTrue so the server sets this cookie.
+
+## Identity Event Functions
+
+Special serverless functions that trigger on Identity lifecycle events. These use the **legacy named `handler` export**
+(not the modern default export) because they receive `event.body` containing the user payload.
+
+**Event names:** `identity-validate`, `identity-signup`, `identity-login`
+
+- `identity-signup` — fires when a new user signs up (email/password or OAuth)
+- `identity-login` — fires on each login
+- `identity-validate` — fires during signup before the user is created; return a non-200 status to reject the signup
+
+The filename must match the event name exactly (e.g. `netlify/functions/identity-signup.mts`).
+
+### Example: Assign Default Role on Signup
+
+```typescript
+// netlify/functions/identity-signup.mts
+import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
+
+const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
+  const { user } = JSON.parse(event.body || '{}')
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      app_metadata: {
+        ...user.app_metadata,
+        roles: ['member'],
+      },
+    }),
+  }
+}
+
+export { handler }
+```
+
+The response body replaces `app_metadata` and/or `user_metadata` on the user record — include all fields you want to
+keep, not just new ones.
+
+## Protected Functions
+
+Functions that verify the calling user's identity. Use the legacy `handler` export to access `context.clientContext`.
+
+```typescript
+// netlify/functions/protected-action.mts
+import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
+
+const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
+  const { identity, user } = context.clientContext || {}
+
+  if (!user) {
+    return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) }
+  }
+
+  // user.sub — user ID
+  // user.email — email address
+  // user.app_metadata.roles — assigned roles
+  // user.user_metadata — user-controlled data
+
+  // Use identity.token (admin token) to call the Identity admin API:
+  const adminAuthHeader = `Bearer ${identity.token}`
+  const response = await fetch(`${identity.url}/admin/users/${user.sub}`, {
+    method: 'PUT',
+    headers: { Authorization: adminAuthHeader },
+    body: JSON.stringify({ app_metadata: { roles: ['editor'] } }),
+  })
+
+  const data = await response.json()
+  return { statusCode: 200, body: JSON.stringify(data) }
+}
+
+export { handler }
+```
+
+**Note:** Operations using `identity.token` (admin token) do **not** work locally with `netlify dev`. Deploy to Netlify
+to test server-side admin operations.
+
+## External OAuth Providers
+
+Netlify Identity supports Google, GitHub, GitLab, and BitBucket as built-in OAuth providers.
+
+**Enable in Netlify UI:** Project configuration > Identity > Registration > External providers
+
+### Widget
+
+Once enabled in the UI, the widget automatically shows OAuth provider buttons. No additional code needed.
+
+### gotrue-js
+
+```javascript
+const url = auth.loginExternalUrl('github')
+// Redirect the user to this URL to start the OAuth flow
+window.location.href = url
+```
+
+Available provider names: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`
+
+## Common Errors & Solutions
+
+- **"Signups not allowed for this instance" (403)** — Registration is set to Invite only. Change to Open in Project
+  configuration > Identity, or invite users from the Identity tab.
+- **"Token expired" / 401 on API calls** — Stale access token. Always call `user.jwt()` or `netlifyIdentity.refresh()`
+  before authenticated requests.
+- **Identity event function not triggering** — Verify filename matches exactly (`identity-signup`, `identity-validate`,
+  or `identity-login`), is in `netlify/functions/`, and uses `.mts`/`.mjs`.
+- **`clientContext` is undefined** — Use named `handler` export (not `export default`), send `Authorization: Bearer`
+  header, and verify token is fresh.
+- **Admin methods not working locally** — `identity.token` is unavailable in local dev. Deploy to Netlify to test.
+- **"User not found" after OAuth login** — Enable the OAuth provider in Project configuration > Identity > External
+  providers. Users are created on first OAuth login.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.75.0-alpha.0",
+  "version": "1.76.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",