@ingram-tech/nk-auth 0.4.1 → 0.6.0

package/README.md

@@ -17,6 +17,8 @@ only what you need from focused subpaths.
 | `createAuthPool` (`./pool`) | `pg` Pool with optional SSL CA verification |
 | `bcryptPassword`, `makeEmailSenders`, `makePasskeyOptions`, `uuidGenerateId` (`./`) | password migration, email hooks, passkeys, UUID ids |
 | `createServerSupabase` (`./`) | RLS-aware supabase-js client (attaches the session JWT) |
+| `createAuthHelpers` (`./server`) | validated App Router session helpers: `getSession` / `getUser` / `requireSession` / `requireUser` / `redirectIfAuthenticated` |
+| `createAuthMiddleware` (`./middleware`) | loop-safe edge middleware that only gates *unauthenticated* users off protected paths |
 
 > **Supabase Auth → Better Auth + RLS migration?** Read
 > [`docs/better-auth-migration.md`](../../docs/better-auth-migration.md) — the
@@ -176,6 +178,74 @@ export const authClient = createAuthClient({
 // authClient.signIn.email(...), signIn.social(...), useSession(), passkey.*
 ```
 
+## 5. Gate routes (without the redirect loop)
+
+Two layers, **one rule that keeps them from fighting**: only the *validated*
+layer may redirect a request *away from* the sign-in page.
+
+The validated layer (server helpers) — bind once to your instance:
+
+```ts
+// lib/auth/session.ts
+import { createAuthHelpers } from "@ingram-tech/nk-auth/server";
+import { auth } from "@/lib/auth";
+
+export const {
+	getSession,
+	getUser,
+	requireSession,
+	requireUser,
+	redirectIfAuthenticated,
+} = createAuthHelpers(auth);
+```
+
+```tsx
+// app/dashboard/page.tsx — gate a protected page (validated, DB-backed).
+import { requireUser } from "@/lib/auth/session";
+export default async function Dashboard() {
+	const user = await requireUser(); // -> /login when signed out
+	return <main>Hi {user.email}</main>;
+}
+
+// app/login/page.tsx — gate the sign-in page HERE, never in middleware.
+import { redirectIfAuthenticated } from "@/lib/auth/session";
+import { LoginForm } from "./login-form";
+export default async function Login() {
+	await redirectIfAuthenticated("/dashboard"); // validated: a stale cookie
+	return <LoginForm />; // resolves to "signed out" and falls through to the form
+}
+```
+
+The optimistic layer (middleware) is a fast edge short-circuit on cookie
+*presence*. It can save a render for users with no cookie at all — but it must
+never decide the sign-in page, because a present-but-invalid cookie there is
+exactly what loops. `createAuthMiddleware` enforces that **at construction**: it
+throws if you try to protect or front-door the sign-in path.
+
+```ts
+// middleware.ts
+import { createAuthMiddleware } from "@ingram-tech/nk-auth/middleware";
+
+export const middleware = createAuthMiddleware({
+	protectedPaths: ["/dashboard", "/memory"], // cookie-less -> signInPath
+	signInPath: "/login",
+	frontDoorPaths: ["/"], // optional: cookie-bearing "/" -> signedInRedirect
+	signedInRedirect: "/dashboard",
+});
+
+export const config = {
+	matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.svg).*)"],
+};
+```
+
+Why the split: middleware runs before render and can't afford a DB lookup, so it
+can only trust the cookie *exists*. The server helpers hit `auth.api.getSession`
+and check the session *contents*. When those disagree (revoked session, rotated
+secret, wiped DB) the validated layer wins and parks the user on `/login` — and
+because middleware refuses to bounce `/login`, the form renders instead of
+ping-ponging. Middleware is optional; sites that prefer one source of truth can
+use the server helpers alone.
+
 ## RLS bridge (the important part)
 
 `auth.uid()` reads the `sub` claim of the JWT PostgREST receives. The `jwt`

package/dist/middleware.d.ts

@@ -0,0 +1,20 @@
+import { type NextRequest, NextResponse } from "next/server";
+export interface AuthMiddlewareConfig {
+    /**
+     * Path prefixes that require a session. A request without a session cookie
+     * to any of these is redirected to `signInPath`. Matched with `startsWith`.
+     */
+    protectedPaths: string[];
+    /** Where unauthenticated users are sent. Default `/login`. */
+    signInPath?: string;
+    /**
+     * Optional front-door redirect: when a session cookie is present and the
+     * path *exactly* equals one of these, redirect to `signedInRedirect`. Safe
+     * because it never targets the sign-in path. Typically `["/"]`.
+     */
+    frontDoorPaths?: string[];
+    /** Destination for the front-door redirect. Required when `frontDoorPaths` is set. */
+    signedInRedirect?: string;
+}
+export declare function createAuthMiddleware(config: AuthMiddlewareConfig): (request: NextRequest) => NextResponse;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,IAwBrC,SAAS,WAAW,KAAG,YAAY,CAyB9D"}

package/dist/middleware.js

@@ -0,0 +1,60 @@
+/**
+ * A loop-safe Next.js auth middleware factory, at
+ * "@ingram-tech/nk-auth/middleware". Middleware runs at the edge before a route
+ * renders, so it can only afford an **optimistic** check — the presence of a
+ * session cookie (`getSessionCookie`), not a database-validated session.
+ *
+ * That optimism is exactly what makes naive auth middleware loop. The validated
+ * server guard (see "@ingram-tech/nk-auth/server") sends an invalid-but-present
+ * session to the sign-in page; if the optimistic layer then bounces the sign-in
+ * page back ("you have a cookie, go to the app"), a stale cookie ping-pongs
+ * forever — and an RSC render can't clear the cookie to break out.
+ *
+ * So this factory enforces the one safe invariant *at construction*:
+ *
+ *   The sign-in path is never the target of an optimistic redirect.
+ *
+ * It will only ever (a) push *cookie-less* requests off `protectedPaths`, and
+ * optionally (b) push *cookie-bearing* requests off a front door to the app. It
+ * refuses to protect or front-door the sign-in path, because either would
+ * reintroduce the loop. Sending a *signed-in* user away from /login is the job
+ * of `redirectIfAuthenticated` in the server helpers, which validates first.
+ */
+import { getSessionCookie } from "better-auth/cookies";
+import { NextResponse } from "next/server";
+export function createAuthMiddleware(config) {
+    const signInPath = config.signInPath ?? "/login";
+    const frontDoorPaths = config.frontDoorPaths ?? [];
+    // Loop-safety, enforced once at construction rather than hoped-for per
+    // request. The sign-in path is where the validated guard parks an
+    // invalid-but-present session; it must never be the target of an optimistic
+    // redirect, or a stale cookie loops.
+    if (config.protectedPaths.some((p) => signInPath.startsWith(p))) {
+        throw new Error(`@ingram-tech/nk-auth: signInPath "${signInPath}" must not fall under protectedPaths — a cookie-less visit would redirect to itself forever.`);
+    }
+    if (frontDoorPaths.includes(signInPath)) {
+        throw new Error(`@ingram-tech/nk-auth: signInPath "${signInPath}" must not be a frontDoorPath — it would reintroduce the stale-cookie redirect loop.`);
+    }
+    if (frontDoorPaths.length > 0 && !config.signedInRedirect) {
+        throw new Error("@ingram-tech/nk-auth: signedInRedirect is required when frontDoorPaths is set.");
+    }
+    return function middleware(request) {
+        const hasSessionCookie = !!getSessionCookie(request);
+        const path = request.nextUrl.pathname;
+        if (!hasSessionCookie &&
+            config.protectedPaths.some((p) => path.startsWith(p))) {
+            const url = request.nextUrl.clone();
+            url.pathname = signInPath;
+            return NextResponse.redirect(url);
+        }
+        if (hasSessionCookie &&
+            config.signedInRedirect &&
+            frontDoorPaths.includes(path)) {
+            const url = request.nextUrl.clone();
+            url.pathname = config.signedInRedirect;
+            return NextResponse.redirect(url);
+        }
+        return NextResponse.next();
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAoB,YAAY,EAAE,MAAM,aAAa,CAAC;AAoB7D,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAChE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,QAAQ,CAAC;IACjD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IAEnD,uEAAuE;IACvE,kEAAkE;IAClE,4EAA4E;IAC5E,qCAAqC;IACrC,IAAI,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACd,qCAAqC,UAAU,8FAA8F,CAC7I,CAAC;IACH,CAAC;IACD,IAAI,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACd,qCAAqC,UAAU,sFAAsF,CACrI,CAAC;IACH,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACd,gFAAgF,CAChF,CAAC;IACH,CAAC;IAED,OAAO,SAAS,UAAU,CAAC,OAAoB;QAC9C,MAAM,gBAAgB,GAAG,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;QAEtC,IACC,CAAC,gBAAgB;YACjB,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EACpD,CAAC;YACF,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC;YAC1B,OAAO,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAED,IACC,gBAAgB;YAChB,MAAM,CAAC,gBAAgB;YACvB,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC5B,CAAC;YACF,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC;YACvC,OAAO,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+/** The shape we need from a session: anything carrying a `user`. */
+interface SessionLike {
+    user: unknown;
+}
+/**
+ * The slice of a Better Auth instance these helpers touch. Generic over the
+ * site's session type `S`, so `getSession`/`getUser` return the site's fully
+ * inferred user shape (additional fields, org id, …) — no `any`, no casts.
+ */
+interface AuthLike<S extends SessionLike> {
+    api: {
+        getSession: (input: {
+            headers: Headers;
+        }) => Promise<S | null>;
+    };
+}
+export declare function createAuthHelpers<S extends SessionLike>(auth: AuthLike<S>): {
+    getSession: () => Promise<S | null>;
+    getUser: () => Promise<S["user"] | null>;
+    requireSession: (redirectTo?: string) => Promise<S>;
+    requireUser: (redirectTo?: string) => Promise<S["user"]>;
+    redirectIfAuthenticated: (to: string) => Promise<void>;
+};
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAwBA,oEAAoE;AACpE,UAAU,WAAW;IACpB,IAAI,EAAE,OAAO,CAAC;CACd;AAED;;;;GAIG;AACH,UAAU,QAAQ,CAAC,CAAC,SAAS,WAAW;IACvC,GAAG,EAAE;QACJ,UAAU,EAAE,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;KAC/D,CAAC;CACF;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;sBAE5C,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAgBpB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;6CARG,OAAO,CAAC,CAAC,CAAC;0CAkBb,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;kCAa1B,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;EAWjE"}

package/dist/server.js

@@ -0,0 +1,75 @@
+/**
+ * Server-side session helpers for the App Router, at
+ * "@ingram-tech/nk-auth/server" so the framework-agnostic core entry never
+ * pulls in `next`. A site binds these once to its own Better Auth instance:
+ *
+ *   // lib/auth/session.ts
+ *   import { createAuthHelpers } from "@ingram-tech/nk-auth/server";
+ *   import { auth } from "@/lib/auth";
+ *
+ *   export const { getSession, getUser, requireUser, redirectIfAuthenticated } =
+ *     createAuthHelpers(auth);
+ *
+ * These are the **validated** authority: every call hits `auth.api.getSession`,
+ * which checks the session against the database — not merely the presence of a
+ * cookie. That distinction is the whole point. The optimistic, cookie-presence
+ * check belongs in middleware (see "@ingram-tech/nk-auth/middleware"); it may
+ * only ever push *unauthenticated* users off protected routes. The decision to
+ * send a signed-in user *away* from the sign-in page must run through
+ * `redirectIfAuthenticated` here, so a stale or revoked cookie resolves to "no
+ * session" and falls through to the form instead of ping-ponging forever.
+ */
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+export function createAuthHelpers(auth) {
+    /** The validated session ({ user, session, … }) or null. */
+    async function getSession() {
+        return auth.api.getSession({ headers: await headers() });
+    }
+    /**
+     * Require a session or redirect, returning the full validated session (use
+     * when the caller needs more than the user — session id, active org, …).
+     */
+    async function requireSession(redirectTo = "/login") {
+        const session = await getSession();
+        // redirect() is typed `never`, so `session` narrows to non-null below.
+        if (!session)
+            redirect(redirectTo);
+        return session;
+    }
+    /** The authenticated user, or null. */
+    async function getUser() {
+        const session = await getSession();
+        return session?.user ?? null;
+    }
+    /**
+     * Require a signed-in user or redirect. Returns the user (non-null) so
+     * callers keep their `const user = await requireUser()` shape. `redirect()`
+     * throws, so control never returns when signed out.
+     */
+    async function requireUser(redirectTo = "/login") {
+        const user = await getUser();
+        // redirect() is typed `never`, so `user` narrows to non-null below.
+        if (!user)
+            redirect(redirectTo);
+        return user;
+    }
+    /**
+     * Redirect an already-signed-in user away (e.g. /login -> /dashboard). This
+     * is the *correct* place to gate the sign-in page: because it validates the
+     * session, a present-but-invalid cookie is treated as signed-out and the
+     * page renders instead of looping. Never do this in middleware.
+     */
+    async function redirectIfAuthenticated(to) {
+        if (await getSession())
+            redirect(to);
+    }
+    return {
+        getSession,
+        getUser,
+        requireSession,
+        requireUser,
+        redirectIfAuthenticated,
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAkB3C,MAAM,UAAU,iBAAiB,CAAwB,IAAiB;IACzE,4DAA4D;IAC5D,KAAK,UAAU,UAAU;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACH,KAAK,UAAU,cAAc,CAAC,UAAU,GAAG,QAAQ;QAClD,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,uEAAuE;QACvE,IAAI,CAAC,OAAO;YAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QACnC,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,uCAAuC;IACvC,KAAK,UAAU,OAAO;QACrB,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,OAAO,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,KAAK,UAAU,WAAW,CAAC,UAAU,GAAG,QAAQ;QAC/C,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC7B,oEAAoE;QACpE,IAAI,CAAC,IAAI;YAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,KAAK,UAAU,uBAAuB,CAAC,EAAU;QAChD,IAAI,MAAM,UAAU,EAAE;YAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,OAAO;QACN,UAAU;QACV,OAAO;QACP,cAAc;QACd,WAAW;QACX,uBAAuB;KACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-auth",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"description": "The Ingram Better Auth foundation: composable presets (org, dual-shape JWT, Supabase RLS bridge, active-org hooks, pg pool) for Next.js sites.",
 	"license": "MIT",
 	"type": "module",
@@ -41,6 +41,14 @@
 			"types": "./dist/paths.d.ts",
 			"import": "./dist/paths.js"
 		},
+		"./server": {
+			"types": "./dist/server.d.ts",
+			"import": "./dist/server.js"
+		},
+		"./middleware": {
+			"types": "./dist/middleware.d.ts",
+			"import": "./dist/middleware.js"
+		},
 		"./client": {
 			"types": "./dist/client.d.ts",
 			"import": "./dist/client.js"
@@ -62,6 +70,7 @@
 		"@better-auth/passkey": "^1.6.0",
 		"@supabase/supabase-js": ">=2.0.0",
 		"better-auth": "^1.6.0",
+		"next": "^15.0.0 || ^16.0.0",
 		"pg": "^8.13.0",
 		"react": "^18.0.0 || ^19.0.0"
 	},
@@ -72,6 +81,9 @@
 		"@supabase/supabase-js": {
 			"optional": true
 		},
+		"next": {
+			"optional": true
+		},
 		"pg": {
 			"optional": true
 		},
@@ -88,6 +100,7 @@
 		"@types/pg": "^8.11.0",
 		"@types/react": "^19.0.0",
 		"better-auth": "^1.6.0",
+		"next": "^16.2.9",
 		"pg": "^8.13.0",
 		"react": "^19.0.0",
 		"typescript": "^6.0.3",