@intelligo-dev/auth 1.0.0-beta.1

package/src/onboarding/service.ts

@@ -0,0 +1,174 @@
+/**
+ * Onboarding service — the durable business rules behind a user's
+ * first-run onboarding flow, extracted from the product application's
+ * onboarding actions (page/registry migration, `onboarding` family,
+ * roadmap item 11).
+ *
+ * Unlike `../team/service.ts` and `../workspace/service.ts`, this
+ * service has no Better-Auth organization-plugin calls to make — it
+ * reads and writes exactly two columns on `@intelligo-dev/core`'s `users`
+ * table (`onboardingCompleted`, `onboardingStep`) directly via Drizzle.
+ *
+ * No ports: `complete()` and `skip()` only flip those two columns and
+ * return the resulting state — they do NOT provision trial credits,
+ * record referrals, or perform any other first-workspace bootstrapping.
+ * Ignite's original `completeOnboarding()` action did exactly that
+ * (`provisionTrialCredits`/`recordReferralSignup`/`grantReferralUpgrade`
+ * inline), but that work belongs to the consumer's own
+ * `onWorkspaceCreated` binding instead — see `../workspace-init.ts`'s
+ * `onWorkspaceCreated` port and the `app-shell` registry item's
+ * `lib/workspace-bootstrap.ts`, which already runs once per new
+ * workspace. Duplicating it here would either double-provision (it
+ * would fire again on every onboarding completion, not just the first
+ * workspace) or force this package to depend on `@intelligo-dev/billing`,
+ * which the allowlist in
+ * `tests/architecture/dependency-direction.test.ts` forbids.
+ *
+ * ---------------------------------------------------------------------
+ * Why `setStep` takes a bare `string`, not an enum
+ * ---------------------------------------------------------------------
+ * See the doc comment on `./schemas.ts`'s `setStepSchema`. Short
+ * version: the `onboarding_step` column is untyped `text`, and a
+ * framework-owned service can't know a consumer's step ids in advance
+ * — a different product may have two steps, or six. This module
+ * accepts any non-empty string up to 64 characters and persists it
+ * verbatim.
+ *
+ * ---------------------------------------------------------------------
+ * Why `skip()` has the same durable effect as `complete()`
+ * ---------------------------------------------------------------------
+ * The `users` table has no separate "skipped" column, so there is
+ * nothing else to persist. Ignite's original `skipOnboarding()` action
+ * logged an analytics event and then delegated to `completeOnboarding()`
+ * unchanged; this service mirrors that shape as two distinct methods
+ * (rather than collapsing `skip` into an alias) so a transport can
+ * still log/tag the skip differently before or after calling it —
+ * that shaping, like everything else transport-level, does not belong
+ * in this service.
+ *
+ * Authorization (`requireAuth`) lives INSIDE each method, not at the
+ * transport. Every recognized failure throws `OnboardingServiceError`
+ * with a stable `code` — no revalidatePath/Sentry/next-intl/toast here;
+ * that shaping is the transport's job (a Server Action, a route
+ * handler).
+ */
+
+import { eq } from "drizzle-orm";
+import { db } from "@intelligo-dev/core/db";
+import { users } from "@intelligo-dev/core/db/schema";
+
+import { requireAuth } from "../helpers";
+import { setStepSchema } from "./schemas";
+import { OnboardingServiceError, isOnboardingServiceError } from "./errors";
+
+/** The caller's onboarding progress. */
+export interface OnboardingState {
+  completed: boolean;
+  currentStep: string | null;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Maps requireAuth failures to `forbidden`. */
+function toForbidden(error: unknown): OnboardingServiceError {
+  if (isOnboardingServiceError(error)) return error;
+  return new OnboardingServiceError("forbidden", errorMessage(error), {
+    cause: error,
+  });
+}
+
+export function createOnboardingService() {
+  async function callRequireAuth() {
+    try {
+      return await requireAuth();
+    } catch (error) {
+      throw toForbidden(error);
+    }
+  }
+
+  /**
+   * Get the caller's current onboarding state.
+   */
+  async function getState(): Promise<OnboardingState> {
+    const { user } = await callRequireAuth();
+
+    const [row] = await db
+      .select({
+        onboardingCompleted: users.onboardingCompleted,
+        onboardingStep: users.onboardingStep,
+      })
+      .from(users)
+      .where(eq(users.id, user.id))
+      .limit(1);
+
+    if (!row) {
+      throw new OnboardingServiceError("not_found", "User not found");
+    }
+
+    return {
+      completed: row.onboardingCompleted,
+      currentStep: row.onboardingStep,
+    };
+  }
+
+  /**
+   * Set the caller's current onboarding step. A product defines its
+   * own step ids (see the module doc comment); this only validates
+   * that `step` is a non-empty, bounded string and persists it
+   * verbatim. Does not touch `onboardingCompleted`.
+   */
+  async function setStep(step: string): Promise<OnboardingState> {
+    const { user } = await callRequireAuth();
+
+    const parsed = setStepSchema.safeParse(step);
+    if (!parsed.success) {
+      throw new OnboardingServiceError(
+        "invalid_input",
+        parsed.error.issues.map((issue) => issue.message).join("; ") ||
+          "Invalid step",
+        { cause: parsed.error }
+      );
+    }
+
+    await db
+      .update(users)
+      .set({ onboardingStep: parsed.data, updatedAt: new Date() })
+      .where(eq(users.id, user.id));
+
+    return { completed: false, currentStep: parsed.data };
+  }
+
+  /**
+   * Mark onboarding complete and clear the step. No trial/referral
+   * side effects — see the module doc comment.
+   */
+  async function complete(): Promise<OnboardingState> {
+    const { user } = await callRequireAuth();
+
+    await db
+      .update(users)
+      .set({
+        onboardingCompleted: true,
+        onboardingStep: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(users.id, user.id));
+
+    return { completed: true, currentStep: null };
+  }
+
+  /**
+   * Skip onboarding. Same durable effect as `complete()` — see the
+   * module doc comment for why this is its own method rather than an
+   * alias.
+   */
+  async function skip(): Promise<OnboardingState> {
+    return complete();
+  }
+
+  return { getState, setStep, complete, skip };
+}
+
+export type OnboardingService = ReturnType<typeof createOnboardingService>;

package/src/org-api.ts

@@ -0,0 +1,198 @@
+/**
+ * Typed wrapper for Better-Auth organization plugin endpoints.
+ *
+ * The plugin endpoints (`/organization/...`) are added at runtime by
+ * Better-Auth's organization plugin and are not present on the inferred
+ * `auth.api` type. Without a wrapper, consumers had to reach for
+ * `as any as Record<...>` casts or `@ts-expect-error` comments — both
+ * lose all type information.
+ *
+ * This module declares the explicit input/output shapes for every
+ * organization endpoint the team service calls and exposes them under
+ * the plugin's HTTP path names (`/organization/invite-member`, etc.),
+ * which is the vocabulary the rest of this package's `team/` module
+ * uses.
+ *
+ * (Ported from the product application’s Better-Auth type wrapper as part of the
+ * team-settings backend extraction — packages/auth owns the org-api
+ * contract now; ignite's copy is retired at cutover.)
+ *
+ * IMPORTANT — found while wiring the real-DB integration test for this
+ * extraction: ignite's original module built `orgApi` as
+ * `auth.api as unknown as OrgApi`, i.e. a bare type-cast that assumes
+ * `auth.api` is keyed by these HTTP path strings. It is not. Better-Auth's
+ * organization plugin (`better-auth@1.6.30`,
+ * `plugins/organization/organization.mjs`) exposes each endpoint on
+ * `auth.api` under its own camelCase *server* id, which does not always
+ * match the path or the *client* SDK name documented alongside it:
+ *
+ *   path                                  | auth.api key (server) | authClient.organization.* (client)
+ *   /organization/invite-member           | createInvitation       | inviteMember
+ *   /organization/get-invitation          | getInvitation          | getInvitation
+ *   /organization/accept-invitation       | acceptInvitation       | acceptInvitation
+ *   /organization/reject-invitation       | rejectInvitation       | rejectInvitation
+ *   /organization/cancel-invitation       | cancelInvitation       | cancelInvitation
+ *   /organization/remove-member           | removeMember           | removeMember
+ *   /organization/update-member-role      | updateMemberRole       | updateMemberRole
+ *   /organization/leave                   | leaveOrganization      | leave
+ *   /organization/list                    | listOrganizations      | list
+ *   /organization/set-active              | setActiveOrganization  | setActive
+ *   /organization/list-user-invitations   | listUserInvitations    | listUserInvitations
+ *
+ * A bare `auth.api as unknown as OrgApi` cast type-checks (TypeScript
+ * cannot see through the cast) but throws `TypeError: ... is not a
+ * function` at runtime for every call whose row above differs in the
+ * first two columns — i.e. invite-member, leave, list, and set-active
+ * unconditionally, since their server ids aren't just a casing change
+ * of the path. This was invisible in ignite's test suite because
+ * `actions/__tests__/team.test.ts` mocks `@/types/better-auth` (the
+ * whole `orgApi` object) rather than exercising the cast against a
+ * real `auth.api`, and only surfaced once this extraction's
+ * `service.integration.test.ts` called the real thing. It is a live
+ * bug in ignite's shipped team-management actions today, not a
+ * hypothetical — worth a fix there independent of this migration.
+ *
+ * `orgApi` below is therefore a real object, not a cast: each path key
+ * forwards to the correctly-named `auth.api` method. The `OrgApi`
+ * type and every call site elsewhere in this package (`team/service.ts`
+ * and its tests) are unaffected — they only ever see the path-keyed
+ * shape.
+ */
+
+import { auth } from "./server";
+
+export interface OrgEndpointOptions<
+  TBody = Record<string, unknown>,
+  TQuery = Record<string, unknown>,
+> {
+  headers: Headers;
+  body?: TBody;
+  query?: TQuery;
+}
+
+export type OrgRole = "owner" | "admin" | "member";
+
+export interface OrgListItem {
+  id: string;
+  name: string;
+  slug?: string;
+}
+
+export interface OrgInvitation {
+  id: string;
+  email: string;
+  role: OrgRole;
+  status: "pending" | "accepted" | "rejected" | "canceled";
+  expiresAt: string | Date;
+  organizationId: string;
+  organizationName?: string;
+  inviterEmail?: string;
+  inviterId?: string;
+}
+
+/**
+ * Minimal member shape read off `auth.api.getFullOrganization()`.
+ * `getFullOrganization` is not part of the org-plugin's typed
+ * `/organization/...` surface — it lives on the base `auth.api` — so
+ * it is called directly rather than through `orgApi` below.
+ */
+export interface OrgMember {
+  id?: string;
+  userId: string;
+  role: string;
+}
+
+export interface OrgApi {
+  "/organization/invite-member": (
+    opts: OrgEndpointOptions<{
+      email: string;
+      role: Exclude<OrgRole, "owner">;
+      organizationId: string;
+    }>
+  ) => Promise<OrgInvitation | null>;
+
+  "/organization/get-invitation": (
+    opts: OrgEndpointOptions<never, { id: string }>
+  ) => Promise<OrgInvitation>;
+
+  "/organization/accept-invitation": (
+    opts: OrgEndpointOptions<{ invitationId: string }>
+  ) => Promise<unknown>;
+
+  "/organization/reject-invitation": (
+    opts: OrgEndpointOptions<{ invitationId: string }>
+  ) => Promise<unknown>;
+
+  "/organization/cancel-invitation": (
+    opts: OrgEndpointOptions<{ invitationId: string }>
+  ) => Promise<unknown>;
+
+  "/organization/remove-member": (
+    opts: OrgEndpointOptions<{
+      memberIdOrEmail: string;
+      organizationId: string;
+    }>
+  ) => Promise<unknown>;
+
+  "/organization/update-member-role": (
+    opts: OrgEndpointOptions<{
+      memberId: string;
+      role: OrgRole;
+      organizationId: string;
+    }>
+  ) => Promise<unknown>;
+
+  "/organization/leave": (
+    opts: OrgEndpointOptions<{ organizationId: string }>
+  ) => Promise<unknown>;
+
+  "/organization/list": (
+    opts: OrgEndpointOptions
+  ) => Promise<OrgListItem[] | null>;
+
+  "/organization/set-active": (
+    opts: OrgEndpointOptions<{ organizationId: string }>
+  ) => Promise<unknown>;
+
+  "/organization/list-user-invitations": (
+    opts: OrgEndpointOptions
+  ) => Promise<OrgInvitation[] | null>;
+}
+
+/**
+ * `auth.api`'s organization-plugin methods are typed loosely by
+ * Better-Auth (broad `Record<string, unknown>`-ish body/query types
+ * driven by its own zod schemas) — each is cast to its specific
+ * `OrgApi` member signature at the point of use below, which is the
+ * same trust boundary the rest of this codebase already accepts for
+ * these calls (see the module doc comment above for why a *blanket*
+ * cast is not safe: it hides the wrong key entirely, whereas casting
+ * per-member here only relaxes the parameter/return types).
+ */
+const api = auth.api as unknown as Record<
+  string,
+  (opts: OrgEndpointOptions<never, never>) => Promise<unknown>
+>;
+
+export const orgApi: OrgApi = {
+  "/organization/invite-member":
+    api.createInvitation as OrgApi["/organization/invite-member"],
+  "/organization/get-invitation":
+    api.getInvitation as OrgApi["/organization/get-invitation"],
+  "/organization/accept-invitation":
+    api.acceptInvitation as OrgApi["/organization/accept-invitation"],
+  "/organization/reject-invitation":
+    api.rejectInvitation as OrgApi["/organization/reject-invitation"],
+  "/organization/cancel-invitation":
+    api.cancelInvitation as OrgApi["/organization/cancel-invitation"],
+  "/organization/remove-member":
+    api.removeMember as OrgApi["/organization/remove-member"],
+  "/organization/update-member-role":
+    api.updateMemberRole as OrgApi["/organization/update-member-role"],
+  "/organization/leave": api.leaveOrganization as OrgApi["/organization/leave"],
+  "/organization/list": api.listOrganizations as OrgApi["/organization/list"],
+  "/organization/set-active":
+    api.setActiveOrganization as OrgApi["/organization/set-active"],
+  "/organization/list-user-invitations":
+    api.listUserInvitations as OrgApi["/organization/list-user-invitations"],
+};

package/src/profile/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Profile service error type.
+ *
+ * The profile 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. Mirrors `TeamServiceError`/`WorkspaceServiceError`
+ * (../team/errors.ts, ../workspace/errors.ts).
+ */
+
+/**
+ * - `forbidden` — the caller is unauthenticated.
+ * - `invalid_input` — schema validation failed.
+ * - `provider_error` — the underlying Better-Auth user API call itself
+ *   failed (network, upstream API error, etc.).
+ */
+export type ProfileServiceErrorCode =
+  | "forbidden"
+  | "invalid_input"
+  | "provider_error";
+
+export interface ProfileServiceErrorMeta {
+  [key: string]: unknown;
+}
+
+export class ProfileServiceError extends Error {
+  readonly code: ProfileServiceErrorCode;
+  readonly meta?: ProfileServiceErrorMeta;
+
+  constructor(
+    code: ProfileServiceErrorCode,
+    message: string,
+    options?: { meta?: ProfileServiceErrorMeta; cause?: unknown }
+  ) {
+    super(message);
+    this.name = "ProfileServiceError";
+    this.code = code;
+    this.meta = options?.meta;
+    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, ProfileServiceError.prototype);
+  }
+}
+
+export function isProfileServiceError(
+  error: unknown
+): error is ProfileServiceError {
+  return error instanceof ProfileServiceError;
+}

package/src/profile/schemas.ts

@@ -0,0 +1,23 @@
+/**
+ * Profile Validation Schemas
+ *
+ * Zod schemas for user profile updates, shared by the profile service
+ * and its transports.
+ *
+ * (Ported from the product application's `lib/validations/profile.ts` —
+ * same semantics: optional name, optional-and-nullable image URL.
+ * Ignite's copy is retired at cutover.)
+ */
+
+import { z } from "zod";
+
+export const updateProfileSchema = z.object({
+  name: z
+    .string()
+    .min(2, "Name must be at least 2 characters")
+    .max(100, "Name must be at most 100 characters")
+    .optional(),
+  image: z.string().url("Image must be a valid URL").optional().nullable(),
+});
+
+export type UpdateProfileInput = z.infer<typeof updateProfileSchema>;

package/src/profile/service.ts

@@ -0,0 +1,208 @@
+/**
+ * Profile management service — the durable business rules behind
+ * reading the caller's own profile, updating it, and deleting the
+ * account, extracted from the product application's profile actions
+ * (page/registry migration, `profile-settings` family, roadmap item 9).
+ *
+ * Mirrors `createTeamService(ports)` / `createWorkspaceService(ports)`
+ * (../team/service.ts, ../workspace/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 an email-sending concern of its own. A consumer binds the
+ * account-deletion confirmation email in at its composition root:
+ *
+ *   const profileService = createProfileService({
+ *     onAccountDeleted: ({ email, name }) =>
+ *       sendEmail({ to: email, subject: ..., html: ... }), // @intelligo-dev/core/email
+ *   });
+ *
+ * Authorization (`requireAuth`) lives INSIDE each method, not at the
+ * transport. Every recognized failure throws `ProfileServiceError` 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 the confirmation email is a port, not a direct import
+ * ---------------------------------------------------------------------
+ * The product application's original `deleteAccount()`
+ * calls `sendEmail` from
+ * `@intelligo-dev/core/email` directly, inline, with a hardcoded English
+ * HTML template. `@intelligo-dev/auth` already imports `@intelligo-dev/core/email`
+ * elsewhere (`server.ts`'s Better-Auth hooks — verification, password
+ * reset, welcome, invitation emails), so nothing in the allowlist
+ * (auth → core only) would technically block importing `sendEmail`
+ * here too. The port exists anyway, for the same reason
+ * `TeamServicePorts.sendInvitationEmail` and
+ * `WorkspaceServicePorts.checkWorkspaceLimit` are ports rather than
+ * direct calls: this service should not own *content* — copy, subject
+ * lines, template shape — for a side effect a consumer may want to
+ * localize, skip, or replace with a different provider. `onAccountDeleted`
+ * is fire-and-forget by design (matching ignite's `.catch(console.error)`
+ * pattern): a failed confirmation email must never block the deletion
+ * that already succeeded.
+ */
+
+import { headers } from "next/headers";
+import type { ZodType } from "zod";
+import { eq } from "drizzle-orm";
+import { createLogger } from "@intelligo-dev/core/logger";
+import { db } from "@intelligo-dev/core/db";
+import { users, sessions } from "@intelligo-dev/core/db/schema";
+
+import { auth } from "../server";
+import { requireAuth } from "../helpers";
+import { updateProfileSchema, type UpdateProfileInput } from "./schemas";
+import { ProfileServiceError, isProfileServiceError } from "./errors";
+
+const log = createLogger("ProfileService");
+
+export interface ProfileRecord {
+  id: string;
+  name: string | null;
+  email: string;
+  image?: string | null;
+  emailVerified: boolean;
+}
+
+export type ProfileServicePorts = {
+  /**
+   * Fired after the account has been soft-deleted and its sessions
+   * invalidated. Fire-and-forget from the service's perspective — a
+   * failure here is logged by the consumer, never surfaced to the
+   * caller of `deleteAccount()` (the deletion has already succeeded).
+   * No port ⇒ no confirmation email is sent.
+   */
+  onAccountDeleted?: (input: {
+    userId: string;
+    email: string;
+    name: string;
+  }) => Promise<void>;
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Maps requireAuth failures to `forbidden`. */
+function toForbidden(error: unknown): ProfileServiceError {
+  if (isProfileServiceError(error)) return error;
+  return new ProfileServiceError("forbidden", errorMessage(error), {
+    cause: error,
+  });
+}
+
+function parseInput<T>(schema: ZodType<T>, input: unknown): T {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    throw new ProfileServiceError(
+      "invalid_input",
+      result.error.issues.map((issue) => issue.message).join("; ") ||
+        "Invalid input",
+      { cause: result.error }
+    );
+  }
+  return result.data;
+}
+
+export function createProfileService(ports: ProfileServicePorts = {}) {
+  async function callRequireAuth() {
+    try {
+      return await requireAuth();
+    } catch (error) {
+      throw toForbidden(error);
+    }
+  }
+
+  /**
+   * Get the caller's own profile.
+   */
+  async function getProfile(): Promise<ProfileRecord> {
+    const { user } = await callRequireAuth();
+
+    return {
+      id: user.id,
+      name: user.name ?? null,
+      email: user.email,
+      image: user.image ?? null,
+      emailVerified: Boolean(user.emailVerified),
+    };
+  }
+
+  /**
+   * Update the caller's own name/image via the Better-Auth user API.
+   * Only the fields present in `input` are sent — omitting a field
+   * leaves it unchanged; `image: null` is dropped rather than forwarded
+   * (Better-Auth's `updateUser` does not accept `null`), matching
+   * ignite's original action.
+   */
+  async function updateProfile(input: UpdateProfileInput): Promise<void> {
+    await callRequireAuth();
+    const validated = parseInput(updateProfileSchema, input);
+    const hdrs = await headers();
+
+    const updateData: { name?: string; image?: string } = {};
+    if (validated.name !== undefined) updateData.name = validated.name;
+    if (validated.image !== undefined && validated.image !== null) {
+      updateData.image = validated.image;
+    }
+
+    try {
+      await auth.api.updateUser({ headers: hdrs, body: updateData });
+    } catch (error) {
+      log.error("updateUser failed", { error: errorMessage(error) });
+      throw new ProfileServiceError(
+        "provider_error",
+        "Failed to update profile",
+        { cause: error }
+      );
+    }
+  }
+
+  /**
+   * Delete the caller's own account: soft delete (`users.deletedAt`),
+   * invalidate every session (force logout), then fire the
+   * `onAccountDeleted` port, if bound, without waiting on it.
+   */
+  async function deleteAccount(): Promise<void> {
+    const { user } = await callRequireAuth();
+
+    try {
+      await db
+        .update(users)
+        .set({ deletedAt: new Date(), updatedAt: new Date() })
+        .where(eq(users.id, user.id));
+
+      await db.delete(sessions).where(eq(sessions.userId, user.id));
+    } catch (error) {
+      log.error("deleteAccount failed", { error: errorMessage(error) });
+      throw new ProfileServiceError(
+        "provider_error",
+        "Failed to delete account",
+        { cause: error }
+      );
+    }
+
+    if (ports.onAccountDeleted) {
+      ports
+        .onAccountDeleted({
+          userId: user.id,
+          email: user.email,
+          name: user.name || "",
+        })
+        .catch((err) =>
+          log.error("onAccountDeleted port failed", {
+            error: errorMessage(err),
+          })
+        );
+    }
+  }
+
+  return {
+    getProfile,
+    updateProfile,
+    deleteAccount,
+  };
+}
+
+export type ProfileService = ReturnType<typeof createProfileService>;

package/src/roles.ts

@@ -0,0 +1,17 @@
+/**
+ * The platform role.
+ *
+ * Deliberately a separate module from helpers.ts and server.ts: both
+ * need the constant, and server.ts (the Better-Auth instance) cannot
+ * import helpers.ts, which imports server.ts.
+ */
+
+/**
+ * Grants the operational console and, through Better-Auth's admin
+ * plugin, the ability to impersonate a user for support.
+ *
+ * Not a workspace role. Workspace `owner` is per-tenant — every
+ * self-serve signup owns a workspace — so anything cross-tenant gated
+ * on it is gated on nothing.
+ */
+export const PLATFORM_ADMIN_ROLE = "platform-admin";