@dbx-tools/email 0.6.41 → 0.6.42

package/src/auth/otp.ts

@@ -0,0 +1,151 @@
+/**
+ * One-time-code store + session JWT for the email-OTP gate.
+ *
+ * Two pieces:
+ *
+ *   - **Code store** - a 6-digit code is generated with `crypto.randomInt` and
+ *     kept server-side as a SHA-256 hash with an expiry and an attempt counter
+ *     (never the plaintext, never in the JWT). `verifyCode` is constant-time on
+ *     the hash, enforces the TTL, and burns the code after too many attempts or
+ *     one success. In-memory `Map` keyed by lowercased email - fine for a
+ *     single-instance app behind a tunnel.
+ *   - **Session JWT** - on a correct code, `signSession` mints a short-lived
+ *     HS256 JWT (via `jose`) carrying only the email; `verifySession` validates
+ *     it. The signing key comes from `AUTH_JWT_SECRET`; when unset the gate
+ *     FAILS OPEN with an ephemeral per-process key (sessions reset on restart)
+ *     rather than refusing service - a Databricks App is already access-limited,
+ *     so an unset secret degrades to "sessions don't survive restarts", not
+ *     "nobody can log in".
+ *
+ * @module
+ */
+
+import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
+import { jwtVerify, SignJWT } from "jose";
+import { log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("email:auth:otp");
+
+/** JWT issuer/audience so a token minted for this gate isn't accepted elsewhere. */
+const JWT_AUD = "dbx-tools-email-auth";
+
+/** SHA-256 hex of a value (for the stored code + a stable key comparison). */
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/** Constant-time compare of two hex digests of equal length. */
+function safeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}
+
+interface CodeEntry {
+  hash: string;
+  expiresAt: number;
+  attempts: number;
+}
+
+/** Result of {@link CodeStore.verify}. */
+export type VerifyOutcome = "ok" | "invalid" | "expired" | "too-many-attempts";
+
+/** In-memory store of pending one-time codes, keyed by lowercased email. */
+export class CodeStore {
+  private readonly codes = new Map<string, CodeEntry>();
+
+  constructor(
+    private readonly ttlMs: number,
+    private readonly maxAttempts: number,
+  ) {}
+
+  /**
+   * Generate, store (hashed), and RETURN a fresh 6-digit code for `email`. The
+   * caller emails the returned plaintext; only the hash is retained. Replaces
+   * any pending code for the address.
+   */
+  issue(email: string, now: number = Date.now()): string {
+    const code = String(randomInt(0, 1_000_000)).padStart(6, "0");
+    this.codes.set(email.toLowerCase(), {
+      hash: sha256(code),
+      expiresAt: now + this.ttlMs,
+      attempts: 0,
+    });
+    return code;
+  }
+
+  /**
+   * Check `code` for `email`. Consumes the entry on success or when attempts are
+   * exhausted, so a code is single-use and can't be brute-forced past the cap.
+   */
+  verify(email: string, code: string, now: number = Date.now()): VerifyOutcome {
+    const key = email.toLowerCase();
+    const entry = this.codes.get(key);
+    if (!entry) return "invalid";
+    if (now >= entry.expiresAt) {
+      this.codes.delete(key);
+      return "expired";
+    }
+    entry.attempts += 1;
+    if (safeEqualHex(entry.hash, sha256(code))) {
+      this.codes.delete(key);
+      return "ok";
+    }
+    if (entry.attempts >= this.maxAttempts) {
+      this.codes.delete(key);
+      return "too-many-attempts";
+    }
+    return "invalid";
+  }
+
+  /** Drop every pending code (tests). */
+  clear(): void {
+    this.codes.clear();
+  }
+}
+
+/**
+ * Resolve the HS256 signing key. Prefers `AUTH_JWT_SECRET`; when unset, mints an
+ * ephemeral per-process key (fail-open) and warns once. Memoized so every
+ * sign/verify in a process shares one key.
+ */
+let cachedKey: Uint8Array | undefined;
+function signingKey(): Uint8Array {
+  if (cachedKey) return cachedKey;
+  const secret = process.env.AUTH_JWT_SECRET?.trim();
+  if (secret) {
+    cachedKey = new TextEncoder().encode(secret);
+  } else {
+    logger.warn(
+      "AUTH_JWT_SECRET is not set - using an ephemeral per-process key; sessions will not survive a restart",
+    );
+    cachedKey = randomBytes(32);
+  }
+  return cachedKey;
+}
+
+/** Reset the memoized key (tests, or after changing the env in-process). */
+export function resetSigningKey(): void {
+  cachedKey = undefined;
+}
+
+/** Mint a short-lived session JWT for `email`, expiring in `ttlSeconds`. */
+export async function signSession(email: string, ttlSeconds: number): Promise<string> {
+  return new SignJWT({ email })
+    .setProtectedHeader({ alg: "HS256" })
+    .setSubject(email)
+    .setAudience(JWT_AUD)
+    .setIssuedAt()
+    .setExpirationTime(`${ttlSeconds}s`)
+    .sign(signingKey());
+}
+
+/** Validate a session JWT, returning the email it was minted for, or `undefined`. */
+export async function verifySession(token: string | undefined): Promise<string | undefined> {
+  if (!token) return undefined;
+  try {
+    const { payload } = await jwtVerify(token, signingKey(), { audience: JWT_AUD });
+    return typeof payload.email === "string" ? payload.email : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/auth/rate-limit.ts

@@ -0,0 +1,59 @@
+/**
+ * A small in-memory fixed-window rate limiter for the email-OTP gate.
+ *
+ * Keyed by an arbitrary string (an email address or a client IP). Each key gets
+ * `max` hits per `windowMs`; the window resets on first use after it elapses.
+ * `hit()` returns whether the call is allowed and, when not, how many seconds
+ * until the window resets so a caller can surface a cooldown.
+ *
+ * In-memory is intentional and sufficient for a single-app-instance gate: an
+ * app behind a portr tunnel serves from one process. It is NOT a distributed
+ * limiter; a multi-replica deployment would need shared state. Entries are
+ * pruned lazily on access, so an idle key costs nothing after its window.
+ *
+ * @module
+ */
+
+interface Window {
+  count: number;
+  resetAt: number;
+}
+
+/** A fixed-window rate limiter over string keys. */
+export class RateLimiter {
+  private readonly windows = new Map<string, Window>();
+
+  constructor(
+    private readonly max: number,
+    private readonly windowMs: number,
+  ) {}
+
+  /**
+   * Record a hit for `key`. Returns `{ allowed }`, plus `retryAfter` (seconds)
+   * when the limit is exceeded. A limit of `<= 0` disables limiting (always
+   * allowed), which lets a config turn it off without special-casing callers.
+   */
+  hit(key: string, now: number = Date.now()): { allowed: boolean; retryAfter?: number } {
+    if (this.max <= 0) return { allowed: true };
+    const existing = this.windows.get(key);
+    if (!existing || now >= existing.resetAt) {
+      this.windows.set(key, { count: 1, resetAt: now + this.windowMs });
+      return { allowed: true };
+    }
+    if (existing.count < this.max) {
+      existing.count += 1;
+      return { allowed: true };
+    }
+    return { allowed: false, retryAfter: Math.ceil((existing.resetAt - now) / 1000) };
+  }
+
+  /** Forget a key (e.g. clear a caller's window after a successful verify). */
+  reset(key: string): void {
+    this.windows.delete(key);
+  }
+
+  /** Drop every window (tests). */
+  clear(): void {
+    this.windows.clear();
+  }
+}

package/src/config.ts

@@ -25,7 +25,7 @@
  */
 import { resolve } from "node:path";
 import { ConfigurationError, ValidationError, type BasePluginConfig } from "@databricks/appkit";
-import { object } from "@dbx-tools/shared-core";
+import { object, string } from "@dbx-tools/shared-core";
 import type { JSONSchema7 } from "json-schema";
 import type { EmailBrand } from "./brand.ts";
 import { parseAllowedSenders } from "./sender.ts";
@@ -114,6 +114,33 @@ export interface EmailPluginConfig extends BasePluginConfig {
    * `BrandContext`.
    */
   brand?: EmailBrand;
+  /**
+   * Optional email-OTP ACCESS GATE. When `enabled`, the plugin mounts a login
+   * flow (`/api/email/auth/*`) and gates every other route behind a session
+   * cookie - the front door for an app exposed publicly (e.g. through a portr
+   * tunnel that bypasses the Databricks OAuth proxy). Reuses this plugin's
+   * transport to email the code. Omit or `enabled: false` to leave the app open.
+   */
+  auth?: AuthConfig;
+}
+
+/** Email-OTP access-gate configuration (see {@link EmailPluginConfig.auth}). */
+export interface AuthConfig {
+  /** Turn the gate on. Falls back to `EMAIL_AUTH_ENABLED`. Default off. */
+  enabled?: boolean;
+  /**
+   * Who may request a code. Each entry is a domain shortcut (`databricks.com`
+   * or `@databricks.com`), a glob (`*.databricks.com`), or a `/regex/`. An
+   * EMPTY list allows nobody (fail closed). Falls back to `EMAIL_AUTH_ALLOW`
+   * (comma/space-separated).
+   */
+  allow?: string | string[];
+  /** Session lifetime (seconds). Falls back to `EMAIL_AUTH_SESSION_TTL`. Default 43200 (12h). */
+  sessionTtlSeconds?: number;
+  /** One-time-code lifetime (seconds). Falls back to `EMAIL_AUTH_CODE_TTL`. Default 600 (10m). */
+  codeTtlSeconds?: number;
+  /** Max verify attempts per issued code. Default 5. */
+  maxAttempts?: number;
 }
 
 /** Config shared by both resolved modes. */
@@ -233,9 +260,71 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
       },
       required: ["accent", "fontFamily"],
     },
+    auth: {
+      type: "object",
+      description:
+        "Email-OTP access gate. When enabled, mounts a login flow at /api/email/auth/* and gates every other route behind a session cookie.",
+      properties: {
+        enabled: {
+          type: "boolean",
+          description: "Turn the gate on (env EMAIL_AUTH_ENABLED). Default off.",
+        },
+        allow: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            'Allow-list of who may request a code: domain shortcut ("databricks.com"), glob ("*.databricks.com"), or "/regex/". Empty = nobody. Also accepts a comma/space-separated string. Env EMAIL_AUTH_ALLOW.',
+        },
+        sessionTtlSeconds: {
+          type: "number",
+          description: "Session lifetime in seconds (env EMAIL_AUTH_SESSION_TTL). Default 43200.",
+        },
+        codeTtlSeconds: {
+          type: "number",
+          description: "One-time-code lifetime in seconds (env EMAIL_AUTH_CODE_TTL). Default 600.",
+        },
+        maxAttempts: {
+          type: "number",
+          description: "Max verify attempts per issued code. Default 5.",
+        },
+      },
+    },
   },
 };
 
+/** Resolved email-OTP gate config, with env fallbacks applied (or `undefined` when off). */
+export interface ResolvedAuthConfig {
+  readonly allow: string[];
+  readonly sessionTtlSeconds: number;
+  readonly codeTtlSeconds: number;
+  readonly maxAttempts: number;
+}
+
+/**
+ * Resolve {@link AuthConfig} against env, returning `undefined` when the gate is
+ * off. `enabled` gates everything; `allow` merges the config list + env
+ * (`parseList` handles a `string[]` or a delimited string). Empty `allow` is
+ * allowed here (the gate then denies everyone - a deliberate fail-closed state).
+ */
+export function resolveAuthConfig(auth: AuthConfig | undefined): ResolvedAuthConfig | undefined {
+  const enabled = auth?.enabled ?? object.toBoolean(process.env.EMAIL_AUTH_ENABLED) ?? false;
+  if (!enabled) return undefined;
+  const allow = [
+    ...string.parseList(auth?.allow),
+    ...string.parseList(process.env.EMAIL_AUTH_ALLOW),
+  ];
+  const num = (value: number | undefined, env: string | undefined, fallback: number): number => {
+    const raw = value ?? (env ? Number(env) : undefined);
+    return typeof raw === "number" && Number.isFinite(raw) && raw > 0 ? raw : fallback;
+  };
+  return {
+    allow,
+    sessionTtlSeconds: num(auth?.sessionTtlSeconds, process.env.EMAIL_AUTH_SESSION_TTL, 43200),
+    codeTtlSeconds: num(auth?.codeTtlSeconds, process.env.EMAIL_AUTH_CODE_TTL, 600),
+    maxAttempts: auth?.maxAttempts ?? 5,
+  };
+}
+
 /** Parse the `SMTP_SECURE` env / config flag, defaulting by port. */
 function resolveSecure(flag: boolean | undefined, port: number): boolean {
   if (typeof flag === "boolean") return flag;

package/src/plugin.ts

@@ -52,7 +52,10 @@ import {
   type EmailResult,
   type EmailSenders,
 } from "@dbx-tools/shared-email";
-import { EMAIL_CONFIG_SCHEMA, type EmailPluginConfig } from "./config.ts";
+import type express from "express";
+import { authRequestSchema, authVerifySchema } from "@dbx-tools/shared-email";
+import { EMAIL_CONFIG_SCHEMA, resolveAuthConfig, type EmailPluginConfig } from "./config.ts";
+import { AuthGate, SESSION_COOKIE } from "./auth/gate.ts";
 import { EMAIL_SENDERS_SETTINGS, EMAIL_VERIFY_SETTINGS } from "./defaults.ts";
 import { isSenderAllowed, listSenderOptions, resolveSenderAddress } from "./sender.ts";
 import { SEND_EMAIL_DESCRIPTION } from "./tool.ts";
@@ -93,6 +96,9 @@ const logger = log.logger("email");
  * ```
  */
 export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvider {
+  /** The email-OTP access gate, constructed in {@link setup} when `auth.enabled`. */
+  private authGate?: AuthGate;
+
   static manifest = {
     name: "email",
     displayName: "Email",
@@ -143,6 +149,7 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
   override async setup(): Promise<void> {
     const { transporter, config } = getEmailRuntime(this.config);
     setEmailExecutor((fn, settings) => this.execute(fn, settings));
+    this.setupAuthGate();
     const policy = {
       mode: config.mode,
       senderPolicy: config.senderPolicy,
@@ -218,6 +225,85 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
         res.json(result.data);
       },
     });
+    this.injectAuthRoutes(router);
+  }
+
+  /**
+   * Mount the email-OTP login flow under `/api/email/auth/*` when the gate is
+   * enabled. These routes are the ONLY ones the gate middleware leaves open (see
+   * {@link AuthGate.middleware}); everything else requires the session cookie
+   * they establish. No-op when auth is off.
+   */
+  private injectAuthRoutes(router: IAppRouter): void {
+    const gate = this.authGate;
+    if (!gate) return;
+
+    // `request` and `verify` take a raw email/code, not an OBO user, so they are
+    // NOT wrapped in `asUser` - the caller is anonymous until verified.
+    this.route(router, {
+      name: "authRequest",
+      method: "post",
+      path: "/auth/request",
+      handler: async (req, res) => {
+        const parsed = authRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+          // Even a malformed body reports success (anti-enumeration).
+          res.json({ ok: true });
+          return;
+        }
+        const result = await gate.handleRequest(parsed.data.email, this.clientIp(req));
+        res.json(result);
+      },
+    });
+
+    this.route(router, {
+      name: "authVerify",
+      method: "post",
+      path: "/auth/verify",
+      handler: async (req, res) => {
+        const parsed = authVerifySchema.safeParse(req.body);
+        if (!parsed.success) {
+          res.json({ ok: false });
+          return;
+        }
+        const result = await gate.handleVerify(
+          parsed.data.email,
+          parsed.data.code,
+          this.clientIp(req),
+          req.secure,
+        );
+        if (result.ok && result.token && result.cookieOptions) {
+          res.cookie(SESSION_COOKIE, result.token, result.cookieOptions);
+        }
+        res.json({ ok: result.ok, ...(result.retryAfter ? { retryAfter: result.retryAfter } : {}) });
+      },
+    });
+
+    this.route(router, {
+      name: "authLogout",
+      method: "post",
+      path: "/auth/logout",
+      handler: async (_req, res) => {
+        res.clearCookie(SESSION_COOKIE, { path: "/" });
+        res.json({ ok: true });
+      },
+    });
+
+    this.route(router, {
+      name: "authStatus",
+      method: "get",
+      path: "/auth/status",
+      handler: async (req, res) => {
+        res.json(await gate.status(req));
+      },
+    });
+  }
+
+  /** Client IP for rate-limiting, honoring the Apps ingress `x-forwarded-for`. */
+  private clientIp(req: express.Request): string {
+    const fwd = req.headers["x-forwarded-for"];
+    const first = Array.isArray(fwd) ? fwd[0] : fwd?.split(",")[0];
+    return (first ?? req.ip ?? "unknown").trim();
   }
 
   override exports() {
@@ -268,6 +354,72 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
     return sendEmail(message, from ?? this.resolveSender(), signal);
   }
 
+  /**
+   * Build the email-OTP access gate when `auth.enabled`, wiring its code
+   * delivery through this plugin's own transport. Called from {@link setup}; a
+   * no-op (leaves {@link authGate} undefined) when the gate is off.
+   */
+  private setupAuthGate(): void {
+    const auth = resolveAuthConfig(this.config.auth);
+    if (!auth) return;
+    const gate = new AuthGate({
+      allow: auth.allow,
+      sessionTtlSeconds: auth.sessionTtlSeconds,
+      codeTtlSeconds: auth.codeTtlSeconds,
+      maxAttempts: auth.maxAttempts,
+      secureCookies: process.env.NODE_ENV === "production",
+      sendCode: (email, code) => this.sendOtpEmail(email, code),
+    });
+    this.authGate = gate;
+
+    // The gate must protect the WHOLE app, but a plugin's own `injectRoutes`
+    // router only covers `/api/email/*`. AppKit's `server` plugin exposes
+    // `addExtension(fn)` for exactly this: an app-level middleware registered
+    // before the server listens. Look it up by its registered name (no
+    // dependency on a specific server-plugin package) and mount the gate there.
+    // The login routes themselves are exempted by the middleware's `emailBase`
+    // open-prefix (`/api/email/auth`).
+    const server = this.context?.getPlugins().get("server") as
+      | { addExtension?: (fn: (app: express.Application) => void) => void }
+      | undefined;
+    if (server?.addExtension) {
+      server.addExtension((app) => app.use(gate.middleware(`/api/${EmailPlugin.manifest.name}`)));
+      logger.info("auth:enabled", {
+        patterns: auth.allow.length,
+        sessionTtlSeconds: auth.sessionTtlSeconds,
+      });
+    } else {
+      // No server plugin to gate through - the login routes still work, but the
+      // rest of the app would be ungated, so refuse to half-enable silently.
+      this.authGate = undefined;
+      logger.warn(
+        "auth:disabled - the `server` plugin is required to gate the app; add server() to your plugins",
+      );
+    }
+  }
+
+  /**
+   * Deliver a one-time code to `email` through this plugin's transport. Throws
+   * on failure (the gate swallows it, so a delivery error never leaks whether
+   * the address was allow-listed).
+   */
+  private async sendOtpEmail(email: string, code: string): Promise<void> {
+    await this.send(
+      {
+        to: [email],
+        subject: `Your sign-in code: ${code}`,
+        body: [
+          `Your one-time sign-in code is:`,
+          ``,
+          `## ${code}`,
+          ``,
+          `It expires shortly. If you didn't request this, you can ignore this email.`,
+        ].join("\n"),
+      },
+      undefined,
+    );
+  }
+
   /** Run the sender-options lookup through the plugin's interceptor chain. */
   private async executeListSenders(): Promise<ExecutionResult<EmailSenders>> {
     return this.execute(async () => this.listSenders(), EMAIL_SENDERS_SETTINGS);