feat: add auth settings and canonical env overrides

Adds canonical OS_* settings env overrides, Auth settings for registration and Google sign-in, runtime better-auth binding, and updated docs/tests.

Author: xuyushun441-sys

.changeset/silver-ai-envs.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/service-settings": major
+"@objectstack/plugin-auth": minor
+"@objectstack/service-ai": patch
+"@objectstack/spec": patch
+---
+
+Settings namespace environment overrides now use the canonical ObjectStack
+`OS_<NAMESPACE>_<KEY>` form, with no unprefixed aliases. For example,
+`ai.openai_base_url` is now `OS_AI_OPENAI_BASE_URL`, and
+`feature_flags.ai_enabled` is now `OS_FEATURE_FLAGS_AI_ENABLED`.
+
+The AI service now treats a stored or env-locked `provider=memory` setting as
+an explicit override, while the manifest default still leaves boot-time
+provider auto-detection intact.
+
+The auth plugin now binds the `auth` settings namespace to better-auth runtime
+configuration, exposes an extension hook for provider packages, and includes a
+basic Google sign-in implementation configured either in Setup → Authentication
+or by deployment-level `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.

content/docs/guides/auth-sso.mdx

@@ -1,16 +1,21 @@
 ---
 title: Social & Enterprise SSO
-description: Enable social sign-in (Google, GitHub, Microsoft, Apple) and enterprise OIDC/SSO in ObjectStack Studio.
+description: Enable Google sign-in in open source, and extend auth providers through packages.
 ---
 
 # Social & Enterprise SSO
 
-ObjectStack supports multiple authentication providers out of the box:
+ObjectStack open source ships one built-in social sign-in implementation:
 
-- **Social OAuth**: Google, GitHub, Microsoft, Apple — via better-auth's built-in `socialProviders`
-- **Enterprise SSO**: Any OIDC-compliant provider (Okta, Azure AD, Keycloak, Ping Identity, …) — via better-auth's `genericOAuth` plugin
+- **Google OAuth**: configure in Setup → Authentication, or from
+  `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` deployment env vars
 
-The Studio login and registration pages automatically render **Continue with …** buttons for every enabled provider. No UI changes are required.
+Additional providers should be contributed by product or enterprise packages through
+the `auth:configure` hook. Those packages can add better-auth `socialProviders`
+or OIDC/generic OAuth providers without forking `@objectstack/plugin-auth`.
+
+The Studio login and registration pages automatically render **Continue with ...**
+buttons for every enabled provider returned by `/api/v1/auth/config`.
 
 ---
 
@@ -27,15 +32,24 @@ The Studio login and registration pages automatically render **Continue with …
    For local development: `http://localhost:3000/api/v1/auth/callback/google`
 4. Copy the **Client ID** and **Client Secret**.
 
+Then either save the values in **Setup → Authentication → Social sign-in** or
+provide them as deployment environment variables:
+
 ```bash
 GOOGLE_CLIENT_ID=your-google-client-id
 GOOGLE_CLIENT_SECRET=your-google-client-secret
 
-# Optional: override default scopes (comma-separated)
-# GOOGLE_OAUTH_SCOPES=openid,email,profile
+# Optional settings env override. UI settings are lower precedence than env.
+# OS_AUTH_GOOGLE_ENABLED=false
 ```
 
-### GitHub
+## Extension Packages
+
+The providers below are examples for enterprise or product packages, not built-in
+open-source settings. A package can register them by listening to `auth:configure`
+and mutating the draft auth config.
+
+### GitHub Example
 
 1. Go to [GitHub Developer Settings](https://github.com/settings/developers) → **OAuth Apps** → **New OAuth App**.
 2. Set **Authorization callback URL**:
@@ -84,14 +98,16 @@ APPLE_CLIENT_SECRET=your-apple-private-key-jwt
 
 ---
 
-## Enterprise SSO (OIDC)
+## Enterprise SSO (OIDC) Extension Example
 
-For enterprise single sign-on, set the `OIDC_PROVIDERS` environment variable to a JSON array. Each entry maps to one SSO provider.
+Enterprise packages can pass `oidcProviders` into `@objectstack/plugin-auth`
+or contribute them through `auth:configure`. The open-source package does not
+ship a generic OIDC settings UI.
 
 ### Quick start — Okta
 
-```bash
-OIDC_PROVIDERS='[
+```ts
+const oidcProviders = [
   {
     "providerId": "okta",
     "name": "Okta",
@@ -100,27 +116,27 @@ OIDC_PROVIDERS='[
     "clientSecret": "your-okta-client-secret",
     "scopes": ["openid", "email", "profile"]
   }
-]'
+];
 ```
 
 ### Quick start — Azure AD (OIDC)
 
-```bash
-OIDC_PROVIDERS='[
+```ts
+const oidcProviders = [
   {
     "providerId": "azure-ad",
     "name": "Azure AD",
     "discoveryUrl": "https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration",
     "clientId": "your-azure-client-id",
     "clientSecret": "your-azure-client-secret"
   }
-]'
+];
 ```
 
 ### Quick start — Keycloak
 
-```bash
-OIDC_PROVIDERS='[
+```ts
+const oidcProviders = [
   {
     "providerId": "keycloak",
     "name": "Keycloak",
@@ -129,13 +145,13 @@ OIDC_PROVIDERS='[
     "clientSecret": "your-client-secret",
     "pkce": true
   }
-]'
+];
 ```
 
 ### Multiple enterprise providers
 
-```bash
-OIDC_PROVIDERS='[
+```ts
+const oidcProviders = [
   {
     "providerId": "okta",
     "name": "Okta SSO",
@@ -150,7 +166,7 @@ OIDC_PROVIDERS='[
     "clientId": "...",
     "clientSecret": "..."
   }
-]'
+];
 ```
 
 ### OIDC provider fields

content/docs/guides/authentication.mdx

@@ -33,7 +33,7 @@ The `@objectstack/plugin-auth` package provides enterprise-grade authentication
 - ✅ **Session Management** - Automatic session handling with configurable expiry
 - ✅ **Password Reset** - Email-based password reset flow
 - ✅ **Email Verification** - Email verification workflow
-- ✅ **2FA** - Two-factor authentication
+- ⚙️ **2FA backend** - better-auth two-factor plugin wiring is available for custom UIs
 - ✅ **Passkeys** - WebAuthn/Passkey support
 - ✅ **Magic Links** - Passwordless authentication
 - ✅ **Organizations** - Multi-tenant support
@@ -91,14 +91,19 @@ Set up your authentication secret in `.env`:
 
 ```bash
 # Required: Secret for session token encryption
-AUTH_SECRET=your-super-secret-key-min-32-chars
+OS_AUTH_SECRET=your-super-secret-key-min-32-chars
 
-# Optional: OAuth providers (if using)
+# Optional: open-source Google login
+# You can also configure these in Setup → Authentication.
 GOOGLE_CLIENT_ID=your-google-client-id
 GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# Optional: lock auth settings from env. Env wins over Setup UI values.
+OS_AUTH_SIGNUP_ENABLED=false
+OS_AUTH_GOOGLE_ENABLED=true
 ```
 
-> **Important**: Never commit `AUTH_SECRET` to version control. Use a strong random string (minimum 32 characters).
+> **Important**: Never commit `OS_AUTH_SECRET` to version control. Use a strong random string (minimum 32 characters).
 
 ### 2. Plugin Configuration
 
@@ -255,7 +260,7 @@ Enable OAuth providers in your plugin configuration:
 
 ```typescript
 new AuthPlugin({
-  secret: process.env.AUTH_SECRET,
+  secret: process.env.OS_AUTH_SECRET,
   baseUrl: 'http://localhost:3000',
   providers: [
     {
@@ -291,14 +296,23 @@ Better-Auth automatically handles the OAuth callback at `/api/v1/auth/callback/g
 
 ### Two-Factor Authentication (2FA)
 
-Enable 2FA in your configuration:
+ObjectStack wires the better-auth two-factor plugin at the backend layer, but
+the open-source Console login UI does not yet ship the complete TOTP challenge
+flow. Do not expose 2FA as an end-user feature until your UI handles:
+
+- enrollment (`/two-factor/enable`),
+- TOTP confirmation (`/two-factor/verify-totp`),
+- the `twoFactorRedirect` response returned by password sign-in, and
+- backup-code recovery.
+
+For custom account UIs, enable the backend plugin in configuration:
 
 ```typescript
 new AuthPlugin({
   secret: process.env.AUTH_SECRET,
   baseUrl: 'http://localhost:3000',
   plugins: {
-    twoFactor: true,  // Enable 2FA
+    twoFactor: true,  // Enable backend two-factor endpoints
   }
 })
 ```
@@ -311,17 +325,20 @@ const response = await fetch('http://localhost:3000/api/v1/auth/two-factor/enabl
   headers: { 
     'Content-Type': 'application/json',
     'Authorization': `Bearer ${accessToken}`
-  }
+  },
+  body: JSON.stringify({
+    password: currentPassword,
+  }),
 });
 
-const { qrCode, secret } = await response.json();
-// Display qrCode to user for scanning with authenticator app
+const { totpURI, backupCodes } = await response.json();
+// Display totpURI as a QR code and show backupCodes once.
 ```
 
 #### Verify 2FA Code
 
 ```typescript
-const response = await fetch('http://localhost:3000/api/v1/auth/two-factor/verify', {
+const response = await fetch('http://localhost:3000/api/v1/auth/two-factor/verify-totp', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
@@ -515,8 +532,8 @@ All endpoints are available under `/api/v1/auth/*`:
 
 #### Two-Factor Authentication
 
-- `POST /api/v1/auth/two-factor/enable` - Enable 2FA for user
-- `POST /api/v1/auth/two-factor/verify` - Verify 2FA code
+- `POST /api/v1/auth/two-factor/enable` - Start 2FA enrollment for the current user
+- `POST /api/v1/auth/two-factor/verify-totp` - Verify a TOTP code
 
 #### Passkeys
 
@@ -554,7 +571,7 @@ For complete API documentation, see the [Better-Auth API Reference](https://www.
 3. **Environment Variables**: Never commit secrets to version control
    ```bash
    # .env (not committed)
-   AUTH_SECRET=your-secret-here
+   OS_AUTH_SECRET=your-secret-here
    GOOGLE_CLIENT_ID=your-client-id
    ```
 
@@ -574,7 +591,7 @@ For complete API documentation, see the [Better-Auth API Reference](https://www.
 
 1. **Email Verification**: Require email verification for sensitive operations
 2. **Password Requirements**: Enforce strong password policies
-3. **2FA for Admin**: Require 2FA for administrative accounts
+3. **2FA for Admin**: Require 2FA only after your UI supports the full TOTP challenge and recovery flow
 4. **OAuth Options**: Provide multiple OAuth providers for convenience
 
 ### Error Handling

content/docs/guides/environment-variables.mdx

@@ -60,16 +60,29 @@ read at startup unless noted otherwise. Boolean variables accept `true` / `false
 |:---|:---|:---|:---|
 | `OS_AUTH_URL` | url | `http://localhost:<OS_PORT>` | Public base URL of the auth server. Required behind a proxy or in production. |
 | `OS_AUTH_SECRET` | string | auto-generated (dev) | Secret used to sign sessions and cookies. **Required** in production. |
-| `OS_AUTH_ADMIN` | boolean | `true` | Enable the admin plugin (first user becomes admin). |
-| `OS_AUTH_TWO_FACTOR` | boolean | `true` | Enable the two-factor authentication plugin. |
+| `OS_AUTH_TWO_FACTOR` | boolean | `false` | Enable the low-level better-auth two-factor plugin. Keep disabled unless your UI handles enrollment, login challenge, and backup-code recovery. |
 | `OS_DISABLE_SIGNUP` | boolean | `false` | When `true`, block new email/password sign-ups. The very first user can still sign up to bootstrap admin. |
+| `OS_AUTH_EMAIL_PASSWORD_ENABLED` | boolean | settings default | Settings env override for `auth.email_password_enabled`. Controls local email/password login. |
+| `OS_AUTH_SIGNUP_ENABLED` | boolean | settings default | Settings env override for `auth.signup_enabled`. Takes precedence over UI settings and is preferred over `OS_DISABLE_SIGNUP`. |
+| `OS_AUTH_REQUIRE_EMAIL_VERIFICATION` | boolean | settings default | Settings env override for `auth.require_email_verification`. |
+| `OS_AUTH_GOOGLE_ENABLED` | boolean | settings default | Settings env override for `auth.google_enabled`. Requires Google OAuth credentials from Settings or env. |
+| `GOOGLE_CLIENT_ID` | string | — | Deployment-level Google OAuth client id for the open-source Google login implementation. |
+| `GOOGLE_CLIENT_SECRET` | string | — | Deployment-level Google OAuth client secret for the open-source Google login implementation. |
 | `OS_MULTI_ORG_ENABLED` | boolean | `false` | When `true`, expose organization creation/switching UI. When `false`, run in single-tenant mode. |
 | `OS_OIDC_PROVIDER_ENABLED` | boolean | `false` | When `true`, expose this instance as an OIDC identity provider. |
 | `OS_COOKIE_DOMAIN` | string | — | Cookie domain for cross-subdomain session sharing (e.g. `.example.com`). |
 | `OS_TRUSTED_ORIGINS` | csv | — | Comma-separated list of origins permitted for auth callbacks / CSRF. |
 | `OS_TERMS_URL` | url | — | URL shown next to the "Terms of Service" link on the sign-up form. Empty string hides the link. |
 | `OS_PRIVACY_URL` | url | — | URL shown next to the "Privacy Policy" link on the sign-up form. Empty string hides the link. |
 
+Auth settings precedence:
+
+1. Environment variables win over values saved in the Setup UI.
+2. `OS_AUTH_<SETTING_KEY>` settings env vars are the canonical form for settings-backed auth controls.
+3. Existing deployment toggles such as `OS_AUTH_TWO_FACTOR` and `OS_DISABLE_SIGNUP` remain supported.
+4. Google credentials can be saved in Setup → Authentication. `google_client_secret` is encrypted at rest.
+5. `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` remain supported for deployment-level Google OAuth configuration.
+
 ---
 
 ## CORS
@@ -112,11 +125,69 @@ read at startup unless noted otherwise. Boolean variables accept `true` / `false
 
 | Variable | Type | Default | Description |
 |:---|:---|:---|:---|
-| `OS_AI_MODEL` | string | `gpt-4o-mini` | Default chat model id. |
-| `OS_AI_ACTION_API_BASE_URL` | url | — | Override the base URL the AI action runtime calls (useful for self-hosted proxies). |
-
-> Provider credentials (`OPENAI_API_KEY`, `AI_GATEWAY_*`, etc.) keep their
-> upstream names.
+| `AI_GATEWAY_MODEL` | string | — | Vercel AI Gateway model id (for example `openai/gpt-4.1-mini` or `anthropic/claude-sonnet-4-5`). When set, the AI service boots with the gateway adapter before trying direct providers. |
+| `AI_GATEWAY_API_KEY` | string | — | Vercel AI Gateway API key. Required by the gateway SDK for real gateway calls; by itself it does not select the gateway adapter. Pair it with `AI_GATEWAY_MODEL`. |
+| `OPENAI_API_KEY` | string | — | Selects the direct OpenAI adapter when no gateway model is configured. Default model: `gpt-4o`. |
+| `ANTHROPIC_API_KEY` | string | — | Selects the direct Anthropic adapter when gateway and OpenAI are not configured. Default model: `claude-sonnet-4-20250514`. |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | string | — | Selects the direct Google Gemini adapter when gateway, OpenAI, and Anthropic are not configured. Default model: `gemini-2.0-flash`. |
+| `OS_AI_MODEL` | string | provider default | Overrides the model id for direct OpenAI / Anthropic / Google provider detection. Does not override `AI_GATEWAY_MODEL`; gateway model ids already include the provider prefix. |
+| `OS_AI_ACTION_API_BASE_URL` | url | — | Base URL prepended to relative `type: 'api'` action targets exposed as AI tools. Without this or a plugin `apiActionBaseUrl`, relative API actions are skipped for AI exposure. |
+| `OS_AI_PROVIDER` | enum | — | Settings override for the AI provider. Supported values include `gateway`, `openai`, `anthropic`, `google`, `deepseek`, `dashscope`, `cloudflare`, `siliconflow`, and `openrouter`. When set, it locks the Settings UI value. |
+| `OS_AI_GATEWAY_MODEL` | string | — | Settings override for the Vercel AI Gateway model id. Use with `OS_AI_PROVIDER=gateway`. |
+| `OS_AI_GATEWAY_API_KEY` | string | — | Settings override for the Vercel AI Gateway API key. Use with `OS_AI_PROVIDER=gateway`. |
+| `OS_AI_OPENAI_BASE_URL` | url | — | Settings override for the OpenAI-compatible chat base URL. Use with `OS_AI_PROVIDER=openai` for Azure, local gateways, or third-party OpenAI-shaped APIs. |
+| `OS_AI_OPENAI_API_KEY` | string | — | Settings override for the OpenAI-compatible API key. Stored only in env; the Settings UI cannot overwrite it while present. |
+| `OS_AI_OPENAI_MODEL` | string | `gpt-4o` | Settings override for the OpenAI-compatible chat model id. |
+| `OS_AI_ANTHROPIC_API_KEY` | string | — | Settings override for the Anthropic API key. Use with `OS_AI_PROVIDER=anthropic`. |
+| `OS_AI_ANTHROPIC_MODEL` | string | `claude-sonnet-4-20250514` | Settings override for the Anthropic model id. |
+| `OS_AI_GOOGLE_API_KEY` | string | — | Settings override for the Google Generative AI API key. Use with `OS_AI_PROVIDER=google`. |
+| `OS_AI_GOOGLE_MODEL` | string | `gemini-2.0-flash` | Settings override for the Google model id. |
+| `OS_AI_<PROVIDER>_API_KEY` | string | — | Settings override for preset OpenAI-compatible providers, for example `OS_AI_DEEPSEEK_API_KEY`, `OS_AI_DASHSCOPE_API_KEY`, `OS_AI_SILICONFLOW_API_KEY`, or `OS_AI_OPENROUTER_API_KEY`. |
+| `OS_AI_<PROVIDER>_MODEL` | string | provider default | Settings override for preset provider model ids, for example `OS_AI_DEEPSEEK_MODEL=deepseek-chat`. |
+
+The boot-time LLM adapter priority is:
+
+1. Explicit `AIServicePlugin({ adapter })` or per-plugin `gatewayModel` option.
+2. `AI_GATEWAY_MODEL` using `@ai-sdk/gateway`.
+3. `OPENAI_API_KEY` using `@ai-sdk/openai`.
+4. `ANTHROPIC_API_KEY` using `@ai-sdk/anthropic`.
+5. `GOOGLE_GENERATIVE_AI_API_KEY` using `@ai-sdk/google`.
+6. `MemoryLLMAdapter` echo mode when no real provider is configured.
+
+After boot, if the Settings service is mounted, `@objectstack/service-ai`
+reads the `ai` Settings namespace and swaps the adapter when the provider
+comes from env or a stored Settings UI value. The manifest default
+`provider=memory` is ignored so it does not mask boot-time auto-detection;
+an explicit `OS_AI_PROVIDER=memory` or stored UI value does switch the runtime
+back to memory. Settings values resolve as:
+
+```text
+env (`OS_<NAMESPACE>_<KEY>`) > stored Settings UI value > default
+```
+
+That means `OS_AI_PROVIDER=openai` plus `OS_AI_OPENAI_BASE_URL=...` wins over
+both the Settings UI and the boot-time provider auto-detection. ObjectStack
+does not read unprefixed settings override names such as `AI_PROVIDER` or
+`AI_OPENAI_BASE_URL`.
+
+For example, a third-party OpenAI-compatible provider can be deployment-locked
+without using the Settings UI:
+
+```bash
+OS_AI_PROVIDER=openai
+OS_AI_OPENAI_API_KEY=sk-...
+OS_AI_OPENAI_MODEL=your-model
+OS_AI_OPENAI_BASE_URL=https://your-provider.example.com/v1
+```
+
+Provider credentials keep their upstream names. ObjectStack does not rename
+`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, or
+`AI_GATEWAY_*` to `OS_*`.
+
+> **OpenAI-compatible base URLs.** Use `OS_AI_OPENAI_BASE_URL` with
+> `OS_AI_PROVIDER=openai`, configure the same fields in **Settings → AI**, or
+> pass an explicit adapter in code. Do not rely on `OPENAI_BASE_URL` as a
+> platform-level environment variable.
 
 ---