@hilbras/keystone 1.1.0

package/src/services/configuration.ts

@@ -0,0 +1,120 @@
+import { config as rawConfig } from "../config.js";
+
+export interface RuntimeConfiguration {
+  nodeEnv: string;
+  port: number;
+  host: string;
+  databaseUrl: string;
+  redisUrl: string;
+  publicUrl?: string;
+  cookieDomain?: string;
+  cookieSecure: boolean;
+  internalApiKey?: string;
+  accessTokenTtlSeconds: number;
+  refreshTokenTtlSeconds: number;
+  secretsProvider: "database" | "environment";
+  queueProvider: "in-process" | "bullmq";
+  hibpCheckEnabled: boolean;
+  magicLinkTtlSeconds: number;
+  oauthCodeTtlSeconds: number;
+  totpIssuer: string;
+  emailProvider: string;
+  smsProvider: string;
+  auditWebhookUrl?: string;
+  auditConsoleExport: boolean;
+  featureFlags: Record<string, boolean>;
+  plugins: string[];
+  allowedOrigins: string[];
+  zitadel?: {
+    domain?: string;
+    orgId?: string;
+    projectId?: string;
+    serviceClientId?: string;
+    serviceClientSecret?: string;
+    servicePat?: string;
+    clientId?: string;
+    clientSecret?: string;
+    googleIdpId?: string;
+    githubIdpId?: string;
+  };
+}
+
+export class ConfigurationService {
+  private readonly values: RuntimeConfiguration;
+
+  constructor(overrides: Partial<RuntimeConfiguration> = {}) {
+    this.values = this.load(overrides);
+  }
+
+  private load(overrides: Partial<RuntimeConfiguration>): RuntimeConfiguration {
+    const featureFlags = this.parseFeatureFlags(process.env.KEYSTONE_FEATURE_FLAGS);
+
+    return {
+      nodeEnv: rawConfig.NODE_ENV,
+      port: rawConfig.PORT,
+      host: rawConfig.HOST,
+      databaseUrl: rawConfig.DATABASE_URL,
+      redisUrl: rawConfig.REDIS_URL,
+      publicUrl: rawConfig.AUTH_API_PUBLIC_URL,
+      cookieDomain: rawConfig.COOKIE_DOMAIN,
+      cookieSecure: rawConfig.COOKIE_SECURE,
+      internalApiKey: rawConfig.INTERNAL_API_KEY,
+      accessTokenTtlSeconds: rawConfig.ACCESS_TOKEN_TTL_SECONDS,
+      refreshTokenTtlSeconds: rawConfig.REFRESH_TOKEN_TTL_SECONDS,
+      secretsProvider: rawConfig.KEYSTONE_SECRETS_PROVIDER as RuntimeConfiguration["secretsProvider"],
+      queueProvider: rawConfig.KEYSTONE_QUEUE_PROVIDER as RuntimeConfiguration["queueProvider"],
+      hibpCheckEnabled: rawConfig.HIBP_CHECK_ENABLED,
+      magicLinkTtlSeconds: rawConfig.MAGIC_LINK_TTL_SECONDS,
+      oauthCodeTtlSeconds: rawConfig.OAUTH_CODE_TTL_SECONDS,
+      totpIssuer: rawConfig.TOTP_ISSUER,
+      emailProvider: rawConfig.EMAIL_PROVIDER,
+      smsProvider: rawConfig.SMS_PROVIDER,
+      auditWebhookUrl: rawConfig.AUDIT_WEBHOOK_URL,
+      auditConsoleExport: rawConfig.AUDIT_CONSOLE_EXPORT === "true",
+      featureFlags: { ...featureFlags, ...overrides.featureFlags },
+      plugins: (rawConfig.KEYSTONE_PLUGINS || "").split(",").map((s) => s.trim()).filter(Boolean),
+      allowedOrigins: rawConfig.ALLOWED_ORIGINS,
+      zitadel: {
+        domain: rawConfig.ZITADEL_DOMAIN,
+        orgId: rawConfig.ZITADEL_ORG_ID,
+        projectId: rawConfig.ZITADEL_PROJECT_ID,
+        serviceClientId: rawConfig.ZITADEL_SERVICE_CLIENT_ID,
+        serviceClientSecret: rawConfig.ZITADEL_SERVICE_CLIENT_SECRET,
+        servicePat: rawConfig.ZITADEL_SERVICE_PAT,
+        clientId: rawConfig.ZITADEL_CLIENT_ID,
+        clientSecret: rawConfig.ZITADEL_CLIENT_SECRET,
+        googleIdpId: rawConfig.ZITADEL_GOOGLE_IDP_ID,
+        githubIdpId: rawConfig.ZITADEL_GITHUB_IDP_ID,
+      },
+      ...overrides,
+    };
+  }
+
+  private parseFeatureFlags(value?: string): Record<string, boolean> {
+    if (!value) return {};
+    const flags: Record<string, boolean> = {};
+    for (const part of value.split(",")) {
+      const [key, val] = part.trim().split("=");
+      if (key) flags[key] = val === "true" || val === "1";
+    }
+    return flags;
+  }
+
+  get(): RuntimeConfiguration {
+    return this.values;
+  }
+
+  getValue<K extends keyof RuntimeConfiguration>(key: K): RuntimeConfiguration[K] {
+    return this.values[key];
+  }
+
+  isEnabled(flag: string): boolean {
+    return this.values.featureFlags[flag] === true;
+  }
+
+  isProduction(): boolean {
+    return this.values.nodeEnv === "production";
+  }
+}
+
+export const configurationService = new ConfigurationService();

package/src/services/connectors/google.ts

@@ -0,0 +1,92 @@
+import { OidcConnector, normalizePayload } from "./oidc.js";
+import type { ExternalIdentity, AuthorizeUrlOptions } from "./types.js";
+
+/**
+ * Google-specific OIDC connector.
+ *
+ * Extends the generic OIDC connector with Google-specific authorization
+ * parameters and a userinfo fallback. Google returns most claims in the
+ * id_token, but the userinfo endpoint is used as a fallback when claims
+ * are missing.
+ */
+export class GoogleConnector extends OidcConnector {
+  getAuthorizeUrl(opts: AuthorizeUrlOptions): string {
+    // Ask the user to pick an account every time. This avoids silent
+    // logins with the wrong Google account when multiple accounts exist.
+    opts.extraParams = {
+      ...opts.extraParams,
+      prompt: "select_account",
+      access_type: "online",
+    };
+    return super.getAuthorizeUrl(opts);
+  }
+
+  async exchangeCode(code: string, redirectUri: string): Promise<ExternalIdentity> {
+    const identity = await super.exchangeCode(code, redirectUri);
+
+    // Google usually returns picture, email_verified, etc. in the id_token.
+    // If something is missing, enrich from the userinfo endpoint.
+    if (!identity.name || !identity.picture || identity.emailVerified === undefined) {
+      try {
+        const enriched = await this.fetchUserinfo(code, redirectUri);
+        return {
+          ...identity,
+          name: identity.name || enriched.name,
+          picture: identity.picture || enriched.picture,
+          emailVerified: identity.emailVerified ?? enriched.emailVerified,
+        };
+      } catch (err) {
+        // Userinfo enrichment is best-effort; the id_token identity is still valid.
+        this.logDebug("Google userinfo enrichment failed", err);
+      }
+    }
+
+    return identity;
+  }
+
+  private async fetchUserinfo(code: string, redirectUri: string): Promise<ExternalIdentity> {
+    // Re-exchange the code for an access token. In practice the parent
+    // exchange already did this, but we do not retain the access token.
+    // A future refactor could pass it through to avoid a second request.
+    const params = new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+      code,
+      redirect_uri: redirectUri,
+    });
+
+    const tokenRes = await fetch(this.config.tokenEndpoint!, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+
+    if (!tokenRes.ok) {
+      throw new Error(`Google token refresh for userinfo failed: ${tokenRes.status}`);
+    }
+
+    const tokenData = (await tokenRes.json()) as { access_token?: string };
+    if (!tokenData.access_token) {
+      throw new Error("Google did not return an access_token for userinfo");
+    }
+
+    const userinfoRes = await fetch(this.config.userinfoEndpoint!, {
+      headers: { Authorization: `Bearer ${tokenData.access_token}` },
+    });
+
+    if (!userinfoRes.ok) {
+      throw new Error(`Google userinfo request failed: ${userinfoRes.status}`);
+    }
+
+    const payload = (await userinfoRes.json()) as Record<string, unknown>;
+    return normalizePayload(payload, this.config.attributeMapping);
+  }
+
+  private logDebug(message: string, err: unknown): void {
+    if (process.env.NODE_ENV !== "test") {
+      // eslint-disable-next-line no-console
+      console.debug(`[GoogleConnector] ${message}:`, err);
+    }
+  }
+}

package/src/services/connectors/oidc.ts

@@ -0,0 +1,111 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import type { IdentityConnector, ExternalIdentity, AuthorizeUrlOptions, ConnectorConfig } from "./types.js";
+import { cache } from "../cache.js";
+
+export class OidcConnector implements IdentityConnector {
+  id: string;
+  name: string;
+  type: string;
+  protected config: ConnectorConfig;
+
+  constructor(id: string, name: string, type: string, config: ConnectorConfig) {
+    this.id = id;
+    this.name = name;
+    this.type = type;
+    this.config = config;
+  }
+
+  getAuthorizeUrl(opts: AuthorizeUrlOptions): string {
+    const scopes = opts.scopes ?? this.config.scopes ?? ["openid", "profile", "email"];
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: opts.redirectUri,
+      response_type: "code",
+      scope: scopes.join(" "),
+      state: opts.state,
+    });
+    if (this.config.idpHint) {
+      params.set("idp_hint", this.config.idpHint);
+    }
+    if (opts.extraParams) {
+      for (const [k, v] of Object.entries(opts.extraParams)) {
+        params.set(k, v);
+      }
+    }
+    return `${this.config.authorizationEndpoint}?${params.toString()}`;
+  }
+
+  async exchangeCode(code: string, redirectUri: string): Promise<ExternalIdentity> {
+    const params = new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+      code,
+      redirect_uri: redirectUri,
+    });
+
+    const res = await fetch(this.config.tokenEndpoint!, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`OIDC token exchange failed: ${res.status} ${text}`);
+    }
+
+    const data = (await res.json()) as { id_token: string; access_token?: string };
+    if (!data.id_token) {
+      throw new Error("OIDC provider did not return an id_token");
+    }
+    return this.verifyToken(data.id_token);
+  }
+
+  async verifyToken(token: string): Promise<ExternalIdentity> {
+    const jwksUrl = this.config.jwksUri || ((await this.discovery())?.jwks_uri as string);
+    if (!jwksUrl) {
+      throw new Error("OIDC connector missing jwks_uri");
+    }
+    const JWKS = createRemoteJWKSet(new URL(jwksUrl));
+    const { payload } = await jwtVerify(token, JWKS, {
+      issuer: this.config.issuer,
+      audience: this.config.clientId,
+    });
+    return normalizePayload(payload as Record<string, unknown>, this.config.attributeMapping);
+  }
+
+  private async discovery(): Promise<Record<string, unknown>> {
+    if (!this.config.issuer) throw new Error("OIDC connector missing issuer for discovery");
+    const key = `oidc:discovery:${this.config.issuer}`;
+    const cached = await cache.get<Record<string, unknown>>(key);
+    if (cached) return cached;
+
+    const res = await fetch(`${this.config.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`);
+    if (!res.ok) throw new Error(`OIDC discovery failed: ${res.status}`);
+    const data = (await res.json()) as Record<string, unknown>;
+    await cache.set(key, data, 3600);
+    return data;
+  }
+}
+
+export function normalizePayload(
+  payload: Record<string, unknown>,
+  mapping?: Record<string, string>
+): ExternalIdentity {
+  const m = mapping ?? {};
+  const get = (key: string): unknown => payload[m[key] || key];
+  const email = String(get("email") || "");
+  if (!email) {
+    throw new Error("Identity provider did not return an email address");
+  }
+  return {
+    sub: String(get("sub") || ""),
+    email,
+    emailVerified: get("email_verified") === true,
+    name: get("name") ? String(get("name")) : undefined,
+    picture: get("picture") ? String(get("picture")) : undefined,
+    username: get("preferred_username") ? String(get("preferred_username")) : undefined,
+    raw: payload,
+  };
+}

package/src/services/connectors/registry.ts

@@ -0,0 +1,124 @@
+import { config, isZitadelConfigured } from "../../config.js";
+import { getConnectorFactory } from "../plugins/registry.js";
+import type { IdentityConnector, ConnectorConfig } from "./types.js";
+import { OidcConnector } from "./oidc.js";
+import { GoogleConnector } from "./google.js";
+import { ZitadelConnector } from "./zitadel.js";
+
+const wellKnownIssuers: Record<string, { issuer: string; authorizationEndpoint?: string; tokenEndpoint?: string; userinfoEndpoint?: string; jwksUri?: string }> = {
+  google: {
+    issuer: "https://accounts.google.com",
+    authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenEndpoint: "https://oauth2.googleapis.com/token",
+    userinfoEndpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+    jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
+  },
+  github: {
+    issuer: "https://github.com",
+    authorizationEndpoint: "https://github.com/login/oauth/authorize",
+    tokenEndpoint: "https://github.com/login/oauth/access_token",
+    userinfoEndpoint: "https://api.github.com/user",
+  },
+  azure: {
+    issuer: "https://login.microsoftonline.com/common/v2.0",
+    authorizationEndpoint: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    tokenEndpoint: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    userinfoEndpoint: "https://graph.microsoft.com/oidc/userinfo",
+    jwksUri: "https://login.microsoftonline.com/common/discovery/v2.0/keys",
+  },
+  okta: {
+    issuer: process.env.OKTA_ISSUER || "",
+    authorizationEndpoint: process.env.OKTA_AUTHORIZATION_ENDPOINT || "",
+    tokenEndpoint: process.env.OKTA_TOKEN_ENDPOINT || "",
+    userinfoEndpoint: process.env.OKTA_USERINFO_ENDPOINT || "",
+    jwksUri: process.env.OKTA_JWKS_URI || "",
+  },
+  keycloak: {
+    issuer: process.env.KEYCLOAK_ISSUER || "",
+    authorizationEndpoint: process.env.KEYCLOAK_AUTHORIZATION_ENDPOINT || "",
+    tokenEndpoint: process.env.KEYCLOAK_TOKEN_ENDPOINT || "",
+    userinfoEndpoint: process.env.KEYCLOAK_USERINFO_ENDPOINT || "",
+    jwksUri: process.env.KEYCLOAK_JWKS_URI || "",
+  },
+};
+
+function getProviderEnvPrefix(type: string): string {
+  return type.toUpperCase();
+}
+
+export function buildConnector(type: string, overrides?: Partial<ConnectorConfig>): IdentityConnector {
+  const pluginFactory = getConnectorFactory(type);
+  if (pluginFactory) {
+    return pluginFactory(overrides);
+  }
+
+  if (type === "zitadel") {
+    if (!isZitadelConfigured()) {
+      throw new Error("Zitadel connector is not configured. Set ZITADEL_DOMAIN and ZITADEL_CLIENT_ID.");
+    }
+    return new ZitadelConnector({
+      issuer: config.ZITADEL_DOMAIN,
+      clientId: config.ZITADEL_CLIENT_ID!,
+      clientSecret: config.ZITADEL_CLIENT_SECRET || "",
+      scopes: ["openid", "profile", "email"],
+      ...overrides,
+    });
+  }
+
+  const prefix = getProviderEnvPrefix(type);
+  const envClientId = process.env[`${prefix}_CLIENT_ID`] || "";
+  const envClientSecret = process.env[`${prefix}_CLIENT_SECRET`] || "";
+  const envIssuer = process.env[`${prefix}_ISSUER`] || "";
+
+  const wellKnown = wellKnownIssuers[type];
+  if (!wellKnown && !envIssuer) {
+    throw new Error(`${type} connector is not configured. Set ${prefix}_ISSUER, ${prefix}_CLIENT_ID, and ${prefix}_CLIENT_SECRET.`);
+  }
+
+  const cfg: ConnectorConfig = {
+    issuer: envIssuer || wellKnown?.issuer,
+    authorizationEndpoint: process.env[`${prefix}_AUTHORIZATION_ENDPOINT`] || wellKnown?.authorizationEndpoint,
+    tokenEndpoint: process.env[`${prefix}_TOKEN_ENDPOINT`] || wellKnown?.tokenEndpoint,
+    userinfoEndpoint: process.env[`${prefix}_USERINFO_ENDPOINT`] || wellKnown?.userinfoEndpoint,
+    jwksUri: process.env[`${prefix}_JWKS_URI`] || wellKnown?.jwksUri,
+    clientId: envClientId || overrides?.clientId || "",
+    clientSecret: envClientSecret || overrides?.clientSecret || "",
+    scopes: ["openid", "profile", "email"],
+    ...overrides,
+  };
+
+  if (!cfg.clientId || !cfg.clientSecret || !cfg.issuer) {
+    throw new Error(`${type} connector is not fully configured. Set ${prefix}_CLIENT_ID, ${prefix}_CLIENT_SECRET, and ${prefix}_ISSUER.`);
+  }
+
+  if (type === "google") {
+    return new GoogleConnector(type, type, type, cfg);
+  }
+
+  return new OidcConnector(type, type, type, cfg);
+}
+
+export function listSupportedProviders(): string[] {
+  return ["zitadel", "google", "github", "azure", "okta", "keycloak"];
+}
+
+/**
+ * Returns supported providers annotated with whether they are currently
+ * configured with client credentials in the environment.
+ */
+export function listConfiguredProviders(): Array<{ type: string; name: string; configured: boolean }> {
+  return listSupportedProviders().map((type) => {
+    const prefix = type.toUpperCase();
+    let configured = false;
+
+    if (type === "zitadel") {
+      configured = Boolean(process.env.ZITADEL_DOMAIN && process.env.ZITADEL_CLIENT_ID);
+    } else {
+      configured = Boolean(
+        process.env[`${prefix}_CLIENT_ID`] && process.env[`${prefix}_CLIENT_SECRET`]
+      );
+    }
+
+    return { type, name: type.charAt(0).toUpperCase() + type.slice(1), configured };
+  });
+}

package/src/services/connectors/types.ts

@@ -0,0 +1,38 @@
+export interface ExternalIdentity {
+  sub: string;
+  email: string;
+  emailVerified?: boolean;
+  name?: string;
+  picture?: string;
+  username?: string;
+  raw?: Record<string, unknown>;
+}
+
+export interface AuthorizeUrlOptions {
+  state: string;
+  redirectUri: string;
+  scopes?: string[];
+  extraParams?: Record<string, string>;
+}
+
+export interface IdentityConnector {
+  id: string;
+  name: string;
+  type: string;
+  getAuthorizeUrl(opts: AuthorizeUrlOptions): string | Promise<string>;
+  exchangeCode(code: string, redirectUri: string): Promise<ExternalIdentity>;
+  verifyToken?(token: string): Promise<ExternalIdentity>;
+}
+
+export interface ConnectorConfig {
+  issuer?: string;
+  authorizationEndpoint?: string;
+  tokenEndpoint?: string;
+  userinfoEndpoint?: string;
+  jwksUri?: string;
+  clientId: string;
+  clientSecret: string;
+  scopes?: string[];
+  idpHint?: string;
+  attributeMapping?: Record<string, string>;
+}

package/src/services/connectors/zitadel.ts

@@ -0,0 +1,77 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { config, zitadelBaseUrl } from "../../config.js";
+import type { IdentityConnector, ExternalIdentity, AuthorizeUrlOptions, ConnectorConfig } from "./types.js";
+import { normalizePayload } from "./oidc.js";
+
+export class ZitadelConnector implements IdentityConnector {
+  id = "zitadel";
+  name = "Zitadel";
+  type = "zitadel";
+  private cfg: ConnectorConfig;
+  private cachedJwksUrl: string | null = null;
+
+  constructor(cfg: ConnectorConfig) {
+    this.cfg = cfg;
+  }
+
+  getAuthorizeUrl(opts: AuthorizeUrlOptions): string {
+    const redirectUri = opts.redirectUri;
+    const params = new URLSearchParams({
+      client_id: this.cfg.clientId,
+      redirect_uri: redirectUri,
+      response_type: "code",
+      scope: (opts.scopes ?? ["openid", "profile", "email"]).join(" "),
+      state: opts.state,
+    });
+    if (this.cfg.idpHint) {
+      params.set("idp_hint", this.cfg.idpHint);
+    }
+    return `${zitadelBaseUrl()}/oauth/v2/authorize?${params.toString()}`;
+  }
+
+  async exchangeCode(code: string, redirectUri: string): Promise<ExternalIdentity> {
+    const params = new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: this.cfg.clientId,
+      client_secret: this.cfg.clientSecret,
+      code,
+      redirect_uri: redirectUri,
+    });
+
+    const res = await fetch(`${zitadelBaseUrl()}/oauth/v2/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Zitadel token exchange failed: ${res.status} ${text}`);
+    }
+
+    const data = (await res.json()) as { id_token: string };
+    return this.verifyToken(data.id_token);
+  }
+
+  async verifyToken(token: string): Promise<ExternalIdentity> {
+    const jwksUrl = await this.getJwksUrl();
+    const JWKS = createRemoteJWKSet(new URL(jwksUrl));
+    const issuer = config.ZITADEL_DOMAIN!.startsWith("http")
+      ? config.ZITADEL_DOMAIN!
+      : `https://${config.ZITADEL_DOMAIN!}`;
+    const { payload } = await jwtVerify(token, JWKS, {
+      issuer,
+      audience: this.cfg.clientId,
+    });
+    return normalizePayload(payload as Record<string, unknown>, this.cfg.attributeMapping);
+  }
+
+  private async getJwksUrl(): Promise<string> {
+    if (this.cachedJwksUrl) return this.cachedJwksUrl;
+    const res = await fetch(`${zitadelBaseUrl()}/.well-known/openid-configuration`);
+    if (!res.ok) throw new Error(`Zitadel discovery failed: ${res.status}`);
+    const discovery = (await res.json()) as Record<string, unknown>;
+    this.cachedJwksUrl = (discovery.jwks_uri as string) || `${zitadelBaseUrl()}/oauth/v2/keys`;
+    return this.cachedJwksUrl;
+  }
+}

package/src/services/devices.ts

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import type { FastifyRequest } from "fastify";
+import { eq, and } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { userDevices, users } from "../db/schema.js";
+import { sendNewDeviceAlert } from "./email.js";
+
+export function fingerprintFromRequest(request: FastifyRequest): string {
+  const ip = request.ip || "unknown";
+  const userAgent = request.headers["user-agent"] || "unknown";
+  const acceptLanguage = request.headers["accept-language"] || "unknown";
+  const value = `${ip}:${userAgent}:${acceptLanguage}`;
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export async function recordDevice(
+  userId: string,
+  fingerprint: string,
+  ip?: string,
+  userAgent?: string
+) {
+  const now = new Date();
+
+  const [existing] = await db
+    .select({ id: userDevices.id })
+    .from(userDevices)
+    .where(
+      and(
+        eq(userDevices.userId, userId),
+        eq(userDevices.fingerprintHash, fingerprint)
+      )
+    )
+    .limit(1);
+
+  if (existing) {
+    await db
+      .update(userDevices)
+      .set({
+        lastSeenAt: now,
+        ipAddress: ip ?? null,
+        userAgent: userAgent ?? null,
+      })
+      .where(eq(userDevices.id, existing.id));
+    return existing.id;
+  }
+
+  const [record] = await db
+    .insert(userDevices)
+    .values({
+      userId,
+      fingerprintHash: fingerprint,
+      ipAddress: ip ?? null,
+      userAgent: userAgent ?? null,
+      firstSeenAt: now,
+      lastSeenAt: now,
+    })
+    .returning();
+
+  // Send new-device alert asynchronously; do not block the login flow.
+  const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+  if (user && !record.newDeviceAlertSent) {
+    sendNewDeviceAlert({
+      email: user.email,
+      ipAddress: ip,
+      userAgent: userAgent,
+    }).catch((err: unknown) => {
+      console.error("[devices] failed to send new-device alert:", err);
+    });
+    await db
+      .update(userDevices)
+      .set({ newDeviceAlertSent: true })
+      .where(eq(userDevices.id, record.id));
+  }
+
+  return record.id;
+}