@@ -0,0 +1,22 @@
+---
+'@objectstack/plugin-auth': patch
+'@objectstack/spec': minor
+'@objectstack/cli': patch
+'@object-ui/auth': patch
+'@object-ui/app-shell': patch
+'@object-ui/i18n': patch
+'@object-ui/console': patch
+---
+
+feat(plugin-auth): opt-in Cloudflare Turnstile on email sign-up — off unless both `OS_TURNSTILE_SITE_KEY` and `OS_TURNSTILE_SECRET_KEY` are set
+
+Clause-②: yes (widening: the public auth config gains `features.turnstileSiteKey`, served only while the challenge is on; `PUBLIC_AUTH_CONFIG_NON_FLAG_KEYS` and `AuthFeaturesConfigSchema` gain `turnstileSiteKey`; with the challenge on, `/sign-up/email` answers better-auth's `captcha` refusals `400 MISSING_RESPONSE`, `403 VERIFICATION_FAILED` and `500 UNKNOWN_ERROR`; two new env vars; `@object-ui/auth` gains `TurnstileWidget`, `TURNSTILE_SCRIPT_URL`, `RegisterForm`'s `turnstileSiteKey` prop and `captchaFailed`/`captchaRetry` labels, `SignUpData.captchaToken` and a fifth `signUp` argument; `@object-ui/app-shell` gains `signUpCaptchaFailedMessage`)
+Metadata-protocol: added
+
+A deployment can now ask for a human check before an email/password account is created. Set both variables and:
+
+- **The server** mounts better-auth's `captcha` plugin with the `cloudflare-turnstile` provider on `/sign-up/email` only. A sign-up without a token in the `x-captcha-response` header is refused before anything is read or written, a token is verified with Cloudflare using the secret, and a verification that cannot complete fails closed. Sign-in and password reset are not challenged (better-auth's default list would have included them; it is overridden). The per-address rate limit still runs first. Server-side registrations through `auth.api.signUpEmail` (the development admin seed, demo staff) are unaffected.
+- **The public auth config** (`GET /api/v1/auth/config`) serves `features.turnstileSiteKey`, the public site key, and never the secret.
+- **The Console** renders the challenge on `/register` and on the first-run `/setup` wizard, holds submit until it is solved, and sends the token. A failed, expired or refused challenge shows one retry message, never Cloudflare's code or the plugin's text. The Console document's content-security-policy admits `https://challenges.cloudflare.com` in `script-src` and `frame-src` only while both variables are set.
+
+With either variable unset or blank nothing changes: no plugin, no config key, no widget, the same policy. A deployment that sets only one gets one boot `warn` naming the missing variable.
@@ -110,6 +110,7 @@ Read by `@objectstack/service-print` when `PrintServicePlugin` is composed; see
 | `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. |
+| `OS_TURNSTILE_SITE_KEY` / `OS_TURNSTILE_SECRET_KEY` | string | — | Opt-in Cloudflare Turnstile on email sign-up. Set **both** and `/sign-up/email` (the register page and the first-run setup) requires a verified Turnstile token, the Console renders the challenge, and its content-security-policy admits `https://challenges.cloudflare.com`; sign-in and password reset are not challenged. Only the site key is served to the browser (`features.turnstileSiteKey`); the secret never leaves the server. With either unset nothing changes (one boot `warn` names the missing one). |
 
 Auth settings precedence:
 
 
@@ -63,6 +63,7 @@ const result = AuthEndpointSchema.parse(data);
 | **phoneNumber** | `boolean` | optional | Phone-number sign-in enabled (phone + password, V1.5) |
 | **phoneNumberOtp** | `boolean` | optional | Phone-number OTP sign-in and self-service password reset available — requires the phoneNumber plugin plus a deliverable SMS service |
 | **cloudManaged** | `boolean` | optional | Managed (cloud-hosted, SSO-only) mode: people arrive through the identity provider, so the UI hides inviting, creating users and setting their passwords; absent means not managed |
+| **turnstileSiteKey** | `string` | optional | Public Cloudflare Turnstile site key, present only while the opt-in sign-up challenge is on: the sign-up form renders the widget and sends its token in the x-captcha-response header; absent means no challenge |
 
 
 ---
@@ -189,6 +190,7 @@ This schema accepts one of the following structures:
 | **phoneNumber** | `boolean` | optional | Phone-number sign-in enabled (phone + password, V1.5) |
 | **phoneNumberOtp** | `boolean` | optional | Phone-number OTP sign-in and self-service password reset available — requires the phoneNumber plugin plus a deliverable SMS service |
 | **cloudManaged** | `boolean` | optional | Managed (cloud-hosted, SSO-only) mode: people arrive through the identity provider, so the UI hides inviting, creating users and setting their passwords; absent means not managed |
+| **turnstileSiteKey** | `string` | optional | Public Cloudflare Turnstile site key, present only while the opt-in sign-up challenge is on: the sign-up form renders the widget and sends its token in the x-captcha-response header; absent means no challenge |
 
 
 ---
 
@@ -49,6 +49,8 @@ const ENV = [
   'OS_TELEMETRY_CLIENT_ERROR_REPORTING_DSN',
   'AWS_ACCESS_KEY_ID',
   'AWS_SECRET_ACCESS_KEY',
+  'OS_TURNSTILE_SITE_KEY',
+  'OS_TURNSTILE_SECRET_KEY',
 ];
 
 let saved: Record<string, string | undefined>;
@@ -516,3 +518,43 @@ describe('connect-src names the host the storage service presigns browser upload
     ]);
   });
 });
+
+describe('the opt-in Turnstile challenge on sign-up', () => {
+  const TURNSTILE = 'https://challenges.cloudflare.com';
+
+  it('admits Cloudflare\'s script and frame only while both keys are set', async () => {
+    process.env.OS_TURNSTILE_SITE_KEY = 'site-key-csp';
+    process.env.OS_TURNSTILE_SECRET_KEY = 'secret-key-csp';
+    const request = await mount();
+    const res = await request('/_console/register');
+    const raw = res.headers.get('content-security-policy');
+    const policy = directives(raw);
+
+    expect(policy.get('script-src')).toContain(TURNSTILE);
+    expect(policy.get('frame-src')).toEqual(["'self'", TURNSTILE]);
+    // The nonce boundary is unchanged: no inline allowance rides along.
+    expect(policy.get('script-src')).not.toContain("'unsafe-inline'");
+    // Presence is read, never the values.
+    expect(raw).not.toContain('site-key-csp');
+    expect(raw).not.toContain('secret-key-csp');
+  });
+
+  for (const [label, env] of [
+    ['neither key', {}],
+    ['the site key alone', { OS_TURNSTILE_SITE_KEY: 'site-key-csp' }],
+    ['the secret alone', { OS_TURNSTILE_SECRET_KEY: 'secret-key-csp' }],
+    ['a blank secret', { OS_TURNSTILE_SITE_KEY: 'site-key-csp', OS_TURNSTILE_SECRET_KEY: '  ' }],
+  ] as const) {
+    it(`leaves the policy as it was with ${label}`, async () => {
+      Object.assign(process.env, env);
+      const request = await mount();
+      const raw = res(await request('/_console/register'));
+      expect(raw).not.toContain(TURNSTILE);
+      expect(directives(raw).has('frame-src')).toBe(false);
+    });
+  }
+
+  function res(response: Response): string | null {
+    return response.headers.get('content-security-policy');
+  }
+});
@@ -838,10 +838,16 @@ const DEFAULT_MAP_STYLE_ORIGIN = 'https://demotiles.maplibre.org';
  * - `frame-ancestors 'self'`, except on the public form page: the Console's
  *   public-forms screen hands authors an `<iframe>` snippet to embed that page
  *   on their own site, so it keeps loading in any frame.
+ * - {@link TURNSTILE_ORIGIN} in `script-src` and `frame-src` only while the
+ *   opt-in Turnstile challenge on sign-up is on (`readTurnstileEnabled`): the
+ *   sign-up form loads Cloudflare's script, which draws the challenge in a
+ *   frame from the same origin. With the challenge off, neither is listed and
+ *   `frame-src` is left to `default-src 'self'`, exactly as before.
  */
 function consoleContentSecurityPolicy(input: {
   nonce: string;
   reactPages: boolean;
+  turnstile: boolean;
   errorReportingOrigin: string | undefined;
   mapStyleOrigin: string | undefined;
   storageUploadOrigin: string | undefined;
@@ -850,6 +856,7 @@ function consoleContentSecurityPolicy(input: {
 }): string {
   const scriptSrc = ["'self'", `'nonce-${input.nonce}'`, "'wasm-unsafe-eval'"];
   if (input.reactPages) scriptSrc.push("'unsafe-eval'");
+  if (input.turnstile) scriptSrc.push(TURNSTILE_ORIGIN);
   const connectSrc = ["'self'", DEFAULT_MAP_STYLE_ORIGIN];
   if (input.mapStyleOrigin !== undefined) connectSrc.push(input.mapStyleOrigin);
   if (input.errorReportingOrigin !== undefined) connectSrc.push(input.errorReportingOrigin);
@@ -864,10 +871,27 @@ function consoleContentSecurityPolicy(input: {
     ['object-src', "'none'"],
     ['base-uri', "'self'"],
   ];
+  if (input.turnstile) directives.push(['frame-src', "'self'", TURNSTILE_ORIGIN]);
   if (!input.embeddable) directives.push(['frame-ancestors', "'self'"]);
   return directives.map((directive) => directive.join(' ')).join('; ');
 }
 
+/** Cloudflare Turnstile's origin: its loader script and its challenge frame. */
+const TURNSTILE_ORIGIN = 'https://challenges.cloudflare.com';
+
+/**
+ * Whether the opt-in Turnstile challenge on sign-up is on: BOTH variables set
+ * and non-blank, the rule `@objectstack/plugin-auth` mounts the challenge and
+ * serves `features.turnstileSiteKey` by (its `turnstile-sign-up.ts`). The two
+ * names are spelled here rather than imported because this module is behind
+ * the published `./console` subpath, which imports Node built-ins only. Only
+ * presence is read; the values never reach the policy.
+ */
+function readTurnstileEnabled(): boolean {
+  const set = (name: string) => String(process.env[name] ?? '').trim() !== '';
+  return set('OS_TURNSTILE_SITE_KEY') && set('OS_TURNSTILE_SECRET_KEY');
+}
+
 /** The variable a deployment sets to turn the `kind:'react'` page tier on. */
 const REACT_PAGES_ENV = 'OS_PAGE_REACT_ENABLED';
 /** Its earlier name, read when the new one is unset. */
@@ -1085,6 +1109,7 @@ export function createConsoleStaticPlugin(distPath: string, options?: { isDev?:
         const policy = consoleContentSecurityPolicy({
           nonce,
           reactPages,
+          turnstile: readTurnstileEnabled(),
           errorReportingOrigin: shell?.errorReportingOrigin,
           mapStyleOrigin,
           storageUploadOrigin: await readStorageUploadOrigin(ctx, reportStorageUploadOriginFailure),
 
@@ -79,6 +79,7 @@ import {
 } from './auth-schema-config.js';
 import { isPlaceholderEmail } from './placeholder-email.js';
 import { userInfoLocaleClaim } from './oidc-userinfo-locale-claim.js';
+import { buildTurnstileSignUpPlugin, reportHalfConfiguredTurnstile, resolveTurnstileKeys } from './turnstile-sign-up.js';
 
 /**
  * The `AuthManager` members the function below reads — every one of them, and
@@ -216,6 +217,17 @@ export async function buildPluginList(this: PluginListHost): Promise<any[]> {
   const { bearer } = await import('better-auth/plugins/bearer');
   plugins.push(bearer());
 
+  // Opt-in Cloudflare Turnstile on email sign-up: mounted only when BOTH keys
+  // are configured, through the same resolver `getPublicConfig()` advertises
+  // `features.turnstileSiteKey` from. Not an optional plugin: a guard that
+  // fails to build must fail the build, never leave sign-up open while the
+  // Console renders a widget. See `turnstile-sign-up.ts`.
+  reportHalfConfiguredTurnstile();
+  const turnstileKeys = resolveTurnstileKeys();
+  if (turnstileKeys) {
+    plugins.push(await buildTurnstileSignUpPlugin(turnstileKeys));
+  }
+
   if (enabled.organization) {
     // [#25224 cut 15] The body of this factory moved to
     // `auth-manager-organization-plugin.ts`; this arrow hands it the members
 
@@ -208,6 +208,7 @@ import { createAuthInstance, type AuthInstanceHost } from './auth-manager-auth-i
 // plugin's factory (cut 15) is now imported there, by the arrow that moved
 // with it.
 import { buildPluginList, type PluginListHost } from './auth-manager-plugin-list.js';
+import { resolveTurnstileKeys } from './turnstile-sign-up.js';
 
 /**
  * Detect WebContainer (StackBlitz) environment.
@@ -4551,6 +4552,7 @@ export class AuthManager {
     const privacyUrl = resolveLegalUrl(rawPrivacyUrl, DEFAULT_PRIVACY_URL);
 
     const twoFactorFromEnv = readBooleanEnv('OS_AUTH_TWO_FACTOR');
+    const turnstileKeys = resolveTurnstileKeys();
 
     // [#7481, maintainer ruling 2026-08-11] `passkeys` / `magicLink` are
     // deliberately NOT advertised here — see PUBLIC_AUTH_FEATURES_NOT_ADVERTISED
@@ -4616,6 +4618,10 @@ export class AuthManager {
       cloudManaged: isCloudManaged(),
       ...(termsUrl ? { termsUrl } : {}),
       ...(privacyUrl ? { privacyUrl } : {}),
+      // The PUBLIC Turnstile site key, served only when the sign-up challenge
+      // is wired (both keys set; the resolver `buildPluginList()` mounts the
+      // plugin from). The secret is never part of this payload.
+      ...(turnstileKeys ? { turnstileSiteKey: turnstileKeys.siteKey } : {}),
     };
 
     // Dev-only login hint (15.1 third-party eval): the empty-DB auto-seeded