Skip to content

feat(auth): introduce email verification policy configuration #3393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
manucorporat merged 2 commits into from
Aug 24, 2026
Merged

feat(auth): introduce email verification policy configuration #3393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c63006f
feat(auth): introduce email verification policy configuration
manucorporat Aug 22, 2026
dbc2432
Merge remote-tracking branch 'origin/main' into fix-verify-email-config
manucorporat Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .agents/skills/authentication/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
| **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 `dev@local.test`. 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. |
Expand Down
13 changes: 13 additions & 0 deletions .changeset/auth-require-email-verification-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
"@agent-native/core": minor
---

Add `auth.requireEmailVerification` to the app config schema, aliased to
`AUTH_REQUIRE_EMAIL_VERIFICATION`, so a deployment can state its password-signup
verification policy instead of inheriting the environment-derived one.
`AUTH_SKIP_EMAIL_VERIFICATION` stays a local/QA-only convenience that hosted
deployments ignore; a declared value outranks it. Setting the field to `false`
accepts an unverified address as a login credential and therefore also lifts the
hosted no-email-provider signup lock, which exists to prevent exactly that;
setting it to `true` where no email provider is configured disables password
signup rather than stranding accounts on a verification that cannot be delivered.
5 changes: 5 additions & 0 deletions .changeset/quiet-vite-rollup-options-alias.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@agent-native/core": patch
---

Stop the dev server from warning that the `agent-native-config` plugin set both `rollupOptions` and `rolldownOptions`. Vite 8 exposes `rollupOptions` as a getter alias of `rolldownOptions`, and spreading the incoming `build` / `optimizeDeps` sections copied that alias back out alongside our own `rolldownOptions`.
1 change: 1 addition & 0 deletions docs/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,7 @@ only in code.
| `app.packageName` | `npm_package_name` | string | — | Package name of the running app, as npm sets it for a script. |
| `app.template` | `VITE_AGENT_NATIVE_TEMPLATE` | string | — | First-party template this app was generated from. |
| `auth.disableDesktopSsoFallbackInDevelopment` | `AGENT_NATIVE_DISABLE_DESKTOP_SSO_FALLBACK` | boolean | `false` | Disable the loopback Desktop SSO fallback in development so isolated acceptance runs can use their configured local identity. Ignored in production. |
| `auth.requireEmailVerification` | `AUTH_REQUIRE_EMAIL_VERIFICATION` | boolean | — | Whether password signup must verify the email address before it gets a session. Unset derives it: hosted deployments require it, local development skips it. Setting it false accepts an unverified email as a login credential, including in production. |
| `integrations.allowUnverifiedWebhooks` | `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` | boolean | `false` | Skip inbound webhook signature verification. Development only — every adapter that reads this treats it as a bypass of sender authentication. |
| `integrations.platforms` | `AGENT_NATIVE_INTEGRATION_PLATFORMS` | array | — | Integration platforms to mount, comma-separated, each matched against an adapter's `platform` id (slack, telegram, whatsapp, microsoft-teams, discord, google-docs, email). Unset mounts every adapter; a name no adapter provides throws at plugin init. |
| `migration.releaseMigrations` | `AGENT_NATIVE_RELEASE_MIGRATIONS` | boolean | `false` | Treat database migrations as release-owned so request runtimes only probe an already-prepared schema. |
Expand Down
61 changes: 40 additions & 21 deletions packages/core/docs/content/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,24 @@ verification and the signup verification email is not sent. It does not change
magic-link delivery. Use it only for QA or preview environments, and name test accounts with a `+qa` address
(`name+qa@example.com`) so they are easy to identify.

## Email Verification Policy {#email-verification-policy}

`AUTH_SKIP_EMAIL_VERIFICATION` is a local and QA convenience — a hosted
deployment ignores it. To state the policy for any environment, production
included, declare it in config:

```ts
defineAppConfig({ auth: { requireEmailVerification: false } });
```

The deployment alias is `AUTH_REQUIRE_EMAIL_VERIFICATION=0`. A declared value
outranks both `AUTH_SKIP_EMAIL_VERIFICATION` and the per-environment default.

`false` accepts an unverified address as a login credential — anyone can claim
any email — so use it only where signup is already restricted another way.
`true` on a deployment with no email provider disables password signup instead,
because the verification could never be delivered.

## Social Providers {#social-providers}

Set environment variables to enable social login. Better Auth auto-detects them:
Expand Down Expand Up @@ -477,27 +495,28 @@ The default `/_agent-native/google/auth-url` route does this automatically — o

## Environment Variables {#environment-variables}

| Variable | Purpose |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | Signing key for Better Auth (auto-generated if not set) |
| `AUTH_SKIP_EMAIL_VERIFICATION` | Set to `1` in QA/preview environments to let password-fallback signups proceed without verification; local dev/test skips by default |
| `AUTH_MAGIC_LINK` | Set to `0`, `false`, or `off` to force the email/password fallback even when outbound email is ready |
| `AUTH_DISABLED` | Set to `true` or `1` to skip login/signup; all requests run as one shared user (local dev/preview only — not for production with real users) |
| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Set to `1` to disable localhost auto-sign-in on a fresh dev database |
| `AUTH_MODE` | `local` resolves CLI/agent identity only (which dev user `pnpm action` runs as); never a browser login bypass |
| `COOKIE_DOMAIN` | Opt into shared session cookies across same-database subdomains (see [Cookie Realms](#cookie-realms)) |
| `AGENT_NATIVE_WORKSPACE` | `1` runs in workspace mode — one shared session realm across workspace apps |
| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN` | Set with `COOKIE_DOMAIN` to share one auth database across first-party subdomains |
| `OAUTH_STATE_SECRET` | Dedicated HMAC key for OAuth state envelopes (see [Security — OAuth State Signing](/docs/security#oauth-state)) |
| `GOOGLE_SIGN_IN_CLIENT_ID` | Preferred low-scope Google OAuth client ID for app login |
| `GOOGLE_SIGN_IN_CLIENT_SECRET` | Preferred low-scope Google OAuth secret for app login |
| `GOOGLE_CLIENT_ID` | Legacy Google login fallback, and provider OAuth client ID for Google API integrations |
| `GOOGLE_CLIENT_SECRET` | Legacy Google login fallback, and provider OAuth secret for Google API integrations |
| `GITHUB_CLIENT_ID` | Enable GitHub OAuth |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth secret |
| `ACCESS_TOKEN` | Static bearer fallback for MCP/connect clients; not browser auth |
| `ACCESS_TOKENS` | Comma-separated static bearer fallbacks for MCP/connect clients; not browser auth |
| `A2A_SECRET` | Shared secret for JWT-signed A2A cross-app identity verification and, when present, MCP OAuth access-token signing |
| Variable | Purpose |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BETTER_AUTH_SECRET` | Signing key for Better Auth (auto-generated if not set) |
| `AUTH_SKIP_EMAIL_VERIFICATION` | Set to `1` in QA/preview environments to let password-fallback signups proceed without verification; local dev/test skips by default |
| `AUTH_REQUIRE_EMAIL_VERIFICATION` | Set to `0` or `1` to declare the password-signup verification policy for any environment, production included; outranks `AUTH_SKIP_EMAIL_VERIFICATION` |
| `AUTH_MAGIC_LINK` | Set to `0`, `false`, or `off` to force the email/password fallback even when outbound email is ready |
| `AUTH_DISABLED` | Set to `true` or `1` to skip login/signup; all requests run as one shared user (local dev/preview only — not for production with real users) |
| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Set to `1` to disable localhost auto-sign-in on a fresh dev database |
| `AUTH_MODE` | `local` resolves CLI/agent identity only (which dev user `pnpm action` runs as); never a browser login bypass |
| `COOKIE_DOMAIN` | Opt into shared session cookies across same-database subdomains (see [Cookie Realms](#cookie-realms)) |
| `AGENT_NATIVE_WORKSPACE` | `1` runs in workspace mode — one shared session realm across workspace apps |
| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN` | Set with `COOKIE_DOMAIN` to share one auth database across first-party subdomains |
| `OAUTH_STATE_SECRET` | Dedicated HMAC key for OAuth state envelopes (see [Security — OAuth State Signing](/docs/security#oauth-state)) |
| `GOOGLE_SIGN_IN_CLIENT_ID` | Preferred low-scope Google OAuth client ID for app login |
| `GOOGLE_SIGN_IN_CLIENT_SECRET` | Preferred low-scope Google OAuth secret for app login |
| `GOOGLE_CLIENT_ID` | Legacy Google login fallback, and provider OAuth client ID for Google API integrations |
| `GOOGLE_CLIENT_SECRET` | Legacy Google login fallback, and provider OAuth secret for Google API integrations |
| `GITHUB_CLIENT_ID` | Enable GitHub OAuth |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth secret |
| `ACCESS_TOKEN` | Static bearer fallback for MCP/connect clients; not browser auth |
| `ACCESS_TOKENS` | Comma-separated static bearer fallbacks for MCP/connect clients; not browser auth |
| `A2A_SECRET` | Shared secret for JWT-signed A2A cross-app identity verification and, when present, MCP OAuth access-token signing |

## What's next

Expand Down
1 change: 1 addition & 0 deletions packages/core/docs/content/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ public app behavior, use the config paths above instead.
| `AUTH_DISABLED` | Disables auth for local or preview-only work. Unset already means false. | `true` or `1`; never use on a public production app. |
| `AUTH_MAGIC_LINK` | Controls the password-first versus magic-link sign-in path. | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links. |
| `AUTH_SKIP_EMAIL_VERIFICATION` | Skips signup email verification for local QA or previews. | `1`; never use it to weaken production auth. |
| `AUTH_REQUIRE_EMAIL_VERIFICATION` | Declares whether password signup must verify the email address, in any environment. | `0` or `1`; outranks `AUTH_SKIP_EMAIL_VERIFICATION`. `0` accepts an unverified address as a login credential. |
| `ACCESS_TOKEN` / `ACCESS_TOKENS` | Static bearer fallback for MCP and Connect clients. | One token or a delimited token list; these are not browser auth. |
| `AGENT_PROD_CODE_EXECUTION` | Production code-execution policy. | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/actions-agent-tools#production-code-execution). |
| `AGENT_NATIVE_SSR_CACHE` | Deployment-wide public SSR shell cache policy. | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/ssr-caching). |
Expand Down
Loading
Loading