fix(auth): app-declared org roles are storable, not just registerable (#3723)

`additionalOrgRoles` registered every `permission` / `position` name a stack
declared with better-auth's organization plugin, so
`POST /organization/invite-member { role: 'sales_rep' }` passed the role check
— and then the write failed, because `sys_invitation.role` and
`sys_member.role` were closed selects listing `owner|admin|member` only:

    ValidationError: role must be one of: owner, admin, member
      { field: 'role', code: 'invalid_option' }

A select is enforced on write and better-auth's own inserts are not exempt (they
run through the ordinary ObjectQL validator, after the security middleware), so
every deployment declaring role names was registering roles that could be
requested and never stored — `declared ≠ enforced` one layer below the
declaration.

Contract-first fix: one list, materialized into both consumers.

- `spec/identity/membership-role.ts` holds the built-in roles + their select
  options. `MEMBERSHIP_ROLE_DELEGATED_ADMIN` moves here from `eval-user.zod`
  (package-level export path unchanged).
- `plugin-auth/org-roles.ts` owns the derivation: `normalizeAdditionalOrgRoles`
  is the single normalizer, and its output feeds better-auth's role map AND the
  two select option lists (`withMembershipRoleOptions`, stamped onto the
  manifest at registration — copy-on-write, the shared definitions are never
  mutated). Neither side keeps a list of its own.
- `sys_invitation` / `sys_member` declare the built-in baseline only.
- `collectStackOrgRoles` is the one producer-side walk; `objectstack serve` and
  the `@objectstack/verify` harness both use it. The harness passed no roles at
  all, which is why the surface that drives the real HTTP route was blind to
  this class of bug.

A declared name that is not a valid machine name is now refused on BOTH sides
with a boot warning, rather than registered and then stored mangled:
`Field.select` strips characters outside `[a-z0-9_]`, so `showcase.export_data`
would be accepted as itself and written as `showcaseexport_data` — the same
mismatch with extra steps.

Verified: `app-org-role-invite.dogfood.test.ts` drives the real invite route on
the showcase stack and fails with the exact reported ValidationError when the
materialization step is removed.

Author: claude

.changeset/app-org-roles-storable.md

@@ -0,0 +1,54 @@
+---
+'@objectstack/platform-objects': patch
+'@objectstack/plugin-auth': patch
+'@objectstack/verify': patch
+'@objectstack/spec': patch
+'@objectstack/cli': patch
+---
+
+fix(auth): app-declared organization roles are now storable, not just registerable (#3723)
+
+`AuthManagerOptions.additionalOrgRoles` registered every `permission` /
+`position` name a stack declared with better-auth's organization plugin, so
+`POST /organization/invite-member { role: 'sales_rep' }` passed the role check —
+and then the write failed, because `sys_invitation.role` and `sys_member.role`
+were closed selects listing `owner|admin|member` only:
+
+```
+ValidationError: role must be one of: owner, admin, member
+  { field: 'role', code: 'invalid_option' }
+```
+
+A select is enforced on write and better-auth's own inserts are not exempt (they
+run through the ordinary ObjectQL validator), so any stack declaring role names
+was registering roles that could be requested and never stored.
+
+Both gatekeepers now read one list. `normalizeAdditionalOrgRoles` is the single
+normalizer; its output feeds better-auth's role map **and** the two `select`
+option lists, so neither side can accept a name the other rejects. The built-in
+roles (`owner`, `admin`, `delegated_admin`, `member`) live in
+`@objectstack/spec` as `BUILTIN_MEMBERSHIP_ROLE_OPTIONS`, which is all the
+platform objects declare statically — app roles are appended at boot.
+
+New exports:
+
+- `@objectstack/spec` — `MEMBERSHIP_ROLE_{OWNER,ADMIN,MEMBER,DELEGATED_ADMIN}`,
+  `BUILTIN_MEMBERSHIP_ROLES`, `BUILTIN_MEMBERSHIP_ROLE_OPTIONS`,
+  `MEMBERSHIP_ROLE_NAME_PATTERN`, `MEMBERSHIP_ROLE_NAME_MIN_LENGTH`
+  (`MEMBERSHIP_ROLE_DELEGATED_ADMIN` moved from `identity/eval-user.zod` to
+  `identity/membership-role`; the package-level export path is unchanged).
+- `@objectstack/plugin-auth` — `collectStackOrgRoles`,
+  `normalizeAdditionalOrgRoles`, `membershipRoleOptions`,
+  `withMembershipRoleOptions`.
+
+Hosts that boot `AuthPlugin` from a loaded stack should derive
+`additionalOrgRoles` with `collectStackOrgRoles(stack)` rather than walking the
+stack themselves — `objectstack serve` and the `@objectstack/verify` harness now
+both do (the harness previously passed none, which is why a dogfood proof could
+boot a stack whose declared roles better-auth had never heard of).
+
+Behaviour change worth noting: a declared role name that is not a valid machine
+name (`/^[a-z][a-z0-9_]*$/`, min 2 chars) is no longer registered at all, with a
+boot warning. `Field.select` strips characters outside `[a-z0-9_]`, so such a
+name would be registered verbatim and stored mangled — the same mismatch with
+extra steps. Every name that passes `SnakeCaseIdentifierSchema` is unaffected.

packages/cli/src/commands/serve.ts

@@ -1388,7 +1388,7 @@ export default class Serve extends Command {
       if (!hasAuthPlugin && tierEnabled('auth')) {
         try {
           const authPkg = '@objectstack/plugin-auth';
-          const { AuthPlugin } = await import(/* webpackIgnore: true */ authPkg);
+          const { AuthPlugin, collectStackOrgRoles } = await import(/* webpackIgnore: true */ authPkg);
 
           // In dev, fall back to a stable local secret so users don't have
           // to set OS_AUTH_SECRET just to try the login/register flow.
@@ -1485,40 +1485,20 @@ export default class Serve extends Command {
 
             // Collect application-defined org roles from the stack so
             // Better-Auth's organization plugin accepts invitations to
-            // those names (otherwise it 400s with `ROLE_NOT_FOUND`).
-            // better-auth boundary: its API keeps the word "roles"
-            // (ADR-0090 D3 exception). Sources:
-            //   - top-level `positions[]` (flat distribution groups)
-            //   - `permissions[]` PermissionSet names
-            // Real RBAC enforcement is still owned by SecurityPlugin.
-            const additionalOrgRoles = new Set<string>();
-            try {
-              const stackAny: any = config ?? {};
-              const collect = (arr: any) => {
-                if (!Array.isArray(arr)) return;
-                for (const r of arr) {
-                  const n = typeof r === 'string' ? r : (r && typeof r.name === 'string' ? r.name : null);
-                  if (n && n !== 'owner' && n !== 'admin' && n !== 'member') additionalOrgRoles.add(n);
-                }
-              };
-              collect(stackAny.positions);
-              if (Array.isArray(stackAny.permissions)) {
-                for (const p of stackAny.permissions) {
-                  if (p && typeof p.name === 'string') {
-                    if (p.name !== 'owner' && p.name !== 'admin' && p.name !== 'member') additionalOrgRoles.add(p.name);
-                  }
-                }
-              }
-            } catch {
-              // best-effort
-            }
+            // those names (otherwise it 400s with `ROLE_NOT_FOUND`) AND the
+            // `sys_invitation.role` / `sys_member.role` selects accept them on
+            // write. #3723: the walk lives in plugin-auth so `serve`, the
+            // `@objectstack/verify` harness and any embedder derive the list
+            // identically — a second copy of it here is how the harness came to
+            // boot without app roles while `serve` had them.
+            const additionalOrgRoles = collectStackOrgRoles(config);
 
             await kernel.use(new AuthPlugin({
               secret,
               baseUrl,
               socialProviders: Object.keys(socialProviders).length > 0 ? socialProviders : undefined,
               trustedOrigins: trustedOrigins.length ? trustedOrigins : undefined,
-              ...(additionalOrgRoles.size > 0 ? { additionalOrgRoles: Array.from(additionalOrgRoles) } : {}),
+              ...(additionalOrgRoles.length > 0 ? { additionalOrgRoles } : {}),
               // Enable the admin plugin by default so the Setup app's
               // ban/unban/set-password/impersonate/set-role row actions
               // resolve to real endpoints. The plugin self-gates by role

packages/platform-objects/src/identity/sys-invitation.object.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { ObjectSchema, Field } from '@objectstack/spec/data';
+import { BUILTIN_MEMBERSHIP_ROLE_OPTIONS, MEMBERSHIP_ROLE_MEMBER } from '@objectstack/spec/identity';
 
 /**
  * sys_invitation — System Invitation Object
@@ -196,22 +197,17 @@ export const SysInvitation = ObjectSchema.create({
       description: 'Email address of the invited user',
     }),
 
+    // [#3723] Same list as `sys_member.role`, from the same constant — this is
+    // the value that lands there on acceptance, so the two can never be allowed
+    // to drift. App-declared organization roles are appended at boot by
+    // plugin-auth's `withMembershipRoleOptions`, from the same normalized array
+    // that registers them with better-auth; do not hand-add one here.
     role: Field.select({
       label: 'Role',
       required: false,
       description: 'Role to assign upon acceptance',
-      options: [
-        { label: 'Owner', value: 'owner' },
-        { label: 'Admin', value: 'admin' },
-        // [ADR-0105 D8 / #3697] Kept in step with `sys_member.role` — this is
-        // the value that lands there on acceptance, and inviting is how a
-        // delegate gets provisioned in the first place. Both selects are
-        // enforced on write, so a role missing from either one is a role that
-        // cannot be handed out.
-        { label: 'Delegated Admin', value: 'delegated_admin' },
-        { label: 'Member', value: 'member' },
-      ],
-      defaultValue: 'member',
+      options: [...BUILTIN_MEMBERSHIP_ROLE_OPTIONS],
+      defaultValue: MEMBERSHIP_ROLE_MEMBER,
     }),
 
     status: Field.select(['pending', 'accepted', 'rejected', 'expired', 'canceled'], {

packages/platform-objects/src/identity/sys-member.object.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { ObjectSchema, Field } from '@objectstack/spec/data';
+import { BUILTIN_MEMBERSHIP_ROLE_OPTIONS, MEMBERSHIP_ROLE_MEMBER } from '@objectstack/spec/identity';
 
 /**
  * sys_member — System Member Object
@@ -165,27 +166,22 @@ export const SysMember = ObjectSchema.create({
       required: true,
     }),
 
+    // [#3723] The framework's built-in roles ONLY. App-declared organization
+    // roles are appended at boot by plugin-auth's `withMembershipRoleOptions`,
+    // from the SAME normalized array that registers them with better-auth —
+    // adding one by hand here re-creates the two-lists-that-must-agree bug.
+    //
+    // This select is ENFORCED on write: better-auth's own accept-invitation
+    // membership insert is validated like any other row (system context does
+    // not exempt it), so a role better-auth accepts and this list omits is a
+    // role nobody can hold. `delegated_admin` (ADR-0105 D8 / #3697) is in the
+    // built-in list for exactly that reason.
     role: Field.select({
       label: 'Role',
       required: false,
       description: 'Member role within the organization',
-      options: [
-        { label: 'Owner', value: 'owner' },
-        { label: 'Admin', value: 'admin' },
-        // [ADR-0105 D8 / #3697] The delegated issuer grade — may reach
-        // `/organization/invite-member` WITHOUT being an org admin, which is
-        // what finally gives D8's scope-bounded issuance gate a caller. It
-        // carries no ObjectStack authority by itself: placement authority
-        // comes from a separately-granted `adminScope`, and the invitation
-        // role cap holds it to inviting plain members.
-        //
-        // Listed here because this select is ENFORCED on write: better-auth's
-        // own accept-invitation membership insert is validated like any other
-        // row, so a role missing from this list is a role nobody can hold.
-        { label: 'Delegated Admin', value: 'delegated_admin' },
-        { label: 'Member', value: 'member' },
-      ],
-      defaultValue: 'member',
+      options: [...BUILTIN_MEMBERSHIP_ROLE_OPTIONS],
+      defaultValue: MEMBERSHIP_ROLE_MEMBER,
     }),
   },
 

packages/plugins/plugin-auth/src/auth-manager.test.ts

@@ -942,6 +942,23 @@ describe('AuthManager', () => {
       expect(orgPlugin._opts.roles.delegated_admin.statements.invitation).toEqual(['create']);
     });
 
+    it('#3723: a role name the write path cannot store is not registered either', async () => {
+      // `Field.select` strips the dot, so `showcase.export_data` would be
+      // registered with better-auth verbatim and stored as
+      // `showcaseexport_data` — the two lists agreeing on the name and
+      // disagreeing on the value is the original bug with extra steps.
+      // Refusing it here makes the invitation fail at the door
+      // (`ROLE_NOT_FOUND`) instead of at the `sys_invitation` insert.
+      const orgPlugin = await bootOrgPlugin({
+        additionalOrgRoles: ['showcase.export_data', 'sales_rep'],
+      });
+
+      const roles = orgPlugin._opts.roles;
+      expect(Object.keys(roles)).toContain('sales_rep');
+      expect(Object.keys(roles)).not.toContain('showcase.export_data');
+      expect(Object.keys(roles)).not.toContain('showcaseexport_data');
+    });
+
     it('role cap: a delegate inviting an `admin` is REFUSED (the escalation chain)', async () => {
       // delegate invites admin → sys_member(role='admin') → auto-org-admin-grant
       // → organization_admin → wildcard modifyAllRecords → isTenantAdmin().

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -21,6 +21,7 @@ import {
 import { MCP_OAUTH_SCOPES } from '@objectstack/spec/ai';
 import { createObjectQLAdapterFactory, withSystemReadContext } from './objectql-adapter.js';
 import { invitationRoleCapFailure, isPlainMemberInvitation } from './invitation-role-cap.js';
+import { normalizeAdditionalOrgRoles } from './org-roles.js';
 import { isPlaceholderEmail } from './placeholder-email.js';
 import { reconcileMembership, type MembershipPolicy } from './reconcile-membership.js';
 import type { TenancyService } from './tenancy-service.js';
@@ -1571,7 +1572,15 @@ export class AuthManager {
       // attribution — so the permission would mean "cancel anyone's pending
       // invitation in the org". Attributed cancel needs its own guard first.
       let customOrgRoles: Record<string, any> | undefined;
-      const extra = this.config.additionalOrgRoles ?? [];
+      // [#3723] The SAME normalized array `AuthPlugin` stamps onto the
+      // `sys_invitation.role` / `sys_member.role` selects. Registering a name
+      // the write path cannot store is the bug this closes, so a name that
+      // cannot round-trip through `Field.select` is refused HERE too — the
+      // invitation then fails at better-auth's door (`ROLE_NOT_FOUND`) rather
+      // than at the insert.
+      // (Idempotent: `AuthPlugin` normalizes before constructing the manager,
+      // so this pass only warns for a caller wiring `AuthManager` directly.)
+      const extra = normalizeAdditionalOrgRoles(this.config.additionalOrgRoles, this.config.logger);
       try {
         const accessMod = await import('better-auth/plugins/organization/access');
         const { defaultAc, memberAc, defaultRoles } = accessMod as any;

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -35,6 +35,7 @@ import {
   authIdentityObjects,
   authPluginManifestHeader,
 } from './manifest.js';
+import { normalizeAdditionalOrgRoles, withMembershipRoleOptions } from './org-roles.js';
 
 /**
  * Auth Plugin Options
@@ -200,8 +201,16 @@ export class AuthPlugin implements Plugin {
       ctx.logger.warn('No data engine service found - auth will use in-memory storage');
     }
 
+    // [#3723] Normalize the app-declared organization roles ONCE, here: the
+    // same array feeds better-auth's role registry (via AuthManager) and the
+    // `sys_invitation.role` / `sys_member.role` selects (via the manifest
+    // below). Two derivations from one caller-supplied list is exactly the
+    // drift that made a registered role unstorable.
+    const additionalOrgRoles = normalizeAdditionalOrgRoles(this.options.additionalOrgRoles, ctx.logger);
+
     const authConfig: AuthManagerOptions & AuthPluginOptions = {
       ...this.options,
+      additionalOrgRoles,
       dataEngine,
       logger: ctx.logger,
       // ADR-0093 D2/D3 — the membership reconciler consults the tenancy service
@@ -330,7 +339,14 @@ export class AuthPlugin implements Plugin {
       ...(this.options.manifestDatasource
         ? { defaultDatasource: this.options.manifestDatasource }
         : {}),
-      objects: authIdentityObjects,
+      // [#3723] App-declared organization roles widen the `sys_invitation.role`
+      // / `sys_member.role` selects, from the SAME normalized array that
+      // registers them with better-auth (`AuthManager`'s org-plugin roles map).
+      // Without this the two lists drift and a registered role is one
+      // better-auth accepts and the write path rejects — the registration is
+      // half a feature. Copy-on-write: `authIdentityObjects` is a shared
+      // module-level array, never mutated.
+      objects: withMembershipRoleOptions(authIdentityObjects, additionalOrgRoles),
       // ADR-0048 — Setup/Studio/Account apps (and the Setup nav contributions)
       // moved to their own one-app packages (@objectstack/{setup,studio,account}),
       // each registering under its own package id so /apps/<packageId> resolves

packages/plugins/plugin-auth/src/index.ts

@@ -30,4 +30,9 @@ export * from './auth-schema-config.js';
 // compose the reconciler into their own hooks; embeddings query tenancy mode).
 export * from './reconcile-membership.js';
 export * from './tenancy-service.js';
+// #3723 — organization roles. Exported because every host that boots AuthPlugin
+// from a loaded stack (`objectstack serve`, the @objectstack/verify harness, the
+// cloud per-project kernel) must derive `additionalOrgRoles` the SAME way; a
+// second copy of the walk is how the harness came to boot without app roles.
+export * from './org-roles.js';
 export type { AuthConfig, AuthProviderConfig, AuthPluginConfig } from '@objectstack/spec/system';

packages/plugins/plugin-auth/src/invitation-role-cap.ts

@@ -43,10 +43,16 @@
  * invitation is refused.
  */
 
-/** better-auth's built-in organization roles. */
-export const MEMBERSHIP_ROLE_OWNER = 'owner';
-export const MEMBERSHIP_ROLE_ADMIN = 'admin';
-export const MEMBERSHIP_ROLE_MEMBER = 'member';
+// better-auth's built-in organization roles — from the one membership-role
+// list (#3723), the same constants the `sys_invitation.role` / `sys_member.role`
+// selects are built from. Re-exported to keep this module's existing surface.
+import {
+  MEMBERSHIP_ROLE_OWNER,
+  MEMBERSHIP_ROLE_ADMIN,
+  MEMBERSHIP_ROLE_MEMBER,
+} from '@objectstack/spec/identity';
+
+export { MEMBERSHIP_ROLE_OWNER, MEMBERSHIP_ROLE_ADMIN, MEMBERSHIP_ROLE_MEMBER };
 
 /** Grade ladder. Anything unrecognized — `member`, `delegated_admin`, an
  *  app-registered role — grades as an ordinary member; only better-auth's two