Repository navigation
Commit 9afcd6a
<!-- claude-projects-attribution: {"github_login":"os-bill"} -->
_Requested by **Bill** · [project
thread](https://claude.ai/code/project/chan_016iMXWSZDzqWRWvWzdNo8wg?thread=cmsg_016iMXWSZDzqWRWvWzdNo8wg1aFpHahTsprKPd3uPCkQ3d)_
domain:server#2 · os-bill · session_01Utp6Cbvcmv8YWFhFJwzjKL
## 维护者速读
-
改了什么:两步验证(twoFactor)没开时,组织上的「强制多因素认证」(`require_mfa`)不能从关改成开(新建即开同样不行),返回
400 并说明原因和出路(先开两步验证;环境变量没把它钉成关时,也可以开全局的
`auth.mfa_required`,它会连同注册入口一起打开)。已经存了开的组织行原样回存照常放行,不挡这一行的其它编辑。同时 MFA
闸门只拦「能去注册的人」:两步验证关着时,任何 MFA 要求都不拦人、不启动宽限期倒计时,服务端只打一条带修法的警告。
- 为什么改:之前管理员在 Setup 勾上这个框就能存,宽限期一过,全组织所有人(包括所有者)都被 403 MFA_REQUIRED
拦住并被引去注册,而注册接口 `POST /api/v1/auth/two-factor/enable` 因为插件没开直接 404;Setup
本身也在同一道闸后面,产品里没人能撤回,整个租户锁死。全局开关一直把「要求」和「注册入口」作为一整块打开,组织字段没有这层配对。
- 风险与回滚:这是一次收窄(Clause-② `no (narrowing)`):两步验证关着的部署上,以前能存的 `require_mfa
= true` 现在被拒。已经存了 `true`
的旧组织行不改动、也不再锁人;一旦打开两步验证,它就开始照常要求未注册成员(宽限期从那时起算)。两步验证开着的部署行为完全不变。回滚即撤本
PR。
-
先看:`packages/plugins/plugin-auth/src/organization-mfa-enrollment-guard.ts`(拒存规则与文案);`auth-manager-password-session-policy.ts`
里 `resolveUserAuthGates` 的 MFA 分支(两步验证关时不拦、不盖戳);`auth-manager.ts` 的
`resolveTwoFactorEnabled`(插件列表、`features.twoFactor`、闸门、拒存四处同一个答案)。
- 两分钟验证:`pnpm --filter @objectstack/plugin-auth exec vitest run
src/organization-mfa-enrollment-guard.test.ts`,预期 29/29
通过,其中端到端一组断言「两步验证关:注册接口 404,会话不被 MFA_REQUIRED 拦住」。
- 需要你做的:无,席位落地。界面半边(Setup 文案、注册失败的本地化提示)不在本卡,已列给席位另立。
Fixes #30201
Clause-②: no (narrowing) — while the two-factor feature is off, a write
that turns `sys_organization.require_mfa` on (an insert with it on, or
an update of a row that stores it off) is refused `400
VALIDATION_FAILED`, a value an administrator could save before;
re-saving a row that already stores it on passes. No published export,
error code or settings key is added; nothing is widened.
Metadata-protocol: none
Skills-docs: follow-up owed —
`content/docs/permissions/authentication.mdx` (the `mfa_required` row
says `require_mfa` is settable per organization with no condition; it
needs two-factor on). Not edited here: outside this card's file surface.
## Why
`sys_organization.require_mfa` is a generically editable extension
column, so an administrator could tick Require Multi-Factor Auth on an
organization's edit form and it saved, with two-factor off (the default,
`features.twoFactor: false`). Once the grace period ended, the ADR-0069
D3 gate held every unenrolled member `403 MFA_REQUIRED` and sent them to
enroll, and the enrollment endpoint (`POST
/api/v1/auth/two-factor/enable`) answered 404 because the twoFactor
plugin that serves it was never wired. Every member, the owner included,
was locked out, and nobody could undo it from inside the product,
because Setup sits behind the same gate. The global `auth.mfa_required`
setting never had this hole: its settings piece applies `{ mfaRequired:
true, plugins: { twoFactor: true } }` as one refusable patch. The
organization column had no such pairing.
## What changes
- **The refusal (route b).** A new `beforeInsert` / `beforeUpdate` hook
on `sys_organization` (`organization-mfa-enrollment-guard.ts`, priority
15, right after the ADR-0092 D2 identity write guard at 10) refuses,
while two-factor is off, a write that turns `require_mfa` on: an insert
with it on, or an update of a row whose stored value is off.
`validationFailure` from `@objectstack/types`, `400 VALIDATION_FAILED`,
one `fields[]` entry `{ field: 'require_mfa', code: 'invalid_value' }`
(the closed ADR-0114 catalog). The message says what was refused, why,
who would have been locked out (every member, the owner included) and
the ways forward; the `auth.mfa_required` remedy is offered only "unless
`OS_AUTH_TWO_FACTOR` is set to false", because the env var outranks the
settings. It is judged for every write context, the system's included
(the lockout does not depend on who wrote the row). The stored value is
the update context's `previous`, which the engine binds before
`beforeUpdate` on both update paths (the by-id row it read, and one
per-row context per matched row on a multi-row update, before anything
is written), so a multi-row update is judged row by row and one row
turning it on refuses the whole write with nothing written. An update
context without a `previous` is judged as a change. Re-sending
`require_mfa: true` for a row that already stores it (a whole-row SDK or
MCP update, an import re-run, a save with no change) passes, so the
row's other edits are not blocked; the gate does not enforce that stored
value while two-factor is off anyway. Clearing the column and writing
other columns pass untouched. Two-factor state is read per write from
the live `AuthManager`, so a settings pass that turns two-factor on
admits the next write with no restart.
- **Why refuse rather than pair (route a was measured and not taken).**
The twoFactor plugin's switch is process configuration: the settings
pass and the `OS_AUTH_TWO_FACTOR` env, re-applied at every boot and read
by the plugin-list builder. An organization row is data. Turning the
plugin on from an organization write would hold only in the process that
took the write, would not survive a restart or reach another node
(nothing that builds the plugin list reads organization rows), and
turning it back off when the last organization clears the column would
silently drop every enrolled member's second factor. So the card's
fallback is taken; the global switch keeps its existing pairing.
- **The gate fail-safe (ADR-0069 D3).** `resolveUserAuthGates` now holds
a user for MFA only while they can enroll. With two-factor off, an MFA
requirement (an organization's `require_mfa`, `auth.mfa_required` under
an `OS_AUTH_TWO_FACTOR=false` pin, or a host config with `mfaRequired`
but no `plugins.twoFactor`) yields no `MFA_REQUIRED` and stamps no
`mfa_required_at`; the manager logs one warning per process naming the
remedy. An organization row stored `require_mfa = true` before this
lands therefore locks nobody out. Enrolled users were never held and
still are not.
- **One answer for "is two-factor on".** `resolveTwoFactorEnabled` (env
`OS_AUTH_TWO_FACTOR`, then `plugins.twoFactor`, then off) is now the
single decision point for the better-auth plugin list,
`features.twoFactor` in `/api/v1/auth/config`, the gate and the refusal;
the two copies of the env read it replaces are gone. It is not
re-exported from `index.ts`. The live reading is
`AuthManager.isTwoFactorEnabled()`, a new public method on an exported
class, marked `@internal` (read by the gate and by the guard
`AuthPlugin` registers; not a supported entry point).
- **Registration.** `AuthPlugin` registers the guard in the
`kernel:ready` identity-guard block, right after
`registerApiKeyRestoreGuard`. This hunk is far from the
`email_password_enabled` settings apply that #30202 edits.
- **Existing tests that relied on the dead end.** Tests that turned on
`mfaRequired` without `plugins.twoFactor` (two `auth-manager.test.ts`
helpers, the impersonation policy fixture, and two `packages/verify`
held-session pins) now set `plugins: { twoFactor: true }`, which is the
only configuration in which the hold they pin can be complied with. In
`held-session-vendor-admin-doors`, the block whose hold only the
session's organization declares turns two-factor on in its own
`beforeAll` (and puts it back after) instead of inheriting it from the
held state that ran before; run alone it now passes 4/4, and without
that line its organization write is refused by the guard.
`held-session-platform-admin` already set `OS_AUTH_TWO_FACTOR=true`.
- Changeset `.changeset/30201-org-mfa-needs-enrollment.md` (`patch`, `!`
summary, **BREAKING** accept-set banner, ADR-0087 `not-required
(no-migration-prescription)` marker).
## Tests
- `organization-mfa-enrollment-guard.test.ts` (new, 29 tests):
- the rule on a capture engine: registration options, the off/on
predicate (`false`, `0`, `'0'`, `'false'`, `null`, `undefined` are off),
refusal while off, admission while on, an update refused for a row
stored off or with no `previous`, re-sending it for a row already on
admitted (an insert never is), other writes never judged, the message's
facts (the conditional settings remedy included) and no tracker number;
- `AuthPlugin` registration: `kernel:ready` registers both hooks on
`sys_organization` above D2's priority, and the captured handler refuses
while two-factor is off and admits after `applyConfigPatch({ plugins: {
twoFactor: true } })`;
- a real SQLite ObjectQL engine with `SysOrganization` and the D2 guard:
the administrator's by-id save is refused and the row keeps its value,
admitted once two-factor is on, refused for a system write, a multi-row
update and an insert; a row that already requires MFA re-saved with it
and another column passes while two-factor is off (the row stored off is
still refused); a multi-row update over one row on and one off is
refused with nothing written, and over rows all on it lands; other
writes pass;
- end to end on real better-auth: an organization stored `require_mfa =
true`, a member past the grace window, `active_organization_id` set.
Two-factor off: `POST /two-factor/enable` answers 404, the session's
`authGate` is not `MFA_REQUIRED`, `resolveUserAuthGates` returns `[]`,
the warning fires once and the clock is not restamped. Two-factor on:
`authGate` is `MFA_REQUIRED` and `/two-factor/enable` answers 200 with a
`totpURI`.
- `auth-manager.test.ts`: "only a user who can enroll is held" (no hold,
no stamp, one warning per manager whose settings remedy is conditional
on the env var; an `OS_AUTH_TWO_FACTOR=false` pin outranks
`plugins.twoFactor` and `features.twoFactor` reads false; control with
two-factor on), plus the per-org case (no block and no clock while off).
- **Ablations** on `9b256807` (every negative pin, via
`scripts/ablation-replace.mjs` in wrap mode, each restore proven blob ==
HEAD; plugin-auth tests import their source, so no build sits between
mutation and run):
- A, guard `throw` deleted: 5 red (the rule's refusal, the registration
pin, the real-engine admin, system and multi-row refusals).
- B, gate fail-safe neutralized: 4 red, including the end-to-end pin
`expected 'MFA_REQUIRED' not to be 'MFA_REQUIRED'`.
- C, registration in `auth-plugin.ts` deleted: the registration pin red
(`expected [] to deeply equal [[beforeInsert…],[beforeUpdate…]]`).
- D, env precedence dropped from `resolveTwoFactorEnabled`: the env-pin
test red (`expected true to be false`).
- **Ablations, review round** on `f643025e`, same method:
- F, the unchanged-value pass deleted: 3 red (the rule's re-send case,
the real-engine re-save, the multi-row case's landing half).
- G, a context without `previous` treated as already on: 3 red (`the
write was admitted`).
- H, the settings remedy made unconditional: the message pin red.
- E, the organization block's own two-factor arming deleted
(`packages/verify`, run alone): its `beforeAll` fails on the guard's
`ValidationError`, 28 skipped.
## Acceptance notes
- **The `domain:ui` half is not here** (the UI lane is off duty): the
Setup copy on the organization form (who is affected, when the block
starts), and a localized enrollment refusal saying what to do. The
server's refusal text above is what the form shows until then.
- Under an `OS_AUTH_TWO_FACTOR=false` pin, the settings console still
shows `auth.mfa_required` as saved; the gate now does not enforce it
(and says so in the log). Before this PR such a deployment held users it
could not enroll.
- A user whose `mfa_required_at` was stamped before this lands, on a
deployment that later turns two-factor on, is held as soon as it is on,
because the stamp is older than the grace window. They can enroll at
that point, which is the difference from today.
- This relaxes a security hold on deployments where two-factor is off: a
configured MFA requirement is no longer enforced there. That is
deliberate (the dispatch's fail-safe): the hold could not be complied
with and locked the tenant out; the warning names the remedy.
## Verification
Suites, typecheck, gates and the full dogfood battery ran on the final
tree, head `05e6e0bd` (the review fixes `f643025e` merged with `main` at
`8b117c0e`; neither `main` merge touched a file in `plugin-auth` or
`packages/verify`). The first-round ablations ran on `9b256807`, the
review-round ones on `f643025e`.
<details><summary>Suites and typecheck (head 05e6e0b, under
scripts/pm/os-verify-lock.sh)</summary>
- `pnpm --filter @objectstack/plugin-auth exec vitest run
--maxWorkers=2`: Test Files 221 passed (221), Tests 3909 passed, 10
skipped. VERDICT command-exit 0.
- `pnpm --filter @objectstack/plugin-auth typecheck`: VERDICT
command-exit 0 (the test-typecheck ratchet holds).
- `pnpm --filter @objectstack/verify exec vitest run` on
`held-session-impersonation-target`, `held-session-vendor-admin-doors`
and `held-session-platform-admin`: Test Files 3 passed, Tests 49 passed.
VERDICT command-exit 0. The organization-declared block alone (`-t
'organization declares'`): 4 passed, 24 skipped.
</details>
<details><summary>Full dogfood battery (owed by the narrowing
arm)</summary>
`pnpm --filter @objectstack/dogfood test` on `05e6e0bd`, under
`scripts/pm/os-verify-lock.sh`: VERDICT command-exit 0 (held the lock
1182s, shared box); Test Files 419 passed, 3 skipped (422); Tests 3492
passed, 36 skipped (3528); no failure. The one red the first round saw
on `8c4430f5` (`permission-set-clone-door.dogfood.test.ts`, from
#30222's `member_default` grant, measured green with that file put back)
is gone: `main` reverted #30222 (#30262) and this head carries the
revert.
</details>
<details><summary>Gates</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` on `05e6e0bd`: 64 derived, each run with its
exit code recorded before any pipe. A session restart cut the first pass
after 60 (all exit 0); the other 4 were re-run: `check:type-check-debt`
exit 0 under the lock, `check:undeclared-dep-imports` and
`check:where-matcher` exit 0, and `check:watch-hint-literal` exit 1 on a
`packages/spec/tsup.config.bundled_*.mjs` temp file that the concurrent
locked build wrote and removed mid-scan (ENOENT), then exit 0 re-run
with no build in flight. `--ran` over the final record: 64 derived, 64
run, 0 NOT-MEASURED, 0 UNRUN, exit 0. `pnpm lint` exit 0.
</details>
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic
(`packages/spec` not touched).
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes (reading under
Verification).
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: n/a.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English (the 维护者速读 block is
Chinese by the Communication rule).
---
_Generated by [Claude
Code](https://claude.ai/code/session_01Utp6CYRZxPEjGeTbGfW4YC)_
<!-- signed: domain:server#2 · os-bill ·
session_01Utp6Cbvcmv8YWFhFJwzjKL -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1c53783 commit 9afcd6a
10 files changed
Lines changed: 794 additions & 12 deletions
File tree
- .changeset
- packages
- plugins/plugin-auth/src
- verify/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
62 | 62 | | |
63 | 63 | | |
64 | 64 | | |
| 65 | + | |
65 | 66 | | |
| 67 | + | |
66 | 68 | | |
67 | 69 | | |
68 | 70 | | |
| |||
136 | 138 | | |
137 | 139 | | |
138 | 140 | | |
139 | | - | |
| 141 | + | |
140 | 142 | | |
141 | 143 | | |
142 | 144 | | |
| |||
205 | 207 | | |
206 | 208 | | |
207 | 209 | | |
208 | | - | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
209 | 225 | | |
210 | 226 | | |
211 | 227 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
71 | 71 | | |
72 | 72 | | |
73 | 73 | | |
| 74 | + | |
74 | 75 | | |
75 | 76 | | |
76 | 77 | | |
| |||
188 | 189 | | |
189 | 190 | | |
190 | 191 | | |
191 | | - | |
192 | 192 | | |
193 | 193 | | |
194 | 194 | | |
195 | | - | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
196 | 199 | | |
197 | 200 | | |
198 | 201 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3876 | 3876 | | |
3877 | 3877 | | |
3878 | 3878 | | |
3879 | | - | |
| 3879 | + | |
| 3880 | + | |
3880 | 3881 | | |
3881 | 3882 | | |
3882 | 3883 | | |
| |||
4695 | 4696 | | |
4696 | 4697 | | |
4697 | 4698 | | |
| 4699 | + | |
| 4700 | + | |
4698 | 4701 | | |
4699 | 4702 | | |
4700 | | - | |
| 4703 | + | |
| 4704 | + | |
| 4705 | + | |
4701 | 4706 | | |
4702 | 4707 | | |
4703 | 4708 | | |
| |||
4749 | 4754 | | |
4750 | 4755 | | |
4751 | 4756 | | |
| 4757 | + | |
| 4758 | + | |
| 4759 | + | |
| 4760 | + | |
| 4761 | + | |
| 4762 | + | |
| 4763 | + | |
| 4764 | + | |
| 4765 | + | |
| 4766 | + | |
| 4767 | + | |
| 4768 | + | |
| 4769 | + | |
| 4770 | + | |
| 4771 | + | |
| 4772 | + | |
| 4773 | + | |
| 4774 | + | |
| 4775 | + | |
| 4776 | + | |
| 4777 | + | |
| 4778 | + | |
| 4779 | + | |
| 4780 | + | |
| 4781 | + | |
| 4782 | + | |
| 4783 | + | |
| 4784 | + | |
| 4785 | + | |
| 4786 | + | |
| 4787 | + | |
| 4788 | + | |
| 4789 | + | |
| 4790 | + | |
| 4791 | + | |
| 4792 | + | |
| 4793 | + | |
| 4794 | + | |
| 4795 | + | |
| 4796 | + | |
| 4797 | + | |
| 4798 | + | |
| 4799 | + | |
| 4800 | + | |
| 4801 | + | |
| 4802 | + | |
| 4803 | + | |
| 4804 | + | |
| 4805 | + | |
| 4806 | + | |
| 4807 | + | |
| 4808 | + | |
| 4809 | + | |
| 4810 | + | |
| 4811 | + | |
| 4812 | + | |
| 4813 | + | |
4752 | 4814 | | |
4753 | 4815 | | |
4754 | 4816 | | |
| |||
4766 | 4828 | | |
4767 | 4829 | | |
4768 | 4830 | | |
| 4831 | + | |
4769 | 4832 | | |
4770 | 4833 | | |
4771 | | - | |
| 4834 | + | |
| 4835 | + | |
| 4836 | + | |
4772 | 4837 | | |
4773 | 4838 | | |
4774 | 4839 | | |
| |||
4803 | 4868 | | |
4804 | 4869 | | |
4805 | 4870 | | |
| 4871 | + | |
| 4872 | + | |
| 4873 | + | |
| 4874 | + | |
| 4875 | + | |
| 4876 | + | |
| 4877 | + | |
| 4878 | + | |
| 4879 | + | |
| 4880 | + | |
| 4881 | + | |
4806 | 4882 | | |
4807 | 4883 | | |
4808 | 4884 | | |
| |||
0 commit comments