@spawn-llc/auth 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.3.1
+
+**Fix: the `config.matcher` recommendation from 0.3.0 does not build under Next 16.** Next requires
+`config.matcher` entries to be inline string literals it can statically parse — `export const config
+= authProxyConfig` (an imported object) fails the build with "the exported `config` field needs to
+be a static object". 0.3.0 shipped and documented exactly that broken pattern.
+
+- **Removed `authProxyConfig`.** It could not be used for its only purpose. Apps paste the matcher
+  literal inline instead.
+- **Added the `AuthMatcher` type** (`typeof AUTH_MATCHER`). Pin the inlined literal with
+  `satisfies { readonly matcher: readonly [AuthMatcher] }` so `tsc` fails if the copy ever drifts
+  from the shared `AUTH_MATCHER`. `AUTH_MATCHER` itself is unchanged.
+- **Docs:** `proxy.ts` is now the one canonical filename (Next 16 deprecates `middleware.ts`,
+  including for apps that wrap the proxy — `safeAuthProxy` is a `proxy.ts` default export too).
+
+## 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,14 @@ 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` (Next 16's name — `middleware.ts` is deprecated) → `export default authProxy()` plus a
+   `config` whose `matcher` is the inline hardened literal, pinned with
+   `satisfies { readonly matcher: readonly [AuthMatcher] }` (Next requires an inline literal, so it
+   can't be an imported object; the `AuthMatcher` type fails `tsc` if the copy drifts from
+   `AUTH_MATCHER`). `app/callback/route.ts` → `export const GET = handleCallback()`. If the app must
+   stay up on preview deploys with no secrets, make the `proxy.ts` default export
+   `safeAuthProxy({ onUnconfigured })`. 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,56 @@ 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` + its
+  `AuthMatcher` literal type for pinning an app's inlined `config.matcher`).
 - **`@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)
 
+Next 16 calls this file `proxy.ts` (the old `middleware.ts` name is deprecated). Next requires
+`config.matcher` to be an **inline** string literal — a `const`/imported object fails the build — so
+paste the matcher and pin it to the shared `AuthMatcher` type, which fails `tsc` if it ever drifts:
+
 ```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 type { AuthMatcher } from "@spawn-llc/auth/config";
 export default authProxy();
-export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"] };
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon\\.ico|(?!(?:.*/)?api/).*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)"],
+} satisfies { readonly matcher: readonly [AuthMatcher] };
+```
+
+Need to fail closed when the WORKOS_* secrets are absent (a preview deploy)? Keep the same `proxy.ts`
+but wrap with `safeAuthProxy({ onUnconfigured })` as the default export:
+
+```ts
+// proxy.ts (fail closed when identity is unconfigured)
+import { safeAuthProxy } from "@spawn-llc/auth/nextjs";
+import { 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)),
+});
+// (same `config` block as above)
+```
+
+```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-XZJS2F5Q.js}

@@ -7,6 +7,10 @@ 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)$).*)";
 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 +46,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, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId };

package/dist/config.d.ts

@@ -8,6 +8,49 @@ 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)$).*)";
+/**
+ * The literal type of {@link AUTH_MATCHER}, for pinning an app's inlined matcher to the shared
+ * source without any runtime import.
+ *
+ * Next requires `config.matcher` entries to be INLINE string literals it can statically parse at
+ * build time — a `const`/imported reference (`export const config = someObject`) fails the build
+ * with "the exported `config` field needs to be a static object". So an app cannot consume a
+ * ready-made config object; it must paste the literal. To stop that copy from silently drifting,
+ * pin it with `satisfies`:
+ *
+ *   import { authProxy } from "@spawn-llc/auth/nextjs";
+ *   import type { AuthMatcher } from "@spawn-llc/auth/config";
+ *   export default authProxy();
+ *   export const config = {
+ *     matcher: [AUTH_MATCHER_LITERAL],   // paste the value of AUTH_MATCHER inline (see README)
+ *   } satisfies { readonly matcher: readonly [AuthMatcher] };
+ *
+ * `tsc` then fails if the pasted literal ever diverges from `AUTH_MATCHER`. The import is type-only,
+ * so nothing lands in the bundle. (The literal is spelled out in README.md / IDENTITY.md — it is
+ * omitted from this doc-comment because the regex contains a comment-terminating sequence.)
+ */
+type AuthMatcher = typeof AUTH_MATCHER;
 /**
  * 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 +82,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, type AuthMatcher, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, assertEmailDomainGate, 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, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId } from './chunk-XZJS2F5Q.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, AuthMatcher, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, 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, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './chunk-XZJS2F5Q.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, AuthMatcher } 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,13 @@ 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
+ * (Next 16's name; `middleware.ts` is deprecated). Next requires `config.matcher` to be an inline
+ * string literal, so paste the matcher and pin it to the shared `AuthMatcher` type — see
+ * {@link AuthMatcher} in `../config` for the exact snippet.
  *
- *   export default authProxy();
- *   export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"] };
+ * When an app needs its own fail-closed behavior for the WORKOS-unconfigured case (a preview deploy
+ * with no secrets), wrap with `safeAuthProxy` — still from `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 +63,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, …).
+ *
+ *   // proxy.ts
+ *   import { safeAuthProxy } from "@spawn-llc/auth/nextjs";
+ *   import { 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 = { matcher: [...] } satisfies { readonly matcher: readonly [AuthMatcher] }
+ *
+ * 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 +183,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-XZJS2F5Q.js';
+export { AUTH_MATCHER } from '../chunk-XZJS2F5Q.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.1",
   "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",