@spawn-llc/auth 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.0
+
+**Thicken the package so apps need no local auth layer or copy-pasted wiring.** Everything the apps
+were reaching around for now lives here, and the docs stop recommending the unsafe matcher.
+
+- **`AUTH_MATCHER` + `authProxyConfig` (from `@spawn-llc/auth/config`).** The one hardened
+  proxy/middleware matcher, defined once instead of copy-pasted per app. It closes the "F1" bypass
+  where a dynamic API segment ending in an image extension (`PATCH /api/thing/{id}.png`) escaped the
+  gate. Use `export const config = authProxyConfig`. The README/IDENTITY examples previously showed a
+  matcher that excluded `/api` entirely and left that bypass open — fixed.
+- **`safeAuthProxy({ onUnconfigured })` (from `@spawn-llc/auth/nextjs`).** Fails **closed** when the
+  WORKOS_* secrets are absent, delegating to an app-supplied fallback (redirect / 404 / next). Folds
+  the three different hand-rolled "unconfigured" branches (`admin`, `landing`, `sites`) into one
+  shared code path. `authProxy()` is unchanged.
+- **`requireApiUser()` (from `@spawn-llc/auth/nextjs`).** The API-handler counterpart to
+  `requireUser()`: returns the `User`, or a `401` JSON `NextResponse` when signed out (never a
+  redirect, which a `fetch()` caller can't parse). Replaces the per-app `lib/api-auth.ts` wrappers.
+- **`appPublicPaths(extra)` (from `@spawn-llc/auth/config`).** Shared defaults plus an app's in-code
+  public routes, so an app with app-specific public paths (a Slack webhook, a cron tick) no longer
+  needs a local config wrapper package.
+- **Convention:** `proxy.ts` + `export default authProxy()` is canonical; use `middleware.ts` only
+  when genuinely wrapping the proxy (e.g. `safeAuthProxy`, host routing).
+
 ## 0.2.1
 
 **Fix: the session readers now force dynamic rendering before any early return.**

package/IDENTITY.md

@@ -51,8 +51,11 @@ app                        →  own /login /signup /verify /reset routes renderi
 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()`.
+3. `proxy.ts` → `export default authProxy()` + `export const config = authProxyConfig` (the shared
+   hardened matcher). `app/callback/route.ts` → `export const GET = handleCallback()`. If the app
+   must stay up on preview deploys with no secrets, use a `middleware.ts` wrapping
+   `safeAuthProxy({ onUnconfigured })` instead. Gate API handlers with `requireApiUser()` (401 JSON,
+   never a redirect); pages/layouts with `requireUser()`.
 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`.

package/README.md

@@ -23,19 +23,36 @@ internal tools), `AUTH_PUBLIC_PATHS`.
 - **`@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/config`** — the edge-safe policy alone (import from middleware; no SDK): the
+  gate + `isPublicPath` / `appPublicPaths` and the shared hardened matcher (`AUTH_MATCHER`,
+  `authProxyConfig`).
 - **`@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`).
+  (`currentUser` / `requireUser` / `requireApiUser` / `session` / `signOut` / `switchOrganization`),
+  `authProxy()` / `safeAuthProxy()`, `handleCallback()`, and the headless flows
+  (`signInWithPassword`, `signUp`, `verifyEmail`, `requestPasswordReset`, `resetPassword`,
+  `startOAuth`).
 
 ## Wire an app (Next.js)
 
 ```ts
-// proxy.ts (gate every route)
+// proxy.ts (refresh the session on every route; gate in-app via requireUser())
 import { authProxy } from "@spawn-llc/auth/nextjs";
+import { authProxyConfig } from "@spawn-llc/auth/config";
 export default authProxy();
-export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"] };
+export const config = authProxyConfig; // the one shared hardened matcher — don't hand-write it
+```
+
+Need to fail closed when the WORKOS_* secrets are absent (a preview deploy)? Use a `middleware.ts`
+that wraps the proxy with `safeAuthProxy({ onUnconfigured })` instead of a bare `proxy.ts`.
+
+```ts
+// app/(any)/api/route.ts — gate a route handler (401 JSON, never a redirect)
+import { requireApiUser } from "@spawn-llc/auth/nextjs";
+export async function GET() {
+  const user = await requireApiUser();
+  if (user instanceof Response) return user; // 401 when signed out
+  // ...use `user`
+}
 ```
 
 ```ts

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

@@ -7,6 +7,11 @@ function publicPaths() {
 function isPublicPath(pathname, paths = publicPaths()) {
   return paths.some((p) => pathname === p || pathname.startsWith(`${p}/`));
 }
+function appPublicPaths(extra) {
+  return [...publicPaths(), ...extra];
+}
+var AUTH_MATCHER = "/((?!_next/static|_next/image|favicon\\.ico|(?!(?:.*/)?api/).*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)";
+var authProxyConfig = { matcher: [AUTH_MATCHER] };
 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
@@ -42,4 +47,4 @@ function workosClientId() {
   return id;
 }
 
-export { DEFAULT_PUBLIC_PATHS, allowedEmailDomains, assertEmailDomainGate, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };
+export { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, assertEmailDomainGate, authProxyConfig, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };

package/dist/config.d.ts

@@ -8,6 +8,31 @@ declare const DEFAULT_PUBLIC_PATHS: readonly ["/login", "/signup", "/verify", "/
 /** 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;
+/**
+ * The public paths for an app that declares extra ones IN CODE (not via `AUTH_PUBLIC_PATHS`):
+ * the shared defaults plus the caller's list. Lets an app keep app-specific public routes (a
+ * Slack webhook, a cron tick, an unsubscribe link) alongside the login-flow defaults without a
+ * local wrapper package. Pair with `isPublicPath(pathname, appPublicPaths([...]))`.
+ */
+declare function appPublicPaths(extra: string[]): string[];
+/**
+ * The canonical proxy/middleware matcher — the ONE hardened regex every app should use, so the
+ * pattern is defined once here instead of copy-pasted per app. Runs the session-refresh proxy on
+ * everything except Next internals and genuine static assets.
+ *
+ * The image-extension carve-out is scoped with a negative lookahead for an "api/" path segment, so
+ * it can only ever match real static files (e.g. "/favicon.svg", "/og.png") — NEVER a route whose
+ * dynamic "[id]" segment happens to end in an image extension. Without that guard,
+ * "PATCH /api/thing/{id}.png" escaped the gate entirely: the extension satisfied the exclusion, yet
+ * Next still resolved the handler and ran it unauthenticated. API routes now always hit the proxy.
+ * Apps whose routes need in-request gating still call requireUser() / requireApiUser() in the
+ * handler — the matcher refreshes the cookie, it does not protect.
+ */
+declare const AUTH_MATCHER = "/((?!_next/static|_next/image|favicon\\.ico|(?!(?:.*/)?api/).*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)";
+/** Ready-made proxy config: `export const config = authProxyConfig` in an app's `proxy.ts`. */
+declare const authProxyConfig: {
+    readonly matcher: readonly ["/((?!_next/static|_next/image|favicon\\.ico|(?!(?:.*/)?api/).*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)"];
+};
 /**
  * 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
@@ -39,4 +64,4 @@ 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, assertEmailDomainGate, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };
+export { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, assertEmailDomainGate, authProxyConfig, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };

package/dist/config.js

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

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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';
+export { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, authProxyConfig, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './config.js';
 
 /**
  * The identity/tenancy port. WorkOS owns organizations, memberships (+ roles) and invitations; this

package/dist/index.js

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

package/dist/nextjs/index.d.ts

@@ -1,10 +1,27 @@
-import { U as User, S as Session } from '../domain-CmEhGW2N.js';
 import * as next_server from 'next/server';
+import { NextResponse, NextMiddleware, NextRequest, NextFetchEvent } from 'next/server';
+import { U as User, S as Session } from '../domain-CmEhGW2N.js';
+export { AUTH_MATCHER, authProxyConfig } from '../config.js';
 
 /** 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 API-route counterpart to `requireUser()`. Returns the signed-in `User`, or a `401` JSON
+ * `NextResponse` when there is no valid session.
+ *
+ * Why not just `requireUser()` in an API handler: `requireUser()` redirects to `/login`, which is
+ * right for a browser navigation but wrong for a `fetch()` — the caller gets a `200` HTML login
+ * page and a JSON parse error instead of a clean `401`. Route handlers should branch on the type:
+ *
+ *   const user = await requireApiUser();
+ *   if (user instanceof NextResponse) return user; // 401
+ *   // ...use `user`
+ *
+ * Applies the same email-domain gate + dynamic-render marking as `currentUser()`.
+ */
+declare function requireApiUser(): Promise<User | NextResponse>;
 /** 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. */
@@ -20,10 +37,16 @@ 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:
+ * unauthenticated visitors to `/login` (a Spawn screen). Use as the app's `proxy.ts` default export,
+ * with the shared hardened matcher (`authProxyConfig`) — do NOT hand-write the regex:
  *
+ *   import { authProxy } from "@spawn-llc/auth/nextjs";
+ *   import { authProxyConfig } from "@spawn-llc/auth/config";
  *   export default authProxy();
- *   export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"] };
+ *   export const config = authProxyConfig;
+ *
+ * When an app needs its own fail-closed behavior for the WORKOS-unconfigured case (a preview deploy
+ * with no secrets), wrap with `safeAuthProxy` from a `middleware.ts` instead of `proxy.ts`.
  *
  * Pass `{ enforce: true }` only if you want middleware-level gating to WorkOS's hosted UI instead
  * of your own screens (not the Spawn default).
@@ -43,7 +66,37 @@ declare function userDisplayName(user: User): string;
 declare function authProxy(options?: {
     enforce?: boolean;
     unauthenticatedPaths?: string[];
-}): next_server.NextMiddleware;
+}): NextMiddleware;
+/**
+ * `authProxy()`, but fail CLOSED when WorkOS is not configured.
+ *
+ * `authProxy()` assumes the WORKOS_* secrets are present; a build/preview deploy without them would
+ * otherwise refresh nothing and let every request through. Rather than each app hand-rolling that
+ * guard three different ways (redirect / 404 / boot-assert), `safeAuthProxy` owns the plumbing:
+ * when identity is configured it delegates to `authProxy(options)`; when it is NOT, it calls the
+ * app-supplied `onUnconfigured` handler so the app keeps its own fallback (redirect to `/login`,
+ * 404 the gated area, `NextResponse.next()` for a public-only preview, …).
+ *
+ *   // middleware.ts (this wraps the proxy, so it is a middleware, not a bare proxy)
+ *   import { safeAuthProxy } from "@spawn-llc/auth/nextjs";
+ *   import { authProxyConfig, isPublicPath } from "@spawn-llc/auth/config";
+ *   import { NextResponse } from "next/server";
+ *   export default safeAuthProxy({
+ *     onUnconfigured: (req) =>
+ *       isPublicPath(req.nextUrl.pathname)
+ *         ? NextResponse.next()
+ *         : NextResponse.redirect(new URL("/login", req.url)),
+ *   });
+ *   export const config = authProxyConfig;
+ *
+ * The configured/unconfigured decision is made ONCE, when the middleware is constructed (module
+ * load) — identity config does not change between requests within a running process.
+ */
+declare function safeAuthProxy(options: {
+    onUnconfigured: (request: NextRequest, event: NextFetchEvent) => ReturnType<NextMiddleware>;
+    enforce?: boolean;
+    unauthenticatedPaths?: string[];
+}): NextMiddleware;
 
 /**
  * The OAuth callback handler for the app's `/callback` route:
@@ -133,4 +186,4 @@ declare function startOAuth(input: {
     redirectUri?: string;
 }): Promise<string>;
 
-export { type FlowResult, type OAuthProvider, authProxy, currentUser, handleCallback, rejectedEmail, requestPasswordReset, requireUser, resetPassword, session, signInWithPassword, signOut, signUp, startOAuth, switchOrganization, userDisplayName, verifyEmail };
+export { type FlowResult, type OAuthProvider, authProxy, currentUser, handleCallback, rejectedEmail, requestPasswordReset, requireApiUser, requireUser, resetPassword, safeAuthProxy, session, signInWithPassword, signOut, signUp, startOAuth, switchOrganization, userDisplayName, verifyEmail };

package/dist/nextjs/index.js

@@ -1,6 +1,8 @@
-import { isWorkosConfigured, isAllowedEmail, publicPaths, workosClientId } from '../chunk-ZIYU4K3F.js';
+import { isWorkosConfigured, isAllowedEmail, publicPaths, workosClientId } from '../chunk-ELKYJ3OA.js';
+export { AUTH_MATCHER, authProxyConfig } from '../chunk-ELKYJ3OA.js';
 import { headers, cookies } from 'next/headers';
 import { redirect } from 'next/navigation';
+import { NextResponse } from 'next/server';
 import { authkitMiddleware, handleAuth, getWorkOS, saveSession } from '@workos-inc/authkit-nextjs';
 
 async function markDynamic() {
@@ -19,6 +21,11 @@ async function requireUser(redirectTo = "/login") {
   if (!user) redirect(redirectTo);
   return user;
 }
+async function requireApiUser() {
+  const user = await currentUser();
+  if (user) return user;
+  return NextResponse.json({ error: "Not authenticated" }, { status: 401 });
+}
 async function session() {
   await markDynamic();
   if (!isWorkosConfigured()) return null;
@@ -68,6 +75,10 @@ function authProxy(options) {
   }
   return authkitMiddleware();
 }
+function safeAuthProxy(options) {
+  const proxy = isWorkosConfigured() ? authProxy({ enforce: options.enforce, unauthenticatedPaths: options.unauthenticatedPaths }) : null;
+  return (request, event) => proxy ? proxy(request, event) : options.onUnconfigured(request, event);
+}
 function handleCallback(options) {
   return handleAuth({ returnPathname: options?.returnPathname ?? "/" });
 }
@@ -266,4 +277,4 @@ async function startOAuth(input) {
   });
 }
 
-export { authProxy, currentUser, handleCallback, rejectedEmail, requestPasswordReset, requireUser, resetPassword, session, signInWithPassword, signOut, signUp, startOAuth, switchOrganization, userDisplayName, verifyEmail };
+export { authProxy, currentUser, handleCallback, rejectedEmail, requestPasswordReset, requireApiUser, requireUser, resetPassword, safeAuthProxy, session, signInWithPassword, signOut, signUp, startOAuth, switchOrganization, userDisplayName, verifyEmail };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spawn-llc/auth",
-  "version": "0.2.1",
+  "version": "0.3.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",