@dbx-tools/tunnel 0.6.89 → 0.6.91

package/src/gate.ts

@@ -6,8 +6,8 @@
  * nothing to forward to. It either short-circuits (401, or answers the open login
  * routes) or calls `next()` to let the app's real handlers run. It is the
  * "stands in for AppKit auth" path:
- * a portr caller proves an email via OTP, and on success the gate injects the
- * identity headers AppKit reads, so a gated request runs like a front-door one.
+ * a portr caller authenticates with Better Auth OTP or a passkey, and on
+ * success the gate injects the identity headers AppKit reads.
  *
  * WHICH TRAFFIC IS GATED - the `Host` header, not the socket. portr's client
  * forwards with Go's `httputil.NewSingleHostReverseProxy` and a `Director` that
@@ -23,15 +23,18 @@
  */
 
 import type { IncomingMessage } from "node:http";
-import { http, json, log, token } from "@dbx-tools/shared-core";
-import { authRequestSchema, authVerifySchema, SESSION_COOKIE_NAME } from "@dbx-tools/shared-email";
-import type { Request, RequestHandler, Response } from "express";
+import { log, token } from "@dbx-tools/shared-core";
+import type { RequestHandler, Response } from "express";
 import { toHeaderPolicy, type HeaderPolicy } from "./headers.ts";
 import type { AuthGateApi } from "./plugin.ts";
 
 const logger = log.logger("tunnel:gate");
 
-/** Route prefix the login flow lives under (open, answered in-process). */
+type WebRequestInput = IncomingMessage & {
+  body?: unknown;
+  originalUrl?: string;
+};
+
 export const AUTH_PREFIX = "/api/email/auth";
 
 /** Options for {@link mountGate}. */
@@ -63,22 +66,6 @@ export function isTunnelHost(req: IncomingMessage, publicDomain: string | undefi
   return host === publicDomain.toLowerCase().split(":")[0];
 }
 
-/** The session cookie for a verified email, as a Set-Cookie string. */
-function sessionCookie(value: string, maxAgeSeconds: number): string {
-  return [
-    `${SESSION_COOKIE_NAME}=${value}`,
-    "Path=/",
-    "HttpOnly",
-    "SameSite=Lax",
-    `Max-Age=${maxAgeSeconds}`,
-    // Real enforcement in production: the session cookie must be Secure so it is
-    // never sent over plaintext. Local dev (http) omits it so the cookie works.
-    process.env.NODE_ENV === "production" ? "Secure" : "",
-  ]
-    .filter(Boolean)
-    .join("; ");
-}
-
 /**
  * Client IP for rate-limiting: the RIGHTMOST `x-forwarded-for` entry (the value
  * the nearest trusted hop - portr - wrote), else the socket address. Reading the
@@ -105,18 +92,18 @@ function stripSessionCookie(req: IncomingMessage): void {
   const kept = raw
     .split(";")
     .map((c) => c.trim())
-    .filter((c) => c && !c.startsWith(`${SESSION_COOKIE_NAME}=`));
+    .filter((c) => c && !c.startsWith("dbx-tools-auth=") && !c.startsWith("dbx-tools-passkey="));
   if (kept.length) req.headers.cookie = kept.join("; ");
   else delete req.headers.cookie;
 }
 
 /**
- * Present an OTP-authenticated caller to the app the SAME way a platform front
+ * Present a passwordless-authenticated caller to the app the SAME way a platform front
  * door does: set the front-door identity headers to the verified address (AppKit
  * reads {@link token.USER_ID_HEADER} for the OBO user id), so the app needs no
  * gate-specific code path.
  *
- * What the gate CANNOT set is {@link token.ACCESS_TOKEN_HEADER}: an OTP session
+ * What the gate CANNOT set is {@link token.ACCESS_TOKEN_HEADER}: an auth session
  * proves an email, not possession of a Databricks credential. Its absence is what
  * `@dbx-tools/appkit`'s `identity: "auto"` detects, so a gated request runs as the
  * app service principal instead of throwing.
@@ -126,14 +113,9 @@ function injectIdentity(req: IncomingMessage, email: string): void {
   req.headers[token.USER_EMAIL_HEADER] = email;
 }
 
-function sendJson(res: Response, status: number, body: unknown, setCookie?: string): void {
-  if (setCookie) res.setHeader("set-cookie", setCookie);
-  res.status(status).json(body);
-}
-
 /** Read the raw request body as text (AppKit parses JSON, but the gate routes
  * are mounted before that runs for tunnel traffic, so read defensively). */
-function readBody(req: Request): Promise<string> {
+function readBody(req: WebRequestInput): Promise<string> {
   // AppKit's json body-parser may have already populated req.body; prefer it.
   if (req.body !== undefined && req.body !== null) {
     return Promise.resolve(typeof req.body === "string" ? req.body : JSON.stringify(req.body));
@@ -146,6 +128,42 @@ function readBody(req: Request): Promise<string> {
   });
 }
 
+export function webHeaders(req: IncomingMessage): Headers {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(name, item);
+    } else if (value !== undefined) {
+      headers.set(name, value);
+    }
+  }
+  headers.set("x-real-ip", clientIp(req));
+  return headers;
+}
+
+export async function webRequest(req: WebRequestInput): Promise<globalThis.Request> {
+  const host = req.headers.host ?? "localhost";
+  const hostname = host.split(":")[0]?.toLowerCase();
+  const protocol = hostname === "localhost" || hostname === "127.0.0.1" ? "http" : "https";
+  const method = (req.method ?? "GET").toUpperCase();
+  const body = method === "GET" || method === "HEAD" ? undefined : await readBody(req);
+  return new globalThis.Request(`${protocol}://${host}${req.originalUrl || req.url}`, {
+    method,
+    headers: webHeaders(req),
+    ...(body ? { body } : {}),
+  });
+}
+
+export async function sendWebResponse(res: Response, response: globalThis.Response): Promise<void> {
+  for (const [name, value] of response.headers.entries()) {
+    if (name.toLowerCase() !== "set-cookie") res.setHeader(name, value);
+  }
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length) res.setHeader("set-cookie", cookies);
+  const body = Buffer.from(await response.arrayBuffer());
+  res.status(response.status).send(body);
+}
+
 /**
  * What the caller should do with a request, from {@link gateRequest}.
  *
@@ -197,9 +215,8 @@ export async function gateRequest(
     return "pass";
   }
 
-  // Every other /api/* needs a valid OTP session.
-  const cookie = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
-  const email = await gate.session(cookie);
+  // Every other /api/* needs a valid Better Auth session.
+  const email = await gate.session(webHeaders(req));
   if (!email) return "deny";
   injectIdentity(req, email);
   stripSessionCookie(req);
@@ -212,14 +229,6 @@ export const UNAUTHORIZED_BODY = {
   loginPath: AUTH_PREFIX,
 } as const;
 
-/** The `Set-Cookie` value that issues a verified session. */
-export function sessionSetCookie(sessionToken: string, maxAgeSeconds: number): string {
-  return sessionCookie(sessionToken, maxAgeSeconds);
-}
-
-/** The `Set-Cookie` value that clears the session. */
-export const LOGOUT_SET_COOKIE = `${SESSION_COOKIE_NAME}=; Path=/; HttpOnly; Max-Age=0`;
-
 /**
  * Register the login routes and the gating middleware on the app's Express
  * instance. Called from {@link AuthGatePlugin} with the router AppKit hands
@@ -231,74 +240,34 @@ export const LOGOUT_SET_COOKIE = `${SESSION_COOKIE_NAME}=; Path=/; HttpOnly; Max
  */
 export function mountGate(
   opts: GateOptions,
-  addRoute: (method: "get" | "post", path: string, handler: RequestHandler) => void,
+  _addRoute: (method: "get" | "post", path: string, handler: RequestHandler) => void,
   addMiddleware: (path: string, handler: RequestHandler) => void,
 ): void {
   const { gate, publicDomain, forwardHeaders } = opts;
   const headerPolicy = toHeaderPolicy(forwardHeaders);
   logger.debug("gate mounted", { publicDomain, forward: headerPolicy.patterns });
 
-  // --- Login routes (open on tunnel traffic; answered in-process) ---
-
-  const statusHandler = (async (req, res) => {
-    // A local or front-door caller is never gated, so the honest answer is that
-    // the gate does not apply - not the session state of a cookie it would never
-    // check. Without this, a browser on `localhost` renders the OTP login screen
-    // for a request that would have passed through untouched.
+  // Better Auth and the compatibility routes share one fetch-compatible
+  // handler in both hosting modes.
+  const authHandler = (async (req, res) => {
     if (!isTunnelHost(req, publicDomain)) {
-      sendJson(res, 200, { authenticated: false, enabled: false });
+      const path = (req.url ?? "/").split("?")[0] ?? "/";
+      if (path.endsWith("/status")) {
+        res.status(200).json({ authenticated: false, enabled: false, passkeysEnabled: false });
+      } else {
+        res.status(404).json({ error: "not found" });
+      }
       return;
     }
-    const cookie = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
-    sendJson(res, 200, await gate.status(cookie));
+    await sendWebResponse(res, await gate.handler(await webRequest(req)));
   }) as RequestHandler;
-
-  const requestHandler = (async (req, res) => {
-    if (!isTunnelHost(req, publicDomain)) {
-      sendJson(res, 404, { error: "not found" });
-      return;
-    }
-    const parsed = authRequestSchema.safeParse(json.parseRecord(await readBody(req)));
-    if (!parsed.success) return sendJson(res, 200, { ok: true }); // anti-enumeration
-    sendJson(res, 200, await gate.request(parsed.data.email, clientIp(req)));
-  }) as RequestHandler;
-
-  const verifyHandler = (async (req, res) => {
-    if (!isTunnelHost(req, publicDomain)) {
-      sendJson(res, 404, { error: "not found" });
-      return;
-    }
-    const parsed = authVerifySchema.safeParse(json.parseRecord(await readBody(req)));
-    if (!parsed.success) return sendJson(res, 200, { ok: false });
-    const result = await gate.verify(parsed.data.email, parsed.data.code, clientIp(req));
-    const cookie =
-      result.ok && result.token ? sessionCookie(result.token, gate.sessionTtlSeconds) : undefined;
-    sendJson(
-      res,
-      200,
-      { ok: result.ok, ...(result.retryAfter ? { retryAfter: result.retryAfter } : {}) },
-      cookie,
-    );
-  }) as RequestHandler;
-
-  const logoutHandler = ((req, res) => {
-    if (!isTunnelHost(req, publicDomain)) {
-      sendJson(res, 404, { error: "not found" });
-      return;
-    }
-    sendJson(res, 200, { ok: true }, LOGOUT_SET_COOKIE);
-  }) as RequestHandler;
-
-  addRoute("get", `${AUTH_PREFIX}/status`, statusHandler);
-  addRoute("post", `${AUTH_PREFIX}/request`, requestHandler);
-  addRoute("post", `${AUTH_PREFIX}/verify`, verifyHandler);
-  addRoute("post", `${AUTH_PREFIX}/logout`, logoutHandler);
+  addMiddleware(AUTH_PREFIX, authHandler);
 
   // --- The gate middleware (runs before static + the app's /api handlers) ---
 
   const gateMiddleware = (async (req, res, next) => {
     const action = await gateRequest(req, { gate, publicDomain, headerPolicy });
-    if (action === "deny") sendJson(res, 401, UNAUTHORIZED_BODY);
+    if (action === "deny") res.status(401).json(UNAUTHORIZED_BODY);
     else next();
   }) as RequestHandler;
 

package/src/interceptor.ts

@@ -9,7 +9,7 @@
  * app's public port, binds the child process to the app, and stops portr during an
  * orderly AppKit shutdown.
  *
- * The email-OTP GATE is a separate concern: it is the `authGate` AppKit plugin,
+ * The passwordless GATE is a separate concern: it is the `authGate` AppKit plugin,
  * which registers the login routes + a gating middleware on the app's own server.
  * Register it in the app's `plugins` for gated traffic. This interceptor is only
  * the portr half - "update the host, bind portr" - the smallest useful unit.

package/src/plugin.ts

@@ -1,12 +1,11 @@
 /**
- * `authGate()` - the AppKit plugin behind the tunnel's email-OTP gate.
+ * `authGate()` - the AppKit adapter around `@dbx-tools/auth`.
  *
  * It has NO routes of its own: the tunnel PROXY (not an HTTP server) calls the
  * handlers this plugin exposes via {@link AuthGatePlugin.exports}. The plugin
- * owns the allow-list, the per-email/per-IP rate limiters, the CacheManager-backed
- * one-time-code store, and the session JWT. `createApp` (with no `server()`) is
- * used only to auto-init `CacheManager` + prime the sibling `email` transport;
- * this plugin is where the gate logic lives.
+ * owns tunnel authorization, AppKit Lakebase discovery, email delivery, and
+ * transport mounting. Better Auth owns users, OTPs, sessions, rate limits, and
+ * passkeys. `createApp` can run this plugin with or without `server()`.
  *
  * Options come from CLI flags OR env, with sensible defaults - see
  * {@link resolveAuthGateConfig}. The one runtime dependency the plugin can't
@@ -16,16 +15,31 @@
  * @module
  */
 
-import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
+import {
+  lakebase,
+  Plugin,
+  toPlugin,
+  type BasePluginConfig,
+  type PluginManifest,
+  type ResourceRequirement,
+  ResourceType,
+} from "@databricks/appkit";
+import { plugin as appkitPlugin } from "@dbx-tools/appkit";
+import {
+  auth as passwordlessAuth,
+  storage as authStorage,
+  type AuthorizeIdentity,
+  type AuthStorageConfig,
+  type AuthStorageMode,
+  type PasswordlessAuthRuntime,
+} from "@dbx-tools/auth";
 import { config as coreConfig } from "@dbx-tools/core";
-import { brand, log, object, string } from "@dbx-tools/shared-core";
-import type { AuthStatus } from "@dbx-tools/shared-email";
+import type { AuthStatus } from "@dbx-tools/shared-auth";
+import { brand, log, string } from "@dbx-tools/shared-core";
 import type { RequestHandler } from "express";
 import { TUNNEL_CONFIG } from "./_config.ts";
 import { looksLikeEmail, matchesAllowlist } from "./allowlist.ts";
 import { mountGate, type GateOptions } from "./gate.ts";
-import { CodeStore, signSession, verifySession } from "./otp.ts";
-import { RateLimiter } from "./rate-limit.ts";
 import { ensureEmailAvailable, sendCode as defaultSendCode } from "./send-code.ts";
 import { KEY_TTL_SECONDS, resolveSessionCutoff, signingKey } from "./signing-key.ts";
 
@@ -73,7 +87,7 @@ export function mountGateOnContext(context: GateMountContext, options: GateOptio
 }
 
 /** Options for the {@link authGate} plugin (all resolvable from env - see below). */
-export interface AuthGateConfig extends BasePluginConfig {
+export interface AuthGateConfig extends BasePluginConfig, AuthStorageConfig {
   /** Allow-list patterns (domain / glob / `/regex/`). Empty = allow nobody. Env TUNNEL_AUTH_ALLOW. */
   allow?: string | string[];
   /**
@@ -133,6 +147,11 @@ export interface AuthGateConfig extends BasePluginConfig {
    * different delivery path.
    */
   sendCode?: (email: string, code: string, opts: SendCodeOptions) => Promise<void>;
+  /**
+   * Identity authorization independent of authentication. Defaults to the
+   * configured allow-list and is re-evaluated for every accepted session.
+   */
+  authorizeIdentity?: AuthorizeIdentity;
   /**
    * The public `<subdomain>.<server>` that identifies portr traffic by its `Host`
    * header. Only requests whose `Host` matches this are gated; everything else
@@ -185,6 +204,8 @@ export interface ResolvedAuthGateConfig {
   forwardHeaders: string[];
   /** Run OPEN with no gate. */
   insecure: boolean;
+  storage: AuthStorageMode;
+  sqlitePath?: string;
 }
 
 const DEFAULTS = {
@@ -204,6 +225,12 @@ const DEFAULTS = {
 
 /** Merge {@link AuthGateConfig} over env over defaults into a resolved config. */
 export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateConfig {
+  const storage = authStorage.resolveAuthStorageConfig({
+    storage:
+      config.storage ??
+      (coreConfig.text("AUTH_STORAGE", TUNNEL_CONFIG) as AuthStorageMode | undefined),
+    sqlitePath: config.sqlitePath ?? coreConfig.text("AUTH_SQLITE_PATH", TUNNEL_CONFIG),
+  });
   return {
     // Both sources are unioned rather than one overriding: a deployment-wide
     // TUNNEL_AUTH_ALLOW and a per-invocation `--allow` should both grant access.
@@ -237,29 +264,27 @@ export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateC
       ...string.parseList(coreConfig.text("FORWARD_HEADERS", TUNNEL_CONFIG)),
     ],
     insecure: coreConfig.boolean(config.insecure, "INSECURE", TUNNEL_CONFIG) ?? false,
+    storage: storage.mode,
+    sqlitePath: storage.sqlitePath,
   };
 }
 
 /** The handlers the gate middleware calls in-process (returned by {@link AuthGatePlugin.exports}). */
 export interface AuthGateApi {
-  /** Handle a code request. Always resolves `{ ok: true }` (anti-enumeration). */
-  request(email: string, ip: string): Promise<{ ok: true; retryAfter?: number }>;
-  /** Handle a code verification. On success returns the session token to cookie. */
-  verify(
-    email: string,
-    code: string,
-    ip: string,
-  ): Promise<{ ok: boolean; token?: string; retryAfter?: number }>;
-  /** Resolve the authenticated email for a session token, or undefined. */
-  session(token: string | undefined): Promise<string | undefined>;
-  /** Session TTL in seconds (for the cookie Max-Age). */
-  readonly sessionTtlSeconds: number;
-  /** The gate status payload (`enabled` is always true when this plugin runs). */
-  status(token: string | undefined): Promise<AuthStatus>;
+  /** Better Auth and compatibility routes under `/api/email/auth/*`. */
+  handler(request: Request): Promise<Response>;
+  /** Resolve the authorized email for request headers, or undefined. */
+  session(headers: Headers): Promise<string | undefined>;
+  /** The gate status payload. */
+  status(headers: Headers): Promise<AuthStatus>;
+  /** Whether the runtime exposes passkey enrollment and authentication. */
+  readonly passkeysEnabled: boolean;
+  /** Close auth storage owned by this runtime. */
+  close(): Promise<void>;
 }
 
 /**
- * AppKit plugin owning the email-OTP gate. On `setup()` it registers the login
+ * AppKit plugin adapting `@dbx-tools/auth` to tunnel traffic. On `setup()` it registers the login
  * routes (`/api/email/auth/*`) and a gating middleware on the app's OWN Express
  * server via `this.context`, so a public portr caller must prove an email before
  * reaching the app's `/api/*` - see `./gate`. Front-door (platform) traffic and
@@ -269,29 +294,74 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
   static manifest = {
     name: "authGate",
     displayName: "Auth Gate",
-    description: "Email one-time-password access gate for a public tunnel.",
+    description: "Better Auth email OTP and passkey access gate for a public tunnel.",
     stability: "beta",
-    resources: { required: [], optional: [] },
+    resources: {
+      required: [],
+      optional: [
+        {
+          type: ResourceType.POSTGRES,
+          alias: "auth",
+          resourceKey: "auth-database",
+          description: "Durable users, sessions, OTP records, and passkeys.",
+          permission: "CAN_CONNECT_AND_CREATE",
+          fields: {
+            instance_name: { env: "LAKEBASE_INSTANCE_NAME" },
+            database_name: { env: "PGDATABASE" },
+          },
+        },
+      ],
+    },
   } satisfies PluginManifest<"authGate">;
 
   private resolved!: ResolvedAuthGateConfig;
-  private codes!: CodeStore;
-  // Requesting a code is email-spam-prone; verifying is a brute-force surface.
-  // Per-email AND per-IP so neither axis alone is a bypass.
-  private readonly requestLimiter = new RateLimiter(5, 15 * 60 * 1000);
-  private readonly verifyLimiter = new RateLimiter(10, 15 * 60 * 1000);
+  private runtime?: PasswordlessAuthRuntime;
+
+  static getResourceRequirements(config: AuthGateConfig): ResourceRequirement[] {
+    if (authStorage.resolveAuthStorageConfig(config).mode !== "lakebase") return [];
+    return [
+      {
+        type: ResourceType.POSTGRES,
+        alias: "auth",
+        resourceKey: "auth-database",
+        description: "Durable users, sessions, OTP records, and passkeys.",
+        permission: "CAN_CONNECT_AND_CREATE",
+        fields: {
+          instance_name: { env: "LAKEBASE_INSTANCE_NAME" },
+          database_name: { env: "PGDATABASE" },
+        },
+        required: true,
+      },
+    ];
+  }
 
   override async setup(): Promise<void> {
     this.resolved = resolveAuthGateConfig(this.config);
-    this.codes = new CodeStore(this.resolved.codeTtlSeconds, this.resolved.maxAttempts);
-    // Resolve the signing key HERE rather than lazily on the first sign-in, so a
-    // cache that cannot hold it (and the resulting "sessions won't survive a
-    // restart" warning) shows up in the startup log, not hours later.
-    const { cutoffMs } = await signingKey(this.resolved.sessionCutoffMs);
 
     if (this.resolved.insecure) {
-      logger.warn("insecure mode - the tunnel runs OPEN with no email-OTP gate");
+      logger.warn("insecure mode - the tunnel runs OPEN with no auth gate");
     } else {
+      const lakebasePlugin = appkitPlugin.instance(this.context, lakebase);
+      const storage = await authStorage.createAuthStorage(
+        this.resolved,
+        lakebasePlugin?.exports().pool,
+      );
+      const { key } = await signingKey(this.resolved.sessionCutoffMs);
+      this.runtime = await passwordlessAuth.createPasswordlessAuth({
+        storage,
+        baseURL: authOrigin(this.resolved.publicDomain),
+        basePath: "/api/email/auth",
+        appName: this.resolved.brandName,
+        secret: Buffer.from(key).toString("base64url"),
+        sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+        sessionCutoffMs: this.resolved.sessionCutoffMs,
+        codeTtlSeconds: this.resolved.codeTtlSeconds,
+        maxAttempts: this.resolved.maxAttempts,
+        authorizeIdentity: (email) => this.authorizeIdentity(email),
+        sendCode: (email, code, options) => this.sendCode(email, code, options),
+        subject: this.resolved.subject,
+        message: this.resolved.message,
+      });
       // `server()` is deferred, so it does not exist during this plugin's setup.
       // At `setup:complete` the Express app exists but has not injected plugin
       // routes or static handling yet, which is the one point the gate can mount
@@ -300,7 +370,7 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
         this.mountGateRoutes();
         // Fail fast once the sibling email plugin has primed its transport: a
         // gate that cannot email a code lets nobody in.
-        await ensureEmailAvailable();
+        if (!this.config.sendCode) await ensureEmailAvailable();
       });
     }
 
@@ -309,10 +379,18 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
       sessionTtlSeconds: this.resolved.sessionTtlSeconds,
       publicDomain: this.resolved.publicDomain ?? null,
       insecure: this.resolved.insecure,
-      ...object.optional("sessionCutoff", cutoffMs > 0 ? new Date(cutoffMs).toISOString() : null),
+      storage: this.resolved.storage,
+      sessionCutoff:
+        this.resolved.sessionCutoffMs > 0
+          ? new Date(this.resolved.sessionCutoffMs).toISOString()
+          : null,
     });
   }
 
+  async shutdown(): Promise<void> {
+    await this.runtime?.close();
+  }
+
   /**
    * Register the login routes (`/api/email/auth/*`) and the gating middleware on
    * the app's OWN Express server. At `setup:complete`, the deferred server plugin
@@ -323,7 +401,7 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
   private mountGateRoutes(): void {
     const context = this.context;
     if (!context) {
-      logger.warn("no plugin context - the OTP gate cannot mount its routes");
+      logger.warn("no plugin context - the auth gate cannot mount its routes");
       return;
     }
     mountGateOnContext(context, {
@@ -338,62 +416,33 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
     return this.config.sendCode ?? defaultSendCode;
   }
 
+  private authorizeIdentity(email: string): boolean | Promise<boolean> {
+    if (this.config.authorizeIdentity) return this.config.authorizeIdentity(email);
+    return looksLikeEmail(email) && matchesAllowlist(email, this.resolved.allow);
+  }
+
   override exports(): AuthGateApi {
+    const runtime = this.runtime;
     return {
-      sessionTtlSeconds: this.resolved.sessionTtlSeconds,
-      request: (email, ip) => this.handleRequest(email, ip),
-      verify: (email, code, ip) => this.handleVerify(email, code, ip),
-      session: (token) => verifySession(token),
-      status: async (token) => ({
-        authenticated: Boolean(await verifySession(token)),
-        email: (await verifySession(token)) ?? undefined,
-        enabled: true,
-      }),
+      passkeysEnabled: runtime?.passkeysEnabled ?? false,
+      handler: (request) =>
+        runtime?.handler(request) ?? Promise.resolve(new Response("Not Found", { status: 404 })),
+      session: (headers) => runtime?.session(headers) ?? Promise.resolve(undefined),
+      status: (headers) =>
+        runtime?.status(headers) ??
+        Promise.resolve({ authenticated: false, enabled: false, passkeysEnabled: false }),
+      close: () => runtime?.close() ?? Promise.resolve(),
     };
   }
+}
 
-  private async handleRequest(
-    email: string,
-    ip: string,
-  ): Promise<{ ok: true; retryAfter?: number }> {
-    const address = email.trim().toLowerCase();
-    const byIp = this.requestLimiter.hit(`ip:${ip}`);
-    const byEmail = this.requestLimiter.hit(`email:${address}`);
-    if (!byIp.allowed || !byEmail.allowed) {
-      return { ok: true, retryAfter: byIp.retryAfter ?? byEmail.retryAfter };
-    }
-    if (looksLikeEmail(address) && matchesAllowlist(address, this.resolved.allow)) {
-      const code = await this.codes.issue(address);
-      try {
-        await this.sendCode(address, code, {
-          subject: this.resolved.subject,
-          brandName: this.resolved.brandName,
-          message: this.resolved.message,
-          codeTtlSeconds: this.resolved.codeTtlSeconds,
-        });
-      } catch (error) {
-        logger.warn("failed to send OTP email", { error });
-      }
-    }
-    return { ok: true };
-  }
-
-  private async handleVerify(
-    email: string,
-    code: string,
-    ip: string,
-  ): Promise<{ ok: boolean; token?: string; retryAfter?: number }> {
-    const address = email.trim().toLowerCase();
-    const byIp = this.verifyLimiter.hit(`ip:${ip}`);
-    const byEmail = this.verifyLimiter.hit(`email:${address}`);
-    if (!byIp.allowed || !byEmail.allowed) {
-      return { ok: false, retryAfter: byIp.retryAfter ?? byEmail.retryAfter };
-    }
-    if ((await this.codes.verify(address, code.trim())) !== "ok") return { ok: false };
-    this.requestLimiter.reset(`email:${address}`);
-    this.verifyLimiter.reset(`email:${address}`);
-    return { ok: true, token: await signSession(address, this.resolved.sessionTtlSeconds) };
-  }
+function authOrigin(publicDomain?: string): string {
+  const value = string.trimToNull(publicDomain);
+  if (!value) return "http://localhost";
+  if (/^https?:\/\//i.test(value)) return new URL(value).origin;
+  const host = value.split("/")[0]!;
+  const local = host === "localhost" || host.startsWith("localhost:");
+  return `${local ? "http" : "https"}://${host}`;
 }
 
 /** Factory: `authGate({ allow, subject, ... })` for an AppKit `plugins` array. */

package/src/signing-key.ts

@@ -1,5 +1,5 @@
 /**
- * The gate's HS256 session-signing key, persisted in AppKit's cache.
+ * The gate's Better Auth secret, persisted in AppKit's cache.
  *
  * The key decides whether a session COOKIE still verifies, so it must OUTLIVE the
  * process: a per-process `randomBytes(32)` would invalidate every outstanding cookie
@@ -62,7 +62,7 @@ export const KEY_TTL_SECONDS = 30 * 24 * 60 * 60;
 /** Cache-key prefix for the signing key, namespaced away from other cache use. */
 const KEY_PREFIX = "tunnel:auth:signing-key:";
 
-/** Bytes of entropy in a generated key (256-bit, matching HS256's hash width). */
+/** Bytes of entropy in a generated Better Auth secret. */
 const KEY_BYTES = 32;
 
 /** What the cache stores: the key plus when it was minted, for observability. */
@@ -176,7 +176,7 @@ let pending: Promise<SigningKey> | undefined;
  * plugin's `setup()` passes its resolved value there, before any request can
  * reach the lazy path.
  *
- * `TUNNEL_AUTH_JWT_SECRET` when set, else the cache-backed key. A cache that is
+ * `TUNNEL_AUTH_JWT_SECRET` when set, else the cache-backed secret. A cache that is
  * unavailable degrades to an ephemeral per-process key (the previous behaviour)
  * rather than refusing to sign: the key only validates an ALREADY-issued session,
  * so losing it costs sessions, never admission - a caller still needs a code