@intelligo-dev/auth 1.0.0-beta.1 → 1.0.0-beta.13

package/src/workspace/service.ts

@@ -1,73 +1,12 @@
 /**
- * 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`.
+ * Workspace listing, creation, switching, editing and deletion. Each method
+ * authorizes itself and throws `WorkspaceServiceError`; the plan limit
+ * arrives as the `checkWorkspaceLimit` port bound at the composition root.
+ * `getFullOrganization` always gets an explicit `organizationId`, because a
+ * bare call resolves to nothing when the session has no active organization.
  */
 
-import { headers } from "next/headers";
+import { getRequestHeaders } from "@intelligo-dev/core/request-context";
 import type { ZodType } from "zod";
 import { createLogger } from "@intelligo-dev/core/logger";
 
@@ -95,17 +34,21 @@ export interface WorkspaceRecord {
 
 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`.
+   * Plan-defined workspace cap for the caller. No port ⇒ unlimited. Not
+   * consulted for the caller's first workspace. Keyed by `userId` because
+   * the workspace being created has no plan yet; how "this user's plan" is
+   * resolved is the binding's decision.
    */
   checkWorkspaceLimit?: (
     userId: string,
     currentCount: number
   ) => Promise<{ allowed: boolean; limit: number }>;
+  /**
+   * Runs before a workspace is deleted, after the owner check. Whatever
+   * outlives the row has to be ended here — a paid subscription keeps
+   * billing the customer otherwise. A throw stops the deletion.
+   */
+  beforeDeleteWorkspace?: (workspaceId: string) => Promise<void>;
 };
 
 function errorMessage(error: unknown): string {
@@ -187,12 +130,10 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
     }
   }
 
-  /**
-   * List all workspaces for the current user.
-   */
+  /** Every workspace the current user belongs to. */
   async function listWorkspaces(): Promise<OrgListItem[]> {
     await callRequireAuth();
-    const hdrs = await headers();
+    const hdrs = await getRequestHeaders();
 
     const orgs = await callOrgApi("list", () =>
       orgApi["/organization/list"]({ headers: hdrs })
@@ -213,7 +154,7 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
   ): Promise<WorkspaceRecord> {
     const { user } = await callRequireAuth();
     const validated = parseInput(createWorkspaceSchema, input);
-    const hdrs = await headers();
+    const hdrs = await getRequestHeaders();
 
     const existing = await callOrgApi("list", () =>
       orgApi["/organization/list"]({ headers: hdrs })
@@ -264,9 +205,7 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
     return org;
   }
 
-  /**
-   * Switch the caller's active workspace.
-   */
+  /** Switch the caller's active workspace. */
   async function switchWorkspace(organizationId: string): Promise<void> {
     await callRequireAuth();
 
@@ -274,7 +213,7 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
       throw new WorkspaceServiceError("invalid_input", "Invalid workspace id");
     }
 
-    const hdrs = await headers();
+    const hdrs = await getRequestHeaders();
 
     await callOrgApi("set-active", () =>
       orgApi["/organization/set-active"]({
@@ -284,15 +223,13 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
     );
   }
 
-  /**
-   * Update workspace settings (name/slug/logo). Owner/admin only.
-   */
+  /** 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 hdrs = await getRequestHeaders();
 
     const updateData: { name?: string; slug?: string; logo?: string } = {};
     if (validated.name) updateData.name = validated.name;
@@ -322,7 +259,19 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
    */
   async function deleteWorkspace(): Promise<void> {
     const { workspace } = await callRequireRole(["owner"]);
-    const hdrs = await headers();
+    const hdrs = await getRequestHeaders();
+
+    if (ports.beforeDeleteWorkspace) {
+      try {
+        await ports.beforeDeleteWorkspace(workspace.id);
+      } catch (error) {
+        throw new WorkspaceServiceError(
+          "provider_error",
+          `Could not prepare the workspace for deletion: ${errorMessage(error)}`,
+          { cause: error }
+        );
+      }
+    }
 
     await callOrgApi("delete", () =>
       auth.api.deleteOrganization({
@@ -345,14 +294,13 @@ export function createWorkspaceService(ports: WorkspaceServicePorts = {}) {
   }
 
   /**
-   * 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.
+   * The caller's active workspace, fully resolved. The id comes from
+   * `requireWorkspace()`, which falls back to the first workspace when the
+   * session has none active.
    */
   async function getActiveWorkspace(): Promise<WorkspaceRecord> {
     const { workspace } = await callRequireWorkspace();
-    const hdrs = await headers();
+    const hdrs = await getRequestHeaders();
 
     const org = (await callOrgApi("getFullOrganization", () =>
       auth.api.getFullOrganization({

package/src/workspace-bootstrap.ts

@@ -0,0 +1,57 @@
+/**
+ * What runs once a user's personal workspace exists: trial credits, a
+ * welcome note, a referral bonus. The product decides, so auth takes it
+ * as a handler set from the composition root and never imports billing.
+ *
+ * The workspace is created by the `user.create` hook at signup, or by
+ * `ensureUserWorkspace` when that hook did not get to it; both call the
+ * handler, for the one workspace each of them created.
+ */
+
+import { createLogger } from "@intelligo-dev/core/logger";
+import { createRegistryRef } from "@intelligo-dev/core/registry";
+
+const log = createLogger("WorkspaceBootstrap");
+
+export type WorkspaceCreated = {
+  workspaceId: string;
+  userId: string;
+  email: string;
+};
+
+export type WorkspaceCreatedHandler = (
+  created: WorkspaceCreated
+) => Promise<void>;
+
+const handler = createRegistryRef<WorkspaceCreatedHandler | null>(
+  "auth/workspace-created",
+  null
+);
+
+/** Set from the composition root; the last call wins. */
+export function setWorkspaceCreatedHandler(
+  next: WorkspaceCreatedHandler
+): void {
+  handler.set(next);
+}
+
+export function clearWorkspaceCreatedHandler(): void {
+  handler.set(null);
+}
+
+/**
+ * Runs the handler without waiting for it: a failed bootstrap is
+ * logged and never fails the signup that created the workspace.
+ */
+export function workspaceCreated(
+  created: WorkspaceCreated,
+  run: WorkspaceCreatedHandler | null = handler.get()
+): void {
+  if (!run) return;
+  run(created).catch((error) =>
+    log.error("Workspace bootstrap failed", {
+      workspaceId: created.workspaceId,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  );
+}

package/src/workspace-init.ts

@@ -1,58 +1,45 @@
 /**
- * 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.
+ * Ensures every authenticated user has a workspace; called from the
+ * authenticated layout on every render. Post-creation work (trial
+ * provisioning) is the handler set with `setWorkspaceCreatedHandler`,
+ * so auth never imports billing.
  */
 
 import { auth } from "./server";
 import type { User } from "better-auth/types";
 import { createLogger } from "@intelligo-dev/core/logger";
+import { personalWorkspaceSlug } from "./workspace-slug";
+import {
+  workspaceCreated,
+  type WorkspaceCreatedHandler,
+} from "./workspace-bootstrap";
 
 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).
+ * Ensure the user has at least one workspace.
  *
- * Idempotent - safe to call repeatedly. Returns quickly if workspace exists.
+ * If the session already has a valid active workspace, returns it
+ * untouched; otherwise sets the first workspace as active. If none
+ * exist, creates a personal workspace, in case the user.create hook has not
+ * completed yet or the user was created outside Better-Auth. Idempotent.
  *
  * @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).
+ * @param options.onWorkspaceCreated - Runs after this call creates a workspace, in place of
+ *   the handler set with `setWorkspaceCreatedHandler`. Fire-and-forget: a failure is logged,
+ *   never thrown.
  * @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>;
+    onWorkspaceCreated?: WorkspaceCreatedHandler;
   }
 ): Promise<string> {
   log.info("Starting workspace check", { email: user.email });
 
-  // Check if user has any organizations
   const orgs = await auth.api.listOrganizations({
     headers,
   });
@@ -60,8 +47,18 @@ export async function ensureUserWorkspace(
   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
+    // Keep a workspace the user switched to while they are still a
+    // member; resetting to orgs[0] would undo every switch on re-render.
+    const current = await auth.api.getSession({ headers });
+    const active = (
+      current?.session as { activeOrganizationId?: string | null } | undefined
+    )?.activeOrganizationId;
+    if (active && orgs.some((org) => org.id === active)) {
+      log.debug("Active workspace still valid, keeping it", { orgId: active });
+      return active;
+    }
+
+    log.debug("No valid active workspace, setting first as active");
     try {
       await auth.api.setActiveOrganization({
         headers,
@@ -77,18 +74,13 @@ export async function ensureUserWorkspace(
     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.
+  // No workspace yet: create one. The unique index on organization.slug
+  // prevents duplicates when the hook or a concurrent request also creates
+  // it, because `personalWorkspaceSlug` is derived from the user; the loser
+  // takes the adopt-the-winner path below.
   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 {
@@ -96,7 +88,7 @@ export async function ensureUserWorkspace(
       headers,
       body: {
         name: `${user.name || "User"}'s Workspace`,
-        slug: `${slug}-${Date.now().toString(36)}`,
+        slug: personalWorkspaceSlug(user.email, user.id),
         userId: user.id,
       },
     });
@@ -106,9 +98,8 @@ export async function ensureUserWorkspace(
     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.
+    // A concurrent creator may have won the unique index; if a workspace
+    // 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");
@@ -118,23 +109,31 @@ export async function ensureUserWorkspace(
       });
       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),
-        })
-      );
+  // Point the session at the new workspace, or later requests that resolve
+  // one from the session alone find none. Not fatal (the next request sets
+  // it), so a failure is logged rather than thrown.
+  try {
+    await auth.api.setActiveOrganization({
+      headers,
+      body: { organizationId: workspaceId },
+    });
+    log.info("Set new workspace active", { workspaceId });
+  } catch (error) {
+    log.error("Failed to set the new workspace active", {
+      error: error instanceof Error ? error.message : String(error),
+    });
   }
 
+  workspaceCreated(
+    { workspaceId, userId: user.id, email: user.email },
+    options?.onWorkspaceCreated
+  );
+
   return workspaceId;
 }

package/src/workspace-slug.ts

@@ -0,0 +1,32 @@
+/**
+ * The slug an auto-provisioned personal workspace gets.
+ *
+ * Deterministic on purpose. Two paths provision a first workspace —
+ * the `user.create` hook in `server.ts` and the layout's
+ * `ensureUserWorkspace` fallback — and several requests can reach the
+ * fallback at once, because the `(app)` layout re-renders for every
+ * request that enters the group (the document, each prefetched sibling
+ * route, an error-boundary retry).
+ *
+ * A slug derived from the user makes `organization.slug`'s unique index
+ * the arbiter: the first caller wins, every other one gets
+ * `ORGANIZATION_ALREADY_EXISTS` and adopts the winner's workspace. A
+ * per-attempt suffix would let each racer create a workspace of its own.
+ *
+ * Only the automatic personal workspace is named this way; a workspace
+ * someone creates by hand names itself.
+ */
+export function personalWorkspaceSlug(
+  email: string | null | undefined,
+  userId: string
+): string {
+  const base = ((email || "user").split("@")[0] || "user").slice(0, 30);
+  // The id fragment is normalised with the rest: Better-Auth ids are
+  // mixed-case, and a slug the workspace settings form refuses
+  // (`[a-z0-9-]+`) makes the personal workspace impossible to rename.
+  return toSlug(`${base}-${userId.slice(0, 8)}`);
+}
+
+function toSlug(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+}