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

package/src/edge.ts

@@ -1,28 +1,8 @@
 /**
- * Edge-safe session presence check.
- *
- * Middleware runs in the Edge Runtime, where no TCP Postgres driver is
- * available. The previous version of this module solved that by
- * instantiating Better-Auth against the Neon HTTP driver — which made
- * middleware silently Neon-only. Against any other Postgres the session
- * query failed with `TypeError: fetch failed`, Better-Auth turned that
- * into `APIError: Failed to get session`, and the middleware threw: every
- * request to the app returned HTTP 500. The old code hid this behind a
- * `NODE_ENV === "development"` bypass that skipped auth entirely, so the
- * failure only appeared in a production build on a non-Neon database.
- *
- * The fix is to stop querying the database from the edge at all.
- * Middleware performs an OPTIMISTIC check: it reads the session cookie
- * and decides where to send the request. It never asserts that the
- * session is valid.
- *
- * The authoritative check stays server-side, where it always was —
- * `requireAuth`/`requireWorkspace`/`requireRole` and the authenticated
- * layout's own `getAuthSession()` redirect. A forged or expired cookie
- * gets past middleware and is then rejected by the page or action that
- * actually reads data. This is the pattern Better-Auth documents for
- * Next.js middleware, and it is what makes the guard work on any
- * Postgres, in any runtime, with one code path in every environment.
+ * Edge-safe session presence check. Middleware runs where no TCP Postgres
+ * driver exists, so it never queries the database: it reads the cookie and
+ * picks a redirect. A forged or expired cookie gets past it and is rejected
+ * server-side by `requireAuth`/`requireWorkspace`/`requireRole`.
  */
 
 import { getSessionCookie } from "better-auth/cookies";
@@ -30,10 +10,24 @@ import { getSessionCookie } from "better-auth/cookies";
 /**
  * True when the request carries a Better-Auth session cookie.
  *
- * Presence only — the cookie's signature is NOT verified and no
- * database read happens. Never use this to authorize access to data;
- * use it to choose a redirect. Authorization belongs to `requireAuth`
- * and friends, which run in the Node runtime against the real session.
+ * For one thing only: an optional optimistic redirect in a consumer's
+ * `proxy.ts` / `middleware.ts`, sending a visitor with no cookie to the
+ * login page before the page renders. The scaffold does not use it; its
+ * session redirect runs server-side in the `(app)` layout.
+ *
+ * Presence only — the cookie's signature is NOT verified and no database
+ * read happens, so this is never authorization. A forged or expired cookie
+ * passes it and is rejected by `requireAuth` and friends, which every
+ * layout, action and route handler still calls.
+ *
+ * @example
+ * const intl = createIntlMiddleware(routing);
+ * export default function proxy(request: NextRequest) {
+ *   const isApp = /^\/(?:[a-z]{2}\/)?dashboard(?:\/|$)/.test(request.nextUrl.pathname);
+ *   if (isApp && !hasSessionCookie(request))
+ *     return NextResponse.redirect(new URL("/login", request.url));
+ *   return intl(request);
+ * }
  */
 export function hasSessionCookie(request: Request): boolean {
   return getSessionCookie(request) !== null;

package/src/guard-error.ts

@@ -0,0 +1,36 @@
+/**
+ * Thrown by `requireAuth`, `requireWorkspace`, `requireRole` and
+ * `requirePlatformAdmin`. A transport picks its status from `code`; the
+ * message is for logs and never reaches a user.
+ */
+
+/**
+ * - `unauthenticated` — no valid session (401).
+ * - `no_workspace` — signed in, but a member of no workspace.
+ * - `forbidden` — signed in, but lacking the required role (403).
+ */
+export type AuthGuardErrorCode =
+  "unauthenticated" | "no_workspace" | "forbidden";
+
+const MESSAGES: Record<AuthGuardErrorCode, string> = {
+  unauthenticated: "Unauthorized",
+  no_workspace: "No active workspace",
+  forbidden: "Insufficient permissions",
+};
+
+export class AuthGuardError extends Error {
+  readonly code: AuthGuardErrorCode;
+
+  constructor(code: AuthGuardErrorCode, message: string = MESSAGES[code]) {
+    super(message);
+    this.name = "AuthGuardError";
+    this.code = code;
+
+    // Extending built-ins loses `instanceof` on some transpilation targets.
+    Object.setPrototypeOf(this, AuthGuardError.prototype);
+  }
+}
+
+export function isAuthGuardError(error: unknown): error is AuthGuardError {
+  return error instanceof AuthGuardError;
+}

package/src/helpers.ts

@@ -1,44 +1,32 @@
 /**
- * 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
- * }
- * ```
+ * Session and workspace guards for server components, Server Actions and
+ * route handlers. Headers come from `@intelligo-dev/core/request-context`.
  */
 
-import { headers } from "next/headers";
+import { getRequestHeaders } from "@intelligo-dev/core/request-context";
 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";
+import { AuthGuardError } from "./guard-error";
+import { PLATFORM_ADMIN_ROLE, platformAdminStanding } from "./roles";
 
-/** Valid Better-Auth workspace roles. Used to type-check allowedRoles in requireRole(). */
+/** Better-Auth workspace roles, as accepted by `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.
+ * The current session and user, or null when unauthenticated.
  */
 export async function getAuthSession(): Promise<{
   session: Session;
   user: User;
 } | null> {
   const session = await auth.api.getSession({
-    headers: await headers(),
+    headers: await getRequestHeaders(),
   });
 
   if (!session?.user) {
@@ -52,12 +40,10 @@ export async function getAuthSession(): Promise<{
 }
 
 /**
- * Require authentication.
- *
- * Throws "Unauthorized" error if no valid session.
- * Use this in server actions to enforce authentication (TECH-10 pattern).
+ * The current session and user.
  *
- * @throws Error with "Unauthorized" message if not authenticated
+ * @throws AuthGuardError `unauthenticated` ("Unauthorized") when there is
+ *   no valid session.
  */
 export async function requireAuth(): Promise<{
   session: Session;
@@ -66,17 +52,15 @@ export async function requireAuth(): Promise<{
   const result = await getAuthSession();
 
   if (!result) {
-    throw new Error("Unauthorized");
+    throw new AuthGuardError("unauthenticated");
   }
 
   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
+ * Workspace context for a given organization id, e.g. just after creating
+ * or activating one. Null when unauthenticated or not a member.
  */
 export async function getWorkspaceContextById(organizationId: string): Promise<{
   session: Session;
@@ -92,9 +76,8 @@ export async function getWorkspaceContextById(organizationId: string): Promise<{
 
   log.debug("getWorkspaceContextById: fetching org");
 
-  // Get organization by ID directly (not from session)
   const org = await auth.api.getFullOrganization({
-    headers: await headers(),
+    headers: await getRequestHeaders(),
     query: { organizationId },
   });
 
@@ -103,7 +86,6 @@ export async function getWorkspaceContextById(organizationId: string): Promise<{
     return null;
   }
 
-  // Find user's membership
   const membership = org.members?.find(
     (m: any) => m.userId === authResult.user.id
   );
@@ -129,48 +111,56 @@ export async function getWorkspaceContextById(organizationId: string): Promise<{
   };
 }
 
-/**
- * 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<{
+type WorkspaceContext = {
   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(),
-  });
+/**
+ * The workspace a session acts in: its active organization, read by explicit
+ * id, falling back to the user's first workspace. Null when the user has none.
+ */
+async function resolveWorkspaceContext(authResult: {
+  session: Session;
+  user: User;
+}): Promise<WorkspaceContext | null> {
+  const activeOrganizationId = (
+    authResult.session as { activeOrganizationId?: string | null }
+  ).activeOrganizationId;
+
+  // Better-Auth throws FORBIDDEN when the active organization no longer
+  // admits this user (removed member); treat that as "no active workspace"
+  // so the fallback below runs.
+  let activeOrg = activeOrganizationId
+    ? await auth.api
+        .getFullOrganization({
+          headers: await getRequestHeaders(),
+          query: { organizationId: activeOrganizationId },
+        })
+        .catch((error: unknown) => {
+          log.debug("getWorkspaceContext: active org not readable", {
+            error: error instanceof Error ? error.message : String(error),
+          });
+          return null;
+        })
+    : null;
 
   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(),
+      headers: await getRequestHeaders(),
     });
 
     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(),
+        headers: await getRequestHeaders(),
         query: { organizationId: orgs[0].id },
       });
     }
@@ -181,7 +171,6 @@ export async function getWorkspaceContext(): Promise<{
     return null;
   }
 
-  // Find user's membership in the active org
   const activeMember = activeOrg.members.find(
     (m: any) => m.userId === authResult.user.id
   );
@@ -212,68 +201,68 @@ export async function getWorkspaceContext(): Promise<{
 }
 
 /**
- * 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.).
+ * Workspace context from the session's active organization, falling back to
+ * the user's first workspace. Null when unauthenticated or when the user has
+ * none.
+ */
+export async function getWorkspaceContext(): Promise<WorkspaceContext | null> {
+  const authResult = await getAuthSession();
+  if (!authResult) {
+    log.debug("getWorkspaceContext: no auth session");
+    return null;
+  }
+
+  return resolveWorkspaceContext(authResult);
+}
+
+/**
+ * Workspace context for workspace-scoped operations.
  *
- * @throws Error with "No active workspace" message if no workspace selected
+ * @throws AuthGuardError `unauthenticated` ("Unauthorized") when there is
+ *   no valid session, `no_workspace` ("No active workspace") when the user
+ *   has none.
  */
-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();
+export async function requireWorkspace(): Promise<WorkspaceContext> {
+  const context = await resolveWorkspaceContext(await requireAuth());
   if (!context) {
-    throw new Error("No active workspace");
+    throw new AuthGuardError("no_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.
+ * Workspace context when the member holds one of `allowedRoles`, e.g.
+ * `requireRole(["owner", "admin"])`.
  *
- * @param allowedRoles - Array of role names that are permitted
- * @throws Error with "Insufficient permissions" message if user lacks required role
+ * @throws AuthGuardError `forbidden` ("Insufficient permissions") when the
+ *   member lacks the role, and whatever `requireWorkspace` throws.
  */
-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 };
-}> {
+export async function requireRole(
+  allowedRoles: WorkspaceRole[]
+): Promise<WorkspaceContext> {
   const context = await requireWorkspace();
-  if (!allowedRoles.includes(context.membership.role)) {
-    throw new Error("Insufficient permissions");
+  // Better-Auth stores roles as a comma-separated string, so a member
+  // may hold more than one; any of them may satisfy the check.
+  const held = String(context.membership.role)
+    .split(",")
+    .map((r) => r.trim()) as WorkspaceRole[];
+  if (!held.some((r) => allowedRoles.includes(r))) {
+    throw new AuthGuardError("forbidden");
   }
   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.
+ * Require a PLATFORM admin, distinct from workspace roles: workspace
+ * `owner` is per-tenant, so platform surfaces 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 on first use, so every
+ * later check, Better-Auth's admin plugin included, reads the same row.
  * Closed by default: no allowlist and no role means no admin.
  *
- * @throws Error("Insufficient permissions") when the user is not a
+ * @throws AuthGuardError `unauthenticated` when there is no session,
+ *   `forbidden` ("Insufficient permissions") when the user is not a
  *   platform admin.
  */
 export async function requirePlatformAdmin(): Promise<{
@@ -282,27 +271,23 @@ export async function requirePlatformAdmin(): Promise<{
 }> {
   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);
+  const { allowlisted, hasRole, roles } = platformAdminStanding(
+    user as {
+      email?: string | null;
+      emailVerified?: boolean | null;
+      role?: string | null;
+    }
+  );
 
   if (!allowlisted && !hasRole) {
-    throw new Error("Insufficient permissions");
+    throw new AuthGuardError("forbidden");
   }
 
   // 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(",");
+    const next = [...roles, PLATFORM_ADMIN_ROLE].join(",");
     try {
       await db.update(users).set({ role: next }).where(eq(users.id, user.id));
     } catch (error) {

package/src/impersonation.ts

@@ -1,22 +1,21 @@
 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.
+ * Impersonation's session mechanics, gated on the platform admin role. The
+ * rest of the policy (an audit event that must be durable first, a mandatory
+ * reason) lives in `@intelligo-dev/admin`; a product calls
+ * `startImpersonation` / `stopImpersonation` there, never these directly.
  */
 
-import { headers } from "next/headers";
+import { eq } from "drizzle-orm";
+
+import { db } from "@intelligo-dev/core/db";
+import { users } from "@intelligo-dev/core/db/schema";
+import { getRequestHeaders } from "@intelligo-dev/core/request-context";
 
+import { AuthGuardError } from "./guard-error";
+import { requirePlatformAdmin } from "./helpers";
+import { platformAdminStanding } from "./roles";
 import { auth } from "./server";
 
 export type ImpersonatedSession = {
@@ -31,14 +30,43 @@ 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.
+ * The caller must be a platform admin and the target must not be one, by
+ * role or by the PLATFORM_ADMIN_EMAILS allowlist: both are checked here,
+ * before Better-Auth's own checks, so no import path reaches the session
+ * swap without them.
+ *
+ * @throws AuthGuardError `unauthenticated` with no session, `forbidden` when
+ *   the caller is not a platform admin or the target is one.
  */
 export async function impersonateUser(
   targetUserId: string
 ): Promise<ImpersonatedSession> {
+  await requirePlatformAdmin();
+
+  const [target] = await db
+    .select({ email: users.email, role: users.role })
+    .from(users)
+    .where(eq(users.id, targetUserId))
+    .limit(1);
+
+  if (target) {
+    // Protective here, so the allowlist counts whether or not the
+    // target has verified the address yet.
+    const { allowlisted, hasRole } = platformAdminStanding({
+      ...target,
+      emailVerified: true,
+    });
+    if (allowlisted || hasRole) {
+      throw new AuthGuardError(
+        "forbidden",
+        "A platform admin cannot be impersonated"
+      );
+    }
+  }
+
   const result = (await auth.api.impersonateUser({
     body: { userId: targetUserId },
-    headers: await headers(),
+    headers: await getRequestHeaders(),
   })) as { session?: { expiresAt?: string | Date } };
 
   const expiresAt = result.session?.expiresAt;
@@ -51,7 +79,14 @@ export async function impersonateUser(
   };
 }
 
-/** Restore the admin's own session. */
+/**
+ * Restore the admin's own session.
+ *
+ * Not gated on the platform admin role: while impersonating, the caller's
+ * session is the target's. Better-Auth refuses a session that carries no
+ * `impersonatedBy`, and restores only the admin session its signed cookie
+ * names.
+ */
 export async function stopImpersonating(): Promise<void> {
-  await auth.api.stopImpersonating({ headers: await headers() });
+  await auth.api.stopImpersonating({ headers: await getRequestHeaders() });
 }

package/src/index.ts

@@ -1,8 +1,5 @@
 /**
- * Better-Auth Server Exports
- *
- * Server-side authentication utilities.
- * For client-side auth, use @intelligo-dev/auth/client
+ * Server-side auth. Client components use `@intelligo-dev/auth/client`.
  */
 
 export { auth } from "./server";
@@ -15,7 +12,20 @@ export {
   requireRole,
   requirePlatformAdmin,
 } from "./helpers";
+export {
+  AuthGuardError,
+  isAuthGuardError,
+  type AuthGuardErrorCode,
+} from "./guard-error";
 export { ensureUserWorkspace } from "./workspace-init";
+export {
+  setWorkspaceCreatedHandler,
+  clearWorkspaceCreatedHandler,
+} from "./workspace-bootstrap";
+export type {
+  WorkspaceCreated,
+  WorkspaceCreatedHandler,
+} from "./workspace-bootstrap";
 export type { WorkspaceRole } from "./helpers";
 export { PLATFORM_ADMIN_ROLE } from "./roles";
 export {
@@ -24,10 +34,8 @@ export {
   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,
@@ -38,7 +46,6 @@ export {
   type OrgMember,
 } from "./org-api";
 
-// Team management service (page/registry migration, section C1)
 export {
   createTeamService,
   type TeamService,
@@ -57,7 +64,6 @@ export {
   type UpdateRoleInput,
 } from "./team/schemas";
 
-// Workspace management service (page/registry migration, workspace-settings family)
 export {
   createWorkspaceService,
   type WorkspaceService,
@@ -77,7 +83,6 @@ export {
   type UpdateWorkspaceInput,
 } from "./workspace/schemas";
 
-// Profile management service (page/registry migration, profile-settings family)
 export {
   createProfileService,
   type ProfileService,
@@ -95,7 +100,6 @@ export {
   type UpdateProfileInput,
 } from "./profile/schemas";
 
-// Onboarding service (page/registry migration, `onboarding` family)
 export {
   createOnboardingService,
   type OnboardingService,

package/src/invitation-links.ts

@@ -0,0 +1,15 @@
+/**
+ * The links an invitation email carries. Both land on the invitation page,
+ * which offers accept and decline to the signed-in invitee; declining is a
+ * decision made there, never the effect of following a link.
+ *
+ * Unprefixed on purpose: the consumer's locale middleware resolves the
+ * invitee's locale, so the email does not have to guess one.
+ */
+export function invitationLinks(
+  appUrl: string,
+  invitationId: string
+): { acceptUrl: string; declineUrl: string } {
+  const page = `${appUrl.replace(/\/+$/, "")}/accept-invitation/${encodeURIComponent(invitationId)}`;
+  return { acceptUrl: page, declineUrl: page };
+}

package/src/onboarding/errors.ts

@@ -1,13 +1,6 @@
 /**
- * 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.
+ * Thrown for every failure the onboarding service recognizes. Shaping it for a UI
+ * (a `{ success, error }` envelope, i18n, revalidation) is the transport's job.
  */
 
 /**
@@ -17,9 +10,7 @@
  * - `not_found` — the caller's `users` row could not be found.
  */
 export type OnboardingServiceErrorCode =
-  | "forbidden"
-  | "invalid_input"
-  | "not_found";
+  "forbidden" | "invalid_input" | "not_found";
 
 export class OnboardingServiceError extends Error {
   readonly code: OnboardingServiceErrorCode;
@@ -33,14 +24,11 @@ export class OnboardingServiceError extends Error {
     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.
+      // The ES2020 target predates the `cause` constructor option.
       (this as { cause?: unknown }).cause = options.cause;
     }
 
-    // Restore prototype chain (extending built-ins across some
-    // transpilation targets loses `instanceof`).
+    // Extending built-ins loses `instanceof` on some transpilation targets.
     Object.setPrototypeOf(this, OnboardingServiceError.prototype);
   }
 }