@intelligo-dev/auth 1.0.0-beta.1

package/src/workspace/schemas.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace Validation Schemas
+ *
+ * Zod schemas for workspace create/update inputs, shared by the
+ * workspace service and its transports.
+ *
+ * (Ported from the product application's workspace validation module —
+ * same semantics. Ignite's copy is retired at cutover.)
+ */
+
+import { z } from "zod";
+
+/**
+ * Create Workspace Schema
+ * Name + optional slug for new workspaces
+ */
+export const createWorkspaceSchema = z.object({
+  name: z
+    .string()
+    .min(2, "Workspace name must be at least 2 characters")
+    .max(50, "Workspace name must be at most 50 characters"),
+  slug: z
+    .string()
+    .min(2, "Slug must be at least 2 characters")
+    .max(50, "Slug must be at most 50 characters")
+    .regex(
+      /^[a-z0-9-]+$/,
+      "Slug can only contain lowercase letters, numbers, and hyphens"
+    )
+    .optional(), // Auto-generated from name if not provided
+});
+
+export type CreateWorkspaceInput = z.infer<typeof createWorkspaceSchema>;
+
+/**
+ * Update Workspace Schema
+ * Optional name, slug, and logo for workspace settings
+ */
+export const updateWorkspaceSchema = z.object({
+  name: z
+    .string()
+    .min(2, "Workspace name must be at least 2 characters")
+    .max(50, "Workspace name must be at most 50 characters")
+    .optional(),
+  slug: z
+    .string()
+    .min(2, "Slug must be at least 2 characters")
+    .max(50, "Slug must be at most 50 characters")
+    .regex(
+      /^[a-z0-9-]+$/,
+      "Slug can only contain lowercase letters, numbers, and hyphens"
+    )
+    .optional(),
+  logo: z.string().url("Logo must be a valid URL").optional().nullable(),
+});
+
+export type UpdateWorkspaceInput = z.infer<typeof updateWorkspaceSchema>;

package/src/workspace/service.ts

@@ -0,0 +1,381 @@
+/**
+ * Workspace management service — the durable business rules behind
+ * workspace listing, creation, switching, editing and deletion,
+ * extracted from the product application's workspace actions (page/
+ * registry migration, `workspace-settings` family, roadmap item 8).
+ *
+ * Mirrors `createTeamService(ports)` (./../team/service.ts) one
+ * directory over: a factory over optional ports, so this package's
+ * allowlisted dependency (`@intelligo-dev/core` only — see
+ * tests/architecture/dependency-direction.test.ts) never grows to
+ * include billing. A consumer binds that in at its composition root:
+ *
+ *   const workspaceService = createWorkspaceService({
+ *     checkWorkspaceLimit: ...,   // adapts @intelligo-dev/billing's checkPlanLimit
+ *   });
+ *
+ * Authorization (`requireAuth`/`requireWorkspace`/`requireRole`) lives
+ * INSIDE each method, not at the transport. Every recognized failure
+ * throws `WorkspaceServiceError` with a stable `code` — no
+ * revalidatePath/Sentry/next-intl/toast here; that shaping is the
+ * transport's job (a Server Action, a route handler).
+ *
+ * ---------------------------------------------------------------------
+ * Why `checkWorkspaceLimit` takes a `userId`, not a `workspaceId`
+ * ---------------------------------------------------------------------
+ * `createWorkspace` has no workspace to check the plan of yet — it is
+ * the thing being created. Ignite's original action worked around this
+ * by reading the caller's *existing* workspaces and using the first
+ * one's id to look up a plan via `@intelligo-dev/billing`'s
+ * `checkPlanLimit(workspaceId, "workspaces", currentCount)`, i.e. it
+ * borrowed an arbitrary existing workspace's subscription as a stand-in
+ * for "the caller's plan". That borrowing is a binding-layer concern,
+ * not a service-layer one: this service only knows the caller's
+ * `userId` and how many workspaces they already have. The composition
+ * root's binding (`checkWorkspaceLimit`) is where a consumer decides
+ * how to resolve "this user's plan" — by reading their first workspace
+ * the same way ignite did, or by a real per-user plan lookup if one
+ * exists.
+ *
+ * ---------------------------------------------------------------------
+ * The two Better-Auth pitfalls (already solved in ../team/service.ts —
+ * copied here rather than re-derived)
+ * ---------------------------------------------------------------------
+ * 1. Method-name mismatch: the typed `orgApi` wrapper (../org-api.ts)
+ *    exists precisely because `auth.api`'s organization-plugin methods
+ *    are keyed by their own camelCase *server* id, which does not
+ *    always match the HTTP path or the client SDK name. This service
+ *    uses `orgApi["/organization/list"]` and
+ *    `orgApi["/organization/set-active"]` for the two calls the
+ *    wrapper covers, and calls `auth.api.{createOrganization,
+ *    updateOrganization, deleteOrganization, getFullOrganization}`
+ *    directly for the base organization CRUD surface, which is not
+ *    part of `orgApi`'s typed table (the same approach
+ *    `../team/service.ts` takes for `getFullOrganization`). Ignite's
+ *    original `actions/workspace.ts` already called these four by
+ *    their correct `auth.api` names directly (it never went through a
+ *    path-keyed cast), so there is no method-name bug to fix here.
+ * 2. `sessions.activeOrganizationId` does not exist on this repo's
+ *    Drizzle schema. Ignite's original `getActiveWorkspace()` called
+ *    `auth.api.getFullOrganization({ headers })` with no
+ *    `organizationId` — the exact bug documented in
+ *    `../team/service.ts`'s module comment: that resolves to *no*
+ *    organization regardless of what the caller most recently
+ *    activated. This service's `getActiveWorkspace` instead resolves
+ *    the caller's workspace via `requireWorkspace()` first (which has
+ *    its own explicit-id fallback) and passes that id explicitly to
+ *    `getFullOrganization`.
+ */
+
+import { headers } from "next/headers";
+import type { ZodType } from "zod";
+import { createLogger } from "@intelligo-dev/core/logger";
+
+import { auth } from "../server";
+import { requireAuth, requireRole, requireWorkspace } from "../helpers";
+import { orgApi, type OrgListItem } from "../org-api";
+import {
+  createWorkspaceSchema,
+  updateWorkspaceSchema,
+  type CreateWorkspaceInput,
+  type UpdateWorkspaceInput,
+} from "./schemas";
+import { WorkspaceServiceError, isWorkspaceServiceError } from "./errors";
+
+const log = createLogger("WorkspaceService");
+
+/** Minimal organization shape returned by create/update/getActiveWorkspace. */
+export interface WorkspaceRecord {
+  id: string;
+  name: string;
+  slug: string;
+  logo?: string | null;
+  [key: string]: unknown;
+}
+
+export type WorkspaceServicePorts = {
+  /**
+   * Plan-defined workspace cap for the caller. No port ⇒ unlimited (no
+   * gate applied) — matches "no billing dependency without one bound
+   * explicitly" (ADR-0005). Not consulted when the caller has zero
+   * existing workspaces (their first workspace is always allowed) —
+   * see the module doc comment for why the port is keyed by `userId`
+   * rather than `workspaceId`.
+   */
+  checkWorkspaceLimit?: (
+    userId: string,
+    currentCount: number
+  ) => Promise<{ allowed: boolean; limit: number }>;
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Maps requireAuth/requireWorkspace/requireRole failures to `forbidden`. */
+function toForbidden(error: unknown): WorkspaceServiceError {
+  if (isWorkspaceServiceError(error)) return error;
+  return new WorkspaceServiceError("forbidden", errorMessage(error), {
+    cause: error,
+  });
+}
+
+function parseInput<T>(schema: ZodType<T>, input: unknown): T {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    throw new WorkspaceServiceError(
+      "invalid_input",
+      result.error.issues.map((issue) => issue.message).join("; ") ||
+        "Invalid input",
+      { cause: result.error }
+    );
+  }
+  return result.data;
+}
+
+/** Derives a URL-safe slug base from a workspace name. */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, 50);
+}
+
+export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
+  async function callRequireAuth() {
+    try {
+      return await requireAuth();
+    } catch (error) {
+      throw toForbidden(error);
+    }
+  }
+
+  async function callRequireWorkspace() {
+    try {
+      return await requireWorkspace();
+    } catch (error) {
+      throw toForbidden(error);
+    }
+  }
+
+  async function callRequireRole(
+    allowedRoles: Array<"owner" | "admin" | "member">
+  ) {
+    try {
+      return await requireRole(allowedRoles);
+    } catch (error) {
+      throw toForbidden(error);
+    }
+  }
+
+  /** Wraps a Better-Auth org-plugin call; unrecognized failures become `provider_error`. */
+  async function callOrgApi<T>(
+    context: string,
+    fn: () => Promise<T>
+  ): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      if (isWorkspaceServiceError(error)) throw error;
+      log.error("Org API call failed", { context, error: errorMessage(error) });
+      throw new WorkspaceServiceError(
+        "provider_error",
+        `Better-Auth organization API call failed (${context})`,
+        { cause: error }
+      );
+    }
+  }
+
+  /**
+   * List all workspaces for the current user.
+   */
+  async function listWorkspaces(): Promise<OrgListItem[]> {
+    await callRequireAuth();
+    const hdrs = await headers();
+
+    const orgs = await callOrgApi("list", () =>
+      orgApi["/organization/list"]({ headers: hdrs })
+    );
+
+    return orgs ?? [];
+  }
+
+  /**
+   * Create a new workspace. Auto-generates a slug from the name if not
+   * provided, and appends a uniqueness suffix (Better-Auth requires
+   * unique slugs). The caller's first workspace is always allowed; the
+   * limit port, when bound, gates every workspace after that. The new
+   * workspace is auto-activated on success.
+   */
+  async function createWorkspace(
+    input: CreateWorkspaceInput
+  ): Promise<WorkspaceRecord> {
+    const { user } = await callRequireAuth();
+    const validated = parseInput(createWorkspaceSchema, input);
+    const hdrs = await headers();
+
+    const existing = await callOrgApi("list", () =>
+      orgApi["/organization/list"]({ headers: hdrs })
+    );
+    const existingCount = existing?.length ?? 0;
+
+    if (ports.checkWorkspaceLimit && existingCount > 0) {
+      const limitCheck = await ports.checkWorkspaceLimit(
+        user.id,
+        existingCount
+      );
+      if (!limitCheck.allowed) {
+        throw new WorkspaceServiceError(
+          "workspace_limit_reached",
+          `Your plan allows up to ${limitCheck.limit} workspace${
+            limitCheck.limit === 1 ? "" : "s"
+          }. Upgrade to create more workspaces.`,
+          { meta: { limit: limitCheck.limit } }
+        );
+      }
+    }
+
+    const slugBase = validated.slug || slugify(validated.name);
+    // Append timestamp for uniqueness (Better-Auth requires unique slugs).
+    const slug = `${slugBase}-${Date.now().toString(36)}`;
+
+    const org = (await callOrgApi("create", () =>
+      auth.api.createOrganization({
+        headers: hdrs,
+        body: { name: validated.name, slug },
+      })
+    )) as WorkspaceRecord | null;
+
+    if (!org) {
+      throw new WorkspaceServiceError(
+        "provider_error",
+        "Failed to create workspace"
+      );
+    }
+
+    await callOrgApi("set-active", () =>
+      orgApi["/organization/set-active"]({
+        headers: hdrs,
+        body: { organizationId: org.id },
+      })
+    );
+
+    return org;
+  }
+
+  /**
+   * Switch the caller's active workspace.
+   */
+  async function switchWorkspace(organizationId: string): Promise<void> {
+    await callRequireAuth();
+
+    if (typeof organizationId !== "string" || organizationId.length === 0) {
+      throw new WorkspaceServiceError("invalid_input", "Invalid workspace id");
+    }
+
+    const hdrs = await headers();
+
+    await callOrgApi("set-active", () =>
+      orgApi["/organization/set-active"]({
+        headers: hdrs,
+        body: { organizationId },
+      })
+    );
+  }
+
+  /**
+   * Update workspace settings (name/slug/logo). Owner/admin only.
+   */
+  async function updateWorkspace(
+    input: UpdateWorkspaceInput
+  ): Promise<WorkspaceRecord> {
+    const { workspace } = await callRequireRole(["owner", "admin"]);
+    const validated = parseInput(updateWorkspaceSchema, input);
+    const hdrs = await headers();
+
+    const updateData: { name?: string; slug?: string; logo?: string } = {};
+    if (validated.name) updateData.name = validated.name;
+    if (validated.slug) updateData.slug = validated.slug;
+    if (validated.logo) updateData.logo = validated.logo;
+
+    const result = (await callOrgApi("update", () =>
+      auth.api.updateOrganization({
+        headers: hdrs,
+        body: { data: updateData, organizationId: workspace.id },
+      })
+    )) as WorkspaceRecord | null;
+
+    if (!result) {
+      throw new WorkspaceServiceError(
+        "provider_error",
+        "Failed to update workspace"
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Delete the caller's active workspace. Owner only. Switches the
+   * caller to another workspace afterward, if one remains.
+   */
+  async function deleteWorkspace(): Promise<void> {
+    const { workspace } = await callRequireRole(["owner"]);
+    const hdrs = await headers();
+
+    await callOrgApi("delete", () =>
+      auth.api.deleteOrganization({
+        headers: hdrs,
+        body: { organizationId: workspace.id },
+      })
+    );
+
+    const orgs = await callOrgApi("list", () =>
+      orgApi["/organization/list"]({ headers: hdrs })
+    );
+    if (orgs && orgs.length > 0) {
+      await callOrgApi("set-active", () =>
+        orgApi["/organization/set-active"]({
+          headers: hdrs,
+          body: { organizationId: orgs[0]!.id },
+        })
+      );
+    }
+  }
+
+  /**
+   * Get the caller's active workspace, fully resolved. Unlike
+   * ignite's original (see the module doc comment), this resolves the
+   * workspace id explicitly via `requireWorkspace()` rather than
+   * relying on a non-existent `sessions.activeOrganizationId` fallback.
+   */
+  async function getActiveWorkspace(): Promise<WorkspaceRecord> {
+    const { workspace } = await callRequireWorkspace();
+    const hdrs = await headers();
+
+    const org = (await callOrgApi("getFullOrganization", () =>
+      auth.api.getFullOrganization({
+        headers: hdrs,
+        query: { organizationId: workspace.id },
+      })
+    )) as WorkspaceRecord | null;
+
+    if (!org) {
+      throw new WorkspaceServiceError("not_found", "Workspace not found");
+    }
+
+    return org;
+  }
+
+  return {
+    listWorkspaces,
+    createWorkspace,
+    switchWorkspace,
+    updateWorkspace,
+    deleteWorkspace,
+    getActiveWorkspace,
+  };
+}
+
+export type WorkspaceService = ReturnType<typeof createWorkspaceService>;

package/src/workspace-init.ts

@@ -0,0 +1,140 @@
+/**
+ * Workspace Initialization
+ *
+ * Ensures every authenticated user has at least one workspace.
+ * Called from the (app) layout to guarantee workspace exists.
+ * Idempotent - safe to call on every page load.
+ *
+ * Pattern: "Belt-and-suspenders" approach consistent with Phase 9.
+ * Better-Auth doesn't provide a reliable hook for post-signup workspace creation,
+ * so we check + create on every authenticated page load.
+ *
+ * Dependency Inversion (Phase 42, PKG-01 preparation):
+ * Post-creation logic (e.g., trial provisioning) is injected via callback,
+ * so this module has ZERO billing imports. The actual billing call lives
+ * in the consumer application's authenticated layout, which already
+ * imports billing.
+ * This breaks the auth → billing circular dependency before Phase 43 extraction.
+ */
+
+import { auth } from "./server";
+import type { User } from "better-auth/types";
+import { createLogger } from "@intelligo-dev/core/logger";
+
+const log = createLogger("WorkspaceInit");
+
+/**
+ * Ensure user has at least one workspace (WORK-01).
+ *
+ * If user has organizations, sets the first as active. If none exist,
+ * creates a personal workspace — this serves as a fallback in case the
+ * user.create hook (server.ts databaseHooks) hasn't completed yet, and
+ * also handles users created via non-Better-Auth flows (e.g. admin panel).
+ *
+ * Idempotent - safe to call repeatedly. Returns quickly if workspace exists.
+ *
+ * @param user - Authenticated user from session
+ * @param headers - Request headers (required for Better-Auth API)
+ * @param options.onWorkspaceCreated - Optional callback invoked after a new workspace is created.
+ *   Receives workspaceId and email. Failure does NOT block workspace creation (same fire-and-forget
+ *   behavior as the previous inline trial provisioning call).
+ * @returns The organization ID that was set as active (useful for immediate access before session updates)
+ */
+export async function ensureUserWorkspace(
+  user: User,
+  headers: Headers,
+  options?: {
+    onWorkspaceCreated?: (params: {
+      workspaceId: string;
+      email: string;
+    }) => Promise<void>;
+  }
+): Promise<string> {
+  log.info("Starting workspace check", { email: user.email });
+
+  // Check if user has any organizations
+  const orgs = await auth.api.listOrganizations({
+    headers,
+  });
+
+  log.info("Found organizations", { count: orgs?.length ?? 0 });
+
+  if (orgs && orgs.length > 0 && orgs[0]) {
+    log.debug("User has workspaces, setting first as active");
+    // User has workspaces - ensure one is active
+    try {
+      await auth.api.setActiveOrganization({
+        headers,
+        body: { organizationId: orgs[0].id },
+      });
+      log.info("Set active organization", { orgId: orgs[0].id });
+    } catch (error) {
+      log.error("Failed to set active organization", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+    return orgs[0].id;
+  }
+
+  // TR-DB03 fix: No organizations found — the user.create hook may not have
+  // completed yet, or user was created via a non-Better-Auth flow.
+  // Create the workspace here as a fallback rather than throwing.
+  // Idempotent: the unique constraint on organization.slug prevents duplicates
+  // if both this fallback and the hook fire for the same signup.
+  log.warn("No workspace found, creating one (hook may still fire)", {
+    email: user.email,
+  });
+  const slug = ((user.email || "user").split("@")[0] || "user")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .slice(0, 30);
+
+  let workspaceId: string;
+  try {
+    const result = await auth.api.createOrganization({
+      headers,
+      body: {
+        name: `${user.name || "User"}'s Workspace`,
+        slug: `${slug}-${Date.now().toString(36)}`,
+        userId: user.id,
+      },
+    });
+    if (!result) {
+      throw new Error("createOrganization returned no result");
+    }
+    workspaceId = result.id;
+    log.info("Created fallback workspace", { workspaceId });
+  } catch (error) {
+    // If creation failed because the unique constraint was hit (hook already
+    // created), the error message contains the duplicate key info.
+    // List orgs again — if one now exists, use it.
+    const orgsAfter = await auth.api.listOrganizations({ headers });
+    if (orgsAfter && orgsAfter.length > 0 && orgsAfter[0]) {
+      log.info("Workspace created concurrently by hook, using it");
+      await auth.api.setActiveOrganization({
+        headers,
+        body: { organizationId: orgsAfter[0].id },
+      });
+      return orgsAfter[0].id;
+    }
+    // Genuine failure
+    log.error("Failed to create fallback workspace", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+
+  // Fire the optional callback (trial credits, referral tracking, etc.)
+  if (options?.onWorkspaceCreated) {
+    options
+      .onWorkspaceCreated({ workspaceId, email: user.email })
+      .catch((err) =>
+        log.error("onWorkspaceCreated callback failed", {
+          error: err instanceof Error ? err.message : String(err),
+        })
+      );
+  }
+
+  return workspaceId;
+}