najm-auth 3.1.5 → 3.2.1

package/README.md

@@ -129,9 +129,10 @@ auth({
   database?: string                        // Default: 'default'
   blacklistPrefix?: string                 // Default: 'auth:blacklist:'
 
-  // Registration
-  defaultRole?: string | null              // Auto-assign role to new users
-  bcryptRounds?: number                    // Default: 10 (valid: 4-31)
+  // Registration
+  defaultRole?: string | null              // Auto-assign role to new users
+  publicRegistration?: boolean             // Default: true; mounts POST /auth/register
+  bcryptRounds?: number                    // Default: 10 (valid: 4-31)
 
   // Frontend
   frontendUrl?: string                     // Password reset link base URL
@@ -181,7 +182,7 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 
 | Method | Path | Description | Auth |
 |--------|------|-------------|------|
-| `POST` | `/auth/register` | Register new user | None |
+| `POST` | `/auth/register` | Register new user (omitted when `publicRegistration: false`) | None |
 | `POST` | `/auth/login` | Login with email/password | None |
 | `POST` | `/auth/refresh` | Refresh access token (cookie) | None (uses refresh cookie) |
 | `POST` | `/auth/session/recover` | Reissue signed session without token rotation | Refresh cookie + recovery header |
@@ -194,7 +195,12 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 | `POST` | `/auth/oauth/google/link` | Link Google to the current user | ✅ Required |
 | `GET` | `/auth/credential-setup/setup` | Read the pending setup session | Setup cookie |
 | `POST` | `/auth/credential-setup/change` | Replace the temporary credential | Setup cookie |
-| `POST` | `/auth/credential-setup/cancel` | Abandon the setup session | Setup cookie |
+| `POST` | `/auth/credential-setup/cancel` | Abandon the setup session | Setup cookie |
+
+Applications with an approval-owned onboarding flow should set
+`publicRegistration: false`. This removes the unauthenticated route while
+retaining `AuthService.registerUser()`, `provisionUser()`, and other internal
+account-management APIs for trusted application services.
 
 ### Identity presets
 
@@ -766,13 +772,14 @@ auth({
 
 ## Next.js App Router Structure
 
-Every App Router application keeps the same three files. Copying more than this
+Every App Router application keeps the same four files. Copying more than this
 between apps means logic that belongs in the package has leaked into them.
 
 ```text
 src/lib/auth.ts     defineAuth() configuration — browser, server, and proxy safe
 src/lib/session.ts  one createReactServerAuth() instance for Server Components
-src/proxy.ts        imports auth.ts only, and exports auth.middleware
+src/proxy.ts        exports auth.proxy plus Next's required static matcher
+src/app/api/[...route]/route.ts  binds the server through auth.routeHandlers()
 ```
 
 ```typescript
@@ -786,6 +793,7 @@ export const auth = defineAuth({
   publicRoutes: ['/', '/login'],
   protectedRoutes: ['/dashboard/:path*', '/admin/:path*'],
   roleRoutes: { '/admin/:path*': ['admin'] },
+  proxySessionMode: 'optimistic',
 });
 ```
 
@@ -804,10 +812,33 @@ export const serverAuth = createReactServerAuth(auth);
 // src/proxy.ts
 import { auth } from './lib/auth';
 
-export default auth.middleware;
-export const config = auth.config;
+export default auth.proxy;
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
 ```
 
+Next.js 16 requires the exported Proxy `config` to be a statically analyzable
+object literal. Turbopack rejects `export const config = auth.config`, so the
+matcher is the one integration value that cannot be composed at runtime.
+
+```typescript
+// src/app/api/[...route]/route.ts
+import { handle } from 'najm-core';
+import server from '@app/server';
+
+import { auth } from '../../../lib/auth';
+
+const handlers = auth.routeHandlers(handle(server));
+export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = handlers;
+```
+
+`auth.routeHandlers()` applies the remember-me lifecycle to login, refresh,
+credential setup, and logout for every supported Next.js verb. It automatically
+uses the refresh and signed-session cookie names from `defineAuth()`; an app only
+passes an option when it intentionally customizes behavior, such as
+`{ rememberCookieName: 'school.remember' }`.
+
 ### Why `session.ts` exists
 
 A Next.js page is not one function. The root layout, each nested layout, and the
@@ -862,7 +893,7 @@ the same reason in mirror image:
 | the `createReactServerAuth()` module | server only | browser, Edge |
 
 `auth.client` and `auth.api` are what Client Components call, and
-`auth.middleware` is what the Edge proxy calls, so the `defineAuth()` module is
+`auth.proxy` is what the Edge proxy calls, so the `defineAuth()` module is
 always in the browser and Edge graphs. The adapter must never be. Putting both
 in one file puts the adapter everywhere `auth` already is, and the `browser`
 export condition — which exists precisely to catch this — resolves to a module
@@ -910,13 +941,19 @@ into a silently anonymous page.
 |---|---|
 | `loginRoute`, `forbiddenRoute`, route matchers, `roleRoutes` | when to redirect where |
 | cookie names, `apiBaseURL`, `authPrefix`, recovery URL | request memoization |
-| `refreshThreshold`, `tabSync`, `verifyAlways` | strict vs optional semantics |
+| `refreshThreshold`, `tabSync`, `proxySessionMode` | strict vs optional semantics |
 | — | `session.roles` / `user.role` fallback |
 | — | error classification |
 
-If a new app has to copy anything beyond the three files above, that logic
+If a new app has to copy anything beyond the four files above, that logic
 belongs in the package instead.
 
+`proxySessionMode: 'optimistic'` is the default and locally verifies the signed
+snapshot, matching Next.js guidance that Proxy is an optimistic routing boundary.
+Use `'authoritative'` only when every protected navigation must also validate
+refresh-session state. The older `verifyAlways` option and `auth.middleware`
+property remain as deprecated compatibility aliases.
+
 ### What a new app must prove
 
 At its real Next.js production boundary, not with mocks:
@@ -999,8 +1036,10 @@ throw new HttpError(403, 'Insufficient permissions for this action');
   when their public reverse-proxy origin is not reachable from the app process.
 - `onRecoveryFailure` exposes structured, secret-free recovery diagnostics
   without logging anything by default.
-- `verifyAlways` forces that authoritative check on every protected request;
-  the default bounds cached role/status staleness to `session.maxAge`.
+- `proxySessionMode: 'authoritative'` forces that check on every protected
+  request; the default `'optimistic'` mode bounds cached role/status staleness
+  to `session.maxAge`. The deprecated `verifyAlways` flag maps to the same
+  behavior for existing applications.
 
 ### Next.js 16 Reverse-Proxy Recovery
 

package/dist/client/edge.d.ts

@@ -2,6 +2,7 @@ import * as next_server from 'next/server';
 import { S as SessionRecoveryFailure } from '../sessionRecovery-D5Fa0yZ1.js';
 export { a as SessionRecoveryErrorDetails, b as SessionRecoveryFailureReason } from '../sessionRecovery-D5Fa0yZ1.js';
 
+type ProxySessionMode = 'optimistic' | 'authoritative';
 interface AuthMiddlewareConfig {
     /** Routes that require authentication (glob patterns) */
     protectedRoutes?: string[];
@@ -28,8 +29,15 @@ interface AuthMiddlewareConfig {
     /**
      * Force authoritative refresh-session validation on every protected request.
      * This reissues the signed session cookie without rotating refresh tokens.
+     * @deprecated Use `proxySessionMode: 'authoritative'` instead.
      */
     verifyAlways?: boolean;
+    /**
+     * How Proxy handles an otherwise valid signed session snapshot.
+     * `optimistic` verifies it locally; `authoritative` also checks refresh state.
+     * Defaults to `optimistic`.
+     */
+    proxySessionMode?: ProxySessionMode;
     /**
      * Session-recovery endpoint. Relative values resolve against the request
      * origin. Defaults to `${apiBaseURL}${authPrefix}/session/recover`.
@@ -67,4 +75,4 @@ interface AuthMiddlewareConfig {
  */
 declare function withAuthMiddleware(config: AuthMiddlewareConfig): (request: Request) => Promise<next_server.NextResponse<unknown>>;
 
-export { type AuthMiddlewareConfig, SessionRecoveryFailure, withAuthMiddleware };
+export { type AuthMiddlewareConfig, type ProxySessionMode, SessionRecoveryFailure, withAuthMiddleware };

package/dist/client/edge.js

@@ -345,11 +345,13 @@ function withAuthMiddleware(config) {
     sessionCookieName = "najm.session",
     sessionSecret,
     sessionMaxAge,
-    verifyAlways = false,
+    verifyAlways: legacyVerifyAlways = false,
+    proxySessionMode,
     recoveryURL,
     internalRecoveryURL,
     onRecoveryFailure
   } = config;
+  const verifyAlways = proxySessionMode === void 0 ? legacyVerifyAlways : proxySessionMode === "authoritative";
   const resolvedInternalRecoveryURL = resolveInternalRecoveryURL(internalRecoveryURL);
   return /* @__PURE__ */ __name(async function middleware(request) {
     const { NextResponse } = await import("next/server");

package/dist/client/server/index.d.ts

@@ -1,5 +1,6 @@
 import { A as AuthUser, R as RetryConfig } from '../../types-BaSfgxqE.js';
 import { F as FetchClient, N as NajmAuthClient } from '../../NajmAuthClient-ZtXTIUSF.js';
+import { ProxySessionMode } from '../edge.js';
 export { withAuthMiddleware } from '../edge.js';
 import { G as GetSessionConfig, S as ServerSession$1 } from '../../getSession-BthP85UA.js';
 export { A as AuthConfigError, a as AuthTransportError, N as NoSessionError, g as getSession } from '../../getSession-BthP85UA.js';
@@ -88,6 +89,68 @@ interface WithAuthProps<P> {
  */
 declare function withAuth<P extends Record<string, unknown> = Record<string, unknown>>(Page: (args: WithAuthProps<P>) => Promise<unknown> | unknown, options?: WithAuthOptions): (props: P) => Promise<unknown>;
 
+type AuthRouteHandler<Args extends unknown[] = []> = (request: Request, ...args: Args) => Response | Promise<Response>;
+interface NextAuthRouteHandlers<Args extends unknown[] = []> {
+    GET: AuthRouteHandler<Args>;
+    POST: AuthRouteHandler<Args>;
+    PUT: AuthRouteHandler<Args>;
+    PATCH: AuthRouteHandler<Args>;
+    DELETE: AuthRouteHandler<Args>;
+    HEAD: AuthRouteHandler<Args>;
+    OPTIONS: AuthRouteHandler<Args>;
+}
+interface AuthCookiePersistenceOptions {
+    /**
+     * Cookies whose lifetime this rewrites. Defaults to the two najm-auth issues.
+     * Anything not named here is passed through untouched.
+     */
+    authCookieNames?: string[];
+    /** Where the one-bit choice is stored. Defaults to `najm.remember`. */
+    rememberCookieName?: string;
+    /** How long a remembered choice lasts. Defaults to 7 days. */
+    maxAgeSeconds?: number;
+    /** Paths whose JSON body carries `rememberMe`. Defaults to `/api/auth/login`. */
+    loginPaths?: string[];
+    /** Paths that end a session and clear the choice. Defaults to `/api/auth/logout`. */
+    logoutPaths?: string[];
+    /** Paths that reissue cookies and must reapply the stored choice. */
+    refreshPaths?: string[];
+    /**
+     * Paths that finish credential setup. The stored choice is cleared there:
+     * the login it was recorded for never produced a session.
+     */
+    setupCompletionPaths?: string[];
+    /**
+     * Recognizes a response that has *not* issued a usable session because the
+     * user must still set up credentials.
+     *
+     * Najm's own setup response is recognized without this — supply it only to
+     * cover an application-specific shape. Such a response may carry auth
+     * cookies anyway, and persisting them would leave a half-authenticated
+     * browser that skips the setup step on reload. Returning `true` replaces
+     * them with deletions and clears the stored choice.
+     */
+    isSetupResponse?: (payload: unknown) => boolean;
+}
+/**
+ * Strips the lifetime attributes so the browser drops the cookie when it closes.
+ *
+ * Only the named auth cookies are touched — rewriting an unrelated `Set-Cookie`
+ * from the same response would be a silent side effect on someone else's state.
+ */
+declare function makeSessionCookie(setCookie: string, authCookieNames?: string[]): string;
+/**
+ * Wraps a request handler so the auth cookies it issues match the user's
+ * "remember me" choice.
+ *
+ * ```ts
+ * // app/api/[...route]/route.ts
+ * const handler = withAuthCookiePersistence((req) => server.fetch(req));
+ * export { handler as GET, handler as POST };
+ * ```
+ */
+declare function withAuthCookiePersistence<Args extends unknown[] = []>(handler: AuthRouteHandler<Args>, options?: AuthCookiePersistenceOptions): AuthRouteHandler<Args>;
+
 interface DefineAuthConfig {
     /** API base URL (default: '/api') */
     apiBaseURL?: string;
@@ -138,13 +201,22 @@ interface DefineAuthConfig {
     recoveryURL?: string | false;
     /** Loopback-only recovery endpoint for self-hosted reverse-proxy setups. */
     internalRecoveryURL?: string;
-    /** Next.js middleware matcher (default: exclude _next, favicon, api) */
+    /**
+     * Next.js middleware matcher (default: exclude _next, favicon, api).
+     * @deprecated Next.js 16 requires a static matcher literal in `proxy.ts`.
+     */
     matcher?: string[];
     /**
      * Force authoritative refresh-session validation on every protected request.
      * Recovery reissues the signed cookie without rotating refresh tokens.
+     * @deprecated Use `proxySessionMode: 'authoritative'` instead.
      */
     verifyAlways?: boolean;
+    /**
+     * How Proxy handles a valid signed session snapshot. Defaults to `optimistic`.
+     * API and server authorization remain authoritative in either mode.
+     */
+    proxySessionMode?: ProxySessionMode;
     /** Secret-free diagnostic hook for failed server or proxy recovery. */
     onRecoveryFailure?: (failure: SessionRecoveryFailure) => void;
 }
@@ -171,12 +243,19 @@ interface AuthKit {
      * ```
      */
     requireRole: (roles: string[]) => Promise<ServerSession$1>;
-    /** Generated Next.js middleware function */
+    /** Generated Next.js 16 Proxy function. */
+    proxy: (request: Request) => Promise<Response>;
+    /** @deprecated Next.js 16 renamed Middleware to Proxy. Use `proxy`. */
     middleware: (request: Request) => Promise<Response>;
-    /** Next.js middleware config with matcher */
+    /** @deprecated Next.js 16 requires a static config literal in `proxy.ts`. */
     config: {
         matcher: string[];
     };
+    /**
+     * Bind a Web Request handler to every Next.js Route Handler verb and apply
+     * Najm's login, refresh, setup, and logout cookie lifecycle consistently.
+     */
+    routeHandlers: <Args extends unknown[] = []>(handler: AuthRouteHandler<Args>, options?: AuthCookiePersistenceOptions) => NextAuthRouteHandlers<Args>;
     /**
      * Protect a server component — redirects to loginRoute if unauthenticated.
      * Passes session to the wrapped component.
@@ -219,57 +298,4 @@ interface SafeRedirectOptions {
  */
 declare function getSafeRedirectPath(value: string | string[] | undefined | null, options?: SafeRedirectOptions | string): string;
 
-type RequestHandler = (request: Request) => Promise<Response>;
-interface AuthCookiePersistenceOptions {
-    /**
-     * Cookies whose lifetime this rewrites. Defaults to the two najm-auth issues.
-     * Anything not named here is passed through untouched.
-     */
-    authCookieNames?: string[];
-    /** Where the one-bit choice is stored. Defaults to `najm.remember`. */
-    rememberCookieName?: string;
-    /** How long a remembered choice lasts. Defaults to 7 days. */
-    maxAgeSeconds?: number;
-    /** Paths whose JSON body carries `rememberMe`. Defaults to `/api/auth/login`. */
-    loginPaths?: string[];
-    /** Paths that end a session and clear the choice. Defaults to `/api/auth/logout`. */
-    logoutPaths?: string[];
-    /** Paths that reissue cookies and must reapply the stored choice. */
-    refreshPaths?: string[];
-    /**
-     * Paths that finish credential setup. The stored choice is cleared there:
-     * the login it was recorded for never produced a session.
-     */
-    setupCompletionPaths?: string[];
-    /**
-     * Recognizes a response that has *not* issued a usable session because the
-     * user must still set up credentials.
-     *
-     * Najm's own setup response is recognized without this — supply it only to
-     * cover an application-specific shape. Such a response may carry auth
-     * cookies anyway, and persisting them would leave a half-authenticated
-     * browser that skips the setup step on reload. Returning `true` replaces
-     * them with deletions and clears the stored choice.
-     */
-    isSetupResponse?: (payload: unknown) => boolean;
-}
-/**
- * Strips the lifetime attributes so the browser drops the cookie when it closes.
- *
- * Only the named auth cookies are touched — rewriting an unrelated `Set-Cookie`
- * from the same response would be a silent side effect on someone else's state.
- */
-declare function makeSessionCookie(setCookie: string, authCookieNames?: string[]): string;
-/**
- * Wraps a request handler so the auth cookies it issues match the user's
- * "remember me" choice.
- *
- * ```ts
- * // app/api/[...route]/route.ts
- * const handler = withAuthCookiePersistence((req) => server.fetch(req));
- * export { handler as GET, handler as POST };
- * ```
- */
-declare function withAuthCookiePersistence(handler: RequestHandler, options?: AuthCookiePersistenceOptions): RequestHandler;
-
-export { type AuthCookiePersistenceOptions, type AuthKit, type DefineAuthConfig, GetSessionConfig, type SafeRedirectOptions, ServerSession$1 as ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, makeSessionCookie, withAuth, withAuthCookiePersistence };
+export { type AuthCookiePersistenceOptions, type AuthKit, type AuthRouteHandler, type DefineAuthConfig, GetSessionConfig, type NextAuthRouteHandlers, ProxySessionMode, type SafeRedirectOptions, ServerSession$1 as ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, makeSessionCookie, withAuth, withAuthCookiePersistence };