@fonderie/auth 5.0.0 → 5.0.1

package/dist/index.d.cts

@@ -2,8 +2,8 @@ export { IMfaChallenge, ISession, IUser } from './types.cjs';
 import { IFonderieModule, IReadinessProblem, IFonderieApp } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
 import { EventBus } from '@fonderie/events';
-import { I as IAuthConfig } from './session-DxsmQjXX.cjs';
-export { A as AUTH_CONFIG_KEYS, a as AuthLimitedRoute, b as AuthMessageKey, c as IAuthRateLimitConfig, d as IAuthRuntimeConfig, e as IAuthSecrets, M as MESSAGE_KEYS, f as buildAuthAccountLimiter, g as buildAuthIpLimiter, w as withSession } from './session-DxsmQjXX.cjs';
+import { I as IAuthConfig } from './session-CTSCI09F.cjs';
+export { A as AUTH_CONFIG_KEYS, a as AuthLimitedRoute, b as AuthMessageKey, c as IAuthRateLimitConfig, d as IAuthRuntimeConfig, e as IAuthSecrets, f as IDataExportContributor, M as MESSAGE_KEYS, g as buildAuthAccountLimiter, h as buildAuthIpLimiter, w as withSession } from './session-CTSCI09F.cjs';
 export { IUserDTO, toUserDTO } from './dtos/user.cjs';
 export { requireAuth, validate } from '@fonderie/core/middlewares';
 import { z } from 'zod';
@@ -54,10 +54,15 @@ declare const updateProfileSchema: z.ZodObject<{
 declare const updatePreferencesSchema: z.ZodObject<{
     locale: z.ZodOptional<z.ZodString>;
     timezone: z.ZodOptional<z.ZodString>;
-    notifications: z.ZodOptional<z.ZodUnknown>;
-    emailDigest: z.ZodOptional<z.ZodUnknown>;
-    dateFormat: z.ZodOptional<z.ZodUnknown>;
-    timeFormat: z.ZodOptional<z.ZodUnknown>;
+    notifications: z.ZodOptional<z.ZodObject<{
+        email: z.ZodOptional<z.ZodBoolean>;
+        inApp: z.ZodOptional<z.ZodBoolean>;
+        sms: z.ZodOptional<z.ZodBoolean>;
+        push: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    emailDigest: z.ZodOptional<z.ZodString>;
+    dateFormat: z.ZodOptional<z.ZodString>;
+    timeFormat: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const updateEmailSchema: z.ZodObject<{
     email: z.ZodPipe<z.ZodString, z.ZodEmail>;
@@ -118,6 +123,18 @@ declare function importUser(store: IStoreAdapter, user: IImportUser): Promise<{
     id: string;
 }>;
 
+interface IPurgeOptions {
+    olderThanDays: number;
+}
+declare function purgeSoftDeletedUsers(store: IStoreAdapter, { olderThanDays }: IPurgeOptions): Promise<number>;
+interface IUserRetentionScheduleOptions extends IPurgeOptions {
+    intervalMs?: number;
+    onPurge?: (deleted: number) => void;
+}
+declare function startUserRetention(store: IStoreAdapter, options: IUserRetentionScheduleOptions): {
+    stop: () => void;
+};
+
 declare function validateAuthConfig(config: IAuthConfig): void;
 
-export { AuthModule, type ChangePasswordInput, IAuthConfig, type IImportUser, type LoginInput, type RegisterInput, type ResetPasswordInput, importUser, normalizeEmail, normalizeEmailSafe, schemas, validateAuthConfig };
+export { AuthModule, type ChangePasswordInput, IAuthConfig, type IImportUser, type IPurgeOptions, type IUserRetentionScheduleOptions, type LoginInput, type RegisterInput, type ResetPasswordInput, importUser, normalizeEmail, normalizeEmailSafe, purgeSoftDeletedUsers, schemas, startUserRetention, validateAuthConfig };

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { IMfaChallenge, ISession, IUser } from './types.js';
 import { IFonderieModule, IReadinessProblem, IFonderieApp } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
 import { EventBus } from '@fonderie/events';
-import { I as IAuthConfig } from './session-DxsmQjXX.js';
-export { A as AUTH_CONFIG_KEYS, a as AuthLimitedRoute, b as AuthMessageKey, c as IAuthRateLimitConfig, d as IAuthRuntimeConfig, e as IAuthSecrets, M as MESSAGE_KEYS, f as buildAuthAccountLimiter, g as buildAuthIpLimiter, w as withSession } from './session-DxsmQjXX.js';
+import { I as IAuthConfig } from './session-CTSCI09F.js';
+export { A as AUTH_CONFIG_KEYS, a as AuthLimitedRoute, b as AuthMessageKey, c as IAuthRateLimitConfig, d as IAuthRuntimeConfig, e as IAuthSecrets, f as IDataExportContributor, M as MESSAGE_KEYS, g as buildAuthAccountLimiter, h as buildAuthIpLimiter, w as withSession } from './session-CTSCI09F.js';
 export { IUserDTO, toUserDTO } from './dtos/user.js';
 export { requireAuth, validate } from '@fonderie/core/middlewares';
 import { z } from 'zod';
@@ -54,10 +54,15 @@ declare const updateProfileSchema: z.ZodObject<{
 declare const updatePreferencesSchema: z.ZodObject<{
     locale: z.ZodOptional<z.ZodString>;
     timezone: z.ZodOptional<z.ZodString>;
-    notifications: z.ZodOptional<z.ZodUnknown>;
-    emailDigest: z.ZodOptional<z.ZodUnknown>;
-    dateFormat: z.ZodOptional<z.ZodUnknown>;
-    timeFormat: z.ZodOptional<z.ZodUnknown>;
+    notifications: z.ZodOptional<z.ZodObject<{
+        email: z.ZodOptional<z.ZodBoolean>;
+        inApp: z.ZodOptional<z.ZodBoolean>;
+        sms: z.ZodOptional<z.ZodBoolean>;
+        push: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    emailDigest: z.ZodOptional<z.ZodString>;
+    dateFormat: z.ZodOptional<z.ZodString>;
+    timeFormat: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const updateEmailSchema: z.ZodObject<{
     email: z.ZodPipe<z.ZodString, z.ZodEmail>;
@@ -118,6 +123,18 @@ declare function importUser(store: IStoreAdapter, user: IImportUser): Promise<{
     id: string;
 }>;
 
+interface IPurgeOptions {
+    olderThanDays: number;
+}
+declare function purgeSoftDeletedUsers(store: IStoreAdapter, { olderThanDays }: IPurgeOptions): Promise<number>;
+interface IUserRetentionScheduleOptions extends IPurgeOptions {
+    intervalMs?: number;
+    onPurge?: (deleted: number) => void;
+}
+declare function startUserRetention(store: IStoreAdapter, options: IUserRetentionScheduleOptions): {
+    stop: () => void;
+};
+
 declare function validateAuthConfig(config: IAuthConfig): void;
 
-export { AuthModule, type ChangePasswordInput, IAuthConfig, type IImportUser, type LoginInput, type RegisterInput, type ResetPasswordInput, importUser, normalizeEmail, normalizeEmailSafe, schemas, validateAuthConfig };
+export { AuthModule, type ChangePasswordInput, IAuthConfig, type IImportUser, type IPurgeOptions, type IUserRetentionScheduleOptions, type LoginInput, type RegisterInput, type ResetPasswordInput, importUser, normalizeEmail, normalizeEmailSafe, purgeSoftDeletedUsers, schemas, startUserRetention, validateAuthConfig };

package/dist/index.js

@@ -165,10 +165,18 @@ var updateProfileSchema = z.object({
 var updatePreferencesSchema = z.object({
   locale: z.string().max(35).optional(),
   timezone: z.string().max(64).optional(),
-  notifications: z.unknown().optional(),
-  emailDigest: z.unknown().optional(),
-  dateFormat: z.unknown().optional(),
-  timeFormat: z.unknown().optional()
+  // Typed at last — these four accepted `unknown`, letting null and
+  // arbitrary JSON into stored preferences that the user DTO then served
+  // against string-typed client fields.
+  notifications: z.object({
+    email: z.boolean().optional(),
+    inApp: z.boolean().optional(),
+    sms: z.boolean().optional(),
+    push: z.boolean().optional()
+  }).optional(),
+  emailDigest: z.string().max(20).optional(),
+  dateFormat: z.string().max(30).optional(),
+  timeFormat: z.string().max(30).optional()
 }).refine(
   (o) => Object.values(o).some((v) => v !== void 0),
   "Provide at least one preference field"
@@ -284,7 +292,7 @@ function verifyToken(token, config) {
 }
 
 // src/services/mfa.ts
-import { createHmac, randomBytes } from "crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
 var STEP = 30;
 var DRIFT = 1;
 var DIGITS = 6;
@@ -355,10 +363,16 @@ function generateTotpUri(email2, secret, issuer) {
   });
   return `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(email2)}?${params}`;
 }
+function safeCodeEqual(a, b) {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
 function verifyTotpToken(token, secret) {
   const t = timeCounter();
   for (let i = -DRIFT; i <= DRIFT; i++) {
-    if (hotp(secret, t + i) === token) {
+    if (safeCodeEqual(hotp(secret, t + i), token)) {
       return true;
     }
   }
@@ -371,6 +385,41 @@ function generateBackupCodes(count = 8) {
 // src/controllers/mfa.controller.ts
 init_password();
 
+// src/services/mfa-crypto.ts
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2 } from "crypto";
+var PREFIX = "mfa.v1:";
+function makeMfaCipher(keyHex) {
+  if (!keyHex) {
+    return { encrypt: (plain) => plain, decrypt: (stored) => stored };
+  }
+  const key = Buffer.from(keyHex, "hex");
+  if (key.length !== 32) {
+    throw new Error("[auth] mfaSecretKey must be 32 bytes (64 hex chars, e.g. `openssl rand -hex 32`)");
+  }
+  return {
+    encrypt(plain) {
+      const iv = randomBytes2(12);
+      const cipher = createCipheriv("aes-256-gcm", key, iv);
+      const enc = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+      const tag = cipher.getAuthTag();
+      return `${PREFIX}${iv.toString("hex")}:${tag.toString("hex")}:${enc.toString("hex")}`;
+    },
+    decrypt(stored) {
+      if (!stored.startsWith(PREFIX)) return stored;
+      const [ivHex, tagHex, dataHex] = stored.slice(PREFIX.length).split(":");
+      if (!ivHex || !tagHex || !dataHex) {
+        throw new Error("[auth] malformed mfa secret ciphertext");
+      }
+      const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(ivHex, "hex"));
+      decipher.setAuthTag(Buffer.from(tagHex, "hex"));
+      return Buffer.concat([
+        decipher.update(Buffer.from(dataHex, "hex")),
+        decipher.final()
+      ]).toString("utf8");
+    }
+  };
+}
+
 // src/dtos/user.ts
 import { stringOrEmpty, booleanOrFalse } from "@fonderie/core";
 var DEFAULT_PREFERENCES = {
@@ -381,8 +430,27 @@ var DEFAULT_PREFERENCES = {
   dateFormat: "MM/DD/YYYY",
   timeFormat: "hh:mm A"
 };
+function cleanPreferences(prefs) {
+  const out = {};
+  if (typeof prefs.locale === "string") out.locale = prefs.locale;
+  if (typeof prefs.timezone === "string") out.timezone = prefs.timezone;
+  if (typeof prefs.emailDigest === "string") out.emailDigest = prefs.emailDigest;
+  if (typeof prefs.dateFormat === "string") out.dateFormat = prefs.dateFormat;
+  if (typeof prefs.timeFormat === "string") out.timeFormat = prefs.timeFormat;
+  return out;
+}
+function cleanNotifications(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const key of ["email", "inApp", "sms", "push"]) {
+    const v = value[key];
+    if (typeof v === "boolean") out[key] = v;
+  }
+  return out;
+}
 function toUserDTO(user, phoneVerified = false) {
   const prefs = user.preferences ?? {};
+  const cleaned = cleanPreferences(prefs);
   return {
     id: stringOrEmpty(user.id),
     email: stringOrEmpty(user.email),
@@ -394,9 +462,13 @@ function toUserDTO(user, phoneVerified = false) {
     lastLogin: user.lastLogin instanceof Date ? user.lastLogin.toISOString() : "",
     preferences: {
       ...DEFAULT_PREFERENCES,
-      ...prefs,
-      locale: user.locale || prefs.locale || "en-US",
-      timezone: user.timezone || prefs.timezone || "UTC"
+      ...cleaned,
+      notifications: {
+        ...DEFAULT_PREFERENCES.notifications,
+        ...cleanNotifications(prefs.notifications)
+      },
+      locale: user.locale || cleaned.locale || "en-US",
+      timezone: user.timezone || cleaned.timezone || "UTC"
     },
     isEmailVerified: user.emailVerifiedAt !== null,
     isPhoneVerified: phoneVerified,
@@ -427,7 +499,6 @@ var USER_COLUMNS = `
 	whitelist,
 	ip_whitelist       AS "ipWhitelist",
 	mfa_enabled        AS "mfaEnabled",
-	mfa_secret         AS "mfaSecret",
 	email_verified_at  AS "emailVerifiedAt",
 	deleted_at         AS "deletedAt",
 	created_at         AS "createdAt",
@@ -636,6 +707,25 @@ var SessionModel = class {
   async delete(token) {
     await this.store.query(`DELETE FROM fonderie_sessions WHERE token = $1`, [token]);
   }
+  // Revoke every session for a user (e.g. on password change). Access tokens
+  // bound to these sessions via the sid claim die on their next request.
+  async deleteByUser(userId) {
+    await this.store.query(`DELETE FROM fonderie_sessions WHERE user_id = $1`, [userId]);
+  }
+  // Session metadata for a user (no tokens) — for the data-export / SAR bundle.
+  async listByUser(userId) {
+    return this.store.query(
+      `SELECT id,
+			        user_agent AS "userAgent",
+			        ip_address AS "ipAddress",
+			        created_at AS "createdAt",
+			        expires_at AS "expiresAt"
+			 FROM fonderie_sessions
+			 WHERE user_id = $1
+			 ORDER BY created_at DESC`,
+      [userId]
+    );
+  }
   async exists(token) {
     const rows = await this.store.query(
       `SELECT id FROM fonderie_sessions WHERE token = $1 AND expires_at > now()`,
@@ -693,6 +783,7 @@ function mfaController(store, config, issuer, bus) {
   const users = new UserModel(store);
   const sessions = new SessionModel(store);
   const backupCodes = new BackupCodeModel(store);
+  const mfaCipher = makeMfaCipher(config.mfaSecretKey);
   return {
     // ── 1. Setup ───────────────────────────────────────────────
     setup: async (ctx) => {
@@ -702,7 +793,7 @@ function mfaController(store, config, issuer, bus) {
       const codeHashes = await Promise.all(plainCodes.map((c) => hashPassword(c)));
       const qr = await QRCode.toDataURL(uri);
       await Promise.all([
-        users.saveMfaPendingSecret(ctx.user.id, secret),
+        users.saveMfaPendingSecret(ctx.user.id, mfaCipher.encrypt(secret)),
         backupCodes.replace(ctx.user.id, codeHashes)
       ]);
       return setApiResponse2(
@@ -724,7 +815,8 @@ function mfaController(store, config, issuer, bus) {
       if (typeof token !== "string") {
         return setApiResponse2(HTTP2.UNPROCESSABLE, "INVALID_PARAMETER", "token is required");
       }
-      const pendingSecret = await users.getMfaPendingSecret(ctx.user.id);
+      const pendingCipher = await users.getMfaPendingSecret(ctx.user.id);
+      const pendingSecret = pendingCipher ? mfaCipher.decrypt(pendingCipher) : null;
       if (pendingSecret) {
         if (!verifyTotpToken(token, pendingSecret)) {
           return setApiResponse2(HTTP2.UNAUTHORIZED, "INVALID_CODE", "Invalid MFA token");
@@ -771,10 +863,11 @@ function mfaController(store, config, issuer, bus) {
             "Use the mfaToken from the login response"
           );
         }
-        const secret = await users.getMfaSecret(ctx.user.id);
-        if (!secret) {
+        const storedSecret = await users.getMfaSecret(ctx.user.id);
+        if (!storedSecret) {
           return setApiResponse2(HTTP2.BAD_REQUEST, "MFA_NOT_CONFIGURED", "MFA not configured");
         }
+        const secret = mfaCipher.decrypt(storedSecret);
         if (!verifyTotpToken(token, secret)) {
           return setApiResponse2(HTTP2.UNAUTHORIZED, "INVALID_CODE", "Invalid MFA token");
         }
@@ -783,7 +876,8 @@ function mfaController(store, config, issuer, bus) {
         }
       }
       const { accessToken, refreshToken, sid } = issueTokenPair(ctx.user.id, config, {
-        loginMethod: ctx.user.loginMethod
+        loginMethod: ctx.user.loginMethod,
+        phoneVerified: ctx.user.phoneVerified
       });
       await sessions.create(ctx.user.id, refreshToken, refreshTokenExpiry(refreshToken), sid);
       const fullUser = await users.findById(ctx.user.id);
@@ -796,7 +890,7 @@ function mfaController(store, config, issuer, bus) {
           explanation: "MFA verified successfully.",
           result: {
             tokens: { access: accessToken, refresh: refreshToken },
-            user: toUserDTO(fullUser)
+            user: toUserDTO(fullUser, ctx.user.phoneVerified)
           }
         },
         {
@@ -815,7 +909,8 @@ function mfaController(store, config, issuer, bus) {
       if (!ctx.user.mfaEnabled) {
         return setApiResponse2(HTTP2.BAD_REQUEST, "MFA_NOT_ENABLED", "MFA is not enabled");
       }
-      const secret = await users.getMfaSecret(ctx.user.id);
+      const storedSecret = await users.getMfaSecret(ctx.user.id);
+      const secret = storedSecret ? mfaCipher.decrypt(storedSecret) : null;
       if (!secret || !verifyTotpToken(token, secret)) {
         return setApiResponse2(HTTP2.UNAUTHORIZED, "INVALID_CODE", "Invalid TOTP code");
       }
@@ -844,7 +939,8 @@ function mfaController(store, config, issuer, bus) {
       if (!user || !user.mfaEnabled) {
         return setApiResponse2(HTTP2.BAD_REQUEST, "MFA_NOT_ENABLED", "MFA is not enabled");
       }
-      const secret = user.mfaSecret;
+      const storedSecret = await users.getMfaSecret(ctx.user.id);
+      const secret = storedSecret ? mfaCipher.decrypt(storedSecret) : null;
       if (!secret || !verifyTotpToken(token, secret)) {
         return setApiResponse2(HTTP2.UNAUTHORIZED, "INVALID_CODE", "Invalid TOTP code");
       }
@@ -1629,6 +1725,7 @@ function isValidPhone2(phone2) {
 }
 function userController(store, config, bus) {
   const users = new UserModel(store);
+  const sessions = new SessionModel(store);
   const emailVerif = new EmailVerificationModel(store);
   const phoneVerif = new PhoneVerificationModel(store);
   return {
@@ -1803,6 +1900,7 @@ function userController(store, config, bus) {
       }
       const hash = await hashPassword2(newPassword);
       await users.updatePassword(ctx.user.id, hash);
+      await sessions.deleteByUser(ctx.user.id);
       return setApiResponse4(HTTP4.OK, "PASSWORD_CHANGED", "Password updated successfully.");
     },
     deleteMe: async (ctx) => {
@@ -1822,6 +1920,42 @@ function userController(store, config, bus) {
           headers: cookieHeaders(clearedTokenCookies(config))
         }
       );
+    },
+    // Subject Access Request — the authenticated user's own data as a portable
+    // JSON bundle. Only auth-owned data, and only safe fields: no password hash,
+    // no MFA secret, no session tokens (session metadata only).
+    exportMe: async (ctx) => {
+      const user = await users.findById(ctx.user.id);
+      if (!user) return setApiResponse4(HTTP4.NOT_FOUND, "NOT_FOUND", "User not found");
+      const sessionRows = await sessions.listByUser(ctx.user.id);
+      const bundle = {
+        exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        profile: toUserDTO(user, ctx.user.phoneVerified),
+        sessions: sessionRows.map((s) => ({
+          id: s.id,
+          userAgent: s.userAgent,
+          ipAddress: s.ipAddress,
+          createdAt: s.createdAt instanceof Date ? s.createdAt.toISOString() : s.createdAt,
+          expiresAt: s.expiresAt instanceof Date ? s.expiresAt.toISOString() : s.expiresAt
+        })),
+        security: {
+          mfaEnabled: user.mfaEnabled === true,
+          emailVerified: user.emailVerifiedAt !== null
+        }
+      };
+      const contributors = config.dataExportContributors ?? [];
+      if (contributors.length > 0) {
+        const modules = {};
+        for (const c of contributors) {
+          try {
+            modules[c.name] = await c.collect(ctx.user.id);
+          } catch {
+            modules[c.name] = null;
+          }
+        }
+        bundle["modules"] = modules;
+      }
+      return setApiResponse4(HTTP4.OK, "DATA_EXPORT", "Your account data.", bundle);
     }
   };
 }
@@ -1966,6 +2100,7 @@ function buildAuthRoutes(store, config, bus) {
     R("updatePhone", "PUT", "/users/phone", requireAuth, verifyGate, validate(updatePhoneSchema), user.updatePhone),
     R("changePassword", "PUT", "/users/password", requireAuth, validate(changePasswordSchema), user.changePassword),
     R("deleteMe", "DELETE", "/users", requireAuth, verifyGate, user.deleteMe),
+    R("exportMe", "GET", "/users/export", requireAuth, user.exportMe),
     // MFA (email sessions only — requireVerified is always enforced here
     // because MFA is a security feature and email verification is meaningful)
     R("mfaSetup", "POST", "/auth/mfa/setup", requireAuth, requireEmailLogin, requireVerified, mfa.setup),
@@ -2007,10 +2142,40 @@ function collectAuthConfigProblems(config) {
   if (config.secureCookies === false) {
     problems.push({
       module: MODULE,
-      severity: "warning",
+      severity: process.env["NODE_ENV"] === "production" ? "error" : "warning",
       message: "secureCookies is false \u2014 auth cookies may be sent over non-HTTPS connections in production"
     });
   }
+  if (config.google) {
+    const clientSecret = config.google.clientSecret ?? "";
+    if (!clientSecret || !config.google.clientId || !config.google.redirectUri) {
+      problems.push({
+        module: MODULE,
+        severity: "error",
+        message: "google OAuth is configured but clientId, clientSecret, or redirectUri is missing"
+      });
+    } else if (PLACEHOLDER_SECRET.test(clientSecret)) {
+      problems.push({
+        module: MODULE,
+        severity: "error",
+        message: "google.clientSecret looks like a placeholder or dev-default value"
+      });
+    }
+  }
+  if (config.mfa && !config.mfaSecretKey) {
+    problems.push({
+      module: MODULE,
+      severity: process.env["NODE_ENV"] === "production" ? "error" : "warning",
+      message: "mfa is enabled without mfaSecretKey \u2014 TOTP secrets are stored plaintext at rest; set a 32-byte key (openssl rand -hex 32)"
+    });
+  }
+  if (config.mfaSecretKey && !/^[0-9a-fA-F]{64}$/.test(config.mfaSecretKey)) {
+    problems.push({
+      module: MODULE,
+      severity: "error",
+      message: "mfaSecretKey must be 64 hex characters (32 bytes, e.g. `openssl rand -hex 32`)"
+    });
+  }
   return problems;
 }
 function validateAuthConfig(config) {
@@ -2131,6 +2296,41 @@ async function importUser(store, user) {
   if (!row) throw new Error("[auth] importUser: insert returned no row");
   return row;
 }
+
+// src/services/retention.ts
+async function purgeSoftDeletedUsers(store, { olderThanDays }) {
+  if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+    throw new Error("[auth] purgeSoftDeletedUsers: olderThanDays must be a non-negative number");
+  }
+  const rows = await store.query(
+    `DELETE FROM fonderie_users
+		 WHERE deleted_at IS NOT NULL
+		   AND deleted_at < now() - make_interval(days => $1)
+		 RETURNING id`,
+    [olderThanDays]
+  );
+  return rows.length;
+}
+function startUserRetention(store, options) {
+  const intervalMs = options.intervalMs ?? 24 * 60 * 60 * 1e3;
+  let stopped = false;
+  const run = async () => {
+    if (stopped) return;
+    try {
+      const deleted = await purgeSoftDeletedUsers(store, { olderThanDays: options.olderThanDays });
+      options.onPurge?.(deleted);
+    } catch (err) {
+      console.error("[auth] scheduled user retention purge failed:", err);
+    }
+  };
+  const timer = setInterval(run, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  void run();
+  return { stop: () => {
+    stopped = true;
+    clearInterval(timer);
+  } };
+}
 export {
   AUTH_CONFIG_KEYS,
   AuthModule,
@@ -2140,8 +2340,10 @@ export {
   importUser,
   normalizeEmail,
   normalizeEmailSafe,
+  purgeSoftDeletedUsers,
   requireAuth2 as requireAuth,
   schemas_exports as schemas,
+  startUserRetention,
   toUserDTO,
   validate,
   validateAuthConfig,