AuthenticationBLOCK

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: authentication
description: >-
  How auth works in agent-native apps. Use when wiring login/signup,
  configuring auth modes, setting up organizations, protecting routes, or
  debugging session issues.
scope: dev
metadata:
  internal: true
---

# Authentication

## Rule

Auth is powered by **Better Auth** with account-first design. Every new user creates an account on first visit. Use `getSession(event)` to authenticate custom routes; actions are auto-protected. Normal app HTML and React Router page-data responses are one impersonal, public-cacheable shell for every visitor. The client decides whether to render private UI or redirect to sign-in.

## Auth Modes

| Mode                      | Behavior                                                                                                                                 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Development (default)** | Real Better Auth — same flow as production. There is **no auth bypass**. On first run the framework auto-creates a throwaway dev account and signs you in without printing its credentials (disable with `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1`), so you are not stuck at a login wall. `getSession()` returns the signed-in user or `null` — it never falls back to a sentinel identity. |
| **Production (default)**  | Magic-link-first Better Auth when outbound email is ready, with email/password fallback and social providers (Google, GitHub). Organizations built in. |
| **`AUTH_MODE=local`**     | **Not** a browser auth bypass, and never returns `local@localhost`. It only affects CLI/agent identity: it lets `pnpm action` / the local agent loop auto-bind to the single real signed-in dev user from the `sessions` table (see `scripts/dev-session.ts`). Browser login is unchanged. |
| **`AUTH_SKIP_EMAIL_VERIFICATION=1`** | QA/preview escape hatch for password-fallback accounts. Signup skips email verification and does not send the signup verification email. Local dev/test skips verification by default; set `AUTH_SKIP_EMAIL_VERIFICATION=0` only when testing verification itself. It does not change magic-link delivery. Use `+qa` emails for test accounts. |
| **`auth.requireEmailVerification`** | Declares the password-signup verification policy for any environment, production included, via `defineAppConfig({ auth: { requireEmailVerification: false } })` or `AUTH_REQUIRE_EMAIL_VERIFICATION=0`. A declared value outranks `AUTH_SKIP_EMAIL_VERIFICATION` and the per-environment default. `false` accepts an unverified address as a login credential; `true` with no email provider disables password signup instead of stranding accounts on a verification nobody can deliver. |
| **`AUTH_MAGIC_LINK=0`** | Force the email/password fallback even when outbound email is ready. |
| **`AUTH_DISABLED=true`** | Skip login/signup entirely — every request runs as `[email protected]`. For local dev, cloud previews, and internal demos only; not for production with real users. |
| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Static bearer fallback for MCP/connect clients that cannot use OAuth. Not browser auth and never a token login page.         |
| **Custom**                | Pass your own `getSession` to `autoMountAuth(app, { getSession })`.                                                                     |

Auth emails (verify signup, reset password, magic link, email change) and org
invites render through `renderTransactionalEmail`. An app changes their copy or
design with `overrideTransactionalEmail(id, render)` from a server plugin, never
by editing `better-auth-instance.ts` call sites. See
`/docs/deployment#email-templates`.

## Hosted Sign-In Pages and the Shared Wave

- First-party server auth plugins use `createToolkitAuthPlugin` from
  `@agent-native/toolkit/app/auth/server`. It server-renders `AuthPage` and
  `ResetPasswordPage` before hydration. Direct Core `createAuthPlugin` calls
  leave generic fallback markup in the response and can flash before React
  replaces it.
- `AuthPage` uses Toolkit's full-page `WaveBackground` for every auth view.
  The Agent-Native homepage hero and Calendar booking use the same renderer:
  Calendar's animated FFT ocean wave. Keep the background empty while WebGPU
  support is checked and when the ocean renderer is unavailable; never show a
  WebGL or Starfield fallback. The homepage positions the wave inside its hero
  section, and hosted auth pages lift it above the lower marketing copy. Do not
  substitute a gradient, a signup-only strip, or a copied renderer.
  `StarfieldBackground` is only a compatibility export for older callers.
- Hosted marketing apps keep auth enabled at `/` so the public root response
  contains the full server-rendered sign-in page. Keep session decisions out of
  public SSR; `RequireSession` resolves signed-in app navigation in the client.

> **Never** use `local@localhost` as a fallback identity in app code
> (`getRequestUserEmail() ?? "local@localhost"`, `session?.email ?? "local@localhost"`,
> etc.). There is no dev auth shim. That pattern pools every unauthenticated
> request into one shared tenant and caused the 2026-04-29 credentials leak.
> When there is no session, **throw or return 401** — never substitute a
> sentinel. Enforced by `scripts/guard-no-localhost-fallback.mjs`.

## Remote MCP OAuth

Every app's `/mcp` endpoint is also a standard protected MCP
resource. OAuth-capable hosts connect with the remote MCP URL only, receive a
`WWW-Authenticate` challenge, discover `/.well-known/oauth-protected-resource`
and `/.well-known/oauth-authorization-server`, then use a validated Client ID
Metadata Document when the client id is an HTTPS URL or dynamically register a
public client otherwise. URL-like client ids never fall back to dynamic
registration when their metadata is missing or invalid. Clients complete
authorization-code + PK

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (7)

- **Flow:** the app creates a bound state and PKCE verifier, then opens `GET <hub>/_agent-native/identity/authorize?response_type=code&app=&client_id=&redirect_uri=&state=&code_challenge=`. Dispatch a

- **Organization federation:** the default-off `organization.cross-app-federation` flag separately enables signed org context. A source app registers its local organization with Dispatch using the sta

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: critical_finding, no_behavioural_pass, undeclared_transfer.

[![ModelsAtlas audit: Authentication](https://modelsatlas.com/skills/builderio/authentication/badge.svg)](https://modelsatlas.com/skills/builderio/authentication/)

Not your listing, or something out of date? Claim or update your listing.