@intelligo-dev/auth 1.0.0-beta.1

package/src/helpers.ts

@@ -0,0 +1,317 @@
+/**
+ * Server-Side Auth Helpers
+ *
+ * Utilities for server components and server actions to check authentication.
+ * These helpers use Better-Auth's session API with Next.js headers.
+ *
+ * Usage in server actions (TECH-10 pattern):
+ * ```typescript
+ * export async function myServerAction() {
+ *   const { user } = await requireAuth();
+ *   // ... proceed with authenticated user
+ * }
+ * ```
+ */
+
+import { headers } from "next/headers";
+import { auth } from "./server";
+import { createLogger } from "@intelligo-dev/core/logger";
+import { db } from "@intelligo-dev/core/db";
+import { users } from "@intelligo-dev/core/db/schema";
+import { eq } from "drizzle-orm";
+import type { Session, User } from "better-auth/types";
+import { PLATFORM_ADMIN_ROLE } from "./roles";
+
+/** Valid Better-Auth workspace roles. Used to type-check allowedRoles in requireRole(). */
+export type WorkspaceRole = "owner" | "admin" | "member";
+
+const log = createLogger("Auth");
+
+/**
+ * Get current auth session from request headers.
+ *
+ * Returns session and user if authenticated, null otherwise.
+ * Use this in server components that handle both authenticated and unauthenticated states.
+ */
+export async function getAuthSession(): Promise<{
+  session: Session;
+  user: User;
+} | null> {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+
+  if (!session?.user) {
+    return null;
+  }
+
+  return {
+    session: session.session,
+    user: session.user,
+  };
+}
+
+/**
+ * Require authentication.
+ *
+ * Throws "Unauthorized" error if no valid session.
+ * Use this in server actions to enforce authentication (TECH-10 pattern).
+ *
+ * @throws Error with "Unauthorized" message if not authenticated
+ */
+export async function requireAuth(): Promise<{
+  session: Session;
+  user: User;
+}> {
+  const result = await getAuthSession();
+
+  if (!result) {
+    throw new Error("Unauthorized");
+  }
+
+  return result;
+}
+
+/**
+ * Get workspace context by organization ID.
+ * Use this when you know the org ID (e.g., just after creating/activating a workspace).
+ *
+ * @param organizationId - The organization ID to get context for
+ */
+export async function getWorkspaceContextById(organizationId: string): Promise<{
+  session: Session;
+  user: User;
+  workspace: { id: string; name: string; slug: string; logo?: string | null };
+  membership: { id: string; role: WorkspaceRole };
+} | null> {
+  const authResult = await getAuthSession();
+  if (!authResult) {
+    log.debug("getWorkspaceContextById: no auth session");
+    return null;
+  }
+
+  log.debug("getWorkspaceContextById: fetching org");
+
+  // Get organization by ID directly (not from session)
+  const org = await auth.api.getFullOrganization({
+    headers: await headers(),
+    query: { organizationId },
+  });
+
+  if (!org) {
+    log.debug("getWorkspaceContextById: org not found");
+    return null;
+  }
+
+  // Find user's membership
+  const membership = org.members?.find(
+    (m: any) => m.userId === authResult.user.id
+  );
+
+  if (!membership) {
+    log.debug("getWorkspaceContextById: user not a member");
+    return null;
+  }
+
+  return {
+    session: authResult.session,
+    user: authResult.user,
+    workspace: {
+      id: org.id,
+      name: org.name,
+      slug: org.slug,
+      logo: org.logo,
+    },
+    membership: {
+      id: membership.id,
+      role: membership.role,
+    },
+  };
+}
+
+/**
+ * Get workspace context from the active organization in session.
+ * Returns null if no active organization set.
+ *
+ * Use this in server components that need workspace context but can handle
+ * the absence of an active workspace (e.g., workspace switcher UI).
+ */
+export async function getWorkspaceContext(): Promise<{
+  session: Session;
+  user: User;
+  workspace: { id: string; name: string; slug: string; logo?: string | null };
+  membership: { id: string; role: WorkspaceRole };
+} | null> {
+  const authResult = await getAuthSession();
+  if (!authResult) {
+    log.debug("getWorkspaceContext: no auth session");
+    return null;
+  }
+
+  log.debug("getWorkspaceContext: session found");
+
+  // Get active organization from session
+  let activeOrg = await auth.api.getFullOrganization({
+    headers: await headers(),
+  });
+
+  log.debug("getWorkspaceContext: active org", { hasOrg: !!activeOrg });
+
+  // Fallback: If no active org in session, auto-select first available workspace
+  if (!activeOrg) {
+    log.debug("getWorkspaceContext: no active org, checking workspaces");
+    const orgs: any = await auth.api.listOrganizations({
+      headers: await headers(),
+    });
+
+    if (orgs && orgs.length > 0) {
+      log.debug("getWorkspaceContext: found workspaces", {
+        count: String(orgs.length),
+      });
+      // Fetch full organization details for the first workspace
+      activeOrg = await auth.api.getFullOrganization({
+        headers: await headers(),
+        query: { organizationId: orgs[0].id },
+      });
+    }
+  }
+
+  if (!activeOrg) {
+    log.debug("getWorkspaceContext: no workspaces found");
+    return null;
+  }
+
+  // Find user's membership in the active org
+  const activeMember = activeOrg.members.find(
+    (m: any) => m.userId === authResult.user.id
+  );
+
+  log.debug("getWorkspaceContext: membership check", {
+    hasMembership: !!activeMember,
+  });
+
+  if (!activeMember) {
+    log.debug("getWorkspaceContext: user not a member of active org");
+    return null;
+  }
+
+  return {
+    session: authResult.session,
+    user: authResult.user,
+    workspace: {
+      id: activeOrg.id,
+      name: activeOrg.name,
+      slug: activeOrg.slug,
+      logo: activeOrg.logo,
+    },
+    membership: {
+      id: activeMember.id,
+      role: activeMember.role,
+    },
+  };
+}
+
+/**
+ * Require workspace context. Use in server actions that need workspace scope (TECH-10).
+ * Throws if not authenticated OR no active workspace selected.
+ *
+ * Use this in server actions that operate on workspace-scoped resources
+ * (conversations, knowledge bases, usage logs, etc.).
+ *
+ * @throws Error with "No active workspace" message if no workspace selected
+ */
+export async function requireWorkspace(): Promise<{
+  session: Session;
+  user: User;
+  workspace: { id: string; name: string; slug: string; logo?: string | null };
+  membership: { id: string; role: WorkspaceRole };
+}> {
+  const context = await getWorkspaceContext();
+  if (!context) {
+    throw new Error("No active workspace");
+  }
+  return context;
+}
+
+/**
+ * Require specific role in active workspace.
+ * Use for admin/owner-only server actions (TEAM-08).
+ *
+ * Example: requireRole(["owner", "admin"]) for workspace settings actions.
+ *
+ * @param allowedRoles - Array of role names that are permitted
+ * @throws Error with "Insufficient permissions" message if user lacks required role
+ */
+export async function requireRole(allowedRoles: WorkspaceRole[]): Promise<{
+  session: Session;
+  user: User;
+  workspace: { id: string; name: string; slug: string; logo?: string | null };
+  membership: { id: string; role: WorkspaceRole };
+}> {
+  const context = await requireWorkspace();
+  if (!allowedRoles.includes(context.membership.role)) {
+    throw new Error("Insufficient permissions");
+  }
+  return context;
+}
+
+/**
+ * Require PLATFORM admin — distinct from workspace roles.
+ *
+ * Workspace `owner` is a per-tenant role: any user who creates a
+ * workspace owns it. Platform-level surfaces (cross-workspace
+ * analytics, the operational console, impersonation) must never be
+ * gated on it.
+ *
+ * The authority is `users.role`. PLATFORM_ADMIN_EMAILS is the
+ * bootstrap: an allowlisted user is promoted into the column the first
+ * time they pass through here, so a fresh deployment has a way in and
+ * every later check — including Better-Auth's admin plugin, which can
+ * only read the row — agrees with this one. Two gates that can
+ * disagree is how the cross-tenant analytics leak happened in the
+ * first place.
+ *
+ * Closed by default: no allowlist and no role means no admin.
+ *
+ * @throws Error("Insufficient permissions") when the user is not a
+ *   platform admin.
+ */
+export async function requirePlatformAdmin(): Promise<{
+  session: Session;
+  user: User;
+}> {
+  const { session, user } = await requireAuth();
+
+  const allowlist = (process.env.PLATFORM_ADMIN_EMAILS ?? "")
+    .split(",")
+    .map((e) => e.trim().toLowerCase())
+    .filter(Boolean);
+
+  const email = user.email?.toLowerCase();
+  const allowlisted = !!email && allowlist.includes(email);
+  const roles = ((user as { role?: string | null }).role ?? "")
+    .split(",")
+    .map((r) => r.trim());
+  const hasRole = roles.includes(PLATFORM_ADMIN_ROLE);
+
+  if (!allowlisted && !hasRole) {
+    throw new Error("Insufficient permissions");
+  }
+
+  // Promote on first use so the row, not the environment, is what
+  // every other check reads. A failure here must not lock an admin out
+  // mid-incident — they are already authorized by the allowlist.
+  if (allowlisted && !hasRole) {
+    const next = [...roles.filter(Boolean), PLATFORM_ADMIN_ROLE].join(",");
+    try {
+      await db.update(users).set({ role: next }).where(eq(users.id, user.id));
+    } catch (error) {
+      log.error("Failed to promote allowlisted platform admin", {
+        userId: user.id,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return { session, user };
+}

package/src/impersonation.ts

@@ -0,0 +1,57 @@
+import "server-only";
+
+/**
+ * Session-level impersonation.
+ *
+ * This module owns only the session mechanics, because that is what
+ * @intelligo-dev/auth owns: it holds the Better-Auth instance and the
+ * request headers. The *policy* — who may do it, that it is audited or
+ * refused, that a reason is mandatory — lives in @intelligo-dev/admin, and
+ * these functions must not be called without going through it.
+ *
+ * Nothing here re-checks authorization. Splitting the check from the
+ * act would give two places that can disagree about who is an admin,
+ * which is the mistake that put cross-tenant analytics behind a
+ * workspace role.
+ */
+
+import { headers } from "next/headers";
+
+import { auth } from "./server";
+
+export type ImpersonatedSession = {
+  targetUserId: string;
+  /** When Better-Auth will expire it — capped in the auth config. */
+  expiresAt: Date;
+};
+
+/** Default matching `impersonationSessionDuration` in server.ts. */
+const FALLBACK_DURATION_MS = 30 * 60_000;
+
+/**
+ * Swap the caller's session cookie for one belonging to `targetUserId`.
+ *
+ * Better-Auth refuses if the target is themselves a platform admin.
+ */
+export async function impersonateUser(
+  targetUserId: string
+): Promise<ImpersonatedSession> {
+  const result = (await auth.api.impersonateUser({
+    body: { userId: targetUserId },
+    headers: await headers(),
+  })) as { session?: { expiresAt?: string | Date } };
+
+  const expiresAt = result.session?.expiresAt;
+
+  return {
+    targetUserId,
+    expiresAt: expiresAt
+      ? new Date(expiresAt)
+      : new Date(Date.now() + FALLBACK_DURATION_MS),
+  };
+}
+
+/** Restore the admin's own session. */
+export async function stopImpersonating(): Promise<void> {
+  await auth.api.stopImpersonating({ headers: await headers() });
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * Better-Auth Server Exports
+ *
+ * Server-side authentication utilities.
+ * For client-side auth, use @intelligo-dev/auth/client
+ */
+
+export { auth } from "./server";
+export {
+  getAuthSession,
+  requireAuth,
+  getWorkspaceContext,
+  getWorkspaceContextById,
+  requireWorkspace,
+  requireRole,
+  requirePlatformAdmin,
+} from "./helpers";
+export { ensureUserWorkspace } from "./workspace-init";
+export type { WorkspaceRole } from "./helpers";
+export { PLATFORM_ADMIN_ROLE } from "./roles";
+export {
+  impersonateUser,
+  stopImpersonating,
+  type ImpersonatedSession,
+} from "./impersonation";
+
+// Re-export common types from Better-Auth
+export type { Session, User } from "better-auth/types";
+
+// Typed Better-Auth organization plugin wrapper
+export {
+  orgApi,
+  type OrgApi,
+  type OrgEndpointOptions,
+  type OrgRole,
+  type OrgListItem,
+  type OrgInvitation,
+  type OrgMember,
+} from "./org-api";
+
+// Team management service (page/registry migration, section C1)
+export {
+  createTeamService,
+  type TeamService,
+  type TeamServicePorts,
+} from "./team/service";
+export {
+  TeamServiceError,
+  isTeamServiceError,
+  type TeamServiceErrorCode,
+  type TeamServiceErrorMeta,
+} from "./team/errors";
+export {
+  inviteMemberSchema,
+  updateRoleSchema,
+  type InviteMemberInput,
+  type UpdateRoleInput,
+} from "./team/schemas";
+
+// Workspace management service (page/registry migration, workspace-settings family)
+export {
+  createWorkspaceService,
+  type WorkspaceService,
+  type WorkspaceServicePorts,
+  type WorkspaceRecord,
+} from "./workspace/service";
+export {
+  WorkspaceServiceError,
+  isWorkspaceServiceError,
+  type WorkspaceServiceErrorCode,
+  type WorkspaceServiceErrorMeta,
+} from "./workspace/errors";
+export {
+  createWorkspaceSchema,
+  updateWorkspaceSchema,
+  type CreateWorkspaceInput,
+  type UpdateWorkspaceInput,
+} from "./workspace/schemas";
+
+// Profile management service (page/registry migration, profile-settings family)
+export {
+  createProfileService,
+  type ProfileService,
+  type ProfileServicePorts,
+  type ProfileRecord,
+} from "./profile/service";
+export {
+  ProfileServiceError,
+  isProfileServiceError,
+  type ProfileServiceErrorCode,
+  type ProfileServiceErrorMeta,
+} from "./profile/errors";
+export {
+  updateProfileSchema,
+  type UpdateProfileInput,
+} from "./profile/schemas";
+
+// Onboarding service (page/registry migration, `onboarding` family)
+export {
+  createOnboardingService,
+  type OnboardingService,
+  type OnboardingState,
+} from "./onboarding/service";
+export {
+  OnboardingServiceError,
+  isOnboardingServiceError,
+  type OnboardingServiceErrorCode,
+} from "./onboarding/errors";
+export { setStepSchema, type SetStepInput } from "./onboarding/schemas";

package/src/onboarding/errors.ts

@@ -0,0 +1,52 @@
+/**
+ * Onboarding service error type.
+ *
+ * Mirrors `../team/errors.ts` and `../workspace/errors.ts`: the
+ * onboarding service (./service.ts) throws this for every failure it
+ * recognizes rather than returning an ad-hoc `{ success, error }`
+ * envelope — that shaping is a transport concern (a Server Action, a
+ * route handler) and belongs one layer up, alongside
+ * revalidatePath/Sentry/toast/i18n, none of which this package may
+ * depend on.
+ */
+
+/**
+ * - `forbidden` — the caller is unauthenticated.
+ * - `invalid_input` — `setStep`'s step id failed validation (empty or
+ *   over 64 characters — see `./schemas.ts`).
+ * - `not_found` — the caller's `users` row could not be found.
+ */
+export type OnboardingServiceErrorCode =
+  | "forbidden"
+  | "invalid_input"
+  | "not_found";
+
+export class OnboardingServiceError extends Error {
+  readonly code: OnboardingServiceErrorCode;
+
+  constructor(
+    code: OnboardingServiceErrorCode,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message);
+    this.name = "OnboardingServiceError";
+    this.code = code;
+    if (options?.cause !== undefined) {
+      // ES2020 target predates the standard `cause` constructor option;
+      // assign it directly so `instanceof Error` consumers (and Node's
+      // own error inspection) still see it.
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+
+    // Restore prototype chain (extending built-ins across some
+    // transpilation targets loses `instanceof`).
+    Object.setPrototypeOf(this, OnboardingServiceError.prototype);
+  }
+}
+
+export function isOnboardingServiceError(
+  error: unknown
+): error is OnboardingServiceError {
+  return error instanceof OnboardingServiceError;
+}

package/src/onboarding/schemas.ts

@@ -0,0 +1,27 @@
+/**
+ * Onboarding validation schema.
+ *
+ * A single generic step-id validator — see the module doc comment on
+ * `./service.ts` for why this is a bare, bounded string rather than a
+ * product-specific enum. Ignite's original
+ * `lib/validations/onboarding.ts` pinned this to
+ * `z.enum(["role", "profile", "complete"])`, Career's own 3-step wizard
+ * shape. The `users.onboarding_step` column itself is untyped `text`,
+ * so that enum was a product-level constraint bolted onto a generic
+ * column, not something this shared contract should require. A
+ * consumer defines its own step ids (typically the `id` field of a
+ * steps-config array it owns) and passes them straight through;
+ * Ignite's cut-over copy keeps its own enum-shaped schema at the
+ * transport layer if it wants stricter validation than "non-empty,
+ * bounded string".
+ */
+
+import { z } from "zod";
+
+export const setStepSchema = z
+  .string()
+  .trim()
+  .min(1, "Step id is required")
+  .max(64, "Step id must be at most 64 characters");
+
+export type SetStepInput = z.infer<typeof setStepSchema>;