@spawn-llc/auth 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

package/IDENTITY.md

@@ -51,11 +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()` + `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()`.
+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

@@ -24,8 +24,8 @@ internal tools), `AUTH_PUBLIC_PATHS`.
   `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): the
-  gate + `isPublicPath` / `appPublicPaths` and the shared hardened matcher (`AUTH_MATCHER`,
-  `authProxyConfig`).
+  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` / `requireApiUser` / `session` / `signOut` / `switchOrganization`),
   `authProxy()` / `safeAuthProxy()`, `handleCallback()`, and the headless flows
@@ -34,16 +34,36 @@ internal tools), `AUTH_PUBLIC_PATHS`.
 
 ## 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 (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";
+import type { AuthMatcher } from "@spawn-llc/auth/config";
 export default authProxy();
-export const config = authProxyConfig; // the one shared hardened matcher — don't hand-write it
+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)? Use a `middleware.ts`
-that wraps the proxy with `safeAuthProxy({ onUnconfigured })` instead of a bare `proxy.ts`.
+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)

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

@@ -11,7 +11,6 @@ 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
@@ -47,4 +46,4 @@ function workosClientId() {
   return id;
 }
 
-export { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, assertEmailDomainGate, authProxyConfig, 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

@@ -29,10 +29,28 @@ declare function appPublicPaths(extra: string[]): string[];
  * 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)$).*)"];
-};
+/**
+ * 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
@@ -64,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 { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, assertEmailDomainGate, authProxyConfig, 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 { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, assertEmailDomainGate, authProxyConfig, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, requiresEmailDomainGate, workosClientId } from './chunk-ELKYJ3OA.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 { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, authProxyConfig, 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 { AUTH_MATCHER, DEFAULT_PUBLIC_PATHS, allowedEmailDomains, appPublicPaths, authProxyConfig, isAllowedEmail, isPublicPath, isWorkosConfigured, publicPaths, workosClientId } from './chunk-ELKYJ3OA.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,7 +1,7 @@
 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';
+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>;
@@ -37,16 +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,
- * 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 = authProxyConfig;
+ * 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.
  *
  * 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`.
+ * 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).
@@ -77,9 +74,9 @@ declare function authProxy(options?: {
  * 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)
+ *   // proxy.ts
  *   import { safeAuthProxy } from "@spawn-llc/auth/nextjs";
- *   import { authProxyConfig, isPublicPath } from "@spawn-llc/auth/config";
+ *   import { isPublicPath } from "@spawn-llc/auth/config";
  *   import { NextResponse } from "next/server";
  *   export default safeAuthProxy({
  *     onUnconfigured: (req) =>
@@ -87,7 +84,7 @@ declare function authProxy(options?: {
  *         ? NextResponse.next()
  *         : NextResponse.redirect(new URL("/login", req.url)),
  *   });
- *   export const config = authProxyConfig;
+ *   // 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.

package/dist/nextjs/index.js

@@ -1,5 +1,5 @@
-import { isWorkosConfigured, isAllowedEmail, publicPaths, workosClientId } from '../chunk-ELKYJ3OA.js';
-export { AUTH_MATCHER, authProxyConfig } from '../chunk-ELKYJ3OA.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';

package/package.json

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