@spawn-llc/auth 0.1.0

package/IDENTITY.md

@@ -0,0 +1,60 @@
+# Spawn identity
+
+**We use one WorkOS project, named "Spawn," as the identity backend for the entire Spawn suite.**
+An account on one Spawn product is an account on all of them — users are shared. This document is
+the canonical reference for how Spawn auth works.
+
+## Principles
+
+1. **One project.** A single WorkOS project/organization (the AuthKit application is named
+   **"Spawn"**) backs every app — one shared user pool. Each app is a client of the same project.
+2. **WorkOS is an invisible engine.** It provides password security, OAuth, sessions, MFA, SSO, and
+   compliance (free to 1M MAU). No app renders a WorkOS page or exposes a WorkOS type. The
+   developer-facing API is `@spawn-llc/auth`; the user-facing UI is `@spawn-llc/design-system`.
+3. **Own the UI, rent the engine.** Screens are ours (headless, from the design system). Auth is
+   WorkOS's. We never store passwords.
+4. **One choke point.** All identity goes through this package. Swapping providers would touch only
+   here.
+
+## Architecture
+
+```
+@spawn-llc/design-system   →  <SignIn> <SignUp> <VerifyEmail> <ResetPassword> …  (the UI)
+@spawn-llc/auth            →  session seam + headless flows + IdentityGateway    (the wiring)
+        └── WorkOS (User Management API)                                          (the engine)
+app                        →  own /login /signup /verify /reset routes rendering the DS screens,
+                              wired to @spawn-llc/auth; middleware = authProxy(); /callback = handleCallback()
+```
+
+- **Sessions & flows:** `@spawn-llc/auth/nextjs` — `currentUser`/`requireUser`/`session`/`signOut`,
+  `authProxy`, `handleCallback`, and headless `signInWithPassword`/`signUp`/`verifyEmail`/
+  `requestPasswordReset`/`resetPassword`/`startOAuth` (each calls WorkOS then seals the cookie).
+- **Tenancy:** `IdentityGateway` (core) — WorkOS organizations, memberships, roles
+  (`owner`/`admin`/`member`), invitations. Apps keep their own org row keyed by the WorkOS org id.
+- **Policy:** `@spawn-llc/auth/config` (edge-safe) — `isWorkosConfigured`, `isAllowedEmail`
+  (optional domain gate for internal tools), `isPublicPath`.
+
+## The "Spawn" WorkOS project
+
+- Team: **Spawn** · Environments: **Staging** (`environment_01KXS4E6ENF6ANWMAPCHJVEN27`) and
+  **Production** (`environment_01KXS4E74YNNKSBGC2J06YKCDH`).
+- AuthKit application **"Spawn"** — Staging `app_01KXS4E74NTVBDEMPQFY32YGAC`
+  (client `client_01KXS4E6XDET3JSD7H8PTEAKBZ`), Production `app_01KXS4E7K3QZ9A7PDFHD841SNS`
+  (client `client_01KXS4E79KKPHTSCJWAEM3CJYR`).
+- Roles: `owner`, `admin`, `member`. Branding: light, Geist, Spawn logo (see the audit repo's
+  `config/authkit-branding.json`).
+- **Emails: WorkOS-sent for now** (verification / reset / invite). Owning branded email is a
+  deferred roadmap item.
+
+## Add auth to a new Spawn app
+
+1. `pnpm add @spawn-llc/auth @spawn-llc/design-system`.
+2. Env from the "Spawn" application: `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_COOKIE_PASSWORD`,
+   `NEXT_PUBLIC_WORKOS_REDIRECT_URI=<app>/callback`; add that redirect URI in the WorkOS dashboard.
+3. `proxy.ts` → `export default authProxy()`. `app/callback/route.ts` → `export const GET =
+   handleCallback()`.
+4. Build `/login`, `/signup`, `/verify`, `/reset` rendering the DS screens, wired to the headless
+   flows via `"use server"` actions.
+5. Internal-only tool? Set `ALLOWED_EMAIL_DOMAINS=spawnpartners.com`.
+
+Because every app points at the same "Spawn" project, the user is the same everywhere.

package/README.md

@@ -0,0 +1,54 @@
+# @spawn-llc/auth
+
+**Spawn shared identity.** One WorkOS project (named **"Spawn"**) backs auth for the entire Spawn
+suite — sign up for one Spawn product and you have an account on all of them. This package is the
+**only** place that touches WorkOS: apps consume a Spawn-shaped API (`signIn`, `signUp`,
+`currentUser`, …) and never see a WorkOS type. WorkOS is an invisible engine (password security,
+OAuth, sessions, MFA, SSO, compliance — free to 1M MAU); the **UI is ours** (rendered from
+`@spawn-llc/design-system`). See [`IDENTITY.md`](./IDENTITY.md) for the architecture.
+
+## Install
+
+```bash
+pnpm add @spawn-llc/auth
+```
+
+Env (from the WorkOS "Spawn" application): `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`,
+`WORKOS_COOKIE_PASSWORD` (32+ chars), `NEXT_PUBLIC_WORKOS_REDIRECT_URI` (the app's `/callback`).
+Optional: `ALLOWED_EMAIL_DOMAINS` (comma-separated — restrict to e.g. `spawnpartners.com` for
+internal tools), `AUTH_PUBLIC_PATHS`.
+
+## Subpaths
+
+- **`@spawn-llc/auth`** — core, edge-safe: the `IdentityGateway` (orgs / members / roles / invites) +
+  `createIdentityGateway()`, domain types (`Role`, `Session`, `Member`, `Invite`), and policy
+  (`isWorkosConfigured`, `isAllowedEmail`, `isPublicPath`).
+- **`@spawn-llc/auth/config`** — the edge-safe policy alone (import from middleware; no SDK).
+- **`@spawn-llc/auth/nextjs`** — the Next server surface: the session seam
+  (`currentUser` / `requireUser` / `session` / `signOut` / `switchOrganization`), `authProxy()`,
+  `handleCallback()`, and the headless flows (`signInWithPassword`, `signUp`, `verifyEmail`,
+  `requestPasswordReset`, `resetPassword`, `startOAuth`).
+
+## Wire an app (Next.js)
+
+```ts
+// proxy.ts (gate every route)
+import { authProxy } from "@spawn-llc/auth/nextjs";
+export default authProxy();
+export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"] };
+```
+
+```ts
+// app/callback/route.ts (social login round-trip)
+import { handleCallback } from "@spawn-llc/auth/nextjs";
+export const GET = handleCallback({ returnPathname: "/" });
+```
+
+```tsx
+// app/login/page.tsx — render the DS <SignIn>, wire it to the headless flow
+import { SignIn } from "@spawn-llc/design-system/components/ui/sign-in";
+import { signInWithPassword, startOAuth } from "@spawn-llc/auth/nextjs";
+// (call these from "use server" actions; redirect on { status: "ok" })
+```
+
+Releases are tag-triggered — see [`RELEASING.md`](./RELEASING.md).

package/dist/chunk-SISIAS4C.js

@@ -0,0 +1,32 @@
+// src/config.ts
+var DEFAULT_PUBLIC_PATHS = ["/login", "/signup", "/verify", "/reset", "/callback"];
+function publicPaths() {
+  const extra = (process.env.AUTH_PUBLIC_PATHS ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+  return [...DEFAULT_PUBLIC_PATHS, ...extra];
+}
+function isPublicPath(pathname, paths = publicPaths()) {
+  return paths.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+}
+function isWorkosConfigured() {
+  return Boolean(
+    process.env.WORKOS_API_KEY && (process.env.WORKOS_CLIENT_ID || process.env.NEXT_PUBLIC_WORKOS_CLIENT_ID) && process.env.WORKOS_COOKIE_PASSWORD
+  );
+}
+function allowedEmailDomains() {
+  const raw = process.env.ALLOWED_EMAIL_DOMAINS;
+  return (raw ? raw.split(",") : []).map((d) => d.trim().toLowerCase().replace(/^@/, "")).filter(Boolean);
+}
+function isAllowedEmail(email) {
+  const domains = allowedEmailDomains();
+  if (domains.length === 0) return true;
+  if (!email) return false;
+  const domain = email.trim().toLowerCase().split("@")[1];
+  return domain ? domains.includes(domain) : false;
+}
+function workosClientId() {
+  const id = process.env.WORKOS_CLIENT_ID || process.env.NEXT_PUBLIC_WORKOS_CLIENT_ID;
+  if (!id) throw new Error("WORKOS_CLIENT_ID is not set");
+  return id;
+}
+
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId };

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Edge-safe auth policy — imported by app middleware. NO framework or SDK imports here
+ * (middleware may run on the edge runtime). This is the one choke point for "is auth configured"
+ * and "who is allowed"; generalized from admin's `@admin/auth` config so every Spawn app shares it.
+ */
+/** Default paths reachable without a session; apps extend via `publicPaths()`. */
+declare const DEFAULT_PUBLIC_PATHS: readonly ["/login", "/signup", "/verify", "/reset", "/callback"];
+/** The public paths for this app: the defaults plus anything in `AUTH_PUBLIC_PATHS` (comma-sep). */
+declare function publicPaths(): string[];
+declare function isPublicPath(pathname: string, paths?: string[]): boolean;
+/**
+ * WorkOS (the engine) is "configured" once its three required secrets are present. When it is NOT
+ * configured, the seam fails CLOSED (no session → redirect to sign-in) rather than letting requests
+ * through. `WORKOS_CLIENT_ID` is public (`NEXT_PUBLIC_WORKOS_CLIENT_ID` also accepted).
+ */
+declare function isWorkosConfigured(): boolean;
+/**
+ * Optional email-domain gate. Off by default (customer products let anyone sign up). Set
+ * `ALLOWED_EMAIL_DOMAINS` (comma-separated) to restrict — e.g. internal tools gate to
+ * `spawnpartners.com`. Returns true (allowed) when no gate is configured.
+ */
+declare function allowedEmailDomains(): string[];
+declare function isAllowedEmail(email: string | null | undefined): boolean;
+/** The WorkOS client id, from either the server or the public var. */
+declare function workosClientId(): string;
+
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId };

package/dist/config.js

@@ -0,0 +1 @@
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './chunk-SISIAS4C.js';

package/dist/domain-CmEhGW2N.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Spawn identity domain types — framework-free, shared by every app. WorkOS is the engine behind
+ * these, but nothing here imports a WorkOS type: apps speak Spawn's vocabulary, never the vendor's.
+ */
+/** A member's role in an organization. Maps 1:1 to a WorkOS environment role slug. */
+type Role = "owner" | "admin" | "member";
+/** A signed-in person. */
+interface User {
+    id: string;
+    email: string;
+    name: string;
+}
+/** The Spawn session — the provider-neutral shape apps consume (never a WorkOS `UserInfo`). */
+interface Session {
+    user: User;
+    /** The active organization for this session, if the app is org-scoped. */
+    organizationId?: string;
+    /** The user's role in the active organization, if any. */
+    role?: Role;
+}
+/** An organization a user belongs to, with that user's role — for org switchers. */
+interface OrgMembership {
+    orgId: string;
+    role: Role;
+}
+/** A member row for team settings: the membership plus the user it belongs to. */
+interface Member {
+    user: User;
+    role: Role;
+    createdAt: string;
+}
+/** A pending team invitation. */
+interface Invite {
+    id: string;
+    email: string;
+    role: Role;
+    state: "pending" | "accepted" | "expired" | "revoked";
+    createdAt: string;
+}
+
+export type { Invite as I, Member as M, OrgMembership as O, Role as R, Session as S, User as U };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { R as Role } from './domain-CmEhGW2N.js';
+export { I as Invite, M as Member, O as OrgMembership, S as Session, U as User } from './domain-CmEhGW2N.js';
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './config.js';
+
+/**
+ * The identity/tenancy port. WorkOS owns organizations, memberships (+ roles) and invitations; this
+ * is the framework-free interface apps talk to. The real impl (`WorkOSIdentityGateway`) wraps
+ * `@workos-inc/node`; tests inject an in-memory fake. Apps store their own org row keyed by the
+ * WorkOS organization id this gateway mints.
+ */
+interface IdentityGateway {
+    /** Create a WorkOS organization; returns its id (use as the app's org PK). */
+    createOrganization(input: {
+        name: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Delete a WorkOS organization (best-effort cleanup). */
+    deleteOrganization(id: string): Promise<void>;
+    /** Add a user to an org with a role (idempotent — re-adding updates the role). */
+    addMembership(input: {
+        userId: string;
+        orgId: string;
+        role: Role;
+    }): Promise<void>;
+    /** The caller's role in an org, or null if not a member (the authorization gate). */
+    getMembership(userId: string, orgId: string): Promise<{
+        role: Role;
+    } | null>;
+    /** Orgs the user belongs to, each with the user's role. */
+    listUserMemberships(userId: string): Promise<{
+        orgId: string;
+        role: Role;
+    }[]>;
+    /** Members of an org (for team settings). */
+    listMembers(orgId: string): Promise<IdentityMember[]>;
+    updateMembershipRole(orgId: string, userId: string, role: Role): Promise<void>;
+    removeMembership(orgId: string, userId: string): Promise<void>;
+    /** Send a WorkOS invitation email joining the invitee to the org with a role. */
+    inviteUser(input: {
+        email: string;
+        orgId: string;
+        role: Role;
+    }): Promise<IdentityInvite>;
+    listInvites(orgId: string): Promise<IdentityInvite[]>;
+    revokeInvite(inviteId: string): Promise<void>;
+}
+/** A member of an org, resolved from a WorkOS organization membership + its user. */
+interface IdentityMember {
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+    role: Role;
+    createdAt: string;
+}
+/** A WorkOS invitation surfaced to the team settings UI. */
+interface IdentityInvite {
+    id: string;
+    email: string;
+    role: Role;
+    state: "pending" | "accepted" | "expired" | "revoked";
+    createdAt: string;
+}
+
+/**
+ * The real {@link IdentityGateway}, backed by WorkOS via `@workos-inc/node`. Our `Role` values
+ * (`owner|admin|member`) are used verbatim as WorkOS role slugs — the "Spawn" environment defines
+ * matching roles. This is the ONLY file that touches WorkOS org/membership/invite APIs.
+ */
+declare class WorkOSIdentityGateway implements IdentityGateway {
+    private readonly apiKey;
+    private clientPromise;
+    constructor(apiKey: string);
+    private client;
+    createOrganization(input: {
+        name: string;
+    }): Promise<{
+        id: string;
+    }>;
+    deleteOrganization(id: string): Promise<void>;
+    addMembership(input: {
+        userId: string;
+        orgId: string;
+        role: Role;
+    }): Promise<void>;
+    getMembership(userId: string, orgId: string): Promise<{
+        role: Role;
+    } | null>;
+    listUserMemberships(userId: string): Promise<{
+        orgId: string;
+        role: Role;
+    }[]>;
+    listMembers(orgId: string): Promise<IdentityMember[]>;
+    updateMembershipRole(orgId: string, userId: string, role: Role): Promise<void>;
+    removeMembership(orgId: string, userId: string): Promise<void>;
+    inviteUser(input: {
+        email: string;
+        orgId: string;
+        role: Role;
+    }): Promise<IdentityInvite>;
+    listInvites(orgId: string): Promise<IdentityInvite[]>;
+    revokeInvite(inviteId: string): Promise<void>;
+    /** Find the caller's (active) membership row in an org, or undefined. */
+    private findMembership;
+}
+/** Composition-root factory. Throws unless WORKOS_API_KEY is set (no offline fallback). */
+declare function createIdentityGateway(): IdentityGateway;
+
+export { type IdentityGateway, type IdentityInvite, type IdentityMember, Role, WorkOSIdentityGateway, createIdentityGateway };

package/dist/index.js

@@ -0,0 +1,136 @@
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './chunk-SISIAS4C.js';
+
+// src/identity/workos-gateway.ts
+var ROLES = ["owner", "admin", "member"];
+function toRole(slug) {
+  return slug && ROLES.includes(slug) ? slug : "member";
+}
+var WorkOSIdentityGateway = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  apiKey;
+  clientPromise = null;
+  client() {
+    if (!this.clientPromise) {
+      this.clientPromise = import('@workos-inc/node').then(({ WorkOS }) => new WorkOS(this.apiKey));
+    }
+    return this.clientPromise;
+  }
+  async createOrganization(input) {
+    const workos = await this.client();
+    const org = await workos.organizations.createOrganization({ name: input.name });
+    return { id: org.id };
+  }
+  async deleteOrganization(id) {
+    const workos = await this.client();
+    await workos.organizations.deleteOrganization(id);
+  }
+  async addMembership(input) {
+    const workos = await this.client();
+    const existing = await this.findMembership(input.userId, input.orgId);
+    if (existing) {
+      await workos.userManagement.updateOrganizationMembership(existing.id, {
+        roleSlug: input.role
+      });
+      return;
+    }
+    await workos.userManagement.createOrganizationMembership({
+      userId: input.userId,
+      organizationId: input.orgId,
+      roleSlug: input.role
+    });
+  }
+  async getMembership(userId, orgId) {
+    const m = await this.findMembership(userId, orgId);
+    return m ? { role: toRole(m.role?.slug) } : null;
+  }
+  async listUserMemberships(userId) {
+    const workos = await this.client();
+    const res = await workos.userManagement.listOrganizationMemberships({
+      userId,
+      statuses: ["active"],
+      limit: 100
+    });
+    return res.data.map((m) => ({ orgId: m.organizationId, role: toRole(m.role?.slug) }));
+  }
+  async listMembers(orgId) {
+    const workos = await this.client();
+    const res = await workos.userManagement.listOrganizationMemberships({
+      organizationId: orgId,
+      limit: 100
+    });
+    return Promise.all(
+      res.data.map(async (m) => {
+        const user = await workos.userManagement.getUser(m.userId);
+        const name = [user.firstName, user.lastName].filter(Boolean).join(" ") || user.email;
+        return {
+          user: { id: user.id, email: user.email, name },
+          role: toRole(m.role?.slug),
+          createdAt: m.createdAt
+        };
+      })
+    );
+  }
+  async updateMembershipRole(orgId, userId, role) {
+    const workos = await this.client();
+    const m = await this.findMembership(userId, orgId);
+    if (m) await workos.userManagement.updateOrganizationMembership(m.id, { roleSlug: role });
+  }
+  async removeMembership(orgId, userId) {
+    const workos = await this.client();
+    const m = await this.findMembership(userId, orgId);
+    if (m) await workos.userManagement.deleteOrganizationMembership(m.id);
+  }
+  async inviteUser(input) {
+    const workos = await this.client();
+    const inv = await workos.userManagement.sendInvitation({
+      email: input.email,
+      organizationId: input.orgId,
+      roleSlug: input.role
+    });
+    return {
+      id: inv.id,
+      email: inv.email,
+      role: input.role,
+      state: inv.state,
+      createdAt: inv.createdAt
+    };
+  }
+  async listInvites(orgId) {
+    const workos = await this.client();
+    const res = await workos.userManagement.listInvitations({ organizationId: orgId, limit: 100 });
+    return res.data.filter((i) => i.state === "pending").map((i) => ({
+      id: i.id,
+      email: i.email,
+      role: "member",
+      state: i.state,
+      createdAt: i.createdAt
+    }));
+  }
+  async revokeInvite(inviteId) {
+    const workos = await this.client();
+    await workos.userManagement.revokeInvitation(inviteId);
+  }
+  /** Find the caller's (active) membership row in an org, or undefined. */
+  async findMembership(userId, orgId) {
+    const workos = await this.client();
+    const res = await workos.userManagement.listOrganizationMemberships({
+      userId,
+      organizationId: orgId,
+      limit: 1
+    });
+    return res.data[0];
+  }
+};
+function createIdentityGateway() {
+  const apiKey = process.env.WORKOS_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "WORKOS_API_KEY is required \u2014 Spawn identity has no offline fallback (WorkOS is the engine)."
+    );
+  }
+  return new WorkOSIdentityGateway(apiKey);
+}
+
+export { WorkOSIdentityGateway, createIdentityGateway };

package/dist/nextjs/index.d.ts

@@ -0,0 +1,114 @@
+import { U as User, S as Session } from '../domain-CmEhGW2N.js';
+import * as next_server from 'next/server';
+
+/**
+ * The Spawn session seam for Next apps. ONE choke point: app code only ever calls `currentUser()` /
+ * `requireUser()` / `session()` / `signOut()` — nothing outside this package knows it's WorkOS.
+ * Generalized from admin's `@admin/auth` + audit's `lib/session.ts`.
+ */
+/** The signed-in Spawn user, or null. Applies the optional email-domain gate. */
+declare function currentUser(): Promise<User | null>;
+/** The signed-in user; redirects to `/login` when absent. */
+declare function requireUser(redirectTo?: string): Promise<User>;
+/** The full Spawn session (user + active org + role), or null. */
+declare function session(): Promise<Session | null>;
+/** The signed-in email BEFORE the domain gate, if any — lets a login page show a wrong-domain denial. */
+declare function rejectedEmail(): Promise<string | null>;
+/** Sign out of the current session (clears the cookie, redirects to WorkOS logout → the app). */
+declare function signOut(): Promise<void>;
+/** Switch the active organization for a multi-org session. */
+declare function switchOrganization(organizationId: string): Promise<void>;
+/** A display name for account UI: full name if set, else email. */
+declare function userDisplayName(user: User): string;
+
+/**
+ * The app middleware/proxy. Because Spawn renders its OWN auth screens (headless), this only
+ * **refreshes** the WorkOS session cookie on each request — it does NOT redirect to any hosted page.
+ * Route protection is done in-app: authed layouts call `requireUser()`, which redirects
+ * unauthenticated visitors to `/login` (a Spawn screen). Use as the app's `proxy.ts` default export:
+ *
+ *   export default authProxy();
+ *   export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"] };
+ *
+ * Pass `{ enforce: true }` only if you want middleware-level gating to WorkOS's hosted UI instead
+ * of your own screens (not the Spawn default).
+ */
+declare function authProxy(options?: {
+    enforce?: boolean;
+    unauthenticatedPaths?: string[];
+}): next_server.NextMiddleware;
+
+/**
+ * The OAuth callback handler for the app's `/callback` route:
+ *
+ *   export const GET = handleCallback({ returnPathname: "/" });
+ *
+ * Exchanges the WorkOS code, seals the Spawn session cookie, and forwards on. This is used for the
+ * social-login round-trip (`startOAuth`) — headless email/password uses `saveSession` directly.
+ */
+declare function handleCallback(options?: {
+    returnPathname?: string;
+}): (request: next_server.NextRequest) => Promise<Response>;
+
+/**
+ * Headless auth flows — the Spawn API over WorkOS's User Management. Our own screens call these;
+ * WorkOS does the crypto. On success the session cookie is sealed via `saveSession`, so the caller
+ * just redirects. Password/verify/reset flows are here; social login uses `startOAuth` + the
+ * `/callback` handler. WorkOS still sends the transactional emails (for now).
+ */
+type FlowResult = {
+    status: "ok";
+} | {
+    status: "verify";
+    email: string;
+    pendingToken?: string;
+} | {
+    status: "error";
+    error: string;
+};
+declare const SUPPORTED_OAUTH: {
+    readonly google: "GoogleOAuth";
+    readonly microsoft: "MicrosoftOAuth";
+    readonly apple: "AppleOAuth";
+    readonly github: "GitHubOAuth";
+};
+type OAuthProvider = keyof typeof SUPPORTED_OAUTH;
+/** Email + password sign-in. Seals the Spawn session on success. */
+declare function signInWithPassword(input: {
+    email: string;
+    password: string;
+}): Promise<FlowResult>;
+/**
+ * Create an account. If the environment requires email verification, WorkOS sends the mail and we
+ * return `verify`; otherwise the new user is signed in and the session sealed.
+ */
+declare function signUp(input: {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+}): Promise<FlowResult>;
+/**
+ * Verify an email with the code we mailed; seals the session on success. `pendingToken` comes from
+ * the preceding signUp/signIn result and is REQUIRED — the code alone cannot be redeemed.
+ */
+declare function verifyEmail(input: {
+    code: string;
+    pendingToken?: string;
+}): Promise<FlowResult>;
+/** Request a password-reset email (WorkOS sends it). Always reports success (no account enumeration). */
+declare function requestPasswordReset(input: {
+    email: string;
+}): Promise<FlowResult>;
+/** Complete a password reset with the token from the email + a new password. */
+declare function resetPassword(input: {
+    token: string;
+    newPassword: string;
+}): Promise<FlowResult>;
+/** The WorkOS authorization URL to start a social-login round-trip; redirect the browser to it. */
+declare function startOAuth(input: {
+    provider: OAuthProvider;
+    redirectUri?: string;
+}): Promise<string>;
+
+export { type FlowResult, type OAuthProvider, authProxy, currentUser, handleCallback, rejectedEmail, requestPasswordReset, requireUser, resetPassword, session, signInWithPassword, signOut, signUp, startOAuth, switchOrganization, userDisplayName, verifyEmail };

package/dist/nextjs/index.js

@@ -0,0 +1,238 @@
+import { isWorkosConfigured, isAllowedEmail, publicPaths, workosClientId } from '../chunk-SISIAS4C.js';
+import { redirect } from 'next/navigation';
+import { authkitMiddleware, handleAuth, getWorkOS, saveSession } from '@workos-inc/authkit-nextjs';
+import { headers, cookies } from 'next/headers';
+
+async function currentUser() {
+  if (!isWorkosConfigured()) return null;
+  const { withAuth } = await import('@workos-inc/authkit-nextjs');
+  const { user } = await withAuth();
+  if (!user?.email || !isAllowedEmail(user.email)) return null;
+  return toUser(user);
+}
+async function requireUser(redirectTo = "/login") {
+  const user = await currentUser();
+  if (!user) redirect(redirectTo);
+  return user;
+}
+async function session() {
+  if (!isWorkosConfigured()) return null;
+  const { withAuth } = await import('@workos-inc/authkit-nextjs');
+  const info = await withAuth();
+  if (!info.user?.email || !isAllowedEmail(info.user.email)) return null;
+  return {
+    user: toUser(info.user),
+    organizationId: info.organizationId,
+    role: normalizeRole(info.role)
+  };
+}
+async function rejectedEmail() {
+  if (!isWorkosConfigured()) return null;
+  const { withAuth } = await import('@workos-inc/authkit-nextjs');
+  const { user } = await withAuth();
+  if (user?.email && !isAllowedEmail(user.email)) return user.email;
+  return null;
+}
+async function signOut() {
+  const { signOut: workosSignOut } = await import('@workos-inc/authkit-nextjs');
+  await workosSignOut();
+}
+async function switchOrganization(organizationId) {
+  const { switchToOrganization } = await import('@workos-inc/authkit-nextjs');
+  await switchToOrganization(organizationId);
+}
+function userDisplayName(user) {
+  return user.name?.trim() || user.email;
+}
+function toUser(u) {
+  const name = [u.firstName, u.lastName].filter(Boolean).join(" ").trim();
+  return { id: u.id, email: u.email, name: name || u.email };
+}
+function normalizeRole(role) {
+  return role === "owner" || role === "admin" || role === "member" ? role : void 0;
+}
+function authProxy(options) {
+  if (options?.enforce) {
+    return authkitMiddleware({
+      middlewareAuth: {
+        enabled: true,
+        unauthenticatedPaths: options.unauthenticatedPaths ?? publicPaths()
+      }
+    });
+  }
+  return authkitMiddleware();
+}
+function handleCallback(options) {
+  return handleAuth({ returnPathname: options?.returnPathname ?? "/" });
+}
+var SUPPORTED_OAUTH = {
+  google: "GoogleOAuth",
+  microsoft: "MicrosoftOAuth",
+  apple: "AppleOAuth",
+  github: "GitHubOAuth"
+};
+async function origin() {
+  const h = await headers();
+  const proto = h.get("x-forwarded-proto") ?? "https";
+  const host = h.get("host") ?? "localhost:3000";
+  return `${proto}://${host}`;
+}
+var FRIENDLY = {
+  email_not_available: "An account with that email already exists. Try signing in instead.",
+  email_verification_required: "Check your email for a verification code to finish signing in.",
+  invalid_credentials: "Invalid email or password.",
+  invalid_one_time_code: "That code isn't right. Check the latest email and try again.",
+  password_strength_error: "That password is too weak. Use at least 8 characters, mixing letters and numbers.",
+  user_not_found: "Invalid email or password.",
+  organization_not_found: "That workspace no longer exists.",
+  mfa_enrollment: "This account needs multi-factor authentication set up before signing in.",
+  sso_required: "This account signs in through your company's identity provider.",
+  rate_limit_exceeded: "Too many attempts. Wait a minute and try again."
+};
+function errorCode(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const code = err.code;
+  return typeof code === "string" ? code : void 0;
+}
+function message(err, fallback) {
+  const code = errorCode(err);
+  if (code && FRIENDLY[code]) return FRIENDLY[code];
+  const errors = err?.errors;
+  if (Array.isArray(errors)) {
+    const field = errors.find(
+      (e) => !!e && typeof e === "object" && typeof e.field === "string"
+    )?.field;
+    if (field === "password") return FRIENDLY.password_strength_error;
+    if (field === "email") return "That email doesn't look right.";
+  }
+  return fallback;
+}
+function pendingVerificationToken(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const e = err;
+  if (e.code !== "email_verification_required") return void 0;
+  return typeof e.pendingAuthenticationToken === "string" ? e.pendingAuthenticationToken : void 0;
+}
+var PENDING_COOKIE = "spawn_pending_verification";
+var PENDING_TTL_SECONDS = 15 * 60;
+async function rememberPendingToken(token) {
+  (await cookies()).set(PENDING_COOKIE, token, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: PENDING_TTL_SECONDS
+  });
+}
+async function takePendingToken() {
+  return (await cookies()).get(PENDING_COOKIE)?.value;
+}
+async function clearPendingToken() {
+  (await cookies()).delete(PENDING_COOKIE);
+}
+async function signInWithPassword(input) {
+  try {
+    const res = await getWorkOS().userManagement.authenticateWithPassword({
+      clientId: workosClientId(),
+      email: input.email,
+      password: input.password
+    });
+    await saveSession(res, await origin());
+    return { status: "ok" };
+  } catch (err) {
+    const pendingToken = pendingVerificationToken(err);
+    if (pendingToken) {
+      await rememberPendingToken(pendingToken);
+      return { status: "verify", email: input.email, pendingToken };
+    }
+    return { status: "error", error: message(err, "Invalid email or password.") };
+  }
+}
+async function signUp(input) {
+  const workos = getWorkOS();
+  try {
+    const user = await workos.userManagement.createUser({
+      email: input.email,
+      password: input.password,
+      firstName: input.firstName,
+      lastName: input.lastName
+    });
+    try {
+      const res = await workos.userManagement.authenticateWithPassword({
+        clientId: workosClientId(),
+        email: input.email,
+        password: input.password
+      });
+      await saveSession(res, await origin());
+      return { status: "ok" };
+    } catch (err) {
+      const pendingToken = pendingVerificationToken(err);
+      if (pendingToken) {
+        await rememberPendingToken(pendingToken);
+      } else {
+        await workos.userManagement.sendVerificationEmail({ userId: user.id }).catch(() => {
+        });
+      }
+      return { status: "verify", email: input.email, pendingToken };
+    }
+  } catch (err) {
+    return { status: "error", error: message(err, "Could not create your account.") };
+  }
+}
+async function verifyEmail(input) {
+  const pendingToken = input.pendingToken ?? await takePendingToken();
+  if (!pendingToken) {
+    return {
+      status: "error",
+      error: "This verification session expired. Sign in again to get a new code."
+    };
+  }
+  try {
+    const res = await getWorkOS().userManagement.authenticateWithEmailVerification({
+      clientId: workosClientId(),
+      code: input.code,
+      pendingAuthenticationToken: pendingToken
+    });
+    await saveSession(res, await origin());
+    await clearPendingToken();
+    return { status: "ok" };
+  } catch (err) {
+    const code = errorCode(err);
+    if (code && code.startsWith("pending_authentication_token")) {
+      await clearPendingToken();
+      return {
+        status: "error",
+        error: "This verification session expired. Sign in again to get a new code."
+      };
+    }
+    return { status: "error", error: message(err, "That code didn't work. Try again.") };
+  }
+}
+async function requestPasswordReset(input) {
+  try {
+    await getWorkOS().userManagement.createPasswordReset({ email: input.email });
+  } catch {
+  }
+  return { status: "ok" };
+}
+async function resetPassword(input) {
+  try {
+    await getWorkOS().userManagement.resetPassword({
+      token: input.token,
+      newPassword: input.newPassword
+    });
+    return { status: "ok" };
+  } catch (err) {
+    return { status: "error", error: message(err, "That reset link is invalid or expired.") };
+  }
+}
+async function startOAuth(input) {
+  const redirectUri = input.redirectUri ?? `${await origin()}/callback`;
+  return getWorkOS().userManagement.getAuthorizationUrl({
+    clientId: workosClientId(),
+    provider: SUPPORTED_OAUTH[input.provider],
+    redirectUri
+  });
+}
+
+export { authProxy, currentUser, handleCallback, rejectedEmail, requestPasswordReset, requireUser, resetPassword, session, signInWithPassword, signOut, signUp, startOAuth, switchOrganization, userDisplayName, verifyEmail };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@spawn-llc/auth",
+  "version": "0.1.0",
+  "description": "Spawn shared identity — headless auth for the whole Spawn suite. One WorkOS project (named \"Spawn\") backs every app; this is the only place that touches it. WorkOS is an invisible engine.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./nextjs": {
+      "types": "./dist/nextjs/index.d.ts",
+      "import": "./dist/nextjs/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "IDENTITY.md"
+  ],
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks || true",
+    "build": "rm -rf dist && tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run typecheck && pnpm run build",
+    "release": "pnpm run release:patch",
+    "release:patch": "pnpm version patch -m \"v%s\" && git push --follow-tags",
+    "release:minor": "pnpm version minor -m \"v%s\" && git push --follow-tags",
+    "release:major": "pnpm version major -m \"v%s\" && git push --follow-tags"
+  },
+  "dependencies": {
+    "@workos-inc/authkit-nextjs": "^4.2.0",
+    "@workos-inc/node": "^10.8.0"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@types/react": "^19.0.0",
+    "next": "^16.2.10",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0"
+  }
+}