feat(plugin-auth): opt-in Cloudflare Turnstile on email sign-up - #28365

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/cli, @objectstack/plugin-auth, @objectstack/spec, touching 25 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/api.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/connectors.mdx (via secretKey (symbol, a field of interface TurnstileKeys))
• content/docs/deployment/environment-variables.mdx (via OS_TURNSTILE_SECRET_KEY (literal, a string literal in TURNSTILE_SECRET_KEY_ENV; a string literal in readTurnstileEnabled), OS_TURNSTILE_SITE_KEY (literal, a string literal in TURNSTILE_SITE_KEY_ENV; a string literal in readTurnstileEnabled))
• content/docs/permissions/sso.mdx (via getPublicConfig (symbol, a method of class AuthManager))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5d32190efed8d46e7a84c82326efe07ad602ed07 && git checkout 5d32190efed8d46e7a84c82326efe07ad602ed07
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 6212fdc6feb192e46b158613d68c4fe12c0b03c8 6672c00912dcd22be450fca94dd69dc3368e35f2 && git checkout -B drift-repro 6212fdc6feb192e46b158613d68c4fe12c0b03c8 && git merge --no-ff 6672c00912dcd22be450fca94dd69dc3368e35f2

node scripts/docs-audit/affected-docs.mjs --json 6212fdc6feb192e46b158613d68c4fe12c0b03c8

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 6212fdc6feb192e46b158613d68c4fe12c0b03c8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Contract-review-claim: session_016WV4czuTWNgKR22fKv7jia · head 2cbc7763c768c53093be9b0d4db98b3e162bdbd3 · 2026-10-31T06:49Z

The lane seat runs the CONTRACT_REVIEW_TIER review this PR owes (Clause-②: yes, packages/spec/src/** paths).

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6672c00912dcd22be450fca94dd69dc3368e35f2
Local-runs: none
Scope: packages/spec/src/api/auth-endpoints.zod.ts, packages/spec/src/kernel/public-auth-features.ts + packages/spec/authorable-surface/api.json, content/docs/references/api/auth-endpoints.mdx, packages/plugins/plugin-auth/src/{turnstile-sign-up.ts, auth-manager-plugin-list.ts, auth-manager.ts, public-feature-registry.test.ts, turnstile-sign-up.test.ts}, packages/cli/src/utils/console.ts (+ its CSP test), ui/packages/auth/src/{types.ts, AuthContext.ts, AuthProvider.tsx, createAuthClient.ts, RegisterForm.tsx, TurnstileWidget.tsx, index.ts}, ui/packages/app-shell/src/{index.ts, console/auth/RegisterPage.tsx, console/auth/signUpRefusalMessages.ts}, ui/apps/console/src/pages/auth/{RegisterPage.tsx, SetupPage.tsx}, ui/packages/i18n/src/locales/*.ts, content/docs/deployment/environment-variables.mdx, .changeset/28100-turnstile-sign-up.md; better-auth 1.7.12 plugins/captcha read as the cited vendor code (tag source, not installed locally)

Delta reviewed: head moved from 2cbc7763 to 6672c009 by one changeset-only commit (2 lines: @objectstack/spec patch → minor, Metadata-protocol: none → added; the PR body line matches). No source changed; the code judgments below were made on 2cbc7763 and hold on 6672c009.

① Derived judgments

• File surface vs grant — all 39 files are inside triage's grants 6523361600 + 6524682167 + 6527231164 (ride-alongs included: regenerated api.json, auth-endpoints.mdx, tests beside changed files, the two /setup doubles gaining getAuthConfig, the changeset). No file outside the granted list. The PR body states the surface as the grant required.
• Spec change is logic-free (Prime Directive ✨ Set up Copilot instructions #2): one optional z.string() key with a describe, one literal appended to PUBLIC_AUTH_CONFIG_NON_FLAG_KEYS, plus JSDoc. api.json and auth-endpoints.mdx carry exactly the one generated row each, consistent with the schema; nothing hand-edited.
• Inert when unconfigured — one resolver (resolveTurnstileKeys) feeds both the plugin mount and getPublicConfig(); it returns a value only when BOTH env vars are set and non-blank (trimmed). Neither / one / blank ⇒ no plugin pushed, no features.turnstileSiteKey key present, CSP unchanged (the CLI reads presence of the same two names with the same trim rule). Pinned by plugin-auth test ③ (4 OFF variants) and the CSP test (4 OFF variants). Half-configuration is not silently half-on: it stays OFF and emits one build-time warn naming the variables only (pinned, and the no-Turnstile-noise case pinned too).
• Scope when on — captcha({ endpoints: ['/sign-up/email'] }); the vendor replaces its default list (/sign-up/email, /sign-in/email, /request-password-reset) when a non-empty list is given, so sign-in and reset stay unchallenged as the ruling orders; OAuth paths are not in the list. Pinned by test ②. Server-side auth.api.signUpEmail callers bypass the router stage the plugin hooks, so seeds are unaffected (matches vendor onRequest placement).
• Secret handling — the secret reaches only the vendor plugin's options and the siteverify POST body. getPublicConfig() spreads siteKey only; the half-config warning names variables not values; the vendor's failure log lines carry fixed messages / Cloudflare error codes / hostname, never the secret. Pinned by tests ①(4) and ④ (JSON.stringify(config) free of the secret; log lines free of it on the unreachable path).
• Fail-closed — vendor code read: no header ⇒ 400 MISSING_RESPONSE; siteverify success:false ⇒ 403 VERIFICATION_FAILED; fetch error / no data / 10s timeout ⇒ thrown ⇒ 500 UNKNOWN_ERROR. All three are the vendor's $ERROR_CODES constants (stable), named in the changeset, PR body and module docblock, and the first two map to one retry message in the Console (signUpRefusalMessages, RegisterForm, SetupPage).
• Clause-②: yes (widening) completeness — checked against the diff: spec keys ✓, two env vars ✓, @object-ui/auth exports (TurnstileWidget, TURNSTILE_SCRIPT_URL, three types) ✓, RegisterForm prop + two labels ✓, SignUpData.captchaToken ✓, signUp fifth optional arg (AuthContextValue and AuthProvider) ✓, @object-ui/app-shell signUpCaptchaFailedMessage ✓, the three refusal codes ✓. The changeset body omits the three type names the PR body lists; a documentation gap, not a contract gap (the exports are typed re-exports). Nothing narrowed: every new prop/arg/field is optional, existing signUp(name, email, password[, callbackURL]) callers and RegisterForm users compile and behave as before; getAuthConfig already existed on AuthContextValue on main.
• Env-var naming (Prime Directive [WIP] Create a new release version #9): OS_TURNSTILE_SITE_KEY / OS_TURNSTILE_SECRET_KEY group as OS_{DOMAIN}_{NAME} with the feature as domain, the shape OS_SSO_* / OS_SCIM_* already use; the card ordered these names and cloud's blocked card will configure them.
• CSP — minimal: one origin (https://challenges.cloudflare.com) in script-src, and frame-src 'self' + that origin, both only while readTurnstileEnabled(); off, frame-src is not emitted and default-src 'self' governs as before. No connect-src, no unsafe-inline; values never enter the header (pinned). ADR-0081's unsafe-eval rule for the react tier is untouched.
• Docs / i18n — one row in environment-variables.mdx, accurate to the code (both set ⇒ /sign-up/email incl. register + setup challenged; sign-in/reset not; only the site key served; one warn on half-config). Ten locales × exactly two keys (auth.register.captchaRetry, auth.register.errors.captchaFailed); en matches the in-code fallbacks. Docs-drift's connectors.mdx hit is a secretKey name collision; sso.mdx mentions only features.sso; neither needs a change. Skills-docs: None owed is correct: the grep over skills/ and content/docs finds only ui/forms.mdx (embeddable public forms, a different surface).
• Tests — each guard is pinned: ON ×4 (incl. no DB row and no siteverify call on refusal), scope ×1, OFF ×4 + warn ×2, public-config ×1, CSP ×5, UI wire ×4 (real AuthProvider + createAuthClient, header asserted on the wire, provider code never rendered, redraw after answer), page ×6 (render iff key served, submit held). The three ablations named in the PR body (mount, endpoint override, header) each red a distinct case, so they are meaningful.

② Semver level

• Metadata-protocol: added + @objectstack/spec: minor, others patch — correct on the delta head. turnstileSiteKey entered the packages/spec/authorable-surface/api.json shard, the baseline the ratchet records; AGENTS.md Post-Task Implement ObjectStack protocol specification with Zod schemas and TypeScript interfaces #3 makes none false there (the gate's none-baseline-moved refused 2cbc7763) and requires at least minor on the package carrying the kind. Spec, cli, plugin-auth, @object-ui/{auth,i18n,console} share changeset fixed-group 0, so the minor lifts them together; @object-ui/app-shell is private (privatePackages.version: true) and its patch entry is valid. The gate's discharged verdict ([finding] Check Changeset's clause-② level rule is PR-scoped but the fact it judges is package-scoped — a PR that widens package A is refused for grading package B patch, where B only received a comment #16361) covers a kind + one moved package at minor + others at patch.
• No (narrowing) arm, no BREAKING banner ⇒ no ADR-0087 marker owed. Both declaration lines are present and identical in the PR body and the changeset.

③ Boundary flags

• Author is objectstack-fleet[bot]; no external-author note.
• open_questions: [] on the dev report; none raised here.
• CI on the superseded head 2cbc7763 showed Check Changeset red (the baseline ruling this delta answers) and Lint & Repo Gates, TypeScript Type Check, Test UI red with the rest cancelled; job logs are not readable from this read-only seat. Landing precondition ② (every check green) is judged on 6672c009's own runs by the lane seat, not by this record.
• Opt-in posture is a rule, not a probe: with both variables set, /sign-up/email is the only challenged door; with either unset or blank, nothing is mounted, served, rendered or added to the policy. The configured branch has no local run behind it in this record (stubbed verifier in the PR's tests).
• Deviation 3 (plain plugins.push, not an optional plugin) is the right fail-closed choice: a guard that cannot build fails the auth build rather than leaving the door open under a rendered widget.

④ Design judgment

• auth-endpoints.zod.ts — turnstileSiteKey?: string on AuthFeaturesConfigSchema is the smallest contract that lets the Console learn "challenge on + which key" from the existing public config, following the termsUrl/privacyUrl pattern the card named. Presence-as-signal is sound because the server derives both mount and advertisement from one resolver, so the advertised widget and the enforced check cannot disagree. First consumer (AuthPublicConfig.features in @object-ui/auth, then RegisterForm/SetupPage) reads it exactly that way.
• public-auth-features.ts — appending to PUBLIC_AUTH_CONFIG_NON_FLAG_KEYS keeps the plugin-auth drift guard (served non-boolean keys ⊆ registry) honest; without it the guard would red when the key is served. The registry's own rule (served = declared) is preserved; no new flag class or parallel whitelist introduced (PD Remove explicit pnpm version from workflows to fix version conflict #7).
• Vendor fit: better-auth's captcha plugin is the mechanism the card named; the only vendor behaviour the design leans on is the endpoint-list override, which test ② pins so a future list change is caught. allowedHostnames / expectedAction left unset is consistent with the card (no configuration surface ordered); a follow-up card may add them.

Implemented-by: claude/project-thread-7tkjc8
Reviewed-by: session_016WV4czuTWNgKR22fKv7jia (seat subagent)

VERDICT: PASS

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Seat ACCEPT · PR #28365 · head 6672c00912dcd22be450fca94dd69dc3368e35f2 · 2026-10-31T08:08Z

维护者速读

• 改了什么： 邮箱注册可选接入 Cloudflare Turnstile 人机验证。只有 OS_TURNSTILE_SITE_KEY 和 OS_TURNSTILE_SECRET_KEY 都配上才生效；生效后只拦 /sign-up/email，登录、重置密码、OAuth 不受影响；Console 注册页和首次安装页显示验证组件。
• 为什么改： 公开注册的站点需要挡住机器批量注册（plugin-auth: opt-in Cloudflare Turnstile on email sign-up (server verify + Console widget), off unless a site key and secret are configured #28100，按你的「同意 A」）。
• 风险与回滚： 两个都不配时行为与现在逐字节一致（已钉）；只配一个会按名告警一次。secret 不下发、不记日志，只公开 site key。验证失败一律拒绝注册。Clause-②: yes (widening)，Metadata-protocol: added（spec 多一个可选键）。回滚即还原本 PR。
• 先看： plugin-auth 的 Turnstile 解析与挂载，以及 @object-ui/auth 的 TurnstileWidget。
• 两分钟验证： 跑 plugin-auth 的 turnstile 测试（不配、配一个、配两个三种情况）。
• 需要你做的： 无（Tier S，未命中受管面；契约复核 PASS 6540345632，按本期落地授权由席位落地）。

席位核对

• Shape: draft → main, Fixes #28100. 39 files (+1298/−13). check-governed-merges --pr 28365: NOT governed (0 of 39 paths).
• File surface: within the claim (6523573640) and the two cross-domain exceptions triage granted (6524682167, 6527231164). The review confirmed all 39 files are inside them.
• Declarations: Clause-②: yes (widening), Metadata-protocol: added. @objectstack/spec is minor because the key moves the authorable-surface shard; the other packages are patch, lifted by the fixed group.
• Contract review: CONTRACT_REVIEW_TIER, PASS at this head, 6540345632. The final commit only changes the changeset level; the code judgments were made at 2cbc7763 and carry over.
• Security wording: security card; the PR body, changeset and records stay at rule level.
• Local (card thread, after rebasing onto a0f86549): whole-tree build green; generated outputs unchanged; dispatch-gates 113/113, 0 NOT-MEASURED; pnpm lint 0; key suites green. Report 6540281599.
• Gate check-runs on this head: all green except one Check Changeset failure, which came from the 06:52Z run that read the PR body before the Metadata-protocol line was patched. The same check went green in the 06:53Z run on this head. mergeable_state: clean.
• Landing: Tier S, under the maintainer's landing grant for this term (2026-10-29T22:05Z, seat thread). Ready + auto-merge through the relay.

ACCEPT