admin-lifecycle: `remove-user` is non-atomic and can never succeed — 409 leaks as a bodyless HTTP 500, credential rows deleted without rollback

[huangyiirene]

Symptom

As a genuine better-auth admin, POST /api/v1/auth/admin/remove-user {userId} on a user that owns a record fails, and the failure is non-atomic:

• Observed: HTTP 500 with an empty body. sys_user is still readable; the owned record still carries its owner_id; and the user's credential sys_account rows have already been deleted — so that email can no longer sign in (401) while still occupying the org roster. Reproduced twice; verified across three victims (accounts=0 for all three vs accounts=1 for untouched users).
• Expected: 2xx, sys_user gone, the owned record surviving with owner_id cleared to null (engine FK clear).

The server log gives the real cause — a 409 leaking to the client as a bodyless 500:

Cannot delete sys_user (): 1 dependent sys_member record(s) reference it via user_id
(user_id is required, so it cannot be cleared)… set deleteBehavior:cascade on sys_member.user_id
{ code: DELETE_RESTRICTED, status: 409 }

Root cause

Three compounding problems, located on origin/main:

1. Every user is auto-bound to the default org at sign-up/create (the membership reconciler in packages/plugins/plugin-auth/src/reconcile-membership.ts runs as a user.create.after hook), and sys_member.user_id is a required FK with no cascade — packages/platform-objects/src/identity/sys-member.object.ts declares user_id: Field.lookup('sys_user', { required: true }) and sets no deleteBehavior:'cascade'. So the engine's referential restrict vetoes the sys_user delete every time — remove-user can never succeed on this deployment.
2. The operator cannot clear the blocker either. DELETE /api/v1/data/sys_member/{id} → 405 — sys-member.object.ts sets enable.apiMethods = ['get', 'list'] (writes owned by better-auth / refused by the identity write guard).
3. No rollback. The account/session deletions performed by better-auth's admin remove-user handler are not rolled back when the engine refuses the sys_user delete, leaving an orphaned, un-authenticatable identity on the roster.

On top of that, the engine's DELETE_RESTRICTED (409) surfaces through the better-auth admin route as a bodyless HTTP 500 rather than a structured 409 envelope (the generic REST data route maps this correctly in packages/rest/src/rest-server.ts, but the better-auth admin path does not).

This is not the #3023 owner-anchor regression — the veto comes from the engine's referential restrict on sys_member.user_id, not from the owner-anchor transfer guard.

The break-glass guard at packages/plugins/plugin-auth/src/auth-manager.ts (ctx.path === '/admin/remove-user') refuses removing the last local-credential holder, but does not cascade sys_member, roll back the credential deletes, or map the 409 — so none of the three problems above are addressed by it.

Reproduction

1. As a genuine better-auth admin: POST /api/v1/auth/admin/create-user {email:…} → 200.
2. Create a record owned by that user.
3. POST /api/v1/auth/admin/remove-user {userId}.
4. Observe HTTP 500 with an empty body; re-read shows sys_user still present, the record still owned, but the user's sys_account rows gone (subsequent sign-in 401).

Related

Shares the bodyless-500 statusCode-leak class with the invitation-acceptance failure from the same run — #7725 (accept-invitation → bodyless 500 on a UNIQUE-constraint collision).

Source

Extracted from the QA run #7663 (framework 92f26f7, console 09987b680).

[os-help]

PM triage (domain:identity seat, #6022, session session_01BVc1ekPpi6yaWywAUhfzfd): stays pm:queue, deliberately not dispatched yet — serialized behind #7725, which is in flight now.

The two cards are one family: both are rooted in the sign-up membership reconciler (reconcile-membership.ts) auto-binding every user to the default org, and both surface through the same bodyless-500 leak on the better-auth admin/organization routes. Dispatched in parallel they would produce two shapes for one problem on sys-member.object.ts and on the shared error mapping. #7725 owns acceptance-side adoption of the existing membership row and is explicitly forbidden from touching this card's surfaces.

This card's scope when it dispatches (recorded now so it is not re-derived later):

1. The sys_member.user_id referential-restrict veto — the engine's own error names deleteBehavior:'cascade' as the fix, and a membership row without its user is meaningless, so this looks decidable by the dev rather than by the maintainer; it will be dispatched with the instruction to verify that nothing depends on the restrict (e.g. as an accidental last-admin guard) before adding the cascade.
2. The non-atomicity — better-auth's remove-user deletes credential/session rows and does not roll them back when the engine refuses the sys_user delete, leaving an un-authenticatable identity on the roster. This is the harmful half: it fires today, on every attempt.
3. The bodyless-500 → structured-409 mapping on the better-auth admin path (packages/rest/src/rest-server.ts maps DELETE_RESTRICTED correctly on the generic data route; the admin path does not). Shared with invitation-scope-gates: accept-invitation → bodyless HTTP 500, invitation stays pending forever (UNIQUE constraint on sys_member) #7725's symptom — fixed once, here, unless invitation-scope-gates: accept-invitation → bodyless HTTP 500, invitation stays pending forever (UNIQUE constraint on sys_member) #7725's dev reports it needs its own card.

Also noted for whoever takes it: the operator cannot clear the blocker by hand either (DELETE /api/v1/data/sys_member/{id} → 405 from enable.apiMethods = ['get','list']), so "just delete the membership first" is not an available workaround, and the break-glass guard in auth-manager.ts addresses none of the three.

---

Generated by Claude Code

[os-help]

Input carried from the family's other half, now that #7725's PR (#7796) is reviewed and armed — read this before dispatching, it changes where the cheapest fix for problem 3 probably lives.

The bodyless-500 residue is confirmed, and it is not where the card assumed. #7725's dev traced it in better-auth 1.7.0-rc.2 source rather than inferring:

1. The rollback is better-auth's, not ours. crud-invites.mjs's runWithTransaction .catch sets the invitation back to pending (fromStatus: 'accepted') and rethrows. So fixing the error mapping alone makes the fault visible without stopping the state from reverting — worth knowing before someone concludes the mapping fix is sufficient.
2. The seam that produced the empty body may be one file away from the REST mapping. packages/plugins/plugin-auth/src/objectql-adapter.ts already has withValidationErrorMapping, which converts engine validation errors into better-auth APIErrors. A raw driver error — the UNIQUE violation here, and by extension a DELETE_RESTRICTED 409 — is not in that set, which is exactly why it escaped as a bodyless 500. Widening rethrowAsBetterAuthError may be cheaper and better-targeted than editing packages/rest/src/rest-server.ts's mapping, which was this card's assumed home for problem 3. Evaluate both when it dispatches; the reserved surface stays reserved either way.

What #7796 did NOT touch, so your three problems are all still yours: sys-member.object.ts is absent from its diff (FK, deleteBehavior, indexes untouched — the unique index is honoured, not modified), and the REST mapping is absent. Confirmed against the merged file list, not just the report.

One consequence of #7796 for this card's problem 1: acceptance now adopts the reconciler's row, so the "every user is already bound" invariant is now load-bearing on two paths rather than one. If you add deleteBehavior: 'cascade' to sys_member.user_id, the cascade will also remove memberships that acceptance adopted — which is correct (a membership without its user is meaningless) but means the delete path is now the only place that decides a membership's end, with no compensating record. Worth a test that removing a user who accepted an invitation leaves nothing behind.

---

Generated by Claude Code

[os-zhuang]

Selected for dispatch this patrol, then fenced — not dispatched. Recording why so the next sweep doesn't re-derive it.

This was the highest-severity card in pm:queue at 16:40Z and I intended to take it. It is blocked by lane serialization, not by anything on the card:

• Root cause 1 requires deleteBehavior: 'cascade' on packages/platform-objects/src/identity/sys-member.object.ts.
• platform-objects: 16 more actions declare both confirmText and params, so one click opens two sequential dialogs (same shape as #7278) #7309 was dispatched into packages/platform-objects at 16:36Z (sys-user, sys-oauth-application, sys-two-factor, sys-account, sys-organization, sys-sso-provider, sys-team-member).

sys-member.object.ts is not in #7309's file set, so the two cards touch disjoint files inside one package. Letting both run would be adopting the mutually-exclusive-region exemption, which has been raised with the maintainer and not ruled. The standing default is strict serialization, so the card waits. I am not taking the exemption on my own authority just because this card is the more serious of the two — that is precisely the pressure the default exists to resist.

Cost of the fence, stated plainly so the ruling can be made on evidence: this card is a live data-integrity defect — remove-user can never succeed on this deployment, and it deletes credential rows without rollback, leaving an un-authenticatable identity on the org roster. It is now waiting on a card about duplicate confirmation dialogs. If the exemption were granted, this would dispatch immediately.

Dispatch the moment #7309 lands (or the moment the exemption is ruled). Notes for whoever takes it:

• Three compounding problems plus a status-code leak — the card is explicit that the break-glass guard in auth-manager.ts addresses none of them. Do not let a fix for the 500-envelope stand in for the atomicity fix; a structured 409 on an operation that can never succeed is still an operation that can never succeed.
• Problem 2 (DELETE /api/v1/data/sys_member/{id} → 405, writes refused by the identity write guard) means the operator has no manual escape today. Whether that 405 is correct is a separate question from whether remove-user should cascade — settle the cascade first.
• Shares the bodyless-500 statusCode-leak class with invitation-scope-gates: accept-invitation → bodyless HTTP 500, invitation stays pending forever (UNIQUE constraint on sys_member) #7725. If the leak turns out to be one seam rather than two, that is a report — the two cards may want merging, but that is a PM call, not a scope-widening.
• The card already rules out the 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 owner-anchor regression; do not re-litigate it.

---

Generated by Claude Code