@spawn-llc/auth 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.2.0
+
+**Security — read this before upgrading an internal tool.**
+
+- **The email-domain gate now runs in the headless flows, not only on session read.** Previously
+  `signUp` would create a real user in the shared "Spawn" WorkOS directory (and email them) for any
+  domain, and `signInWithPassword` would seal a session cookie before anything checked policy. Both
+  now deny up front, so no credential is minted and no directory write happens. `verifyEmail`
+  re-checks after redeeming a token, and `requestPasswordReset` sends no mail off-domain while still
+  reporting `ok` (no account enumeration).
+- **Added `AUTH_REQUIRE_EMAIL_DOMAINS=true` + `assertEmailDomainGate()`.** Every Spawn app shares one
+  WorkOS user pool, so an internal console whose `ALLOWED_EMAIL_DOMAINS` went missing would silently
+  admit every customer of every customer-facing product. Apps that must never be world-readable now
+  declare it: `isAllowedEmail` fails **closed** when a gate is required but unset, and
+  `assertEmailDomainGate()` turns the misconfiguration into a failed boot instead of an open door.
+- **`isAllowedEmail` rejects malformed input.** `"@allowed.com"` (empty local part) previously read
+  as allowed, because splitting on `@` yielded the allowed domain. A gate must never answer "allowed"
+  for something that is not an address.
+
+Non-breaking for customer products: with no `ALLOWED_EMAIL_DOMAINS` set, behaviour is unchanged.
+
+**Also**
+
+- First tests (27). They cover the pending-token thread, unverified sign-in routing, the guarantee
+  that no raw WorkOS string reaches a screen, and every domain-gate boundary.
+- CI now runs on push and PR — previously nothing validated a commit until a release tag was cut.
+- `publish.yml` runs the tests and installs with `--frozen-lockfile`.
+- Working git hooks. The `prepare` script pointed at a `.githooks/` directory that did not exist, so
+  no hook had ever run.
+- Documented why the OAuth callback gate is enforced on read rather than at the callback: the
+  address is only known after the code exchange, and authkit's `onSuccess` cannot veto a login.
+
+## 0.1.1
+
+Republished from a clean tree so the artifact is reproducible from source. No code change from what
+0.1.0 actually shipped.
+
+- Untracked the committed `.tgz` and ignored build/debug artifacts.
+
+## 0.1.0 — deprecated
+
+Do not use. Published from a dirty working tree, so the tarball contains code that exists in no
+commit and cannot be rebuilt from the repository. Superseded by 0.1.1.
+
+Initial release: headless WorkOS over one shared "Spawn" project — `IdentityGateway`, the edge-safe
+policy layer, the Next.js session seam, `authProxy`, `handleCallback`, and the headless flows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spawn LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/{chunk-SISIAS4C.js → chunk-ZIYU4K3F.js}

@@ -16,12 +16,25 @@ function allowedEmailDomains() {
   const raw = process.env.ALLOWED_EMAIL_DOMAINS;
   return (raw ? raw.split(",") : []).map((d) => d.trim().toLowerCase().replace(/^@/, "")).filter(Boolean);
 }
+function requiresEmailDomainGate() {
+  return process.env.AUTH_REQUIRE_EMAIL_DOMAINS === "true";
+}
+function assertEmailDomainGate() {
+  if (requiresEmailDomainGate() && allowedEmailDomains().length === 0) {
+    throw new Error(
+      "AUTH_REQUIRE_EMAIL_DOMAINS=true but ALLOWED_EMAIL_DOMAINS is empty. This app must not run ungated: every Spawn app shares one WorkOS user pool, so an empty gate admits everyone."
+    );
+  }
+}
 function isAllowedEmail(email) {
   const domains = allowedEmailDomains();
-  if (domains.length === 0) return true;
+  if (domains.length === 0) return !requiresEmailDomainGate();
   if (!email) return false;
-  const domain = email.trim().toLowerCase().split("@")[1];
-  return domain ? domains.includes(domain) : false;
+  const parts = email.trim().toLowerCase().split("@");
+  if (parts.length !== 2) return false;
+  const [local, domain] = parts;
+  if (!local || !domain) return false;
+  return domains.includes(domain);
 }
 function workosClientId() {
   const id = process.env.WORKOS_CLIENT_ID || process.env.NEXT_PUBLIC_WORKOS_CLIENT_ID;
@@ -29,4 +42,4 @@ function workosClientId() {
   return id;
 }
 
-export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId };
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, assertEmailDomainGate, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };

package/dist/config.d.ts

@@ -20,8 +20,23 @@ declare function isWorkosConfigured(): boolean;
  * `spawnpartners.com`. Returns true (allowed) when no gate is configured.
  */
 declare function allowedEmailDomains(): string[];
+/**
+ * Internal tools opt in with `AUTH_REQUIRE_EMAIL_DOMAINS=true`, declaring "I am gated".
+ *
+ * Why this exists: the whole suite shares ONE WorkOS client, so every app's user pool is every
+ * other app's user pool. An internal console that relies on the env default would, the moment
+ * `ALLOWED_EMAIL_DOMAINS` went missing or got typo'd, silently admit every customer of every
+ * customer-facing product — with no error and no visible symptom. Declaring the requirement turns
+ * that silent full-access failure into a loud boot failure.
+ */
+declare function requiresEmailDomainGate(): boolean;
+/**
+ * Throw unless the domain gate is actually configured. Call at boot (module scope) in any app that
+ * must never be world-readable, so a misconfiguration fails the deploy instead of opening the door.
+ */
+declare function assertEmailDomainGate(): void;
 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 };
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, assertEmailDomainGate, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };

package/dist/config.js

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

package/dist/index.js

@@ -1,4 +1,4 @@
-export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './chunk-SISIAS4C.js';
+export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './chunk-ZIYU4K3F.js';
 
 // src/identity/workos-gateway.ts
 var ROLES = ["owner", "admin", "member"];

package/dist/nextjs/index.d.ts

@@ -32,6 +32,18 @@ declare function userDisplayName(user: User): string;
  *
  * Pass `{ enforce: true }` only if you want middleware-level gating to WorkOS's hosted UI instead
  * of your own screens (not the Spawn default).
+ *
+ * ## There is deliberately no "redirect to my own /login" middleware mode
+ *
+ * It looks like the obvious third option, and it is a trap. The default mode does NOT protect
+ * anything — it only refreshes. So an app that has routes reachable *only* because middleware
+ * gates them (typically API route handlers with no in-handler check) becomes wide open the moment
+ * it adopts this proxy. Middleware gating reads as protection while being the easiest thing to
+ * silently lose to a matcher edit.
+ *
+ * Gate in the route instead: `requireUser()` in authed layouts, and an explicit `requireUser()` at
+ * the top of every API handler that returns data. That survives matcher changes, is greppable, and
+ * fails closed. Before adopting this proxy, audit for handlers whose only protection is the matcher.
  */
 declare function authProxy(options?: {
     enforce?: boolean;
@@ -45,6 +57,21 @@ declare function authProxy(options?: {
  *
  * 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.
+ *
+ * ## Where the email-domain gate runs for social login
+ *
+ * NOT here, deliberately. The password flows in `flows.ts` gate before calling WorkOS, so no
+ * credential is ever minted for an off-domain address. Social login cannot do that: the address is
+ * only known after the code exchange, and authkit's `onSuccess` hook is typed
+ * `(data) => void | Promise<void>` — it can observe the result but cannot redirect or veto it.
+ *
+ * So for OAuth the gate is enforced on READ, by `currentUser()`/`session()`/`requireUser()` in
+ * `session.ts`, which return null for a disallowed domain. An off-domain social login therefore
+ * receives a session cookie that grants nothing — every read treats it as signed out and the app
+ * bounces to `/login`.
+ *
+ * The consequence worth knowing: for OAuth, those readers are load-bearing. An app that reaches
+ * past them to `withAuth()` directly would see a user the gate intends to reject. Use the seam.
  */
 declare function handleCallback(options?: {
     returnPathname?: string;

package/dist/nextjs/index.js

@@ -1,4 +1,4 @@
-import { isWorkosConfigured, isAllowedEmail, publicPaths, workosClientId } from '../chunk-SISIAS4C.js';
+import { isWorkosConfigured, isAllowedEmail, publicPaths, workosClientId } from '../chunk-ZIYU4K3F.js';
 import { redirect } from 'next/navigation';
 import { authkitMiddleware, handleAuth, getWorkOS, saveSession } from '@workos-inc/authkit-nextjs';
 import { headers, cookies } from 'next/headers';
@@ -94,9 +94,20 @@ function errorCode(err) {
   const code = err.code;
   return typeof code === "string" ? code : void 0;
 }
+function requirementCodes(err) {
+  const msg = err?.message;
+  if (typeof msg !== "string") return [];
+  return msg.split("\n").slice(1).map((line) => line.trim()).filter((line) => /^[a-z0-9_]+$/.test(line));
+}
 function message(err, fallback) {
   const code = errorCode(err);
   if (code && FRIENDLY[code]) return FRIENDLY[code];
+  const requirements = requirementCodes(err);
+  for (const requirement of requirements) {
+    if (FRIENDLY[requirement]) return FRIENDLY[requirement];
+  }
+  if (requirements.some((r) => r.includes("password"))) return FRIENDLY.password_strength_error;
+  if (requirements.some((r) => r.includes("email"))) return "That email doesn't look right.";
   const errors = err?.errors;
   if (Array.isArray(errors)) {
     const field = errors.find(
@@ -113,6 +124,10 @@ function pendingVerificationToken(err) {
   if (e.code !== "email_verification_required") return void 0;
   return typeof e.pendingAuthenticationToken === "string" ? e.pendingAuthenticationToken : void 0;
 }
+function domainRejection(email) {
+  if (isAllowedEmail(email)) return null;
+  return { status: "error", error: "That email address isn't allowed to sign in here." };
+}
 var PENDING_COOKIE = "spawn_pending_verification";
 var PENDING_TTL_SECONDS = 15 * 60;
 async function rememberPendingToken(token) {
@@ -131,6 +146,8 @@ async function clearPendingToken() {
   (await cookies()).delete(PENDING_COOKIE);
 }
 async function signInWithPassword(input) {
+  const rejected = domainRejection(input.email);
+  if (rejected) return rejected;
   try {
     const res = await getWorkOS().userManagement.authenticateWithPassword({
       clientId: workosClientId(),
@@ -149,6 +166,8 @@ async function signInWithPassword(input) {
   }
 }
 async function signUp(input) {
+  const rejected = domainRejection(input.email);
+  if (rejected) return rejected;
   const workos = getWorkOS();
   try {
     const user = await workos.userManagement.createUser({
@@ -193,6 +212,11 @@ async function verifyEmail(input) {
       code: input.code,
       pendingAuthenticationToken: pendingToken
     });
+    const rejected = domainRejection(res.user.email);
+    if (rejected) {
+      await clearPendingToken();
+      return rejected;
+    }
     await saveSession(res, await origin());
     await clearPendingToken();
     return { status: "ok" };
@@ -209,6 +233,7 @@ async function verifyEmail(input) {
   }
 }
 async function requestPasswordReset(input) {
+  if (!isAllowedEmail(input.email)) return { status: "ok" };
   try {
     await getWorkOS().userManagement.createPasswordReset({ email: input.email });
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spawn-llc/auth",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -29,18 +29,10 @@
   "files": [
     "dist",
     "README.md",
-    "IDENTITY.md"
+    "IDENTITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
-  "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"
@@ -57,6 +49,17 @@
     "@types/react": "^19.0.0",
     "next": "^16.2.10",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "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"
   }
-}
+}