@payez/next-mvp 4.0.4 → 4.0.6

package/README.md

@@ -1,30 +1,40 @@
 # @payez/next-mvp
 
-PayEz IDP authentication package for Next.js 14/15 with pre-built UI components and complete authentication flow.
+Drop-in authentication for Next.js. One package, zero secret management in production.
 
-## Version History
+```bash
+npm install @payez/next-mvp next-auth
+```
+
+## How Secrets Work
+
+You never manage signing keys or OAuth credentials directly. The package resolves them automatically at startup based on your environment.
 
-### v2.4.2 (2025-11-14)
-- **Fixed**: Redirect loop on token expiration - middleware now allows NextAuth JWT callback to refresh expired tokens instead of immediately redirecting to login, preventing infinite redirect loops when access tokens expire
+| Environment | How it works | Secrets in your config? |
+|-------------|-------------|------------------------|
+| **Dev** | App calls IDP broker on your private network. One API key in `.env.local`. | One key (rotatable via CLI) |
+| **Production** | App calls a cluster-internal endpoint. Network boundary = identity. | None |
+| **Enterprise** | App uses an issued license key against your own or our IDP. | One key (rotatable via CLI) |
 
-### v2.4.1 (2025-11-14)
-- **Fixed**: Stale cookie detection - viability API now properly detects when JWT exists but Redis session is missing, preventing access with expired sessions
-- **Fixed**: Token refresh field names - changed to PascalCase (`RefreshToken`, `AuthenticationMethods`, `AuthenticationLevel`, `TwoFactorMethod`) to match IDP requirements, resolving 400 errors during token refresh
+**In production, there are no secrets to configure, rotate, or leak.** The app proves its identity by being inside the cluster.
+
+In dev, you have one key. Rotate it anytime:
+
+```bash
+npx @payez/cli secret rotate
+```
 
-### v2.4.0
-- Auth-ready v2 handlers with pre-configured routes
-- Redis session management improvements
-- Token refresh optimizations
+Full architecture: [SECRET-MANAGEMENT-ARCHITECTURE.md](../../docs/SECRET-MANAGEMENT-ARCHITECTURE.md)
 
 ## Features
 
-- 🔐 **Complete Authentication Flow** - Login, logout, session management, password recovery
-- 🎨 **Pre-built UI Components** - Ready-to-use login, recovery, and verify-code pages
-- 🔄 **Automatic Token Refresh** - Built-in refresh token handling
-- 🎭 **Themeable** - Customize branding, colors, and layout via ThemeProvider
-- 📱 **Responsive Design** - Mobile-first Tailwind CSS components
-- 🚀 **Next.js 14/15 Ready** - Works with App Router and React Server Components
-- 🔒 **Secure by Default** - JWT-based authentication with PayEz IDP
+- **Zero-secret production deployment** — no signing keys, no OAuth secrets in your env
+- **Complete authentication flow** — login, logout, session management, password recovery
+- **Pre-built UI components** — themed login, recovery, and verify-code pages
+- **Automatic token refresh** — built-in refresh token handling with Redis session backing
+- **Google OAuth + 2FA** — pre-configured providers, MFA with email/SMS
+- **Themeable** — branding, colors, and layout via ThemeProvider
+- **Next.js 14/15** — App Router, React Server Components, middleware-ready
 
 ## Installation
 

package/dist/auth/better-auth.d.ts

@@ -29,6 +29,7 @@ export declare function buildBetterAuthProviders(config: IDPClientConfig): Recor
  * Call after getIDPClientConfig() resolves.
  */
 export declare function createBetterAuthInstance(idpConfig: IDPClientConfig): import("better-auth").Auth<{
+    baseURL: string;
     secret: string;
     socialProviders: Record<string, BetterAuthSocialProvider>;
     trustedOrigins: string[];
@@ -39,6 +40,14 @@ export declare function createBetterAuthInstance(idpConfig: IDPClientConfig): im
             refreshCache: true;
         };
     };
+    advanced: {
+        cookiePrefix: string;
+        cookies: {
+            session_token: {
+                name: string;
+            };
+        };
+    };
     plugins: [{
         id: "next-cookies";
         hooks: {

package/dist/auth/better-auth.js

@@ -19,6 +19,7 @@ const better_auth_1 = require("better-auth");
 const next_js_1 = require("better-auth/next-js");
 const next_js_2 = require("better-auth/next-js");
 const idp_client_config_1 = require("../lib/idp-client-config");
+const app_slug_1 = require("../lib/app-slug");
 /**
  * Build Better Auth social providers from IDP config.
  */
@@ -43,13 +44,19 @@ function buildBetterAuthProviders(config) {
  * Call after getIDPClientConfig() resolves.
  */
 function createBetterAuthInstance(idpConfig) {
+    const appSlug = idpConfig.clientSlug || (0, app_slug_1.getAppSlug)();
+    // Resolve base URL: BETTER_AUTH_URL env > IDP config > localhost fallback
+    const baseURL = process.env.BETTER_AUTH_URL
+        || idpConfig.baseClientUrl
+        || `http://localhost:${process.env.PORT || '3000'}`;
     return (0, better_auth_1.betterAuth)({
+        baseURL,
         secret: idpConfig.nextAuthSecret,
         socialProviders: buildBetterAuthProviders(idpConfig),
         // Trust the app's own origin + any configured base URL
         trustedOrigins: [
-            ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
-            ...(process.env.BETTER_AUTH_URL ? [process.env.BETTER_AUTH_URL] : []),
+            baseURL,
+            ...(idpConfig.baseClientUrl && idpConfig.baseClientUrl !== baseURL ? [idpConfig.baseClientUrl] : []),
             'http://localhost:3000',
             'http://localhost:3400',
             'http://localhost:3600',
@@ -63,6 +70,15 @@ function createBetterAuthInstance(idpConfig) {
                 refreshCache: true,
             },
         },
+        // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
+        advanced: {
+            cookiePrefix: appSlug,
+            cookies: {
+                session_token: {
+                    name: `${appSlug}.session-token`,
+                },
+            },
+        },
         plugins: [
             (0, next_js_1.nextCookies)(),
         ],

package/dist/server/auth.d.ts

@@ -12,6 +12,7 @@ import 'server-only';
  * Get the initialized Better Auth instance (singleton).
  */
 export declare function getAuthInstance(): Promise<import("better-auth/types").Auth<{
+    baseURL: string;
     secret: string;
     socialProviders: Record<string, import("../auth/better-auth").BetterAuthSocialProvider>;
     trustedOrigins: string[];
@@ -22,6 +23,14 @@ export declare function getAuthInstance(): Promise<import("better-auth/types").A
             refreshCache: true;
         };
     };
+    advanced: {
+        cookiePrefix: string;
+        cookies: {
+            session_token: {
+                name: string;
+            };
+        };
+    };
     plugins: [{
         id: "next-cookies";
         hooks: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.0.4",
+  "version": "4.0.6",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -861,6 +861,7 @@
   "dependencies": {
     "@azure/identity": "^4.0.1",
     "@azure/keyvault-secrets": "^4.7.0",
+    "@better-auth/memory-adapter": "^1.5.6",
     "@upstash/redis": "^1.35.6",
     "better-auth": "^1.5.6",
     "ioredis": "^5.3.2",
@@ -872,10 +873,13 @@
     "nanoid": "^5.0.7"
   },
   "devDependencies": {
+    "@microsoft/signalr": "^8.0.17",
+    "@tanstack/react-query": "^5.95.2",
     "@types/jsonwebtoken": "^9.0.6",
     "@types/jwk-to-pem": "^2.0.3",
     "@types/node": "^22.14.0",
     "@types/react": "^19.0.0",
+    "lucide-react": "^1.7.0",
     "next": "^16.1.5",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.4.5",

package/src/auth/better-auth.ts

@@ -15,6 +15,7 @@ import { nextCookies } from 'better-auth/next-js';
 import { toNextJsHandler } from 'better-auth/next-js';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getAppSlug } from '../lib/app-slug';
 
 /**
  * Better Auth social provider config shape.
@@ -53,15 +54,23 @@ export function buildBetterAuthProviders(
  * Call after getIDPClientConfig() resolves.
  */
 export function createBetterAuthInstance(idpConfig: IDPClientConfig) {
+  const appSlug = idpConfig.clientSlug || getAppSlug();
+
+  // Resolve base URL: BETTER_AUTH_URL env > IDP config > localhost fallback
+  const baseURL = process.env.BETTER_AUTH_URL
+    || idpConfig.baseClientUrl
+    || `http://localhost:${process.env.PORT || '3000'}`;
+
   return betterAuth({
+    baseURL,
     secret: idpConfig.nextAuthSecret as string,
 
     socialProviders: buildBetterAuthProviders(idpConfig),
 
     // Trust the app's own origin + any configured base URL
     trustedOrigins: [
-      ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
-      ...(process.env.BETTER_AUTH_URL ? [process.env.BETTER_AUTH_URL] : []),
+      baseURL,
+      ...(idpConfig.baseClientUrl && idpConfig.baseClientUrl !== baseURL ? [idpConfig.baseClientUrl] : []),
       'http://localhost:3000',
       'http://localhost:3400',
       'http://localhost:3600',
@@ -77,6 +86,16 @@ export function createBetterAuthInstance(idpConfig: IDPClientConfig) {
       },
     },
 
+    // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
+    advanced: {
+      cookiePrefix: appSlug,
+      cookies: {
+        session_token: {
+          name: `${appSlug}.session-token`,
+        },
+      },
+    },
+
     plugins: [
       nextCookies(),
     ],