@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/lib/auth/org-permissions.ts

@@ -0,0 +1,55 @@
+/**
+ * Organization-scoped access control for Better Auth's organization plugin.
+ *
+ * Defines resources, actions, and roles that govern what org members
+ * can do within their organization. Exported for use in both the
+ * server config (server.ts) and client config (auth/client.ts).
+ *
+ * Role hierarchy: owner > admin > member
+ *
+ * | Resource      | member        | admin              | owner              |
+ * |---------------|---------------|--------------------|--------------------|
+ * | organization  | —             | —                  | update, delete     |
+ * | member        | —             | create,read,update,delete | create,read,update,delete |
+ * | connection    | read          | create,read,update,delete | create,read,update,delete |
+ * | conversation  | create,read   | create,read,delete | create,read,delete |
+ * | semantic      | read          | read,update        | read,update        |
+ * | settings      | read          | read,update        | read,update        |
+ */
+
+import { createAccessControl } from "better-auth/plugins/access";
+
+const statement = {
+  organization: ["update", "delete"],
+  member: ["create", "read", "update", "delete"],
+  connection: ["create", "read", "update", "delete"],
+  conversation: ["create", "read", "delete"],
+  semantic: ["read", "update"],
+  settings: ["read", "update"],
+} as const;
+
+export const ac = createAccessControl(statement);
+
+export const member = ac.newRole({
+  connection: ["read"],
+  conversation: ["create", "read"],
+  semantic: ["read"],
+  settings: ["read"],
+});
+
+export const admin = ac.newRole({
+  member: ["create", "read", "update", "delete"],
+  connection: ["create", "read", "update", "delete"],
+  conversation: ["create", "read", "delete"],
+  semantic: ["read", "update"],
+  settings: ["read", "update"],
+});
+
+export const owner = ac.newRole({
+  organization: ["update", "delete"],
+  member: ["create", "read", "update", "delete"],
+  connection: ["create", "read", "update", "delete"],
+  conversation: ["create", "read", "delete"],
+  semantic: ["read", "update"],
+  settings: ["read", "update"],
+});

package/templates/nextjs-standalone/src/lib/auth/permissions.ts

@@ -5,13 +5,16 @@
  * and the action's approval mode. Roles are extracted from the authenticated
  * user, with defaults that vary by auth mode.
  *
- * Role hierarchy: admin > analyst > viewer
+ * Role hierarchy: platform_admin > owner > admin > member
  *
- * | Approval mode | viewer | analyst | admin |
- * |---------------|--------|---------|-------|
- * | auto          | yes*   | yes*    | yes*  |
- * | manual        | no     | yes     | yes   |
- * | admin-only    | no     | no      | yes   |
+ * platform_admin is a global (cross-tenant) role for platform operators.
+ * The other three roles are workspace-scoped via Better Auth's org plugin.
+ *
+ * | Approval mode | member | admin | owner | platform_admin |
+ * |---------------|--------|-------|-------|----------------|
+ * | auto          | yes*   | yes*  | yes*  | yes*           |
+ * | manual        | no     | yes   | yes   | yes            |
+ * | admin-only    | no     | no    | yes   | yes            |
  *
  * * Auto-approved actions are executed immediately in handleAction and never
  *   reach the approval endpoint. canApprove returns true for any authenticated
@@ -30,9 +33,10 @@ const log = createLogger("auth:permissions");
 // ---------------------------------------------------------------------------
 
 const ROLE_LEVEL: Record<AtlasRole, number> = {
-  viewer: 0,
-  analyst: 1,
-  admin: 2,
+  member: 0,
+  admin: 1,
+  owner: 2,
+  platform_admin: 3,
 };
 
 // ---------------------------------------------------------------------------
@@ -42,14 +46,14 @@ const ROLE_LEVEL: Record<AtlasRole, number> = {
 /**
  * Default role for each auth mode when the user object does not carry
  * an explicit role.
- * - simple-key: analyst (overridable via ATLAS_API_KEY_ROLE)
- * - managed: viewer (role comes from Better Auth organization plugin)
- * - byot: viewer (role comes from JWT claim)
+ * - simple-key: admin (overridable via ATLAS_API_KEY_ROLE)
+ * - managed: member (role comes from Better Auth organization plugin)
+ * - byot: member (role comes from JWT claim)
  */
 const AUTH_MODE_DEFAULT_ROLE: Record<string, AtlasRole> = {
-  "simple-key": "analyst",
-  managed: "viewer",
-  byot: "viewer",
+  "simple-key": "admin",
+  managed: "member",
+  byot: "member",
 };
 
 /**
@@ -58,7 +62,7 @@ const AUTH_MODE_DEFAULT_ROLE: Record<string, AtlasRole> = {
  */
 export function getUserRole(user: AtlasUser): AtlasRole {
   if (user.role) return user.role;
-  return AUTH_MODE_DEFAULT_ROLE[user.mode] ?? "viewer";
+  return AUTH_MODE_DEFAULT_ROLE[user.mode] ?? "member";
 }
 
 /**
@@ -82,9 +86,12 @@ export function parseRole(value: string | undefined): AtlasRole | undefined {
  * Auto-approved actions bypass this check entirely (no human approval needed).
  */
 const APPROVAL_MODE_MIN_ROLE: Record<ActionApprovalMode, AtlasRole> = {
-  auto: "viewer", // Not actually checked — auto actions don't need approval
-  manual: "analyst",
-  "admin-only": "admin",
+  auto: "member", // Not actually checked — auto actions don't need approval
+  manual: "admin",
+  // "admin-only" requires the owner role. The name is a legacy holdover from
+  // when admin was the highest role. With the owner > admin > member hierarchy,
+  // this effectively means "owner-only". Renaming would be a config-breaking change.
+  "admin-only": "owner",
 };
 
 /**

package/templates/nextjs-standalone/src/lib/auth/server.ts

@@ -12,15 +12,212 @@
  */
 
 import { betterAuth } from "better-auth";
-import { bearer, admin } from "better-auth/plugins";
+import { bearer, admin, organization } from "better-auth/plugins";
 // @better-auth/api-key must match the better-auth core version.
 // Both are pinned to ^1.5.1 in package.json — update together.
 import { apiKey } from "@better-auth/api-key";
-import { getInternalDB, hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { scim } from "@better-auth/scim";
+import { stripe as stripePlugin } from "@better-auth/stripe";
+import Stripe from "stripe";
+import { getInternalDB, hasInternalDB, internalQuery, updateWorkspacePlanTier, type PlanTier } from "@atlas/api/lib/db/internal";
 import { createLogger } from "@atlas/api/lib/logger";
+import { isEnterpriseEnabled } from "@atlas/ee/index";
+import { ac, owner as ownerRole, admin as adminRole, member as memberRole } from "@atlas/api/lib/auth/org-permissions";
+import { adminAccessControl, adminRole as adminUserRole, platformAdminRole } from "@atlas/api/lib/auth/admin-permissions";
+import { getStripePlans } from "@atlas/api/lib/billing/plans";
+import { invalidatePlanCache } from "@atlas/api/lib/billing/enforcement";
+
+/**
+ * Build the socialProviders config from environment variables.
+ * Only providers with both CLIENT_ID and CLIENT_SECRET set are enabled.
+ * Returns undefined if no providers are configured.
+ */
+function buildSocialProviders(): Record<string, { clientId: string; clientSecret: string; tenantId?: string }> | undefined {
+  const providers: Record<string, { clientId: string; clientSecret: string; tenantId?: string }> = {};
+
+  if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+    providers.google = {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    };
+  }
+
+  if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+    providers.github = {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    };
+  }
+
+  if (process.env.MICROSOFT_CLIENT_ID && process.env.MICROSOFT_CLIENT_SECRET) {
+    providers.microsoft = {
+      clientId: process.env.MICROSOFT_CLIENT_ID,
+      clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
+      tenantId: process.env.MICROSOFT_TENANT_ID || "common",
+    };
+  }
+
+  return Object.keys(providers).length > 0 ? providers : undefined;
+}
 
 const log = createLogger("auth:server");
 
+/**
+ * Build the Better Auth plugins array.
+ *
+ * Stripe plugin is conditionally included when STRIPE_SECRET_KEY is set.
+ * This keeps all Stripe dependencies out of the module graph for
+ * self-hosted deployments that don't use billing.
+ */
+function buildPlugins() {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Better Auth plugin types are complex union types that vary by plugin combination
+  const plugins: any[] = [
+    bearer(),
+    apiKey(),
+    admin({
+      defaultRole: "member",
+      ac: adminAccessControl,
+      roles: {
+        admin: adminUserRole,
+        platform_admin: platformAdminRole,
+      },
+    }),
+    organization({
+      ac,
+      roles: { owner: ownerRole, admin: adminRole, member: memberRole },
+      async sendInvitationEmail(data) {
+        log.warn(
+          { email: data.email, orgName: data.organization.name, inviterId: data.inviter.user.id },
+          "Organization invitation created but email delivery is not configured — share the invite link manually",
+        );
+
+        // Trigger onboarding milestone for the inviter
+        try {
+          const { onTeamMemberInvited } = await import("@atlas/api/lib/email/hooks");
+          onTeamMemberInvited({
+            userId: data.inviter.user.id,
+            email: data.inviter.user.email,
+            orgId: data.organization.id,
+          });
+        } catch (err) {
+          log.debug(
+            { err: err instanceof Error ? err.message : String(err) },
+            "Onboarding hook not available — non-blocking",
+          );
+        }
+      },
+    }),
+  ];
+
+  // SCIM directory sync — enterprise only.
+  // No try/catch: if the plugin fails to initialize (missing dep, bad config),
+  // the auth server must fail to start rather than silently running without
+  // SCIM while the admin UI suggests it is available.
+  if (isEnterpriseEnabled()) {
+    plugins.push(
+      scim({
+        storeSCIMToken: "encrypted",
+        async beforeSCIMTokenGenerated(data) {
+          // Only admins can generate SCIM tokens — enforced via Better Auth hook.
+          // The admin check is done upstream by the admin route preamble;
+          // this hook acts as a defense-in-depth guard.
+          // Cast needed: the admin plugin adds `role` to the user object but the
+          // SCIM plugin's hook type only includes base user fields.
+          const user = data.user as Record<string, unknown> | undefined;
+          if (user?.role !== "admin" && user?.role !== "platform_admin") {
+            throw new Error("Only admin users can generate SCIM tokens.");
+          }
+        },
+      }),
+    );
+    log.info("SCIM directory sync plugin enabled (enterprise)");
+  }
+
+  // Stripe billing — only when STRIPE_SECRET_KEY is set (SaaS mode)
+  if (process.env.STRIPE_SECRET_KEY) {
+    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+    if (!webhookSecret) {
+      log.error(
+        "STRIPE_SECRET_KEY is set but STRIPE_WEBHOOK_SECRET is missing — "
+        + "Stripe plugin will NOT be enabled. Set STRIPE_WEBHOOK_SECRET to enable billing.",
+      );
+    } else {
+      try {
+        const stripeClient = new Stripe(process.env.STRIPE_SECRET_KEY);
+
+        plugins.push(
+          stripePlugin({
+            stripeClient,
+            stripeWebhookSecret: webhookSecret,
+            createCustomerOnSignUp: true,
+            subscription: {
+              enabled: true,
+              plans: getStripePlans(),
+              async onSubscriptionComplete({ subscription, plan }) {
+                const orgId = subscription.referenceId;
+                if (orgId && (plan.name === "team" || plan.name === "enterprise")) {
+                  try {
+                    await updateWorkspacePlanTier(orgId, plan.name as PlanTier);
+                    invalidatePlanCache(orgId);
+                    log.info({ orgId, plan: plan.name }, "Subscription activated — plan tier synced");
+                  } catch (err) {
+                    log.error(
+                      { err: err instanceof Error ? err.message : String(err), orgId, plan: plan.name },
+                      "Failed to sync plan tier on subscription activation — Stripe will retry webhook",
+                    );
+                    throw err;
+                  }
+                }
+              },
+              async onSubscriptionCancel({ subscription }) {
+                const orgId = subscription.referenceId;
+                if (orgId) {
+                  try {
+                    await updateWorkspacePlanTier(orgId, "free");
+                    invalidatePlanCache(orgId);
+                    log.info({ orgId }, "Subscription canceled — downgraded to free tier");
+                  } catch (err) {
+                    log.error(
+                      { err: err instanceof Error ? err.message : String(err), orgId },
+                      "Failed to downgrade plan on subscription cancel — Stripe will retry webhook",
+                    );
+                    throw err;
+                  }
+                }
+              },
+              async onSubscriptionDeleted({ subscription }) {
+                const orgId = subscription.referenceId;
+                if (orgId) {
+                  try {
+                    await updateWorkspacePlanTier(orgId, "free");
+                    invalidatePlanCache(orgId);
+                    log.info({ orgId }, "Subscription deleted — downgraded to free tier");
+                  } catch (err) {
+                    log.error(
+                      { err: err instanceof Error ? err.message : String(err), orgId },
+                      "Failed to downgrade plan on subscription delete — Stripe will retry webhook",
+                    );
+                    throw err;
+                  }
+                }
+              },
+            },
+          }),
+        );
+
+        log.info("Stripe billing plugin enabled");
+      } catch (err) {
+        log.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          "Failed to initialize Stripe billing plugin — billing features will be unavailable",
+        );
+      }
+    }
+  }
+
+  return plugins;
+}
+
 /**
  * Intentionally typed as the base Auth type (without plugin extensions).
  * The codebase only uses .handler, .api.getSession, and .$context — all of
@@ -82,6 +279,11 @@ export function getAuthInstance(): AuthInstance {
         ? `https://${process.env.VERCEL_URL}`
         : undefined);
 
+  const socialProviders = buildSocialProviders();
+  if (socialProviders) {
+    log.info({ providers: Object.keys(socialProviders) }, "Social login providers configured");
+  }
+
   const instance = betterAuth({
     // getInternalDB() returns a pg.Pool typed as InternalPool.
     // Cast needed because Better Auth expects its own pool/adapter type.
@@ -93,12 +295,13 @@ export function getAuthInstance(): AuthInstance {
       requireEmailVerification: false,
       autoSignIn: true,
     },
+    socialProviders,
     session: {
       expiresIn: 60 * 60 * 24 * 7,
       updateAge: 60 * 60 * 24,
       cookieCache: { enabled: true, maxAge: 5 * 60 },
     },
-    plugins: [bearer(), apiKey(), admin({ defaultRole: "analyst", adminRoles: ["admin"] })],
+    plugins: buildPlugins(),
     trustedOrigins:
       process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",")
         .map((s) => s.trim())
@@ -109,27 +312,170 @@ export function getAuthInstance(): AuthInstance {
       },
     } : undefined,
     databaseHooks: {
+      member: {
+        create: {
+          after: async (member: { role: string; userId: string; organizationId: string }) => {
+            // When a user becomes org "owner", promote their user-level role
+            // to "admin" so Better Auth's admin plugin APIs (list users,
+            // manage roles, etc.) work. Without this, org owners have
+            // user.role="member" and Better Auth blocks admin operations.
+            try {
+              if (member.role !== "owner") return;
+              if (!hasInternalDB()) return;
+
+              // Don't downgrade platform_admin → admin
+              const rows = await internalQuery<{ role: string | null }>(
+                `SELECT role FROM "user" WHERE id = $1 LIMIT 1`,
+                [member.userId],
+              );
+              const currentRole = rows[0]?.role;
+              if (currentRole === "admin" || currentRole === "platform_admin") return;
+
+              await getInternalDB().query(
+                `UPDATE "user" SET role = 'admin' WHERE id = $1`,
+                [member.userId],
+              );
+              log.info(
+                { userId: member.userId, orgId: member.organizationId },
+                "Promoted org owner to user-level admin",
+              );
+            } catch (err) {
+              log.warn(
+                { err: err instanceof Error ? err.message : String(err), userId: member.userId },
+                "Failed to promote org owner to admin — Better Auth admin APIs may return 403",
+              );
+            }
+          },
+        },
+      },
+      session: {
+        create: {
+          before: async (session) => {
+            // Auto-set the active org on login when the user has exactly one
+            // org and the session doesn't already have one. Uses the `before`
+            // hook so Better Auth writes the activeOrganizationId directly
+            // into the session row (no post-hoc UPDATE needed).
+            try {
+              if (session.activeOrganizationId) return;
+              if (!hasInternalDB()) return;
+
+              const orgs = await internalQuery<{ organizationId: string }>(
+                `SELECT "organizationId" FROM member WHERE "userId" = $1 LIMIT 2`,
+                [session.userId],
+              );
+              if (orgs.length !== 1) return;
+
+              log.info(
+                { userId: session.userId, orgId: orgs[0].organizationId },
+                "Auto-set active organization for new session",
+              );
+              return {
+                data: {
+                  ...session,
+                  activeOrganizationId: orgs[0].organizationId,
+                },
+              };
+            } catch (err) {
+              log.warn(
+                { err: err instanceof Error ? err.message : String(err), userId: session.userId },
+                "Failed to auto-set active org — user may need to switch manually",
+              );
+            }
+          },
+        },
+      },
       user: {
         create: {
           before: async (user) => {
             try {
               if (adminEmail && user.email?.toLowerCase().trim() === adminEmail) {
-                log.info({ email: user.email }, "Bootstrap: promoting signup to admin (ATLAS_ADMIN_EMAIL match)");
-                return { data: { ...user, role: "admin" } };
+                log.info({ email: user.email }, "Bootstrap: promoting signup to platform_admin (ATLAS_ADMIN_EMAIL match)");
+                return { data: { ...user, role: "platform_admin" } };
               }
 
               if (!adminEmail) {
                 if (!hasInternalDB()) return;
                 const rows = await internalQuery<{ id: string }>(
-                  `SELECT id FROM "user" WHERE role = 'admin' LIMIT 1`,
+                  `SELECT id FROM "user" WHERE role IN ('admin', 'platform_admin') LIMIT 1`,
                 );
                 if (rows.length === 0) {
-                  log.info({ email: user.email }, "Bootstrap: no admin exists — promoting first signup to admin");
-                  return { data: { ...user, role: "admin" } };
+                  log.info({ email: user.email }, "Bootstrap: no admin exists — promoting first signup to platform_admin");
+                  return { data: { ...user, role: "platform_admin" } };
                 }
               }
+
+            } catch (err) {
+              log.error({ err: err instanceof Error ? err.message : String(err) }, "Bootstrap admin check failed — defaulting to normal role assignment");
+            }
+          },
+          after: async (user) => {
+            // Onboarding welcome email — fire-and-forget after signup.
+            // Deferred with setTimeout to allow Better Auth to create the org/membership first.
+            if (user.email) {
+              const userEmail = user.email;
+              setTimeout(async () => {
+                try {
+                  const { onUserSignup } = await import("@atlas/api/lib/email/hooks");
+                  // Look up the user's first org membership
+                  const memberships = await internalQuery<{ organizationId: string }>(
+                    `SELECT "organizationId" FROM member WHERE "userId" = $1 LIMIT 1`,
+                    [user.id],
+                  );
+                  const orgId = memberships[0]?.organizationId;
+                  if (!orgId) {
+                    log.warn({ userId: user.id }, "No org membership found after signup — welcome email deferred to fallback scheduler");
+                    return;
+                  }
+                  onUserSignup({ userId: user.id, email: userEmail, orgId });
+                } catch (err) {
+                  log.warn(
+                    { userId: user.id, err: err instanceof Error ? err.message : String(err) },
+                    "Failed to trigger welcome email — non-blocking",
+                  );
+                }
+              }, 2000);
+            }
+
+            // Domain-based SSO auto-provisioning: if the user's email domain
+            // matches an enabled SSO provider, auto-add them to that org.
+            try {
+              if (!isEnterpriseEnabled() || !hasInternalDB() || !user.email) return;
+
+              const domain = user.email.split("@")[1]?.toLowerCase();
+              if (!domain) return;
+
+              const providers = await internalQuery<{ org_id: string }>(
+                `SELECT org_id FROM sso_providers WHERE domain = $1 AND enabled = true LIMIT 1`,
+                [domain],
+              );
+              if (providers.length === 0) return;
+
+              const orgId = providers[0].org_id;
+
+              // Check if already a member (idempotent)
+              const existing = await internalQuery<{ id: string }>(
+                `SELECT id FROM member WHERE "userId" = $1 AND "organizationId" = $2 LIMIT 1`,
+                [user.id, orgId],
+              );
+              if (existing.length > 0) return;
+
+              // Auto-add as member — awaited so failures are caught by the
+              // surrounding try/catch and logged as warnings.
+              await getInternalDB().query(
+                `INSERT INTO member (id, "organizationId", "userId", role, "createdAt")
+                 VALUES (gen_random_uuid(), $1, $2, 'member', now())`,
+                [orgId, user.id],
+              );
+
+              log.info(
+                { userId: user.id, email: user.email, domain, orgId },
+                "SSO auto-provisioning: user added to organization via domain match",
+              );
             } catch (err) {
-              log.error({ err }, "Bootstrap admin check failed — defaulting to normal role assignment");
+              log.warn(
+                { err: err instanceof Error ? err.message : String(err), userId: user.id },
+                "SSO auto-provisioning failed — user created but not auto-joined to org",
+              );
             }
           },
         },

package/templates/nextjs-standalone/src/lib/auth/simple-key.ts

@@ -61,11 +61,11 @@ export function validateApiKey(req: Request): AuthResult {
   const id = `api-key-${sha256(key).slice(0, 8)}`;
   const label = `api-key-${key.slice(0, 4)}`;
 
-  // Role override via ATLAS_API_KEY_ROLE (default: analyst — see permissions.ts)
+  // Role override via ATLAS_API_KEY_ROLE (default: admin — see permissions.ts)
   const rawRole = process.env.ATLAS_API_KEY_ROLE;
   const role = parseRole(rawRole);
   if (rawRole && !role) {
-    log.warn({ value: rawRole, validRoles: ["viewer", "analyst", "admin"] }, "ATLAS_API_KEY_ROLE is set to an invalid value — defaulting to 'analyst'. Valid values: viewer, analyst, admin.");
+    log.warn({ value: rawRole, validRoles: ["member", "admin", "owner"] }, "ATLAS_API_KEY_ROLE is set to an invalid value — defaulting to 'admin'. Valid values: member, admin, owner.");
   }
 
   // Parse optional claims from env var for RLS policy evaluation
@@ -87,6 +87,6 @@ export function validateApiKey(req: Request): AuthResult {
   return {
     authenticated: true,
     mode: "simple-key",
-    user: createAtlasUser(id, "simple-key", label, role, claims),
+    user: createAtlasUser(id, "simple-key", label, { role, claims }),
   };
 }

package/templates/nextjs-standalone/src/lib/auth/types.ts

@@ -4,46 +4,40 @@
  * AuthMode determines how requests are authenticated.
  * AtlasRole determines the user's permission level for action approval.
  * AtlasUser represents a verified identity attached to a request.
- * AuthResult is the return type from all auth validators.
  */
 
-export const AUTH_MODES = ["none", "simple-key", "managed", "byot"] as const;
-export type AuthMode = (typeof AUTH_MODES)[number];
+export { AUTH_MODES, ATLAS_ROLES } from "@useatlas/types/auth";
+export type { AuthMode, AtlasRole, AtlasUser } from "@useatlas/types/auth";
 
-export const ATLAS_ROLES = ["viewer", "analyst", "admin"] as const;
-export type AtlasRole = (typeof ATLAS_ROLES)[number];
-
-export interface AtlasUser {
-  id: string;
-  mode: Exclude<AuthMode, "none">;
-  label: string;
-  /** Permission role for action approval. Defaults based on auth mode when not set. */
-  role?: AtlasRole;
-  /** Auth-source claims for RLS policy evaluation (JWT payload, session user, or env-derived). */
-  claims?: Readonly<Record<string, unknown>>;
-}
+import type { AuthMode, AtlasRole, AtlasUser } from "@useatlas/types/auth";
 
 export type AuthResult =
   | { authenticated: true; mode: Exclude<AuthMode, "none">; user: AtlasUser }
   | { authenticated: true; mode: "none"; user: undefined }
-  | { authenticated: false; mode: AuthMode; status: 401 | 500; error: string };
+  | { authenticated: false; mode: AuthMode; status: 401 | 403 | 500; error: string; ssoRedirectUrl?: string };
+
+export interface CreateAtlasUserOptions {
+  role?: AtlasRole;
+  activeOrganizationId?: string;
+  claims?: Record<string, unknown>;
+}
 
 /** Create a frozen AtlasUser with non-empty id/label validation. */
 export function createAtlasUser(
   id: string,
   mode: Exclude<AuthMode, "none">,
   label: string,
-  role?: AtlasRole,
-  claims?: Record<string, unknown>,
+  options?: CreateAtlasUserOptions,
 ): AtlasUser {
   if (!id) throw new Error("AtlasUser id must be non-empty");
   if (!label) throw new Error("AtlasUser label must be non-empty");
-  const frozenClaims = claims ? Object.freeze({ ...claims }) : undefined;
+  const frozenClaims = options?.claims ? Object.freeze({ ...options.claims }) : undefined;
   return Object.freeze({
     id,
     mode,
     label,
-    ...(role ? { role } : {}),
-    ...(frozenClaims ? { claims: frozenClaims } : {}),
+    ...(options?.role !== undefined ? { role: options.role } : {}),
+    ...(options?.activeOrganizationId !== undefined ? { activeOrganizationId: options.activeOrganizationId } : {}),
+    ...(frozenClaims !== undefined ? { claims: frozenClaims } : {}),
   });
 }