@fonderie/auth 7.9.3 → 7.10.0

package/README.md

@@ -14,10 +14,17 @@ npm install @fonderie/auth
 
 ```ts
 import { FonderieApp, defineConfig } from '@fonderie/core';
+import { PGAdapter } from '@fonderie/store';
 import { AuthModule } from '@fonderie/auth';
 
-const app = await new FonderieApp(defineConfig({}))
-  .register(new AuthModule())
+const store = new PGAdapter(process.env.DATABASE_URL!);
+
+const app = await new FonderieApp(defineConfig({ db: { url: process.env.DATABASE_URL! } }))
+  .register(new AuthModule(store, {
+    providers: ['email'],
+    appName: 'my-app',
+    jwtSecret: process.env.JWT_SECRET!,
+  }))
   .boot();
 ```
 
@@ -30,12 +37,43 @@ import { withSession, requireAuth } from '@fonderie/auth';
 Also exports `toUserDTO`, `normalizeEmail`, and the full type surface
 (`IUser`, `ISession`, `IMfaChallenge`, …).
 
+## Where did that request come from? (optional)
+
+Pass a `location` resolver and auth stamps a location on every event it
+records — each login attempt, each registration, and each new session:
+
+```ts
+import { geoFromHeaders } from '@fonderie/geo';
+
+new AuthModule(store, {
+  providers: ['email'],
+  jwtSecret: process.env.JWT_SECRET!,
+  // Vercel/Cloudflare edge headers — zero infrastructure. Trust comes from
+  // the deployment, never the request.
+  location: ({ headers }) =>
+    geoFromHeaders(headers, { trust: process.env.VERCEL ? 'vercel' : undefined }),
+});
+```
+
+Login history then includes `registration` rows alongside sign-ins, and both
+history events and active sessions carry `location: { country, subdivision,
+city, timeZone, … } | null` (plus `isp`/`asn`/`proxy`/`hosting` if your
+resolver knows them). Registration matters most when verification is not
+enforced: the account is live from that request, so it is the first record of
+where the user came from.
+
+Run your migrations: `018_login_event_location.sql` and
+`019_session_location.sql` add the columns. The resolver runs at most once per
+request; its output is sanitized and bounded (coordinates ~1 km); if it throws or takes over 500 ms the row is written without a location
+and the request is unaffected. Country is reliable; region and city are
+approximate.
+
 ## Why this exists
 
 You've shipped this plumbing before — auth, teams, billing, messaging —
 and the next project will ask for it again. Fonderie packages it once:
 plain TypeScript modules for
-[`@fonderie/core`](https://github.com/fonderiejs/sdk/tree/main/packages/core),
+[`@fonderie/core`](https://github.com/fonderiejs/fonderie/tree/main/packages/core),
 PostgreSQL-backed, self-hosted, MIT. No external control plane, no
 per-seat anything. Register the modules you need; skip the ones you don't.
 
@@ -43,7 +81,7 @@ per-seat anything. Register the modules you need; skip the ones you don't.
 other brick trusts the `ctx.user` this one establishes.
 
 Browse the whole set at
-[fonderiejs/sdk](https://github.com/fonderiejs/sdk) · follow
+[fonderiejs/fonderie](https://github.com/fonderiejs/fonderie) · follow
 [@fonderiejs](https://x.com/fonderiejs)
 
 ## License

package/brain/outcomes.md

@@ -38,6 +38,7 @@ failure_reason           TEXT
 ip_address               TEXT
 user_agent               TEXT
 created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+location                 JSONB
 ```
 
 ### `fonderie_mfa_backup_codes`
@@ -93,6 +94,7 @@ ip_address               TEXT
 expires_at               TIMESTAMPTZ NOT NULL
 created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 sid                      UUID
+location                 JSONB
 -- INDEX idx_fonderie_sessions_expires_at (expires_at)
 -- INDEX idx_fonderie_sessions_sid (sid)
 ```

package/brain/signatures.md

@@ -56,6 +56,7 @@ new AuthModule(store: IStoreAdapter, config: IAuthConfig, bus?: EventBus | undef
   .install(app: IFonderieApp): void
 
 interface IAuthConfig extends IAuthSecrets, IAuthRuntimeConfig {
+    location?: LocationResolver;
     secureCookies?: boolean;
     rateLimit?: IAuthRateLimitConfig | false;
     accessTokenDuration?: string;
@@ -139,6 +140,7 @@ interface ILoginEventDTO {
     failureReason: string | null;
     ipAddress: string | null;
     userAgent: string | null;
+    location: IRequestLocation | null;
     createdAt: string;
 }
 
@@ -152,10 +154,42 @@ interface ISessionDTO {
     current: boolean;
     ipAddress: string | null;
     userAgent: string | null;
+    location: IRequestLocation | null;
     createdAt: string;
     expiresAt: string;
 }
 
+function sanitizeLocation(input: unknown): IRequestLocation | null
+
+function resolveLocation(resolver: LocationResolver | undefined, req: ILocationRequest, timeoutMs?: number): Promise<IRequestLocation | null>
+
+interface IRequestLocation {
+    country?: string | null;
+    countryName?: string | null;
+    subdivision?: string | null;
+    subdivisionName?: string | null;
+    city?: string | null;
+    postalCode?: string | null;
+    continent?: string | null;
+    timeZone?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    accuracyRadius?: number | null;
+    isp?: string | null;
+    org?: string | null;
+    asn?: string | null;
+    mobile?: boolean | null;
+    proxy?: boolean | null;
+    hosting?: boolean | null;
+}
+
+interface ILocationRequest {
+    ip: string | null;
+    headers: Headers;
+}
+
+type LocationResolver = (req: ILocationRequest) => IRequestLocation | null | undefined | Promise<IRequestLocation | null | undefined>;
+
 function validate(schema: IRequestSchema): Middleware
 
 namespace schemas — exports: ChangePasswordInput, LoginInput, RegisterInput, ResetPasswordInput, appleNativeSchema, changePasswordSchema, forgotPasswordSchema, loginSchema, mfaTokenSchema, refreshSchema, registerSchema, resetPasswordSchema, updateEmailSchema, updatePhoneSchema, updatePreferencesSchema, updateProfileSchema, verifySchema

package/dist/index.cjs

@@ -80,6 +80,8 @@ __export(index_exports, {
   normalizeEmailSafe: () => normalizeEmailSafe,
   purgeSoftDeletedUsers: () => purgeSoftDeletedUsers,
   requireAuth: () => import_middlewares3.requireAuth,
+  resolveLocation: () => resolveLocation,
+  sanitizeLocation: () => sanitizeLocation,
   schemas: () => schemas_exports,
   startUserRetention: () => startUserRetention,
   toAdminUserDTO: () => toAdminUserDTO,
@@ -881,18 +883,106 @@ var UserModel = class {
 };
 var MAX_LIST_LIMIT = 200;
 
+// src/services/request-location.ts
+var LOCATION_TIMEOUT_MS = 500;
+var TEXT_MAX = 128;
+function str(v, re) {
+  if (typeof v !== "string") return null;
+  const t = v.trim();
+  if (t.length === 0 || t.length > TEXT_MAX) return null;
+  return re && !re.test(t) ? null : t;
+}
+function upperCode(v, re) {
+  const t = str(v, re);
+  return t ? t.toUpperCase() : null;
+}
+function bool(v) {
+  return typeof v === "boolean" ? v : null;
+}
+function coord(v, limit) {
+  if (typeof v !== "number" || !Number.isFinite(v) || Math.abs(v) > limit) return null;
+  return Math.round(v * 100) / 100;
+}
+function radius(v) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0 || v > 2e4) return null;
+  return Math.round(v);
+}
+function sanitizeLocation(input) {
+  if (!input || typeof input !== "object") return null;
+  const i = input;
+  const out = {
+    country: upperCode(i["country"], /^[A-Za-z]{2}$/),
+    countryName: str(i["countryName"]),
+    subdivision: upperCode(i["subdivision"], /^[A-Za-z0-9]{1,3}$/),
+    subdivisionName: str(i["subdivisionName"]),
+    city: str(i["city"]),
+    postalCode: upperCode(i["postalCode"], /^[A-Za-z0-9][A-Za-z0-9 -]{0,11}$/),
+    continent: upperCode(i["continent"], /^[A-Za-z]{2}$/),
+    timeZone: str(i["timeZone"], /^(UTC|[A-Za-z_]+(\/[A-Za-z0-9_+-]+)+)$/),
+    latitude: coord(i["latitude"], 90),
+    longitude: coord(i["longitude"], 180),
+    accuracyRadius: radius(i["accuracyRadius"]),
+    isp: str(i["isp"]),
+    org: str(i["org"]),
+    asn: upperCode(i["asn"], /^AS\d{1,10}$/i),
+    mobile: bool(i["mobile"]),
+    proxy: bool(i["proxy"]),
+    hosting: bool(i["hosting"])
+  };
+  const known = Object.fromEntries(Object.entries(out).filter(([, v]) => v !== null));
+  return Object.keys(known).length > 0 ? known : null;
+}
+var perRequest = /* @__PURE__ */ new WeakMap();
+function resolveLocation(resolver, req, timeoutMs = LOCATION_TIMEOUT_MS) {
+  if (!resolver) return Promise.resolve(null);
+  const cached = perRequest.get(req.headers);
+  if (cached && cached.resolver === resolver) return cached.result;
+  const result = resolveOnce(resolver, req, timeoutMs);
+  perRequest.set(req.headers, { resolver, result });
+  return result;
+}
+async function resolveOnce(resolver, req, timeoutMs) {
+  let timer;
+  try {
+    const result = await Promise.race([
+      Promise.resolve().then(() => resolver(req)),
+      new Promise((resolve2) => {
+        timer = setTimeout(() => resolve2(null), timeoutMs);
+      })
+    ]);
+    return sanitizeLocation(result);
+  } catch (err) {
+    console.warn("[auth] location resolver failed; recording without a location:", err);
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 // src/models/session.model.ts
 var SessionModel = class {
-  constructor(store) {
+  // `locate` is IAuthConfig.location. Absent ⇒ sessions carry no location.
+  constructor(store, locate) {
     this.store = store;
+    this.locate = locate;
   }
   store;
+  locate;
   async create(userId, token, expiresAt, sid, meta) {
+    const location = this.locate && meta?.headers ? await resolveLocation(this.locate, { ip: meta.ipAddress, headers: meta.headers }) : null;
     await this.store.query(
-      `INSERT INTO fonderie_sessions (user_id, token, expires_at, sid, user_agent, ip_address)
-			VALUES ($1, $2, $3, $4, $5, $6)
+      `INSERT INTO fonderie_sessions (user_id, token, expires_at, sid, user_agent, ip_address, location)
+			VALUES ($1, $2, $3, $4, $5, $6, $7)
 			ON CONFLICT (token) DO NOTHING`,
-      [userId, token, expiresAt, sid ?? null, meta?.userAgent ?? null, meta?.ipAddress ?? null]
+      [
+        userId,
+        token,
+        expiresAt,
+        sid ?? null,
+        meta?.userAgent ?? null,
+        meta?.ipAddress ?? null,
+        location ? JSON.stringify(location) : null
+      ]
     );
   }
   async delete(token) {
@@ -931,6 +1021,7 @@ var SessionModel = class {
       `SELECT id, sid,
 			        user_agent AS "userAgent",
 			        ip_address AS "ipAddress",
+			        location,
 			        created_at AS "createdAt",
 			        expires_at AS "expiresAt"
 			 FROM fonderie_sessions
@@ -1014,15 +1105,20 @@ var BackupCodeModel = class {
 // src/models/login-event.model.ts
 var import_core4 = require("@fonderie/core");
 var LoginEventModel = class {
-  constructor(store) {
+  // `locate` is IAuthConfig.location. Absent ⇒ rows carry no location,
+  // exactly as before.
+  constructor(store, locate) {
     this.store = store;
+    this.locate = locate;
   }
   store;
+  locate;
   async record(e) {
+    const location = this.locate ? await resolveLocation(this.locate, { ip: e.ipAddress, headers: e.headers ?? new Headers() }) : null;
     await this.store.query(
       `INSERT INTO fonderie_login_events
-			   (user_id, email_attempted, method, outcome, failure_reason, ip_address, user_agent)
-			 VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+			   (user_id, email_attempted, method, outcome, failure_reason, ip_address, user_agent, location)
+			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
       [
         e.userId,
         e.emailAttempted ?? null,
@@ -1030,7 +1126,8 @@ var LoginEventModel = class {
         e.outcome,
         e.failureReason ?? null,
         e.ipAddress,
-        e.userAgent
+        e.userAgent,
+        location ? JSON.stringify(location) : null
       ]
     );
   }
@@ -1069,7 +1166,7 @@ var LoginEventModel = class {
     params.push(limit + 1);
     const rows = await this.store.query(
       `SELECT id, method, outcome, failure_reason AS "failureReason",
-			        ip_address AS "ipAddress", user_agent AS "userAgent",
+			        ip_address AS "ipAddress", user_agent AS "userAgent", location,
 			        created_at AS "createdAt", created_at::text AS "createdAtRaw"
 			 FROM   fonderie_login_events
 			 WHERE  ${where.join(" AND ")}
@@ -1097,7 +1194,8 @@ function requestMeta(ctx) {
   const ua = ctx.request.headers.get("user-agent");
   const meta = {
     ipAddress: typeof ip === "string" && ip.length > 0 ? ip : null,
-    userAgent: ua && ua.length > 0 ? ua.slice(0, UA_MAX) : null
+    userAgent: ua && ua.length > 0 ? ua.slice(0, UA_MAX) : null,
+    headers: ctx.request.headers
   };
   if (meta.ipAddress === null && meta.userAgent === null) warnIfIdentityless(ctx);
   return meta;
@@ -1106,9 +1204,9 @@ function requestMeta(ctx) {
 // src/controllers/mfa.controller.ts
 function mfaController(store, config, issuer, bus) {
   const users = new UserModel(store);
-  const sessions = new SessionModel(store);
+  const sessions = new SessionModel(store, config.location);
   const backupCodes = new BackupCodeModel(store);
-  const loginEvents = new LoginEventModel(store);
+  const loginEvents = new LoginEventModel(store, config.location);
   const mfaCipher = makeMfaCipher(config.mfaSecretKey);
   return {
     // ── 1. Setup ───────────────────────────────────────────────
@@ -1506,8 +1604,8 @@ function extractRefreshToken(ctx) {
 }
 function authController(store, config, bus) {
   const users = new UserModel(store);
-  const sessions = new SessionModel(store);
-  const loginEvents = new LoginEventModel(store);
+  const sessions = new SessionModel(store, config.location);
+  const loginEvents = new LoginEventModel(store, config.location);
   const passwordReset = new PasswordResetModel(store);
   const emailVerif = new EmailVerificationModel(store);
   const phoneVerif = new PhoneVerificationModel(store);
@@ -1575,7 +1673,15 @@ function authController(store, config, bus) {
         const { accessToken, refreshToken, sid } = issueTokenPair(user.id, config, {
           loginMethod: "email"
         });
-        await sessions.create(user.id, refreshToken, refreshTokenExpiry(refreshToken), sid, requestMeta(ctx));
+        const registerMeta = requestMeta(ctx);
+        await sessions.create(user.id, refreshToken, refreshTokenExpiry(refreshToken), sid, registerMeta);
+        await loginEvents.recordSafe({
+          userId: user.id,
+          emailAttempted: normalizedEmail,
+          method: "registration",
+          outcome: "success",
+          ...registerMeta
+        });
         const resolvedRegister = { ...config, ...config.resolve?.(ctx) };
         const requiresVerification = !!resolvedRegister.requireVerification && !user.emailVerifiedAt;
         return Response.json(
@@ -2134,6 +2240,9 @@ function toLoginEventDTO(row) {
     failureReason: row.failureReason,
     ipAddress: row.ipAddress,
     userAgent: row.userAgent,
+    // Re-sanitized on read: the column is JSONB and could have been written
+    // by anything with database access.
+    location: sanitizeLocation(row.location),
     createdAt: row.createdAt instanceof Date ? row.createdAt.toISOString() : String(row.createdAt)
   };
 }
@@ -2149,6 +2258,7 @@ function toSessionDTO(row, currentSid) {
     current: currentSid !== null && row.sid === currentSid,
     ipAddress: row.ipAddress,
     userAgent: row.userAgent,
+    location: sanitizeLocation(row.location),
     createdAt: row.createdAt instanceof Date ? row.createdAt.toISOString() : String(row.createdAt),
     expiresAt: row.expiresAt instanceof Date ? row.expiresAt.toISOString() : String(row.expiresAt)
   };
@@ -2163,8 +2273,8 @@ function isValidPhone2(phone2) {
 }
 function userController(store, config, bus) {
   const users = new UserModel(store);
-  const sessions = new SessionModel(store);
-  const loginEvents = new LoginEventModel(store);
+  const sessions = new SessionModel(store, config.location);
+  const loginEvents = new LoginEventModel(store, config.location);
   const emailVerif = new EmailVerificationModel(store);
   const phoneVerif = new PhoneVerificationModel(store);
   return {
@@ -2608,8 +2718,8 @@ async function verifyAppleIdToken(idToken, opts) {
 var appleEmailVerified = (c) => c.email_verified === true || c.email_verified === "true";
 function oauthController(store, config, bus) {
   const users = new UserModel(store);
-  const sessions = new SessionModel(store);
-  const loginEvents = new LoginEventModel(store);
+  const sessions = new SessionModel(store, config.location);
+  const loginEvents = new LoginEventModel(store, config.location);
   const consumedTokens = new ConsumedTokenModel(store);
   const announceOAuthUpsert = async (ctx, upserted, provider, user) => {
     if (!bus) return;
@@ -3398,7 +3508,7 @@ var AuthModule = class {
   name = "@fonderie/auth";
   // Baked in at build time by tsup.base, so the operator's Modules page can
   // say what is actually deployed rather than 'not reported'.
-  version = "7.9.3";
+  version = "7.10.0";
   // Users, sessions, login history, suspend — only through @fonderie/admin.
   describeAdmin() {
     return { routes: describeAuthAdminRoutes(this.store) };
@@ -3676,6 +3786,8 @@ function startUserRetention(store, options) {
   normalizeEmailSafe,
   purgeSoftDeletedUsers,
   requireAuth,
+  resolveLocation,
+  sanitizeLocation,
   schemas,
   startUserRetention,
   toAdminUserDTO,