M10.2: user invite + custom org roles

hotlong · Copilot · hotlong · commit 4135b515cfc3 · 2026-05-18T20:20:06.000+08:00
Wire CRM profile names (sales_rep, sales_manager, service_agent,
marketing_user, system_admin) through Better-Auth's organization
plugin so /api/v1/auth/organization/invite-member accepts invitations
to application-defined roles instead of rejecting them with
ROLE_NOT_FOUND.

Changes:
- AuthManagerOptions / AuthPluginOptions gain additionalOrgRoles:
  string[] forwarded into better-auth's organization() roles map.
- Each extra role is registered with defaultAc.newRole(memberAc.statements)
  so it satisfies better-auth's access-control validator with the same
  minimum capabilities as 'member'. Real RBAC enforcement remains in
  ObjectStack's SecurityPlugin, which matches role names against
  'permission' metadata (PermissionSets).
- Critical: re-include better-auth's built-in defaultRoles when
  populating roles, because hasPermission() does
  '{...options.roles || defaultRoles}' (|| then spread) and would
  otherwise drop owner/admin/member entirely, breaking the inviter.
- Default requireEmailVerificationOnInvitation:false since framework
  ships no mailer; operators wiring real email can opt back in.
- CLI serve.ts auto-collects roles from stack config: top-level
  roles[] and permissions[] with isProfile=true. Built-in
  owner/admin/member are filtered out.

Verified end-to-end with curl:
- POST invite-member role=sales_rep -&gt; 200 sys_invitation row
- POST invite-member role=service_agent -&gt; 200
- POST invite-member role=hacker -&gt; 400 ROLE_NOT_FOUND: hacker
- sign-up + accept-invitation -&gt; 200 sys_member.role=sales_rep
- sales_rep query against /api/v1/lead honours sharing rules (0 rows)
- admin retains owner privileges (no FORBIDDEN regression)

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
@@ -671,11 +671,43 @@ export default class Serve extends Command {
               if (!trustedOrigins.includes(wildcard)) trustedOrigins.push(wildcard);
             }
 
+            // Collect application-defined org roles from the stack so
+            // Better-Auth's organization plugin accepts invitations to
+            // those roles (otherwise it 400s with `ROLE_NOT_FOUND`).
+            // Sources:
+            //   - top-level `roles[]` (role hierarchy entries)
+            //   - `permissions[]` PermissionSets where `isProfile === true`
+            //     (these double as role identifiers; e.g. CRM Profiles)
+            // Real RBAC enforcement is still owned by SecurityPlugin, which
+            // matches these names against `permission` metadata entries.
+            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.roles);
+              if (Array.isArray(stackAny.permissions)) {
+                for (const p of stackAny.permissions) {
+                  if (p && typeof p.name === 'string' && p.isProfile !== false) {
+                    if (p.name !== 'owner' && p.name !== 'admin' && p.name !== 'member') additionalOrgRoles.add(p.name);
+                  }
+                }
+              }
+            } catch {
+              // best-effort
+            }
+
             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) } : {}),
               advanced: process.env.OS_COOKIE_DOMAIN
                 ? ({
                     crossSubDomainCookies: {
diff --git a/packages/plugins/plugin-auth/src/auth-manager.ts b/packages/plugins/plugin-auth/src/auth-manager.ts
@@ -53,6 +53,26 @@ export interface AuthManagerOptions extends Partial<AuthConfig> {
    * Each entry is passed to better-auth's genericOAuth plugin.
    */
   oidcProviders?: OidcProvidersConfig;
+
+  /**
+   * Application-specific organization roles to register with Better-Auth's
+   * organization plugin. Each name becomes a valid role for invitations and
+   * member assignments without going through Better-Auth's default
+   * `owner|admin|member` whitelist.
+   *
+   * The ObjectStack SecurityPlugin handles real RBAC enforcement by matching
+   * these role names against `permission` metadata (PermissionSets / Profiles),
+   * so Better-Auth only needs to accept them as opaque strings. Each role is
+   * registered with the minimum access-control privileges (equivalent to
+   * Better-Auth's `member` role) so it cannot inadvertently grant org-level
+   * admin capabilities.
+   *
+   * Typical source: the union of `permission` metadata names that have
+   * `isProfile: true`, collected from the loaded stack at CLI boot.
+   *
+   * @example ['sales_rep', 'sales_manager', 'service_agent']
+   */
+  additionalOrgRoles?: string[];
 }
 
 /**
@@ -248,6 +268,44 @@ export class AuthManager {
 
     if (enabled.organization) {
       const { organization } = await import('better-auth/plugins/organization');
+      // Build a `roles` map that registers each app-supplied org role
+      // (e.g. CRM's sales_rep, sales_manager) as a valid Better-Auth role
+      // so invitations to those roles aren't rejected with ROLE_NOT_FOUND.
+      // Real RBAC enforcement is handled by ObjectStack's SecurityPlugin,
+      // which matches the role name against `permission` metadata
+      // (PermissionSets). Here we register them with minimum org-plugin
+      // capabilities (same as the built-in `member` role) so they cannot
+      // inadvertently grant org-level admin powers.
+      let customOrgRoles: Record<string, any> | undefined;
+      const extra = this.config.additionalOrgRoles;
+      if (extra && extra.length > 0) {
+        try {
+          const accessMod = await import('better-auth/plugins/organization/access');
+          const stmtMod = await import('better-auth/plugins/organization/access/statement' as any).catch(() => null as any);
+          const { defaultAc, memberAc } = accessMod as any;
+          // Better-Auth's `hasPermission` does `{...options.roles || defaultRoles}`
+          // (precedence: `||` then spread). When we pass our own `roles`, the
+          // built-in owner/admin/member are silently dropped, so even the org
+          // owner loses `invitation:create` and every mutation 403s. We must
+          // re-include the defaults alongside our extras.
+          const defaultRoles =
+            (stmtMod && (stmtMod as any).defaultRoles) ||
+            (accessMod as any).defaultRoles ||
+            null;
+          if (defaultAc && memberAc && typeof memberAc.statements === 'object') {
+            const built: Record<string, any> = defaultRoles ? { ...defaultRoles } : {};
+            const stmts = memberAc.statements;
+            for (const name of extra) {
+              if (!name) continue;
+              if (built[name]) continue;
+              built[name] = defaultAc.newRole(stmts);
+            }
+            customOrgRoles = built;
+          }
+        } catch {
+          customOrgRoles = undefined;
+        }
+      }
       plugins.push(organization({
         schema: buildOrganizationPluginSchema(),
         // Enable the team sub-feature so the framework's `sys_team` /
@@ -258,6 +316,13 @@ export class AuthManager {
         // portal exposes a Teams page; without this flag those endpoints
         // 404 and the section silently breaks.
         teams: { enabled: true },
+        // Without a mailer wired in framework, requiring email verification
+        // before accepting invitations dead-ends every invite flow with
+        // FORBIDDEN EMAIL_VERIFICATION_REQUIRED…. Default-off here keeps
+        // the built-in /accept-invitation route usable for pilots; operators
+        // who wire a real mailer can re-enable downstream.
+        requireEmailVerificationOnInvitation: false,
+        ...(customOrgRoles ? { roles: customOrgRoles } : {}),
         // No mailer is wired in framework yet — log the accept URL so
         // operators / UI can fall back to copy-paste flows. Replace this
         // with a real mail integration when available.
diff --git a/packages/plugins/plugin-auth/src/auth-plugin.ts b/packages/plugins/plugin-auth/src/auth-plugin.ts
@@ -46,6 +46,14 @@ export interface AuthPluginOptions extends Partial<AuthConfig> {
    * project's own database — each project owns its own users.
    */
   manifestDatasource?: string;
+
+  /**
+   * Application-specific organization roles to register with Better-Auth's
+   * organization plugin so invitations to those roles aren't rejected with
+   * ROLE_NOT_FOUND. Forwarded as-is to AuthManager. See
+   * {@link AuthManagerOptions.additionalOrgRoles} for details.
+   */
+  additionalOrgRoles?: string[];
 }
 
 /**
