@ingram-tech/nk-auth 0.13.6 → 0.14.1

package/README.md

@@ -1,32 +1,28 @@
 # @ingram-tech/nk-auth
 
-The Ingram **[Better Auth](https://better-auth.com) foundation**: a toolkit of
-composable presets each Ingram Next.js site spreads into its *own*
-`betterAuth()` call. It is **not** a `betterAuth()` wrapper — the site stays
-plain Better Auth (prime directive), keeping full plugin type inference. Import
-only what you need from focused subpaths.
+Composable [Better Auth](https://better-auth.com) presets for Next.js apps, spread
+into your *own* `betterAuth()` call. This is not a `betterAuth()` wrapper: your app
+stays plain Better Auth, so plugin type inference survives. Import only what you
+need from focused subpaths.
 
-`better-auth`, `pg`, `@better-auth/passkey` are **peer dependencies** so there's
+`better-auth`, `pg`, `@better-auth/passkey` are peer dependencies, so there is
 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`) |
+| `authEnv`, `authSecret`, `isConfigured` (`./`) | env validation — `authEnv()` returns the full `{ secret, baseURL, databaseUrl }` bundle; `authSecret()` resolves just the secret (with the prod/dev rule) for apps that derive their own `baseURL` / DB connection |
+| `backendJwtOptions` / `verifyBackendJwt` (`./jwt`) | a JWT for your 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 |
+| `createAuthPool` (`./pool`) | **deprecated** — alias of `createPool` from [`@ingram-tech/nk-db`](../nk-db); inject your app's shared pool instead |
 | `makeEmailSenders`, `makePasskeyOptions`, `passkeyOptionsForBaseUrl`, `uuidGenerateId` (`./`) | email hooks, passkeys (`passkeyOptionsForBaseUrl` derives `rpID`/`origin` from a single base URL), UUID ids |
-| `bcryptPassword` (`./`) | **legacy only** — bcrypt verifier for sites with pre-existing bcrypt hashes. New sites omit it (Better Auth defaults to scrypt). See [Migrating bcrypt passwords to scrypt](#migrating-bcrypt-passwords-to-scrypt) |
+| `bcryptPassword` (`./`) | **legacy only** — bcrypt verifier for apps with pre-existing bcrypt hashes. New apps omit it (Better Auth defaults to scrypt). See [Migrating bcrypt passwords to scrypt](#migrating-bcrypt-passwords-to-scrypt) |
 | `createAuthHelpers`, `safeNext` (`./server`) | validated App Router session helpers (`getSession` / `getUser` / `requireSession` / `requireUser` / `redirectIfAuthenticated`), request-memoized via React `cache()`, with automatic `next` + stale-cookie signalling; `safeNext` validates a `?next=` param |
 | `createAuthMiddleware` (`./middleware`) | loop-safe edge middleware: gates unauthenticated users off protected paths, preserves `next`, and clears a stale session cookie so a bad session self-heals |
 
-> **Data access + RLS** is owned by [`@ingram-tech/nk-db`](../nk-db): query over a
-> direct `pg` connection and enforce per-request Row Level Security with
-> `withRls` / `withRlsTransaction` (claims taken from the Better Auth session — no
-> JWT minting, no REST proxy).
+> **Data access + RLS** is owned by [`@ingram-tech/nk-db`](../nk-db); see §3.
 >
-> **Backend-JWT + org sites** (a backend API plus the org plugin): compose the
-> site's shared nk-db pool, `backendJwtOptions({ audience })`,
+> **Backend-JWT + org sites** (a backend API plus the org plugin): compose your
+> app's shared nk-db pool, `backendJwtOptions({ audience })`,
 > `nkOrganizationDefaults`, and `lastActiveOrganizationHooks(pool)` in your
 > `betterAuth()`; verify backend tokens with `verifyBackendJwt`. Keep
 > app-specific bits (SSO restrictions, permissions/roles, connectors) in the app.
@@ -49,7 +45,7 @@ Outside production, `BETTER_AUTH_SECRET` falls back to a well-known insecure
 placeholder, so local dev and tests run without setting it (a warning is logged).
 In production it stays required — a missing secret throws at startup.
 
-If your site derives its own `baseURL` and opens its own database connection, it
+If your app derives its own `baseURL` and opens its own database connection, it
 may not want `authEnv()`'s all-or-nothing bundle (which also requires
 `BETTER_AUTH_URL` and `DATABASE_URL`). Take just the secret — same prod/dev rule —
 with `authSecret()`:
@@ -116,14 +112,14 @@ const db = await createTestDb({
 });
 ```
 
-**Upgrading better-auth** never means hand-writing a migration in your site: a
+**Upgrading better-auth** never means hand-writing a migration in your app: a
 schema-changing upgrade ships as a new file in nk-auth's chain, so you bump the
 dependency and your next migrate applies it. Reconcile the shipped schema against
-a pinned `better-auth` with `npx @better-auth/cli generate` (a nextkit-maintainer
-task, done once here — not per site).
+a pinned `better-auth` with `npx @better-auth/cli generate` (a maintainer task,
+done once in this package).
 
-> **Adopting from the old copy-in model?** Earlier docs told sites to `cp` the
-> baseline into their own `drizzle/` chain. If you already did, keep that file
+> **Adopting from the old copy-in model?** Earlier versions told you to `cp` the
+> baseline into your own `drizzle/` chain. If you already did, keep that file
 > (deleting an applied migration causes journal drift) and just add the auth-chain
 > invocation above: its DDL is all `… if not exists`, so it no-ops against your
 > existing tables and simply records the nk-auth journal. New auth migrations then
@@ -131,10 +127,8 @@ task, done once here — not per site).
 
 ## 2. Configure the server
 
-This package is **not** a `betterAuth()` wrapper — your site calls `betterAuth`
-itself and spreads in our presets. That keeps full Better Auth type inference at
-the call site (so `auth.api.*` stays typed) and keeps the site plain Better Auth,
-per the prime directive.
+Your app calls `betterAuth` itself and spreads in the presets, which keeps full
+Better Auth type inference at the call site, so `auth.api.*` stays typed.
 
 ```ts
 // lib/auth.ts
@@ -166,13 +160,13 @@ export const auth = betterAuth({
 	basePath: authBasePath, // mount at /auth, not the framework default /api/auth
 	advanced: { database: { generateId: uuidGenerateId } }, // UUIDv7 ids
 	// ^ stored as hyphenated UUIDv7 (uuid columns / RLS policies stay valid).
-	// To show those same ids as prefixed base58 on the wire/UI — `team_…`,
-	// matching the Ingram Cloud API's `agt_`/`smt_` ids — skin them with
+	// To show those same ids as prefixed base58 on the wire/UI — `team_…`, the
+	// way an API exposes prefixed ids like `agt_`/`smt_` — skin them with
 	// `toPrefixedId(uuid, "team")` / recover with `fromPrefixedId`. `base58Id`
-	// mints a fresh one directly for text-id sites. All from `@ingram-tech/nk-auth`.
+	// mints a fresh one directly for text-id apps. All from `@ingram-tech/nk-auth`.
 	emailAndPassword: {
 		enabled: true,
-		// Better Auth hashes with scrypt by default. Only sites carrying
+		// Better Auth hashes with scrypt by default. Only apps carrying
 		// pre-existing bcrypt hashes set `password: bcryptPassword` (legacy).
 		sendResetPassword: email.sendResetPassword,
 	},
@@ -232,11 +226,11 @@ has any stored preference.
 mail a user ever gets from you; a bare `<a href=url>url</a>` reads as phishing
 and trains people to distrust your domain. Take the
 [`registry`](https://github.com/ingram-technologies/registry) email components
-(`shadcn add email-verification email-password-reset`) — they accept `heading` /
-`body` / `ctaLabel` / `preview` overrides precisely so you can pass translated
-copy — or write your own. Send auth links from the default `notifications` local
-part (`fromAddress("Example")`) — **not** `no-reply`: this is the mail users are
-most likely to reply to, and dropping that reply is hostile. See
+(`shadcn add email-verification email-password-reset`), which accept `heading` /
+`body` / `ctaLabel` / `preview` overrides so you can pass translated copy, or
+write your own. Send auth links from the default `notifications` local part
+(`fromAddress("Example")`), **not** `no-reply`: this is the mail users are most
+likely to reply to, and dropping that reply is hostile. See
 [transactional-email.md](../../docs/transactional-email.md).
 
 **Spread all three in; do not hand-write them.** `betterAuth()` takes its
@@ -268,12 +262,14 @@ 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
 
-Assemble the client in a `"use client"` module (full plugin inference is
-preserved here too):
+Assemble the client in a `"use client"` module (plugin inference is preserved
+here too):
 
 ```tsx
 "use client";
@@ -312,9 +308,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";
@@ -378,13 +388,13 @@ marker and bounces to a clean `/login?next=…`; signing in returns them to
 `next`. `next` for the cookie-less case is filled in by middleware directly; for
 the cookie-present case the guard reads it from the `x-nk-auth-path` header
 middleware injects — so the self-heal (next + clearing) needs the middleware.
-Sites that skip middleware still get validated gating from the server helpers,
+An app that skips middleware still gets validated gating from the server helpers,
 just without automatic `next`/clearing.
 
 ## 6. Passwords: change, set, and reset
 
 nk-auth owns the reset **sender** (`makeEmailSenders.sendResetPassword`, §2) and
-now closes the loop so a site never touches Better Auth's `account` table or
+closes the loop so your app never touches Better Auth's `account` table or
 endpoint names directly. Three pieces:
 
 **Detect what login the user has.** A social-only account (Google, …) has no
@@ -462,11 +472,11 @@ async redirects() {
 ## Migrating bcrypt passwords to scrypt
 
 `bcryptPassword` is **legacy support only** (see its `@deprecated` note). It
-exists so sites whose `account.password` hashes are bcrypt keep verifying —
+exists so apps whose `account.password` hashes are bcrypt keep verifying:
 that is all nk-auth ships for the bcrypt case.
 
-The path to move a site fully onto scrypt is a **dual-format verifier**, wired
-in the site (nk-auth does not ship it). Better Auth's default hasher is scrypt
+The path to move fully onto scrypt is a **dual-format verifier**, wired in your
+app (nk-auth does not ship it). Better Auth's default hasher is scrypt
 (`<salt-hex>:<key-hex>`) and bcrypt hashes are trivially distinguishable (they
 start with `$2a$`/`$2b$`/`$2y$`), so override only
 `emailAndPassword.password.verify` to branch on `hash.startsWith("$2")` →

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.6",
+	"version": "0.14.1",
 	"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",
@@ -68,7 +68,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-db": "^2.0.0",
+		"@ingram-tech/nk-db": "^2.1.1",
 		"bcrypt": "^6.0.0",
 		"jose": "^6.2.9",
 		"zod": "^4.4.3"
@@ -96,7 +96,7 @@
 	},
 	"devDependencies": {
 		"@better-auth/passkey": "^1.7.0",
-		"@ingram-tech/nk-dev": "0.12.0",
+		"@ingram-tech/nk-dev": "0.13.1",
 		"@types/bcrypt": "^6.0.0",
 		"@types/node": "^26.2.0",
 		"@types/pg": "^8.23.1",

package/src/jwt.ts

@@ -1,3 +1,4 @@
+import type { IdHelper } from "@ingram-tech/nk-db/id";
 import type { JwtOptions } from "better-auth/plugins/jwt";
 import {
 	createRemoteJWKSet,
@@ -23,12 +24,28 @@ 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 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,
 	},

package/src/server.ts

@@ -24,6 +24,7 @@
  * `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";
 import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { cache } from "react";
@@ -62,9 +63,27 @@ 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`,
@@ -73,6 +92,45 @@ export interface AuthHelpersOptions {
 	sessionCookiePrefix?: string;
 }
 
+const encodeIfString = (helper: IdHelper | undefined, value: unknown): unknown =>
+	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<S extends SessionLike>(
+	session: S,
+	ids: SessionIds,
+): S {
+	const out: Record<string, unknown> = { ...(session as Record<string, unknown>) };
+	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 as Record<string, unknown>;
+		out.session = {
+			...rec,
+			...("userId" in rec
+				? { userId: encodeIfString(ids.user, rec.userId) }
+				: {}),
+			...("activeOrganizationId" in rec
+				? {
+						activeOrganizationId: encodeIfString(
+							ids.organization,
+							rec.activeOrganizationId,
+						),
+					}
+				: {}),
+		};
+	}
+	return out as S;
+}
+
 export function createAuthHelpers<S extends SessionLike>(
 	auth: AuthLike<S>,
 	options: AuthHelpersOptions = {},
@@ -92,9 +150,12 @@ export function createAuthHelpers<S extends SessionLike>(
 	 * pre-mutation snapshot; re-read through `auth.api.getSession` directly if
 	 * that ever matters.
 	 */
-	const getSession = cache(async (): Promise<S | null> =>
-		auth.api.getSession({ headers: await headers() }),
-	);
+	const getSession = cache(async (): Promise<S | null> => {
+		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(): Promise<S["user"] | null> {