@ingram-tech/nk-auth 0.12.3 → 0.13.1

package/README.md

@@ -70,16 +70,64 @@ the app: the security-sensitive default then lives in exactly one place.
 
 ## 1. Apply the schema
 
-```bash
-cp node_modules/@ingram-tech/nk-auth/migrations/0001_better_auth.sql \
-   migrations/$(date +%Y%m%d%H%M%S)_better_auth.sql
+nk-auth **owns its auth tables as its own migration chain** — the versioned SQL
+files it ships in `migrations/`, journaled separately from your app's `drizzle/`
+migrations. You don't copy anything in; you point the runner at the shipped
+folder. It creates Better Auth's tables (`user`, `session`, `account`,
+`verification`, `jwks`, `passkey`), defaults new user ids to UUIDs, and puts
+**deny-all RLS** on all of them (Better Auth reaches them through its own
+privileged connection). See [db-package.md § "The nk-auth migration
+chain"](../../docs/db-package.md#the-nk-auth-migration-chain) for the full model.
+
+The auth chain runs **before** your app chain, because your app tables FK to
+`user`.
+
+**Production / deploy** — add the auth chain to your `db:migrate` script,
+auth-first, on its own journal table:
+
+```jsonc
+// package.json
+"scripts": {
+  "db:migrate": "nk-pg-migrate --migrations node_modules/@ingram-tech/nk-auth/migrations --table __nkauth_migrations && nk-pg-migrate"
+}
+```
+
+The first invocation applies (and journals) nk-auth's chain; the second applies
+your app's `drizzle/` chain. Both are idempotent and drift-checked, so re-running
+is a no-op — see the [`nk-pg-migrate` runner](../../docs/db-package.md#migrations).
+
+**Local dev** — nothing to do. `nk dev` resolves nk-auth and applies its chain to
+the local PGlite database automatically, before your `drizzle/` migrations.
+
+**Tests** — when a test needs the auth tables, pass the shipped folder to
+`createTestDb` as a dependency chain (applied first, own journal table):
+
+```ts
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const authMigrations = join(
+	dirname(createRequire(import.meta.url).resolve("@ingram-tech/nk-auth/package.json")),
+	"migrations",
+);
+
+const db = await createTestDb({
+	dependencyMigrations: [{ folder: authMigrations, table: "__nkauth_migrations" }],
+});
 ```
 
-It creates Better Auth's tables (`user`, `session`, `account`, `verification`,
-`jwks`, `passkey`), defaults new user ids to UUIDs, and puts **deny-all RLS** on
-all of them (Better Auth reaches them through its own privileged connection).
-Reconcile against your pinned `better-auth` with `npx @better-auth/cli generate`
-after upgrades.
+**Upgrading better-auth** never means hand-writing a migration in your site: 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).
+
+> **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
+> (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
+> flow through the shipped chain from here on.
 
 ## 2. Configure the server
 
@@ -103,9 +151,13 @@ import { betterAuth } from "better-auth";
 import { pool } from "@/lib/db"; // the ONE shared createPool() from @ingram-tech/nk-db
 
 const env = authEnv();
-const email = makeEmailSenders(({ to, subject, url }) =>
-	sendEmail({ to, from: fromAddress(), subject, text: url, html: url }),
-);
+// Render a real template per `kind` — these are the first mails a user ever
+// gets from you. `text: url, html: url` ships a bare link that reads as
+// phishing; see "Auth emails" below.
+const email = makeEmailSenders(async ({ kind, to, url, user, newEmail }) => {
+	const { subject, html, text } = await renderAuthEmail({ kind, url, user, newEmail });
+	sendEmail({ to, from: fromAddress("Example", "no-reply"), subject, html, text });
+});
 
 export const auth = betterAuth({
 	database: pool, // inject the shared pool — exactly one pool per process
@@ -125,6 +177,15 @@ export const auth = betterAuth({
 		sendResetPassword: email.sendResetPassword,
 	},
 	emailVerification: { sendVerificationEmail: email.sendVerificationEmail },
+	user: {
+		// Confirms the move from the CURRENT address. Note the name: it is
+		// `sendChangeEmailConfirmation`, and betterAuth() does not
+		// excess-property-check, so a wrong name here silently never fires.
+		changeEmail: {
+			enabled: true,
+			sendChangeEmailConfirmation: email.sendChangeEmailConfirmation,
+		},
+	},
 	socialProviders: {
 		google: {
 			clientId: process.env.GOOGLE_CLIENT_ID ?? "",
@@ -149,6 +210,57 @@ import { auth } from "@/lib/auth";
 export const { GET, POST } = toNextJsHandler(auth);
 ```
 
+## Auth emails
+
+`makeEmailSenders(send)` returns the three callbacks Better Auth needs. Every
+message reaches your `send` with a **`kind`** discriminator — switch on that to
+pick a template. Never switch on `subject`: it is default English copy that a
+localized site is expected to throw away.
+
+| `kind`           | Better Auth option                            | Goes to               |
+| ---------------- | --------------------------------------------- | --------------------- |
+| `verify-email`   | `emailVerification.sendVerificationEmail`      | the new signup        |
+| `reset-password` | `emailAndPassword.sendResetPassword`           | the account address   |
+| `change-email`   | `user.changeEmail.sendChangeEmailConfirmation` | the **current** address |
+
+Each message also carries `user` (`id` for a locale/preferences lookup, `name`
+to personalize), `token`, and the originating `request` — whose `Accept-Language`
+is the only locale signal available for a signup verification, before the user
+has any stored preference.
+
+**Render a real template.** Verification, reset and change-email are the first
+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 `no-reply` local part
+(`fromAddress("Example", "no-reply")`), per
+[transactional-email.md](../../docs/transactional-email.md).
+
+**Spread all three in; do not hand-write them.** `betterAuth()` takes its
+options through a generic, which switches **off** excess-property checking on
+that object literal. A callback under a wrong-but-plausible name compiles
+perfectly and then never fires:
+
+```ts
+user: {
+	changeEmail: {
+		enabled: true,
+		// WRONG NAME. No type error — and no email, ever. The real option is
+		// `sendChangeEmailConfirmation`.
+		sendChangeEmailVerification: async ({ user, url }) => { /* dead code */ },
+	},
+},
+```
+
+That is not hypothetical — it shipped, and the failure is silent in both
+directions: Better Auth falls through to sending the *verification* mail to the
+**new** address instead, so the current address is never told its account is
+moving. `makeEmailSenders` exists to keep you off that path; `options.ts` pins
+all three names to the real Better Auth option types, so an upstream rename
+fails nk-auth's build rather than quietly disabling your mail.
+
 ## 3. Query data with RLS intact
 
 Data access lives in [`@ingram-tech/nk-db`](../nk-db), not here. Query over the

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { bcryptPassword, makeEmailSenders, makePasskeyOptions, type PasskeyConfig, passkeyOptionsForBaseUrl, type SendEmail, } from "./options.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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACjF,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACN,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,wBAAwB,EACxB,KAAK,SAAS,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,mBAAmB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACjF,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,wBAAwB,EACxB,KAAK,SAAS,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,mBAAmB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AAExE,OAAO,EAAyB,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACjF,OAAO,EAAgB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACN,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAElB,wBAAwB,GAExB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAE3B,cAAc,EAGd,mBAAmB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AAExE,OAAO,EAAyB,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACjF,OAAO,EAAgB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAIN,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAElB,wBAAwB,GAExB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAE3B,cAAc,EAGd,mBAAmB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/options.d.ts

@@ -57,28 +57,73 @@ export declare const makePasskeyOptions: (cfg: PasskeyConfig) => PasskeyOptions;
  * for an "app.example.com" origin).
  */
 export declare const passkeyOptionsForBaseUrl: (baseURL: string, rpName: string) => PasskeyOptions;
-/** Send one transactional email (wire to `@ingram-tech/nk-email`'s `sendEmail`). */
-export type SendEmail = (message: {
+/**
+ * Which auth mail is being sent. Switch on this to pick a template — never on
+ * `subject`, which is English default copy a site is expected to replace.
+ */
+export type AuthEmailKind = "verify-email" | "reset-password" | "change-email";
+/** The subset of the Better Auth user these callbacks pass through. */
+export interface AuthEmailUser {
+    id: string;
+    email: string;
+    name?: string;
+}
+/** One outgoing auth mail, handed to the site's sender. */
+export interface AuthEmailMessage {
+    /** Discriminator — pick the template off this. */
+    kind: AuthEmailKind;
+    /**
+     * Recipient. For `change-email` this is deliberately the user's CURRENT
+     * address: confirming the move from the address that already owns the
+     * account is what stops a hijacked session from walking off with it.
+     */
     to: string;
+    /**
+     * Default English subject, for sites that don't localize. Prefer your own
+     * translated copy — see the README.
+     */
     subject: string;
+    /** The one-time action link. */
     url: string;
-}) => Promise<unknown>;
+    /** The raw token behind `url`, if you need to build your own link. */
+    token: string;
+    /** `id` lets you look up a locale/preferences; `name` personalizes copy. */
+    user: AuthEmailUser;
+    /** `change-email` only: the address the user is moving to. */
+    newEmail?: string;
+    /** The originating request — `Accept-Language` is a locale source. */
+    request?: Request;
+}
+/** Send one transactional email (wire to `@ingram-tech/nk-email`'s `sendEmail`). */
+export type SendEmail = (message: AuthEmailMessage) => Promise<unknown>;
 /**
- * Email callbacks for `emailAndPassword.sendResetPassword` and
- * `emailVerification.sendVerificationEmail`, routed through your sender.
+ * Email callbacks for `emailAndPassword.sendResetPassword`,
+ * `emailVerification.sendVerificationEmail` and
+ * `user.changeEmail.sendChangeEmailConfirmation`, routed through your sender.
+ *
+ * Spread all three in. Hand-writing them is a trap: `betterAuth()` infers its
+ * options generically, so TypeScript does NOT excess-property-check that object
+ * literal — a callback under a misremembered name (`sendChangeEmailVerification`
+ * is the one people reach for) compiles clean and simply never fires. The
+ * `PinnedEmailSenders` assertion below ties these three names to the real Better
+ * Auth options, so a rename upstream breaks this build instead of your site.
  */
 export declare const makeEmailSenders: (send: SendEmail) => {
-    sendResetPassword: ({ user, url, }: {
-        user: {
-            email: string;
-        };
+    sendResetPassword: ({ user, url, token }: {
+        user: AuthEmailUser;
+        url: string;
+        token: string;
+    }, request?: Request) => Promise<void>;
+    sendVerificationEmail: ({ user, url, token }: {
+        user: AuthEmailUser;
         url: string;
-    }) => Promise<void>;
-    sendVerificationEmail: ({ user, url, }: {
-        user: {
-            email: string;
-        };
+        token: string;
+    }, request?: Request) => Promise<void>;
+    sendChangeEmailConfirmation: ({ user, newEmail, url, token, }: {
+        user: AuthEmailUser;
+        newEmail: string;
         url: string;
-    }) => Promise<void>;
+        token: string;
+    }, request?: Request) => Promise<void>;
 };
 //# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAM3D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc;IAC1B,IAAI,aAAa,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;IACzC,MAAM,wBAGH;QACF,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KACjB,KAAG,OAAO,CAAC,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,WAAW,aAAa;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAS,aAAa,KAAG,cAItD,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,YAC3B,MAAM,UACP,MAAM,KACZ,cAKA,CAAC;AAEJ,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACZ,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB;;;GAGG;AACH,eAAO,MAAM,gBAAgB,SAAU,SAAS;IAC/C,iBAAiB,mBAGd;QACF,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC;KACZ,KAAG,OAAO,CAAC,IAAI,CAAC;IAGjB,qBAAqB,mBAGlB;QACF,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC;KACZ,KAAG,OAAO,CAAC,IAAI,CAAC;CAGhB,CAAC"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAO3D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc;IAC1B,IAAI,aAAa,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;IACzC,MAAM,wBAGH;QACF,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KACjB,KAAG,OAAO,CAAC,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,WAAW,aAAa;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAS,aAAa,KAAG,cAItD,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,YAC3B,MAAM,UACP,MAAM,KACZ,cAKA,CAAC;AAEJ;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAE/E,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAChC,kDAAkD;IAClD,IAAI,EAAE,aAAa,CAAC;IACpB;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,EAAE,aAAa,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,SAAU,SAAS;IAC/C,iBAAiB,yBACM;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,YAC/D,OAAO,KACf,OAAO,CAAC,IAAI,CAAC;IAWhB,qBAAqB,yBACE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,YAC/D,OAAO,KACf,OAAO,CAAC,IAAI,CAAC;IAWhB,2BAA2B,oCAMvB;QACF,IAAI,EAAE,aAAa,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACd,YACS,OAAO,KACf,OAAO,CAAC,IAAI,CAAC;CAYf,CAAC"}

package/dist/options.js

@@ -58,15 +58,60 @@ export const passkeyOptionsForBaseUrl = (baseURL, rpName) => makePasskeyOptions(
     origin: baseURL,
 });
 /**
- * Email callbacks for `emailAndPassword.sendResetPassword` and
- * `emailVerification.sendVerificationEmail`, routed through your sender.
+ * Email callbacks for `emailAndPassword.sendResetPassword`,
+ * `emailVerification.sendVerificationEmail` and
+ * `user.changeEmail.sendChangeEmailConfirmation`, routed through your sender.
+ *
+ * Spread all three in. Hand-writing them is a trap: `betterAuth()` infers its
+ * options generically, so TypeScript does NOT excess-property-check that object
+ * literal — a callback under a misremembered name (`sendChangeEmailVerification`
+ * is the one people reach for) compiles clean and simply never fires. The
+ * `PinnedEmailSenders` assertion below ties these three names to the real Better
+ * Auth options, so a rename upstream breaks this build instead of your site.
  */
 export const makeEmailSenders = (send) => ({
-    sendResetPassword: async ({ user, url, }) => {
-        await send({ to: user.email, subject: "Reset your password", url });
+    sendResetPassword: async ({ user, url, token }, request) => {
+        await send({
+            kind: "reset-password",
+            to: user.email,
+            subject: "Reset your password",
+            url,
+            token,
+            user,
+            request,
+        });
+    },
+    sendVerificationEmail: async ({ user, url, token }, request) => {
+        await send({
+            kind: "verify-email",
+            to: user.email,
+            subject: "Verify your email",
+            url,
+            token,
+            user,
+            request,
+        });
     },
-    sendVerificationEmail: async ({ user, url, }) => {
-        await send({ to: user.email, subject: "Verify your email", url });
+    sendChangeEmailConfirmation: async ({ user, newEmail, url, token, }, request) => {
+        await send({
+            kind: "change-email",
+            to: user.email, // the CURRENT address — see AuthEmailMessage.to
+            subject: "Confirm your email change",
+            url,
+            token,
+            user,
+            newEmail,
+            request,
+        });
     },
 });
+const _pinEmailSenders = (send) => {
+    const senders = makeEmailSenders(send);
+    return {
+        reset: senders.sendResetPassword,
+        verify: senders.sendVerificationEmail,
+        change: senders.sendChangeEmailConfirmation,
+    };
+};
+void _pinEmailSenders;
 //# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,iFAAiF;AACjF,kFAAkF;AAClF,iEAAiE;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,IAAI,EAAE,CAAC,QAAgB,EAAmB,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;IACtE,MAAM,EAAE,CAAC,EACR,IAAI,EACJ,QAAQ,GAIR,EAAoB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;CACtD,CAAC;AAWF,iFAAiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAkB,EAAkB,EAAE,CAAC,CAAC;IAC1E,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,MAAM,EAAE,GAAG,CAAC,MAAM;IAClB,MAAM,EAAE,GAAG,CAAC,MAAM;CAClB,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACvC,OAAe,EACf,MAAc,EACG,EAAE,CACnB,kBAAkB,CAAC;IAClB,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ;IAC/B,MAAM;IACN,MAAM,EAAE,OAAO;CACf,CAAC,CAAC;AASJ;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,CAAC;IACrD,iBAAiB,EAAE,KAAK,EAAE,EACzB,IAAI,EACJ,GAAG,GAIH,EAAiB,EAAE;QACnB,MAAM,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,GAAG,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,qBAAqB,EAAE,KAAK,EAAE,EAC7B,IAAI,EACJ,GAAG,GAIH,EAAiB,EAAE;QACnB,MAAM,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC,CAAC;IACnE,CAAC;CACD,CAAC,CAAC"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAEA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,iFAAiF;AACjF,kFAAkF;AAClF,iEAAiE;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,IAAI,EAAE,CAAC,QAAgB,EAAmB,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;IACtE,MAAM,EAAE,CAAC,EACR,IAAI,EACJ,QAAQ,GAIR,EAAoB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;CACtD,CAAC;AAWF,iFAAiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAkB,EAAkB,EAAE,CAAC,CAAC;IAC1E,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,MAAM,EAAE,GAAG,CAAC,MAAM;IAClB,MAAM,EAAE,GAAG,CAAC,MAAM;CAClB,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACvC,OAAe,EACf,MAAc,EACG,EAAE,CACnB,kBAAkB,CAAC;IAClB,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ;IAC/B,MAAM;IACN,MAAM,EAAE,OAAO;CACf,CAAC,CAAC;AA6CJ;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,CAAC;IACrD,iBAAiB,EAAE,KAAK,EACvB,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAuD,EACzE,OAAiB,EACD,EAAE;QAClB,MAAM,IAAI,CAAC;YACV,IAAI,EAAE,gBAAgB;YACtB,EAAE,EAAE,IAAI,CAAC,KAAK;YACd,OAAO,EAAE,qBAAqB;YAC9B,GAAG;YACH,KAAK;YACL,IAAI;YACJ,OAAO;SACP,CAAC,CAAC;IACJ,CAAC;IACD,qBAAqB,EAAE,KAAK,EAC3B,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAuD,EACzE,OAAiB,EACD,EAAE;QAClB,MAAM,IAAI,CAAC;YACV,IAAI,EAAE,cAAc;YACpB,EAAE,EAAE,IAAI,CAAC,KAAK;YACd,OAAO,EAAE,mBAAmB;YAC5B,GAAG;YACH,KAAK;YACL,IAAI;YACJ,OAAO;SACP,CAAC,CAAC;IACJ,CAAC;IACD,2BAA2B,EAAE,KAAK,EACjC,EACC,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,KAAK,GAML,EACD,OAAiB,EACD,EAAE;QAClB,MAAM,IAAI,CAAC;YACV,IAAI,EAAE,cAAc;YACpB,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,gDAAgD;YAChE,OAAO,EAAE,2BAA2B;YACpC,GAAG;YACH,KAAK;YACL,IAAI;YACJ,QAAQ;YACR,OAAO;SACP,CAAC,CAAC;IACJ,CAAC;CACD,CAAC,CAAC;AAgCH,MAAM,gBAAgB,GAAG,CAAC,IAAe,EAAsB,EAAE;IAChE,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO;QACN,KAAK,EAAE,OAAO,CAAC,iBAAiB;QAChC,MAAM,EAAE,OAAO,CAAC,qBAAqB;QACrC,MAAM,EAAE,OAAO,CAAC,2BAA2B;KAC3C,CAAC;AACH,CAAC,CAAC;AACF,KAAK,gBAAgB,CAAC"}

package/migrations/0001_better_auth.sql

@@ -1,11 +1,20 @@
 -- @ingram-tech/nk-auth — Better Auth schema, hardened for RLS.
 --
--- This mirrors Better Auth's core tables (user / session / account /
--- verification), the `jwt` plugin's `jwks` table, and the `passkey` plugin's
--- `passkey` table, for the version of `better-auth` this package depends on.
--- Reconcile against the exact pinned version with:
+-- This is the BASELINE (0001) of nk-auth's own migration chain — an append-only
+-- set of SQL files this package ships and versions, journaled independently of a
+-- consuming site's `drizzle/` chain (see docs/db-package.md § "The nk-auth
+-- migration chain"). It mirrors Better Auth's core tables (user / session /
+-- account / verification), the `jwt` plugin's `jwks` table, and the `passkey`
+-- plugin's `passkey` table, for the version of `better-auth` this package pins.
+--
+-- Upgrading better-auth: this file is APPEND-ONLY. Once shipped it must never be
+-- rewritten — the runner hashes each file and a changed baseline drifts every
+-- site that already applied it. When a better-auth upgrade changes the schema,
+-- diff it against the pinned version with:
 --     npx @better-auth/cli generate
--- and re-run after upgrading better-auth.
+-- and land the delta as a NEW file (0002_*.sql, …) plus a `meta/_journal.json`
+-- entry, written as idempotent `... if not exists` DDL and re-applying the two
+-- hardening steps below to any new table. Never edit 0001.
 --
 -- TWO hardening steps the generator does NOT produce, both required:
 --   1. New users default to a UUID id, because `auth.uid()`-style RLS policies
@@ -16,6 +25,13 @@
 --      which bypasses RLS, so denying the app's RLS role any access here costs
 --      nothing and keeps the auth tables off-limits to user-facing queries.
 
+-- Statements below are separated by drizzle's per-statement breakpoint marker
+-- (a plain SQL line comment). It is REQUIRED: the PGlite dev/test migrator parses
+-- one statement per command and rejects a multi-statement string, so the runner
+-- splits the file on that marker. Keep one statement per segment when appending
+-- deltas — and never write the literal marker token inside prose like this, or
+-- the splitter will cut here.
+
 create table if not exists "public"."user" (
 	"id" text primary key default gen_random_uuid()::text, -- hardening (1)
 	"name" text not null,
@@ -25,7 +41,7 @@ create table if not exists "public"."user" (
 	"createdAt" timestamptz not null default now(),
 	"updatedAt" timestamptz not null default now()
 );
-
+--> statement-breakpoint
 create table if not exists "public"."session" (
 	"id" text primary key,
 	"expiresAt" timestamptz not null,
@@ -36,7 +52,7 @@ create table if not exists "public"."session" (
 	"createdAt" timestamptz not null default now(),
 	"updatedAt" timestamptz not null default now()
 );
-
+--> statement-breakpoint
 create table if not exists "public"."account" (
 	"id" text primary key,
 	"accountId" text not null,
@@ -52,7 +68,7 @@ create table if not exists "public"."account" (
 	"createdAt" timestamptz not null default now(),
 	"updatedAt" timestamptz not null default now()
 );
-
+--> statement-breakpoint
 create table if not exists "public"."verification" (
 	"id" text primary key,
 	"identifier" text not null,
@@ -61,7 +77,7 @@ create table if not exists "public"."verification" (
 	"createdAt" timestamptz not null default now(),
 	"updatedAt" timestamptz not null default now()
 );
-
+--> statement-breakpoint
 -- `jwt` plugin: holds the asymmetric keypair used to sign session JWTs.
 create table if not exists "public"."jwks" (
 	"id" text primary key,
@@ -69,7 +85,7 @@ create table if not exists "public"."jwks" (
 	"privateKey" text not null,
 	"createdAt" timestamptz not null default now()
 );
-
+--> statement-breakpoint
 -- `passkey` plugin.
 create table if not exists "public"."passkey" (
 	"id" text primary key,
@@ -84,17 +100,25 @@ create table if not exists "public"."passkey" (
 	"aaguid" text,
 	"createdAt" timestamptz default now()
 );
-
+--> statement-breakpoint
 create index if not exists "idx_session_userId" on "public"."session" ("userId");
+--> statement-breakpoint
 create index if not exists "idx_account_userId" on "public"."account" ("userId");
+--> statement-breakpoint
 create index if not exists "idx_passkey_userId" on "public"."passkey" ("userId");
+--> statement-breakpoint
 create index if not exists "idx_verification_identifier" on "public"."verification" ("identifier");
-
+--> statement-breakpoint
 -- Hardening (2): deny-all RLS. No policies = no anon/authenticated access.
 -- Better Auth's privileged connection bypasses RLS, so auth still works.
 alter table "public"."user" enable row level security;
+--> statement-breakpoint
 alter table "public"."session" enable row level security;
+--> statement-breakpoint
 alter table "public"."account" enable row level security;
+--> statement-breakpoint
 alter table "public"."verification" enable row level security;
+--> statement-breakpoint
 alter table "public"."jwks" enable row level security;
+--> statement-breakpoint
 alter table "public"."passkey" enable row level security;

package/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+	"version": "7",
+	"dialect": "postgresql",
+	"entries": [
+		{
+			"idx": 0,
+			"version": "7",
+			"when": 1735689600000,
+			"tag": "0001_better_auth",
+			"breakpoints": true
+		}
+	]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-auth",
-	"version": "0.12.3",
+	"version": "0.13.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",
@@ -60,12 +60,12 @@
 		"./migrations/*": "./migrations/*"
 	},
 	"scripts": {
-		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json",
+		"build": "rm -rf dist *.tsbuildinfo && tsc -p tsconfig.build.json",
 		"type-check": "tsc -p tsconfig.json --noEmit",
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-db": "^1.4.0",
+		"@ingram-tech/nk-db": "^1.4.2",
 		"bcrypt": "^6.0.0",
 		"jose": "^6.2.3",
 		"zod": "^4.4.3"
@@ -93,7 +93,7 @@
 	},
 	"devDependencies": {
 		"@better-auth/passkey": "^1.6.23",
-		"@ingram-tech/nk-dev": "0.5.0",
+		"@ingram-tech/nk-dev": "0.8.0",
 		"@types/bcrypt": "^6.0.0",
 		"@types/node": "^26.1.1",
 		"@types/pg": "^8.20.0",