@nextsparkjs/core 0.1.0-beta.185 → 0.1.0-beta.187

package/dist/lib/auth/security-notifications/dispatcher.js

@@ -0,0 +1,157 @@
+import { AUTH_CONFIG, I18N_CONFIG, APP_NAME } from "../../config/index.js";
+import { queryWithRLS, mutateWithRLS } from "../../db.js";
+import { scheduleAction, isActionRegistered } from "../../scheduled-actions/index.js";
+import { registerSecurityNotificationAction } from "../../scheduled-actions/handlers/security-notification.js";
+import { computeDeviceFingerprint, extractClientIp } from "./device-fingerprint.js";
+const ACTION_TYPE = "auth:security-notification";
+function getPathname(req) {
+  var _a;
+  try {
+    const pathname = (_a = req.nextUrl) == null ? void 0 : _a.pathname;
+    if (pathname) return pathname;
+  } catch {
+  }
+  try {
+    return new URL(req.url).pathname;
+  } catch {
+    return "";
+  }
+}
+function isOk(response) {
+  return response.status >= 200 && response.status < 300;
+}
+function resolveAppName() {
+  return process.env.NEXT_PUBLIC_APP_NAME || APP_NAME || "Your App";
+}
+function ensureHandlerRegistered() {
+  if (!isActionRegistered(ACTION_TYPE)) {
+    registerSecurityNotificationAction();
+  }
+}
+async function queueNotification(userId, payload) {
+  if (!payload.to) return;
+  ensureHandlerRegistered();
+  await scheduleAction(ACTION_TYPE, {
+    ...payload,
+    // entityId+entityType drive the scheduler's dedup so a double-submit of the
+    // same event for the same user within the dedup window collapses to one email.
+    entityId: `${userId}:${payload.type}`,
+    entityType: "security-notification"
+  });
+}
+async function handleNewDeviceLogin(req, body) {
+  var _a;
+  const user = body.user;
+  if (!(user == null ? void 0 : user.id)) return;
+  const ip = extractClientIp(req.headers);
+  const userAgent = req.headers.get("user-agent");
+  const fingerprint = computeDeviceFingerprint(userAgent, ip);
+  const ttlDays = ((_a = AUTH_CONFIG.securityNotifications) == null ? void 0 : _a.fingerprintTtlDays) ?? null;
+  const params = [user.id, fingerprint];
+  let ttlClause = "";
+  if (typeof ttlDays === "number" && ttlDays > 0) {
+    ttlClause = `AND "createdAt" > now() - make_interval(days => $3)`;
+    params.push(ttlDays);
+  }
+  const existing = await queryWithRLS(
+    `SELECT id FROM "login_events"
+      WHERE "userId" = $1 AND "deviceFingerprint" = $2 ${ttlClause}
+      LIMIT 1`,
+    params,
+    null
+  );
+  const isNew = existing.length === 0;
+  await mutateWithRLS(
+    `INSERT INTO "login_events"
+       ("userId", "ipAddress", "userAgent", "deviceFingerprint", "isNew")
+     VALUES ($1, $2, $3, $4, $5)`,
+    [user.id, ip === "unknown" ? null : ip, userAgent, fingerprint, isNew],
+    null
+  );
+  if (!isNew) return;
+  await queueNotification(user.id, {
+    type: "newDeviceLogin",
+    locale: user.language || I18N_CONFIG.defaultLocale,
+    appName: resolveAppName(),
+    to: user.email || "",
+    userName: user.firstName || user.name,
+    ipAddress: ip === "unknown" ? void 0 : ip,
+    userAgent: userAgent || void 0,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+async function handlePasswordChanged(body) {
+  const user = body.user;
+  if (!(user == null ? void 0 : user.id) || !user.email) return;
+  await queueNotification(user.id, {
+    type: "passwordChanged",
+    locale: user.language || I18N_CONFIG.defaultLocale,
+    appName: resolveAppName(),
+    to: user.email,
+    userName: user.firstName || user.name,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+async function handleEmailChanged(req) {
+  const { auth } = await import("../../auth.js");
+  const session = await auth.api.getSession({ headers: req.headers });
+  const user = session == null ? void 0 : session.user;
+  if (!(user == null ? void 0 : user.id) || !user.email) return;
+  let newEmail;
+  try {
+    const reqBody = await req.json();
+    newEmail = reqBody == null ? void 0 : reqBody.newEmail;
+  } catch {
+  }
+  await queueNotification(user.id, {
+    type: "emailChanged",
+    locale: user.language || I18N_CONFIG.defaultLocale,
+    appName: resolveAppName(),
+    to: user.email,
+    // OLD address — deliberate
+    userName: user.firstName || user.name,
+    newEmail,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+function classifyEvent(pathname) {
+  if (pathname.endsWith("/sign-in/email") || pathname.endsWith("/sign-in/email-otp")) {
+    return "newDeviceLogin";
+  }
+  if (pathname.endsWith("/change-password")) return "passwordChanged";
+  if (pathname.endsWith("/change-email")) return "emailChanged";
+  return null;
+}
+async function dispatchSecurityNotificationsForRequest(req, response) {
+  var _a, _b, _c;
+  try {
+    const cfg = AUTH_CONFIG.securityNotifications;
+    if (!(cfg == null ? void 0 : cfg.enabled)) return;
+    if (!isOk(response)) return;
+    const event = classifyEvent(getPathname(req));
+    if (!event) return;
+    if (event === "newDeviceLogin" && !((_a = cfg.events) == null ? void 0 : _a.newDeviceLogin)) return;
+    if (event === "passwordChanged" && !((_b = cfg.events) == null ? void 0 : _b.passwordChanged)) return;
+    if (event === "emailChanged" && !((_c = cfg.events) == null ? void 0 : _c.emailChanged)) return;
+    if (event === "emailChanged") {
+      await handleEmailChanged(req);
+      return;
+    }
+    let body;
+    try {
+      body = await response.clone().json();
+    } catch {
+      return;
+    }
+    if (event === "newDeviceLogin") {
+      await handleNewDeviceLogin(req, body);
+    } else {
+      await handlePasswordChanged(body);
+    }
+  } catch (error) {
+    console.error("[security-notifications] dispatch failed:", error);
+  }
+}
+export {
+  dispatchSecurityNotificationsForRequest
+};

package/dist/lib/auth/security-notifications/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Built-in security email notifications (issue #75).
+ *
+ * Public surface:
+ *   - dispatchSecurityNotificationsForRequest(req, response)  → wire into the
+ *       Better Auth route handler (best-effort, guarded by config).
+ *   - registerSecurityEmailTemplate(type, locale, builder)    → theme branding
+ *       / localization override, no core fork required.
+ *   - computeDeviceFingerprint(ua, ip) / extractClientIp(headers) → fingerprint
+ *       primitives (also used by tests).
+ *
+ * The scheduled-action handler that actually sends the email lives at
+ * `@nextsparkjs/core/lib/scheduled-actions/handlers` as
+ * `registerSecurityNotificationAction()`.
+ */
+export { dispatchSecurityNotificationsForRequest } from './dispatcher';
+export { registerSecurityEmailTemplate, getSecurityEmailTemplate, clearSecurityEmailTemplates, } from './registry';
+export { computeDeviceFingerprint, extractClientIp, normalizeUserAgent, ipToNetworkKey, } from './device-fingerprint';
+export type { SecurityEventType, SecurityEmailContext, SecurityEmailContent, SecurityEmailTemplateBuilder, SecurityNotificationActionPayload, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/auth/security-notifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/security-notifications/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,uCAAuC,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,iCAAiC,GAClC,MAAM,SAAS,CAAA"}

package/dist/lib/auth/security-notifications/index.js

@@ -0,0 +1,22 @@
+import { dispatchSecurityNotificationsForRequest } from "./dispatcher.js";
+import {
+  registerSecurityEmailTemplate,
+  getSecurityEmailTemplate,
+  clearSecurityEmailTemplates
+} from "./registry.js";
+import {
+  computeDeviceFingerprint,
+  extractClientIp,
+  normalizeUserAgent,
+  ipToNetworkKey
+} from "./device-fingerprint.js";
+export {
+  clearSecurityEmailTemplates,
+  computeDeviceFingerprint,
+  dispatchSecurityNotificationsForRequest,
+  extractClientIp,
+  getSecurityEmailTemplate,
+  ipToNetworkKey,
+  normalizeUserAgent,
+  registerSecurityEmailTemplate
+};

package/dist/lib/auth/security-notifications/registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Template registry for security emails.
+ *
+ * Resolution order for a given (type, locale):
+ *   1. a theme-registered builder for the exact `type:locale`
+ *   2. a theme-registered builder for the language-only `type:<lang>` (e.g. es-AR → es)
+ *   3. a theme-registered builder for `type:*` (locale-agnostic override)
+ *   4. the core baseline builder for that type (locale-aware ES/EN copy)
+ *
+ * The registry lives on globalThis so it survives Next.js HMR module reloads in
+ * dev — same pattern as the scheduled-actions registry.
+ */
+import type { SecurityEventType, SecurityEmailTemplateBuilder } from './types';
+/**
+ * Register (or override) a security-email template for a `(type, locale)` pair.
+ *
+ * Themes call this from their bootstrap to brand/translate the built-in security
+ * emails without forking core. Pass `'*'` as the locale to override a type for
+ * every locale.
+ *
+ * @example
+ * registerSecurityEmailTemplate('newDeviceLogin', 'es', (ctx) => ({
+ *   subject: `🔐 Nuevo inicio de sesión en ${ctx.appName}`,
+ *   html: renderBranding(ctx),
+ * }))
+ */
+export declare function registerSecurityEmailTemplate(type: SecurityEventType, locale: string, builder: SecurityEmailTemplateBuilder): void;
+/**
+ * Resolve the effective builder for a `(type, locale)`, applying the fallback
+ * chain described at the top of the file. Always returns a builder (baseline is
+ * guaranteed to exist for every SecurityEventType).
+ */
+export declare function getSecurityEmailTemplate(type: SecurityEventType, locale: string): SecurityEmailTemplateBuilder;
+/** Test helper: drop all theme-registered overrides (baseline is untouched). */
+export declare function clearSecurityEmailTemplates(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/lib/auth/security-notifications/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/security-notifications/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,4BAA4B,EAC7B,MAAM,SAAS,CAAA;AAuBhB;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,4BAA4B,GACpC,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,GACb,4BAA4B,CAS9B;AAED,gFAAgF;AAChF,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/lib/auth/security-notifications/registry.js

@@ -0,0 +1,26 @@
+import newDeviceLogin from "./templates/new-device-login.js";
+import passwordChanged from "./templates/password-changed.js";
+import emailChanged from "./templates/email-changed.js";
+const BASELINE = {
+  newDeviceLogin,
+  passwordChanged,
+  emailChanged
+};
+const globalForTemplates = globalThis;
+const templateRegistry = globalForTemplates.__securityEmailTemplates ??= /* @__PURE__ */ new Map();
+const key = (type, locale) => `${type}:${locale}`;
+function registerSecurityEmailTemplate(type, locale, builder) {
+  templateRegistry.set(key(type, locale), builder);
+}
+function getSecurityEmailTemplate(type, locale) {
+  const lang = (locale || "").split("-")[0];
+  return templateRegistry.get(key(type, locale)) ?? (lang && lang !== locale ? templateRegistry.get(key(type, lang)) : void 0) ?? templateRegistry.get(key(type, "*")) ?? BASELINE[type];
+}
+function clearSecurityEmailTemplates() {
+  templateRegistry.clear();
+}
+export {
+  clearSecurityEmailTemplates,
+  getSecurityEmailTemplate,
+  registerSecurityEmailTemplate
+};

package/dist/lib/auth/security-notifications/templates/email-changed.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Baseline "email changed" security email (ES/EN).
+ *
+ * IMPORTANT: this notification is sent to the OLD address — it is the account
+ * owner's last chance to notice (and react to) an attacker moving the account to
+ * a new email. The new address will get Better Auth's own verification flow.
+ *
+ * Overridable per (type, locale) via registerSecurityEmailTemplate.
+ */
+import type { SecurityEmailContext, SecurityEmailContent } from '../types';
+export default function emailChanged(ctx: SecurityEmailContext): SecurityEmailContent;
+//# sourceMappingURL=email-changed.d.ts.map

package/dist/lib/auth/security-notifications/templates/email-changed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-changed.d.ts","sourceRoot":"","sources":["../../../../../src/lib/auth/security-notifications/templates/email-changed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AA+B1E,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,CAkBpF"}

package/dist/lib/auth/security-notifications/templates/email-changed.js

@@ -0,0 +1,43 @@
+import { baseLayout, content, detailRows, escapeHtml, resolveBaselineLocale } from "./shared.js";
+const COPY = {
+  en: {
+    subject: (app) => `Your ${app} email address is being changed`,
+    heading: "Email address change requested",
+    greeting: (name) => `Hi${name ? ` ${name}` : ""},`,
+    intro: (app) => `We received a request to change the email address on your ${app} account.`,
+    newLabel: "New email",
+    whenLabel: "When",
+    reassurance: "If you requested this, you can ignore this message. If you did NOT request it, contact support immediately \u2014 this email address may still control the account until the change is confirmed.",
+    footer: (app) => `This is an automated security email from ${app}, sent to your current address.`
+  },
+  es: {
+    subject: (app) => `Se est\xE1 cambiando el correo de tu cuenta de ${app}`,
+    heading: "Solicitud de cambio de correo",
+    greeting: (name) => `Hola${name ? ` ${name}` : ""},`,
+    intro: (app) => `Recibimos una solicitud para cambiar la direcci\xF3n de correo de tu cuenta de ${app}.`,
+    newLabel: "Nuevo correo",
+    whenLabel: "Fecha",
+    reassurance: "Si vos lo solicitaste, pod\xE9s ignorar este mensaje. Si NO lo solicitaste, contact\xE1 a soporte de inmediato: esta direcci\xF3n todav\xEDa puede controlar la cuenta hasta que se confirme el cambio.",
+    footer: (app) => `Este es un correo de seguridad autom\xE1tico de ${app}, enviado a tu direcci\xF3n actual.`
+  }
+};
+function emailChanged(ctx) {
+  const t = COPY[resolveBaselineLocale(ctx.locale)];
+  const app = ctx.appName;
+  const bodyHtml = `
+    <p style="color:#374151;font-size:15px;line-height:1.6;margin:0 0 12px 0;">${escapeHtml(t.greeting(ctx.userName))}</p>
+    <p style="color:#374151;font-size:15px;line-height:1.6;margin:0 0 8px 0;">${escapeHtml(t.intro(app))}</p>
+    ${detailRows([
+    { label: t.newLabel, value: ctx.newEmail },
+    { label: t.whenLabel, value: ctx.occurredAt }
+  ])}
+    <p style="color:#b45309;font-size:14px;line-height:1.6;margin:0;">${escapeHtml(t.reassurance)}</p>
+  `;
+  return content(
+    t.subject(app),
+    baseLayout({ appName: app, heading: t.heading, bodyHtml, footer: t.footer(app) })
+  );
+}
+export {
+  emailChanged as default
+};

package/dist/lib/auth/security-notifications/templates/new-device-login.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Baseline "new device login" security email (ES/EN).
+ * Overridable per (type, locale) via registerSecurityEmailTemplate.
+ */
+import type { SecurityEmailContext, SecurityEmailContent } from '../types';
+export default function newDeviceLogin(ctx: SecurityEmailContext): SecurityEmailContent;
+//# sourceMappingURL=new-device-login.d.ts.map

package/dist/lib/auth/security-notifications/templates/new-device-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-device-login.d.ts","sourceRoot":"","sources":["../../../../../src/lib/auth/security-notifications/templates/new-device-login.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAgC1E,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,CAmBtF"}

package/dist/lib/auth/security-notifications/templates/new-device-login.js

@@ -0,0 +1,46 @@
+import { baseLayout, content, detailRows, escapeHtml, resolveBaselineLocale } from "./shared.js";
+const COPY = {
+  en: {
+    subject: (app) => `New sign-in to your ${app} account`,
+    heading: "New device sign-in",
+    greeting: (name) => `Hi${name ? ` ${name}` : ""},`,
+    intro: (app) => `We noticed a sign-in to your ${app} account from a device or location we haven't seen before.`,
+    ipLabel: "IP address",
+    deviceLabel: "Device",
+    whenLabel: "When",
+    reassurance: "If this was you, you can safely ignore this email. If you don't recognize this activity, change your password immediately.",
+    footer: (app) => `This is an automated security email from ${app}.`
+  },
+  es: {
+    subject: (app) => `Nuevo inicio de sesi\xF3n en tu cuenta de ${app}`,
+    heading: "Inicio de sesi\xF3n desde un nuevo dispositivo",
+    greeting: (name) => `Hola${name ? ` ${name}` : ""},`,
+    intro: (app) => `Detectamos un inicio de sesi\xF3n en tu cuenta de ${app} desde un dispositivo o ubicaci\xF3n que no hab\xEDamos visto antes.`,
+    ipLabel: "Direcci\xF3n IP",
+    deviceLabel: "Dispositivo",
+    whenLabel: "Fecha",
+    reassurance: "Si fuiste vos, pod\xE9s ignorar este correo. Si no reconoc\xE9s esta actividad, cambi\xE1 tu contrase\xF1a de inmediato.",
+    footer: (app) => `Este es un correo de seguridad autom\xE1tico de ${app}.`
+  }
+};
+function newDeviceLogin(ctx) {
+  const t = COPY[resolveBaselineLocale(ctx.locale)];
+  const app = ctx.appName;
+  const bodyHtml = `
+    <p style="color:#374151;font-size:15px;line-height:1.6;margin:0 0 12px 0;">${escapeHtml(t.greeting(ctx.userName))}</p>
+    <p style="color:#374151;font-size:15px;line-height:1.6;margin:0 0 8px 0;">${escapeHtml(t.intro(app))}</p>
+    ${detailRows([
+    { label: t.deviceLabel, value: ctx.userAgent },
+    { label: t.ipLabel, value: ctx.ipAddress },
+    { label: t.whenLabel, value: ctx.occurredAt }
+  ])}
+    <p style="color:#b45309;font-size:14px;line-height:1.6;margin:0;">${escapeHtml(t.reassurance)}</p>
+  `;
+  return content(
+    t.subject(app),
+    baseLayout({ appName: app, heading: t.heading, bodyHtml, footer: t.footer(app) })
+  );
+}
+export {
+  newDeviceLogin as default
+};

package/dist/lib/auth/security-notifications/templates/password-changed.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Baseline "password changed" security email (ES/EN).
+ * Overridable per (type, locale) via registerSecurityEmailTemplate.
+ */
+import type { SecurityEmailContext, SecurityEmailContent } from '../types';
+export default function passwordChanged(ctx: SecurityEmailContext): SecurityEmailContent;
+//# sourceMappingURL=password-changed.d.ts.map

package/dist/lib/auth/security-notifications/templates/password-changed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-changed.d.ts","sourceRoot":"","sources":["../../../../../src/lib/auth/security-notifications/templates/password-changed.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAwB1E,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,CAcvF"}

package/dist/lib/auth/security-notifications/templates/password-changed.js

@@ -0,0 +1,35 @@
+import { baseLayout, content, escapeHtml, resolveBaselineLocale } from "./shared.js";
+const COPY = {
+  en: {
+    subject: (app) => `Your ${app} password was changed`,
+    heading: "Password changed",
+    greeting: (name) => `Hi${name ? ` ${name}` : ""},`,
+    intro: (app) => `The password for your ${app} account was just changed.`,
+    reassurance: "If you made this change, no action is needed. If you did NOT change your password, reset it immediately and contact support.",
+    footer: (app) => `This is an automated security email from ${app}.`
+  },
+  es: {
+    subject: (app) => `Se cambi\xF3 la contrase\xF1a de tu cuenta de ${app}`,
+    heading: "Contrase\xF1a actualizada",
+    greeting: (name) => `Hola${name ? ` ${name}` : ""},`,
+    intro: (app) => `La contrase\xF1a de tu cuenta de ${app} se acaba de cambiar.`,
+    reassurance: "Si hiciste este cambio, no necesit\xE1s hacer nada. Si NO cambiaste tu contrase\xF1a, restablecela de inmediato y contact\xE1 a soporte.",
+    footer: (app) => `Este es un correo de seguridad autom\xE1tico de ${app}.`
+  }
+};
+function passwordChanged(ctx) {
+  const t = COPY[resolveBaselineLocale(ctx.locale)];
+  const app = ctx.appName;
+  const bodyHtml = `
+    <p style="color:#374151;font-size:15px;line-height:1.6;margin:0 0 12px 0;">${escapeHtml(t.greeting(ctx.userName))}</p>
+    <p style="color:#374151;font-size:15px;line-height:1.6;margin:0 0 16px 0;">${escapeHtml(t.intro(app))}</p>
+    <p style="color:#b45309;font-size:14px;line-height:1.6;margin:0;">${escapeHtml(t.reassurance)}</p>
+  `;
+  return content(
+    t.subject(app),
+    baseLayout({ appName: app, heading: t.heading, bodyHtml, footer: t.footer(app) })
+  );
+}
+export {
+  passwordChanged as default
+};

package/dist/lib/auth/security-notifications/templates/shared.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared helpers for the baseline security-email templates.
+ *
+ * The baseline templates ship self-contained ES/EN copy (no next-intl
+ * dependency) so they render correctly inside the scheduled-action worker with
+ * zero i18n wiring, and so unit tests stay hermetic. Themes that want full
+ * branding or additional locales register their own builders via
+ * `registerSecurityEmailTemplate(type, locale, builder)` — those take
+ * precedence over everything here.
+ */
+import type { SecurityEmailContent } from '../types';
+/** Locales the baseline copy is written in. Anything else falls back to 'en'. */
+export type BaselineLocale = 'es' | 'en';
+/** Map any BCP47 locale to the closest baseline locale ('es' or 'en'). */
+export declare function resolveBaselineLocale(locale: string | undefined): BaselineLocale;
+/** Escape a value for safe interpolation into HTML text/attributes. */
+export declare function escapeHtml(value: string | undefined | null): string;
+/**
+ * Wrap body content in a minimal, email-client-safe HTML shell. Kept intentionally
+ * plain (no gradients/branding) — this is the neutral baseline; themes override
+ * for a branded look.
+ */
+export declare function baseLayout(params: {
+    appName: string;
+    heading: string;
+    bodyHtml: string;
+    footer: string;
+}): string;
+/** Render a labeled detail row block (used by the new-device email). */
+export declare function detailRows(rows: Array<{
+    label: string;
+    value: string | undefined;
+}>): string;
+/** Build a `SecurityEmailContent` with an auto-derived plain-text fallback. */
+export declare function content(subject: string, html: string, text?: string): SecurityEmailContent;
+//# sourceMappingURL=shared.d.ts.map

package/dist/lib/auth/security-notifications/templates/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../../src/lib/auth/security-notifications/templates/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAEpD,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,CAAA;AAExC,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAEhF;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAQnE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,MAAM,CAuCT;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,GAAG,MAAM,CAc5F;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAE1F"}

package/dist/lib/auth/security-notifications/templates/shared.js

@@ -0,0 +1,68 @@
+function resolveBaselineLocale(locale) {
+  return (locale || "").toLowerCase().startsWith("es") ? "es" : "en";
+}
+function escapeHtml(value) {
+  if (value == null) return "";
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function baseLayout(params) {
+  const { appName, heading, bodyHtml, footer } = params;
+  const year = (/* @__PURE__ */ new Date()).getFullYear();
+  return `<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  </head>
+  <body style="margin:0;padding:0;font-family:'Segoe UI',Tahoma,Geneva,Verdana,sans-serif;background-color:#f4f4f4;">
+    <table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0">
+      <tr>
+        <td align="center" style="padding:40px 0;">
+          <table role="presentation" width="600" cellspacing="0" cellpadding="0" border="0" style="background-color:#ffffff;border-radius:8px;box-shadow:0 2px 4px rgba(0,0,0,0.08);">
+            <tr>
+              <td style="padding:32px 40px 8px 40px;">
+                <h1 style="color:#111827;font-size:20px;margin:0;font-weight:600;">${escapeHtml(appName)}</h1>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:8px 40px 24px 40px;">
+                <h2 style="color:#111827;font-size:22px;margin:0 0 16px 0;font-weight:600;">${escapeHtml(heading)}</h2>
+                ${bodyHtml}
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:16px 40px 32px 40px;border-top:1px solid #eee;">
+                <p style="color:#9ca3af;font-size:12px;line-height:1.5;margin:16px 0 0 0;">
+                  ${escapeHtml(footer)}<br>
+                  &copy; ${year} ${escapeHtml(appName)}.
+                </p>
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>`;
+}
+function detailRows(rows) {
+  const cells = rows.filter((r) => r.value).map(
+    (r) => `<tr><td style="color:#6b7280;font-size:14px;padding:4px 12px 4px 0;">${escapeHtml(
+      r.label
+    )}</td><td style="color:#111827;font-size:14px;padding:4px 0;">${escapeHtml(
+      r.value
+    )}</td></tr>`
+  ).join("");
+  if (!cells) return "";
+  return `<table role="presentation" cellspacing="0" cellpadding="0" border="0" style="margin:8px 0 24px 0;background:#f9fafb;border-radius:6px;padding:8px 16px;">${cells}</table>`;
+}
+function content(subject, html, text) {
+  return { subject, html, text: text ?? subject };
+}
+export {
+  baseLayout,
+  content,
+  detailRows,
+  escapeHtml,
+  resolveBaselineLocale
+};

package/dist/lib/auth/security-notifications/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Security Notifications — shared types.
+ *
+ * Built-in security email notifications for three scenarios Better Auth does
+ * not cover out of the box (issue #75):
+ *   - new-device login alerts
+ *   - password-changed confirmation
+ *   - email-changed notification (sent to the OLD address)
+ */
+/**
+ * The three security events. Keys match `AUTH_CONFIG.securityNotifications.events`
+ * so a single key toggles both the config flag and the template lookup.
+ */
+export type SecurityEventType = 'newDeviceLogin' | 'passwordChanged' | 'emailChanged';
+/**
+ * Context passed to a template builder. `appName` is always present; the rest is
+ * event-specific and best-effort (any field may be undefined if it could not be
+ * resolved from the request/response without leaking user-existence info).
+ */
+export interface SecurityEmailContext {
+    /** Event this email is for. */
+    type: SecurityEventType;
+    /** Resolved locale (BCP47) used to pick copy; falls back to the app default. */
+    locale: string;
+    /** Display name of the application (NEXT_PUBLIC_APP_NAME or config). */
+    appName: string;
+    /** The user's display name / first name, when known. */
+    userName?: string;
+    /** Recipient email address (the OLD address for `emailChanged`). */
+    email?: string;
+    /** New device sign-in metadata (newDeviceLogin only). */
+    ipAddress?: string;
+    userAgent?: string;
+    /** When the event happened (ISO string), for display in the email body. */
+    occurredAt?: string;
+    /** For emailChanged: the address the account is being moved TO. */
+    newEmail?: string;
+}
+/** What a template builder returns. `text` is an optional plain-text fallback. */
+export interface SecurityEmailContent {
+    subject: string;
+    html: string;
+    text?: string;
+}
+/**
+ * A template builder turns a context into rendered email content. Themes register
+ * their own builders (per type + locale) via `registerSecurityEmailTemplate` to
+ * brand/translate these emails without forking core.
+ */
+export type SecurityEmailTemplateBuilder = (ctx: SecurityEmailContext) => SecurityEmailContent | Promise<SecurityEmailContent>;
+/**
+ * Payload persisted on the `auth:security-notification` scheduled action. Kept to
+ * plain references + already-resolved display data (never secrets): the handler
+ * only needs it to render and send the email.
+ */
+export interface SecurityNotificationActionPayload {
+    type: SecurityEventType;
+    locale: string;
+    appName: string;
+    /** Recipient (OLD address for emailChanged). */
+    to: string;
+    userName?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    occurredAt?: string;
+    newEmail?: string;
+    /**
+     * Dedup discriminator so scheduleAction() collapses rapid duplicates of the
+     * same (user, event). Present for the scheduler's entityId-based dedup only.
+     */
+    entityId?: string;
+    entityType?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/auth/security-notifications/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/security-notifications/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,CAAA;AAElB;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,IAAI,EAAE,iBAAiB,CAAA;IACvB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG,CACzC,GAAG,EAAE,oBAAoB,KACtB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAEzD;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD,IAAI,EAAE,iBAAiB,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}