@ingram-tech/nk-auth 0.13.5 → 0.14.0

package/README.md

@@ -12,7 +12,7 @@ exactly one Better Auth copy in the app.
 | Export (subpath) | For |
 | --- | --- |
 | `authEnv`, `authSecret`, `isConfigured` (`./`) | env validation — `authEnv()` returns the full `{ secret, baseURL, databaseUrl }` bundle; `authSecret()` resolves just the secret (with the prod/dev rule) for sites that derive their own `baseURL` / DB connection |
-| `backendJwtOptions` / `verifyBackendJwt` (`./jwt`) | a JWT for the site's own backend API (custom `audience`) |
+| `backendJwtOptions` / `verifyBackendJwt` (`./jwt`) | a JWT for the site's own backend API (custom `audience`; `ids` mints `sub` as the public user id) |
 | `nkOrganizationDefaults`, `lastActiveOrganizationHooks`, `lastActiveOrganizationUserField` (`./organization`) | org-plugin defaults + active-org restore/persist |
 | `createAuthPool` (`./pool`) | **deprecated** — alias of `createPool` from [`@ingram-tech/nk-db`](../nk-db); inject the site's shared pool instead |
 | `makeEmailSenders`, `makePasskeyOptions`, `passkeyOptionsForBaseUrl`, `uuidGenerateId` (`./`) | email hooks, passkeys (`passkeyOptionsForBaseUrl` derives `rpID`/`origin` from a single base URL), UUID ids |
@@ -268,7 +268,9 @@ Data access lives in [`@ingram-tech/nk-db`](../nk-db), not here. Query over the
 direct `pg` connection and wrap reads/writes in `withRls` / `withRlsTransaction`,
 which set `request.jwt.claims` + `SET LOCAL ROLE` per transaction from the Better
 Auth session — so `auth.uid()` policies fire unchanged, with no JWT minting and
-no REST proxy. See its README for the pattern.
+no REST proxy. See its README for the pattern. Pass `user.id` as it comes from
+the helpers: a public `usr_…` is decoded to the uuid before it reaches the
+claims GUC, so a policy's `auth.uid()` still compares to a `uuid` column.
 
 ## 4. Client
 
@@ -312,9 +314,23 @@ export const {
 	redirectIfAuthenticated,
 	getLinkedProviders, // providerIds linked to the current user
 	hasCredentialAccount, // does the current user have an email/password login?
-} = createAuthHelpers(auth);
+} = createAuthHelpers(auth, {
+	// Session ids in public form (`usr_…`, `org_…`), the same form `idColumn`
+	// reads return, so `row.organization_id === session.activeOrganizationId`
+	// holds. Omit on a site with no public id form.
+	ids: { user: ids.user, organization: ids.organization },
+});
 ```
 
+With `ids`, every read through the helpers presents `user.id`,
+`session.userId` and `session.activeOrganizationId` as public ids; Better Auth
+itself keeps working on raw uuids underneath, and anything read directly from
+`auth.api.*` is raw — the same rule as raw SQL vs `idColumn`. Pass the same
+helper to `backendJwtOptions({ audience, ids: { user } })` and the backend
+JWT's `sub` (and payload `id`) is the public id too. RLS needs nothing: nk-db's
+`withRls*` decode a prefixed `sub` before it reaches `request.jwt.claims`, so
+`auth.uid()` policies hold either way.
+
 ```tsx
 // app/dashboard/page.tsx — gate a protected page (validated, DB-backed).
 import { requireUser } from "@/lib/auth/session";

package/dist/jwt.d.ts

@@ -1,3 +1,4 @@
+import type { IdHelper } from "@ingram-tech/nk-db/id";
 import type { JwtOptions } from "better-auth/plugins/jwt";
 import { type JWTPayload } from "jose";
 /**
@@ -16,6 +17,14 @@ export interface BackendJwtConfig {
      * the site mints tokens on demand via `auth.api.signJWT` instead.
      */
     disableSettingJwtHeader?: boolean;
+    /**
+     * Mint the token's `sub` (and the `id` in its payload) as the user's public
+     * id rather than the raw uuid, so a backend that also talks to the app sees
+     * ids in one form. The same helper the site passes to `createAuthHelpers`.
+     */
+    ids?: {
+        user: IdHelper;
+    };
 }
 /** `jwt` plugin options for a backend-API token (custom audience). */
 export declare const backendJwtOptions: (config: BackendJwtConfig) => JwtOptions;

package/dist/jwt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAGN,KAAK,UAAU,EAEf,MAAM,MAAM,CAAC;AAEd;;;;;GAKG;AAEH,MAAM,WAAW,gBAAgB;IAChC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,WAAY,gBAAgB,KAAG,UAM3D,CAAC;AAWH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,WAAkB;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf,KAAG,OAAO,CAAC,UAAU,CAmCrB,CAAC"}
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAGN,KAAK,UAAU,EAEf,MAAM,MAAM,CAAC;AAEd;;;;;GAKG;AAEH,MAAM,WAAW,gBAAgB;IAChC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;CACzB;AAED,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,WAAY,gBAAgB,KAAG,UAgB3D,CAAC;AAWH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,WAAkB;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf,KAAG,OAAO,CAAC,UAAU,CAmCrB,CAAC"}

package/dist/jwt.js

@@ -3,6 +3,15 @@ import { createRemoteJWKSet, errors as joseErrors, jwtVerify, } from "jose";
 export const backendJwtOptions = (config) => ({
     disableSettingJwtHeader: config.disableSettingJwtHeader,
     jwt: {
+        ...(config.ids
+            ? {
+                getSubject: ({ user }) => config.ids?.user.encode(user.id) ?? user.id,
+                definePayload: ({ user }) => ({
+                    ...user,
+                    id: config.ids?.user.encode(user.id) ?? user.id,
+                }),
+            }
+            : {}),
         audience: config.audience,
         expirationTime: config.expirationTime,
     },

package/dist/jwt.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AACA,OAAO,EACN,kBAAkB,EAClB,MAAM,IAAI,UAAU,EAEpB,SAAS,GACT,MAAM,MAAM,CAAC;AAqBd,sEAAsE;AACtE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAwB,EAAc,EAAE,CAAC,CAAC;IAC3E,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;IACvD,GAAG,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,cAAc,EAAE,MAAM,CAAC,cAAc;KACrC;CACD,CAAC,CAAC;AAEH,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;AAE3E,+EAA+E;AAC/E,yEAAyE;AACzE,4EAA4E;AAC5E,mDAAmD;AACnD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,MAMtC,EAAuB,EAAE;IACzB,MAAM,GAAG,GACR,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IAC/E,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IAChC,IAAI,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC/B,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,OAAO,GAAG;QACf,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU,EAAE,CAAC,OAAO,CAAC;QACrB,yEAAyE;QACzE,4EAA4E;QAC5E,cAAc,EAAE,CAAC;KACjB,CAAC;IACF,IAAI,CAAC;QACJ,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,CAAC,GAAG,YAAY,UAAU,CAAC,iBAAiB,CAAC;YAAE,MAAM,GAAG,CAAC;QAC9D,2EAA2E;QAC3E,yEAAyE;QACzE,qEAAqE;QACrE,UAAU;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,kBAAkB,EAAE,CAAC;YACtE,MAAM,GAAG,CAAC;QACX,CAAC;QACD,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACpC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IAChB,CAAC;AACF,CAAC,CAAC"}
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,3 +1,30 @@
+/**
+ * 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, requireSession, requireUser,
+ *     redirectIfAuthenticated } = createAuthHelpers(auth);
+ *
+ * These are the **validated** authority: they resolve through
+ * `auth.api.getSession`, which checks the session against the database — not
+ * merely the presence of a cookie. The read is memoized per request with React
+ * `cache()`, so a render fanning out many `getUser()` calls validates once,
+ * not once per call. When a guard finds no valid session it redirects to the sign-in page,
+ * preserving the requested path as `next` (read from the header the middleware
+ * injects) and, when a session cookie is present-but-invalid, adding `stale=1`
+ * so the middleware clears the dead cookie. 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 cookie resolves to "no session"
+ * and falls through to the form instead of ping-ponging forever.
+ */
+import type { IdHelper } from "@ingram-tech/nk-db/id";
 /**
  * Validate a `next` redirect param: returns it only if it's an internal,
  * non-protocol-relative path, else null. Use on the login page before honoring
@@ -31,9 +58,26 @@ interface AuthLike<S extends SessionLike> {
         }>>;
     };
 }
+/**
+ * The registry helpers for the ids a session carries. With these, every
+ * session read through the helpers presents `user.id` / `session.userId` as
+ * the user's public id and `session.activeOrganizationId` as the
+ * organization's, so app code compares session ids with `idColumn` reads in
+ * one form. Better Auth itself keeps working on raw uuids underneath.
+ */
+export interface SessionIds {
+    user: IdHelper;
+    organization?: IdHelper;
+}
 export interface AuthHelpersOptions {
     /** Where guards send unauthenticated users. Default `/login`. */
     signInPath?: string;
+    /**
+     * Encode session ids to their public form on every read (see
+     * {@link SessionIds}). Omit on a site that has no public id form: the
+     * helpers then return Better Auth's raw uuids.
+     */
+    ids?: SessionIds;
     /**
      * Cookie-name fragment that identifies the Better Auth session cookie, used
      * to detect a present-but-invalid (stale) cookie. Default `better-auth`,
@@ -41,6 +85,13 @@ export interface AuthHelpersOptions {
      */
     sessionCookiePrefix?: string;
 }
+/**
+ * A session with its ids in public form: `user.id`, `session.userId` and
+ * `session.activeOrganizationId` (each only when present and a string). Pure —
+ * Better Auth's own object is left untouched, since it is what the adapter
+ * writes back. `encode` is idempotent, so an already-public id is unchanged.
+ */
+export declare function encodeSessionIds<S extends SessionLike>(session: S, ids: SessionIds): S;
 export declare function createAuthHelpers<S extends SessionLike>(auth: AuthLike<S>, options?: AuthHelpersOptions): {
     getSession: () => Promise<S | null>;
     getUser: () => Promise<S["user"] | null>;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAElE,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;QAC/D;;;;;WAKG;QACH,gBAAgB,EAAE,CAAC,KAAK,EAAE;YACzB,OAAO,EAAE,OAAO,CAAC;SACjB,KAAK,OAAO,CAAC,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC,CAAC;KAC7C,CAAC;CACF;AAED,MAAM,WAAW,kBAAkB;IAClC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACtD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,kBAAuB;sBAiBG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAK1B,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;0BAkClB,OAAO,CAAC,CAAC,CAAC;uBAXb,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;kCAuBL,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;8BAU5B,OAAO,CAAC,MAAM,EAAE,CAAC;gCAcf,OAAO,CAAC,OAAO,CAAC;EAcvD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAOtD;;;;GAIG;AACH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAElE,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;QAC/D;;;;;WAKG;QACH,gBAAgB,EAAE,CAAC,KAAK,EAAE;YACzB,OAAO,EAAE,OAAO,CAAC;SACjB,KAAK,OAAO,CAAC,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC,CAAC;KAC7C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IAClC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACrD,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,UAAU,GACb,CAAC,CAyBH;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACtD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,kBAAuB;sBAiBG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAQ1B,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;0BAkClB,OAAO,CAAC,CAAC,CAAC;uBAXb,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;kCAuBL,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;8BAU5B,OAAO,CAAC,MAAM,EAAE,CAAC;gCAcf,OAAO,CAAC,OAAO,CAAC;EAcvD"}

package/dist/server.js

@@ -1,29 +1,3 @@
-/**
- * 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, requireSession, requireUser,
- *     redirectIfAuthenticated } = createAuthHelpers(auth);
- *
- * These are the **validated** authority: they resolve through
- * `auth.api.getSession`, which checks the session against the database — not
- * merely the presence of a cookie. The read is memoized per request with React
- * `cache()`, so a render fanning out many `getUser()` calls validates once,
- * not once per call. When a guard finds no valid session it redirects to the sign-in page,
- * preserving the requested path as `next` (read from the header the middleware
- * injects) and, when a session cookie is present-but-invalid, adding `stale=1`
- * so the middleware clears the dead cookie. 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 cookie resolves to "no session"
- * and falls through to the form instead of ping-ponging forever.
- */
 import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { cache } from "react";
@@ -35,6 +9,36 @@ import { CREDENTIAL_PROVIDER_ID } from "./password.js";
  * `?next=` so it can't become an open redirect.
  */
 export { safeNextParam as safeNext } from "./gating-internals.js";
+const encodeIfString = (helper, value) => helper && typeof value === "string" ? helper.encode(value) : value;
+/**
+ * A session with its ids in public form: `user.id`, `session.userId` and
+ * `session.activeOrganizationId` (each only when present and a string). Pure —
+ * Better Auth's own object is left untouched, since it is what the adapter
+ * writes back. `encode` is idempotent, so an already-public id is unchanged.
+ */
+export function encodeSessionIds(session, ids) {
+    const out = { ...session };
+    const user = session.user;
+    if (user && typeof user === "object" && "id" in user) {
+        out.user = { ...user, id: encodeIfString(ids.user, user.id) };
+    }
+    const inner = "session" in session ? session.session : undefined;
+    if (inner && typeof inner === "object") {
+        const rec = inner;
+        out.session = {
+            ...rec,
+            ...("userId" in rec
+                ? { userId: encodeIfString(ids.user, rec.userId) }
+                : {}),
+            ...("activeOrganizationId" in rec
+                ? {
+                    activeOrganizationId: encodeIfString(ids.organization, rec.activeOrganizationId),
+                }
+                : {}),
+        };
+    }
+    return out;
+}
 export function createAuthHelpers(auth, options = {}) {
     const signInPath = options.signInPath ?? "/login";
     const cookiePrefix = options.sessionCookiePrefix ?? "better-auth";
@@ -50,7 +54,12 @@ export function createAuthHelpers(auth, options = {}) {
      * pre-mutation snapshot; re-read through `auth.api.getSession` directly if
      * that ever matters.
      */
-    const getSession = cache(async () => auth.api.getSession({ headers: await headers() }));
+    const getSession = cache(async () => {
+        const session = await auth.api.getSession({ headers: await headers() });
+        return session && options.ids
+            ? encodeSessionIds(session, options.ids)
+            : session;
+    });
     /** The authenticated user, or null. */
     async function getUser() {
         const session = await getSession();

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-auth",
-	"version": "0.13.5",
+	"version": "0.14.0",
 	"description": "The Ingram Better Auth foundation: composable presets (org, dual-shape JWT, active-org hooks, pg pool) for Next.js sites.",
 	"license": "MIT",
 	"type": "module",
@@ -14,6 +14,9 @@
 	},
 	"files": [
 		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
 		"migrations"
 	],
 	"exports": {
@@ -65,7 +68,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-db": "^1.6.0",
+		"@ingram-tech/nk-db": "^2.1.0",
 		"bcrypt": "^6.0.0",
 		"jose": "^6.2.9",
 		"zod": "^4.4.3"
@@ -93,7 +96,7 @@
 	},
 	"devDependencies": {
 		"@better-auth/passkey": "^1.7.0",
-		"@ingram-tech/nk-dev": "0.11.1",
+		"@ingram-tech/nk-dev": "0.12.2",
 		"@types/bcrypt": "^6.0.0",
 		"@types/node": "^26.2.0",
 		"@types/pg": "^8.23.1",

package/src/client.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser auth re-exports, at "@ingram-tech/nk-auth/client" so the server entry
+ * never pulls in React. A site builds its own client to preserve full plugin
+ * type inference:
+ *
+ *   "use client";
+ *   import {
+ *     createAuthClient, jwtClient, passkeyClient,
+ *   } from "@ingram-tech/nk-auth/client";
+ *
+ *   export const authClient = createAuthClient({
+ *     baseURL: process.env.NEXT_PUBLIC_SITE_URL,
+ *     plugins: [jwtClient(), passkeyClient()],
+ *   });
+ *
+ * This exposes the client auth call surface:
+ *   signUp.email / signIn.email / signIn.social / signOut / useSession,
+ *   plus passkey.* (register / authenticate).
+ */
+export { passkeyClient } from "@better-auth/passkey/client";
+export { jwtClient } from "better-auth/client/plugins";
+export { createAuthClient } from "better-auth/react";
+// Password-policy primitives (pure), so a reset form validates against the same
+// bounds the server enforces without a second import.
+export {
+	CREDENTIAL_PROVIDER_ID,
+	DEFAULT_MAX_PASSWORD_LENGTH,
+	DEFAULT_MIN_PASSWORD_LENGTH,
+	type PasswordPolicy,
+	passwordSchema,
+	type ResetPasswordError,
+	type ResetPasswordErrorCode,
+	validateNewPassword,
+} from "./password.js";
+// Re-exported here too so the client can set `basePath` without a server import.
+export { authBasePath } from "./paths.js";
+// Headless reset-/set-password controller (React hook); the site brings the shell.
+export {
+	type ResetPasswordClient,
+	type ResetPasswordStatus,
+	type UseResetPassword,
+	type UseResetPasswordOptions,
+	useResetPassword,
+} from "./reset-password.js";

package/src/gating-internals.ts

@@ -0,0 +1,47 @@
+/**
+ * Internal helpers shared by the server helpers and the middleware. Kept in a
+ * zero-`next` module so neither subpath imports the other (server pulls
+ * next/navigation, middleware pulls next/server — mixing them breaks the
+ * respective runtimes). Not a public export.
+ */
+
+/**
+ * Request header the middleware sets to the originally-requested path so a
+ * server-component guard — which Next.js otherwise gives no way to learn its own
+ * URL — can preserve it as a `next` param when it redirects to sign-in.
+ */
+export const NK_AUTH_PATH_HEADER = "x-nk-auth-path";
+
+/**
+ * Accept only an internal, non-protocol-relative path as a post-login redirect,
+ * so `next` can never be turned into an open redirect to another origin.
+ *
+ * Beyond the `//` check, backslashes and ASCII controls must also be rejected:
+ * browsers treat `\` as `/` in http(s) URLs (so `/\evil.com` resolves to
+ * `https://evil.com/`) and the URL parser strips tab/newline (so an encoded
+ * `/\t/evil.com` collapses to `//evil.com`).
+ */
+export function safeNextParam(value: string | null | undefined): string | null {
+	if (!value) return null;
+	if (!value.startsWith("/") || value.startsWith("//")) return null;
+	// oxlint-disable-next-line no-control-regex -- rejecting control chars is the point
+	if (/[\\\u0000-\u001f\u007f]/.test(value)) return null;
+	return value;
+}
+
+/**
+ * Build a sign-in URL: `signInPath`, plus `next` (when safe) so the user returns
+ * to where they were headed, plus a `stale=1` marker when a session cookie is
+ * present but invalid — the signal the middleware uses to clear the dead cookie.
+ */
+export function signInUrl(
+	signInPath: string,
+	opts: { next?: string | null; stale?: boolean },
+): string {
+	const params = new URLSearchParams();
+	const next = safeNextParam(opts.next);
+	if (next) params.set("next", next);
+	if (opts.stale) params.set("stale", "1");
+	const qs = params.toString();
+	return qs ? `${signInPath}?${qs}` : signInPath;
+}

package/src/id.ts

@@ -0,0 +1,12 @@
+// The Ingram id codec is the standalone `id758` package, re-exported via
+// `@ingram-tech/nk-db/id` — the lowest package in
+// the graph — so a site can mint ids without pulling this auth slice. This
+// re-export keeps `@ingram-tech/nk-auth/id` (and Better Auth's
+// `advanced.database.generateId`, wired in `./options`) working unchanged. For
+// the typed prefix registry (`createIdRegistry`), import from `@ingram-tech/nk-db/id`.
+export {
+	base58Id,
+	fromPrefixedId,
+	toPrefixedId,
+	uuidGenerateId,
+} from "@ingram-tech/nk-db/id";

package/src/index.ts

@@ -0,0 +1,36 @@
+// Server entry — the Ingram Better Auth foundation. Browser re-exports live at
+// "@ingram-tech/nk-auth/client" so importing the server presets never pulls in
+// React. Focused subpaths (./jwt, ./organization, ./pool) let a site import
+// only what it needs (e.g. avoid bcrypt when it doesn't use passwords).
+
+export { type BackendJwtConfig, backendJwtOptions, verifyBackendJwt } from "./jwt.js";
+export { base58Id, fromPrefixedId, toPrefixedId, uuidGenerateId } from "./id.js";
+export { type AuthEnv, authEnv, authSecret, isConfigured } from "./keys.js";
+export {
+	type AuthEmailKind,
+	type AuthEmailMessage,
+	type AuthEmailUser,
+	bcryptPassword,
+	makeEmailSenders,
+	makePasskeyOptions,
+	type PasskeyConfig,
+	passkeyOptionsForBaseUrl,
+	type SendEmail,
+} from "./options.js";
+export {
+	lastActiveOrganizationHooks,
+	lastActiveOrganizationUserField,
+	nkOrganizationDefaults,
+} from "./organization.js";
+export {
+	CREDENTIAL_PROVIDER_ID,
+	DEFAULT_MAX_PASSWORD_LENGTH,
+	DEFAULT_MIN_PASSWORD_LENGTH,
+	type PasswordPolicy,
+	passwordSchema,
+	type ResetPasswordError,
+	type ResetPasswordErrorCode,
+	validateNewPassword,
+} from "./password.js";
+export { authBasePath } from "./paths.js";
+export { createAuthPool } from "./pool.js";

package/src/jwt.ts

@@ -0,0 +1,117 @@
+import type { IdHelper } from "@ingram-tech/nk-db/id";
+import type { JwtOptions } from "better-auth/plugins/jwt";
+import {
+	createRemoteJWKSet,
+	errors as joseErrors,
+	type JWTPayload,
+	jwtVerify,
+} from "jose";
+
+/**
+ * `jwt` plugin preset for a site's OWN backend API: a short-lived token with a
+ * specific `audience`, typically carrying extra claims the site adds via
+ * `auth.api.signJWT`. Defaults to EdDSA (Better Auth's default), with the JWKS
+ * exposed at `/api/auth/jwks` so the backend can verify it (`verifyBackendJwt`).
+ */
+
+export interface BackendJwtConfig {
+	/** Expected audience of the site's backend, e.g. "my-app-backend". */
+	audience: string;
+	/** Token lifetime, e.g. "15m". */
+	expirationTime?: string;
+	/**
+	 * Don't auto-attach the JWT to the `set-auth-jwt` response header — set when
+	 * the site mints tokens on demand via `auth.api.signJWT` instead.
+	 */
+	disableSettingJwtHeader?: boolean;
+	/**
+	 * Mint the token's `sub` (and the `id` in its payload) as the user's public
+	 * id rather than the raw uuid, so a backend that also talks to the app sees
+	 * ids in one form. The same helper the site passes to `createAuthHelpers`.
+	 */
+	ids?: { user: IdHelper };
+}
+
+/** `jwt` plugin options for a backend-API token (custom audience). */
+export const backendJwtOptions = (config: BackendJwtConfig): JwtOptions => ({
+	disableSettingJwtHeader: config.disableSettingJwtHeader,
+	jwt: {
+		...(config.ids
+			? {
+					getSubject: ({ user }) =>
+						config.ids?.user.encode(user.id) ?? user.id,
+					definePayload: ({ user }) => ({
+						...user,
+						id: config.ids?.user.encode(user.id) ?? user.id,
+					}),
+				}
+			: {}),
+		audience: config.audience,
+		expirationTime: config.expirationTime,
+	},
+});
+
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+// Forced-reload throttle (per JWKS URL). The no-matching-key path is reachable
+// by anyone who can send a request with a made-up `kid`, and `.reload()`
+// deliberately bypasses jose's cooldown — unthrottled, garbage tokens would
+// each cost a fresh fetch against the auth origin.
+const RELOAD_COOLDOWN_MS = 30_000;
+const lastForcedReload = new Map<string, number>();
+
+/**
+ * Verify a Better-Auth-minted backend JWT (EdDSA) against the issuer's JWKS.
+ * For use by the backend that consumes `backendJwtOptions` tokens. Throws on an
+ * invalid/expired token or audience/issuer mismatch; returns the claims.
+ *
+ * Hardened against Better Auth signing-key rotation: jose's `createRemoteJWKSet`
+ * refuses to refetch the JWKS for `cooldownDuration` (30s default) after any
+ * fetch, so a token signed with a freshly rotated key whose `kid` isn't yet in
+ * the cached set would fail for the *whole* cooldown window — a ~30s burst of
+ * auth failures on every request that verifies a token. On a no-matching-key
+ * miss we force a single `.reload()` (which bypasses the cooldown) and retry, so
+ * a rotation costs one extra fetch instead of a brief outage.
+ */
+export const verifyBackendJwt = async (params: {
+	token: string;
+	/** The issuer's JWKS endpoint, e.g. `${BETTER_AUTH_URL}/api/auth/jwks`. */
+	jwksUrl: string | URL;
+	audience: string;
+	issuer: string;
+}): Promise<JWTPayload> => {
+	const url =
+		typeof params.jwksUrl === "string" ? new URL(params.jwksUrl) : params.jwksUrl;
+	const cacheKey = url.toString();
+	let jwks = jwksCache.get(cacheKey);
+	if (!jwks) {
+		jwks = createRemoteJWKSet(url);
+		jwksCache.set(cacheKey, jwks);
+	}
+	const options = {
+		audience: params.audience,
+		issuer: params.issuer,
+		algorithms: ["EdDSA"],
+		// Tolerate a few seconds of clock skew between the minting and verifying
+		// hosts; jose's default of 0 fails legitimate tokens at exp/nbf boundaries.
+		clockTolerance: 5,
+	};
+	try {
+		const { payload } = await jwtVerify(params.token, jwks, options);
+		return payload;
+	} catch (err) {
+		if (!(err instanceof joseErrors.JWKSNoMatchingKey)) throw err;
+		// `kid` absent from the cached JWKS — almost always a just-rotated signing
+		// key. Force a refresh past the cooldown and retry exactly once, at most
+		// once per cooldown window so unknown-`kid` garbage can't hammer the
+		// issuer.
+		const now = Date.now();
+		if (now - (lastForcedReload.get(cacheKey) ?? 0) < RELOAD_COOLDOWN_MS) {
+			throw err;
+		}
+		lastForcedReload.set(cacheKey, now);
+		await jwks.reload();
+		const { payload } = await jwtVerify(params.token, jwks, options);
+		return payload;
+	}
+};