`sys_member.role` app-role channel reverses ADR-0057 D4 ("never as the authority for RBAC") — pin to the built-ins before the next RC; placement is the governed channel

[os-zhuang]

> Revision 2 (2026-07-28, amended the same day): the first cut of this revision corrected the record — this issue was closed by #3747 (merged 2026-07-28 02:44Z, the same minute), not without rationale, and the reopen comment missed it — and recommended keeping #3747's landed design. The amendment reverses that recommendation. Two things were put back on the table: ADR-0057 D4 already decided this exact question, and the governed replacement (invitation placement, ADR-0105 D8) has already shipped. Earlier framings are summarized in History.

Where this stands (audited against main, 2026-07-28)

• The original symptom is fixed. fix(auth): app-declared org roles are storable, not just registerable (#3723) #3747 built the one list (normalizeAdditionalOrgRoles → better-auth's role map and both select option lists; built-ins in @objectstack/spec as BUILTIN_MEMBERSHIP_ROLE_OPTIONS), dogfood-proven end to end (app-org-role-invite.dogfood.test.ts).
• The "un-gated entrance" is no longer un-gated. Three gates: the invitation role cap (invitation-role-cap.ts:143-150 — below-admin issuers invite plain member only), fix(security): govern sys_member writes — membership is not a delegable capability (#3697 follow-up) #3767 (sys_member in GOVERNED_OBJECTS, tenant-admin-only, non-delegable), and better-auth's admin-grade ACL on update-member-role. Only tenant admins can hand out an app role, and they bypass D12 by design — the sub-admin escalation revision 1 was reopened for does not exist on main.
• But the channel itself was made deliberate: plugin-auth/src/org-roles.ts:61-69 documents the projection into grants.positions as "the intended channel (it is why apps declare these roles)".

Already decided — the doctrine exists, and #3747 reverses it

ADR-0057 D4 (accepted; status table: ✅ landed):

> sys_member.role is reframed to org-administration only (owner/admin/member) […]
> Continue feeding declared role names to better-auth additionalOrgRoles […] only so invitations to those role names are accepted — never as the authority for RBAC.

Consequences: "The model becomes self-owned: RBAC no longer borrows better-auth's membership role; better-auth is cleanly confined to identity + org-administration."

ADR-0095 D3 (accepted): better-auth role='admin' is "demoted to one source that grants that position (the existing mapMembershipRole normalization becomes a grant-provisioning concern, not an enforcement-time input)", and "no enforcement-time code path may consult the better-auth role directly".

ADR-0105 D8 conforms: delegated_admin "carries NO ObjectStack authority by construction […] Role = can reach the endpoint; adminScope = what the endpoint permits."

Against that: the projection union in resolve-authz-context.ts:305-324 is ADR-0057 D4's transition window ("union sys_member.role during a transition window"), not a contract — mapMembershipRole's default passthrough is its residue. #3747 took the residue and promoted it to "the intended channel", storable app roles included: an accepted ADR reversed by a patch-level changeset, with no superseding ADR. Revision 1's "option 4" was never a new proposal — it is the standing recorded doctrine.

The channel is also redundant — the governed one-step flow already shipped

Scoped invitation placement (ADR-0105 D8, .changeset/scoped-invitation-placement.md): an invitation carries business_unit_id + positions; issuance is dry-run through DelegatedAdminGate against the very sys_user_position rows acceptance would write; acceptance applies idempotently, failure-isolated.

	membership-role channel (#3747)	placement channel (shipped)
Who can issue	org owner/admin only (the cap holds delegates to member)	admins and delegated admins, inside subtree + allowlist
What acceptance writes	a role string on sys_member	real sys_user_position rows
Audit / validity	none — no granted_by, no ADR-0091 windows	full assignment-grade audit
Scope checks	none (its only issuers are admins, who bypass)	subtree, allowlist, strict containment
ADR status	reverses 0057 D4	implements 0105 D8

The governed path is a strict superset: more delegable, fully audited. The convenience channel's only unique behavior is storing a business-role label on the membership row — presentational, and derivable from positions.

Decision — default: enforce the ADR, before the next RC cut

.changeset/pre.json shows app-org-roles-storable is not consumed by any RC: cutting now removes a feature that never shipped. After the next RC cut it becomes a breaking removal. Plan:

1. Pin sys_member.role / sys_invitation.role to the four built-ins — BUILTIN_MEMBERSHIP_ROLE_OPTIONS becomes the whole list. Keep fix(auth): app-declared org roles are storable, not just registerable (#3723) #3747's one-list infrastructure; pinned, it is exactly "derive once the vocabulary is closed" from revision 1.
2. Stop registering app names with better-auth; deprecate the additionalOrgRoles app-role feed (collectStackOrgRoles) with a boot warning pointing at placement. An invitation naming an app role then fails loudly at the door (ROLE_NOT_FOUND) with a migration pointer, instead of being stored as un-governed authority.
3. Flip the dogfood (app-org-role-invite.dogfood.test.ts): the app-role invite is refused at the door; the same intent expressed as member + placement succeeds, governed.
4. ADR note (short amendment, not new doctrine): affirm 0057 D4 post-fix(auth): app-declared org roles are storable, not just registerable (#3723) #3747; name placement as the delegable capability channel; record the three-facts distinction (what names exist / which mean authority / how names project) so the next agent does not re-unify them.
5. Derive the closed vocabulary: lint's MEMBERSHIP_TIERS (validate-approval-approvers.ts:109-117 — hand-maintained, carries guest, absent from BUILTIN_MEMBERSHIP_ROLES; verify which is right) and objectui's mirror (feat(console): make delegated_admin reachable and narrow both role pickers (framework#3697) objectui#2891) read the four names from @objectstack/spec.

Keeping #3747 instead would mean superseding ADR-0057 D4 with a new ADR — and with placement shipped there is no DX case left to make in it; what remains is a label the console can render from positions.

Standing review-checklist item either way: any new surface that writes sys_member.role (SCIM group mapping, a future direct-write API) must carry the invitation cap's logic — #3767's gate is isSystem-short-circuited for every actual writer.

History

• Revision 0 (2026-07-27): filed as a list mismatch (better-auth registry vs the two closed selects, five copies, ValidationError). Symptom accurate; cause misattributed. Fixed by fix(auth): app-declared org roles are storable, not just registerable (#3723) #3747.
• Revision 1 (2026-07-28): reframed as "second, un-gated entrance to the position system". The gate asymmetry was closed by feat(auth): give ADR-0105 D8's scope-bounded issuance a caller — delegated_admin, capped (#3697) #3722's cap + fix(security): govern sys_member writes — membership is not a delegable capability (#3697 follow-up) #3767 while it was being written; the reopen premise ("nothing had addressed it") missed fix(auth): app-declared org roles are storable, not just registerable (#3723) #3747. Its option 4 turned out to be ADR-0057 D4's standing text, not a proposal.
• Revision 2, first cut (2026-07-28): corrected the record; recommended keeping the landed design. Amended hours later when ADR-0057 D4 / ADR-0095 D3 and the shipped placement channel were surfaced: the default flips to enforcing the ADR.

Related: #3697, #3722, #3747 (the reversal), #3767, objectstack-ai/objectui#2891 · ADR-0057 D4 · ADR-0095 D3 · ADR-0105 D8.

[os-zhuang]

⚠️ Reopened and rewritten — the finding got bigger, not smaller.

Two things changed since this was filed.

1. It was closed as completed (2026-07-28 02:44Z) without anything having addressed it. #3722 explicitly scoped it out — it added the delegated_admin value to the two selects, which this issue listed under "Not in scope here". The general case was untouched. Reopened; re-close if the closure was a deliberate wont-fix rather than triage noise, but please leave the reason.

2. The original framing was wrong about the cause. I filed this as a list-mismatch: two role lists that must agree, nothing keeping them in step. Verifying the projection path while implementing #3722 and #3767 showed that is the symptom.

resolve-authz-context.ts:305-322 pushes sys_member.role and sys_user_position.position into the same grants.positions array. A membership role is a position by another name — and the two doors are guarded asymmetrically: the position table sits behind DelegatedAdminGate (subtree anchoring, allowlist, strict containment, granted_by stamp); the membership role behind nothing. additionalOrgRoles is therefore a second entrance to the position system with none of ADR-0090 D12's controls.

That reframes the options:

• option 1 (open the two fields) makes app roles work by widening the un-gated door — the most tempting and the most wrong;
• option 2 (derive one list) makes five copies consistent, but making a wrong design reliable is not fixing it; it would fossilize "membership role = un-governed position" into a formal contract;
• option 3 (lint) is honest and worth doing first, but does not make app roles work.

The rewritten body recommends a fourth: retire the channel. Membership role = organization grade (a closed, framework-owned four-name vocabulary — the Field.selects are then correct as they stand); capability = positions, which already carry the full D12 apparatus. additionalOrgRoles deprecates toward sys_position + sys_user_position — exactly what ADR-0090 D3's rename was for. Only after the vocabulary is closed does deriving it (option 2) become worth the effort, and it then collapses three of the five copies.

Two corrections worth carrying forward regardless of which option wins:

• "Make it one list" is too coarse. Three different facts are tangled here — what names exist (the five duplicated lists), which names mean administrative authority (isAdminRole, the role-cap grade ladder, useIsWorkspaceAdmin), and how a name projects into positions (mapMembershipRole). Only the first is duplication. Unifying all three would be a modeling error.
• The migration is probably not a migration. The write path has never worked — an app-role invitation has always 400'd at the sys_invitation insert — so this is closer to removing a never-enforced feature than to migrating a live one. One thing to check before relying on that: whether any deployment already has custom values in sys_member.role (reachable only by direct DB write; expected zero).

Step 1 of the suggested order (the lint) needs no decision and can land immediately — say the word and I'll do it. Steps 2–4 need the founder call.

---

Generated by Claude Code