@voidbase-cloud/voidbase 0.1.0

package/src/server/auth-extra.ts

@@ -0,0 +1,113 @@
+// OTP (apis/record_auth_otp_request.go, record_auth_with_otp.go) and superuser impersonation.
+import type { Context, Hono } from "hono";
+import { newAuthToken, requireSuperuser } from "./auth";
+import { recordAuthResponse } from "./auth-response";
+import type { Collection } from "./collections/model";
+import { all, ident, one, run, stmt } from "./db";
+import { ApiError, badRequest, forbidden, notFound } from "./errors";
+import { nowString, randomId } from "./ids";
+import { sendRecordOTP } from "./mail";
+import { hashPassword, verifyPassword } from "./password";
+import { updateRecord, type RecordContext } from "./records/service";
+import { requestHook } from "./hooks/runtime";
+import { CollectionRef, HookRecord } from "./hooks/record";
+import type { AppEnv, Row } from "./types";
+
+type Fe = { code: string; message: string; params?: Record<string, unknown> };
+const REQUIRED: Fe = { code: "validation_required", message: "Cannot be blank." };
+const lengthErr = (min: number, max: number): Fe => ({ code: "validation_length_out_of_range", message: `The length must be between ${min} and ${max}.`, params: { max, min } });
+const validationFailed = (errs: Record<string, Fe>) => new ApiError(400, "An error occurred while validating the submitted data.", Object.fromEntries(Object.entries(errs).sort(([a], [b]) => (a < b ? -1 : 1))) as never);
+const opt = <T>(c: Collection, path: string, fallback: T): T => { let cur: unknown = c.options; for (const k of path.split(".")) { if (!cur || typeof cur !== "object") return fallback; cur = (cur as Record<string, unknown>)[k]; } return (cur === undefined || cur === null ? fallback : cur) as T; };
+async function readBody(c: Context<AppEnv>): Promise<Record<string, unknown>> {
+  try { const v = await c.req.json(); if (!v || typeof v !== "object") throw new Error(); return v as Record<string, unknown>; }
+  catch { throw badRequest("An error occurred while loading the submitted data."); }
+}
+const createdMs = (row: Row) => Date.parse(String(row.created).replace(" ", "T"));
+
+export function mountAuthExtra(app: Hono<AppEnv>, deps: { collection: (c: Context<AppEnv>) => Promise<Collection>; ctx: (c: Context<AppEnv>) => Promise<RecordContext> }) {
+  app.post("/api/collections/:collection/request-otp", async (c) => {
+    const collection = await deps.collection(c);
+    if (!opt<boolean>(collection, "otp.enabled", false)) throw forbidden("The collection is not configured to allow OTP authentication.");
+    const body = await readBody(c);
+    const email = String(body.email ?? "");
+    if (!email) throw validationFailed({ email: REQUIRED });
+    if (email.length > 255) throw validationFailed({ email: lengthErr(1, 255) });
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw validationFailed({ email: { code: "validation_is_email", message: "Must be a valid email address." } });
+    const row = await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE email = ? LIMIT 1`, [email]);
+    const length = Number(opt<number>(collection, "otp.length", 8)) || 8;
+    const durationMs = (Number(opt<number>(collection, "otp.duration", 180)) || 180) * 1000;
+    const digits = crypto.getRandomValues(new Uint8Array(length));
+    const generated = [...digits].map((d) => String(d % 10)).join("");
+    return requestHook("onRecordRequestOTPRequest", c, collection.name, { collection: new CollectionRef(collection), record: row ? HookRecord.fromRow(collection, row) : null, password: generated }, async (ev) => {
+    const pass = String(ev.password ?? generated);
+    if (!row) return c.json({ otpId: randomId() }); // same shape for unknown emails, like PocketBase
+    // too many recent OTPs: reuse the newest instead of issuing another (and drop the expired ones while here)
+    const existing = await all<Row>(c.env.DB, "SELECT * FROM `_otps` WHERE collectionRef = ? AND recordRef = ? ORDER BY created DESC", [collection.id, String(row.id)]);
+    const expired = existing.filter((o) => Date.now() - createdMs(o) > durationMs);
+    if (expired.length) await c.env.DB.batch(expired.map((o) => stmt(c.env.DB, "DELETE FROM `_otps` WHERE id = ?", [o.id])));
+    const recent = existing.filter((o) => Date.now() - createdMs(o) <= durationMs);
+    if (recent.length > 9) return c.json({ otpId: String(existing[0]!.id) });
+    const id = randomId(); const now = nowString();
+    await run(c.env.DB, "INSERT INTO `_otps` (id, collectionRef, recordRef, password, sentTo, created, updated) VALUES (?, ?, ?, ?, '', ?, ?)", [id, collection.id, String(row.id), await hashPassword(pass), now, now]);
+    c.executionCtx.waitUntil((async () => {
+      try {
+        await sendRecordOTP(c.env.DB, collection, row, id, pass);
+        await run(c.env.DB, "UPDATE `_otps` SET sentTo = ?, updated = ? WHERE id = ? AND sentTo = ''", [String(row.email), nowString(), id]);
+      } catch (err) { console.error("voidbase: failed to send OTP email", err); await run(c.env.DB, "DELETE FROM `_otps` WHERE id = ?", [id]); }
+    })());
+    return c.json({ otpId: id });
+    });
+  });
+
+  app.post("/api/collections/:collection/auth-with-otp", async (c) => {
+    const collection = await deps.collection(c);
+    if (!opt<boolean>(collection, "otp.enabled", false)) throw forbidden("The collection is not configured to allow OTP authentication.");
+    const body = await readBody(c);
+    const otpId = String(body.otpId ?? ""), password = String(body.password ?? "");
+    const errs: Record<string, Fe> = {};
+    if (!otpId) errs.otpId = REQUIRED; else if (otpId.length > 255) errs.otpId = lengthErr(1, 255);
+    if (!password) errs.password = REQUIRED; else if (password.length > 71) errs.password = lengthErr(1, 71);
+    if (Object.keys(errs).length) throw validationFailed(errs);
+    const otp = await one<Row>(c.env.DB, "SELECT * FROM `_otps` WHERE id = ? LIMIT 1", [otpId]);
+    if (!otp || otp.collectionRef !== collection.id) throw badRequest("Invalid or expired OTP");
+    const durationMs = (Number(opt<number>(collection, "otp.duration", 180)) || 180) * 1000;
+    if (Date.now() - createdMs(otp) > durationMs) throw badRequest("Invalid or expired OTP");
+    const row = await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [otp.recordRef]);
+    if (!row) throw badRequest("Invalid or expired OTP");
+    // 5 attempts per 180s per record (checkRateLimit "@pb_otp_<id>")
+    const key = `@pb_otp_${row.id}`;
+    const bucket = await one<{ value: string }>(c.env.DB, "SELECT value FROM `_params` WHERE id = ?", [key]);
+    let state = bucket ? (JSON.parse(bucket.value) as { count: number; resetAt: number }) : { count: 0, resetAt: Date.now() + 180_000 };
+    if (state.resetAt < Date.now()) state = { count: 0, resetAt: Date.now() + 180_000 };
+    state.count++;
+    await run(c.env.DB, "INSERT OR REPLACE INTO `_params` (id, value, created, updated) VALUES (?, ?, ?, ?)", [key, JSON.stringify(state), nowString(), nowString()]);
+    if (state.count > 5) throw new ApiError(429, "Too many attempts, please try again later with a new OTP.", {});
+    if (!(await verifyPassword(password, String(otp.password ?? "")))) throw badRequest("Invalid or expired OTP");
+    const ctx = await deps.ctx(c);
+    return requestHook("onRecordAuthWithOTPRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, row), otp }, async () => {
+    await run(c.env.DB, "DELETE FROM `_otps` WHERE id = ?", [otpId]);
+    let fresh = row;
+    if (!row.verified && otp.sentTo && String(row.email) === String(otp.sentTo)) {
+      const patch: Record<string, unknown> = { verified: true };
+      if (!opt<boolean>(collection, "mfa.enabled", false)) { const pw = randomString30(); patch.password = pw; patch.passwordConfirm = pw; }
+      try { await updateRecord({ ...ctx, superuser: true, hookEvent: undefined }, collection, String(row.id), patch, {} as never); fresh = (await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [row.id])) ?? row; }
+      catch (err) { console.error("voidbase: failed to update record verified state after OTP", err); }
+    }
+    return recordAuthResponse(c, { ...ctx, request: { ...ctx.request, context: "otp" } }, collection, fresh, "otp", { body });
+    });
+  });
+
+  app.post("/api/collections/:collection/impersonate/:id", async (c) => {
+    requireSuperuser(c); // RequireSuperuserAuth middleware: 401 anonymous, 403 for other records
+    const collection = await deps.collection(c);
+    const row = await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [c.req.param("id") ?? ""]);
+    if (!row) throw notFound();
+    const body = await readBody(c);
+    const duration = Number(body.duration ?? 0);
+    if (duration < 0) throw validationFailed({ duration: { code: "validation_min_greater_equal_than_required", message: "Must be no less than 0.", params: { threshold: 0 } } });
+    const token = await newAuthToken({ collection, row }, false, duration > 0 ? duration : undefined);
+    const ctx = await deps.ctx(c);
+    return recordAuthResponse(c, ctx, collection, row, "", { token, body });
+  });
+}
+const randomString30 = () => { const chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"; return [...crypto.getRandomValues(new Uint8Array(30))].map((b) => chars[b % chars.length]).join(""); };

package/src/server/auth-flows.ts

@@ -0,0 +1,186 @@
+// Email-driven auth flows (apis/record_auth_{verification,password_reset,email_change}_{request,confirm}.go):
+// request endpoints always answer 204 (unknown emails and resend limits are hidden, like PocketBase), confirm
+// endpoints validate the signed token and apply the change through the record service so hooks and realtime fire.
+import { requestHook } from "./hooks/runtime";
+import { CollectionRef, HookRecord } from "./hooks/record";
+import type { Context, Hono } from "hono";
+import { findAuthRecordByToken } from "./auth";
+import { verifyPassword } from "./password";
+import type { Collection } from "./collections/model";
+import { ident, one, run } from "./db";
+import { ApiError, badRequest, unauthorized, forbidden } from "./errors";
+import { nowString, randomString } from "./ids";
+import { sendRecordChangeEmail, sendRecordPasswordReset, sendRecordVerification } from "./mail";
+import { updateRecord, type RecordContext } from "./records/service";
+import type { AppEnv, Row } from "./types";
+
+type Fe = { code: string; message: string; params?: Record<string, unknown> };
+const REQUIRED: Fe = { code: "validation_required", message: "Cannot be blank." };
+const isEmail = (v: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+const validationFailed = (errs: Record<string, Fe>) => new ApiError(400, "An error occurred while validating the submitted data.", Object.fromEntries(Object.entries(errs).sort(([a], [b]) => (a < b ? -1 : 1))) as never);
+const RESEND_TTL_MS = 2 * 60 * 1000;
+
+async function readBody(c: Context<AppEnv>): Promise<Record<string, unknown>> {
+  try { const v = await c.req.json(); if (!v || typeof v !== "object") throw new Error(); return v as Record<string, unknown>; }
+  catch { throw badRequest("An error occurred while loading the submitted data."); }
+}
+const unverifiedClaims = (token: string): Record<string, unknown> => { try { const p = token.split(".")[1] ?? ""; return JSON.parse(atob(p.replace(/-/g, "+").replace(/_/g, "/"))) as Record<string, unknown>; } catch { return {}; } };
+
+// PocketBase keeps the "already requested" flag in memory for 2 minutes; here it lives in _params so every isolate sees it
+async function resendLimited(db: D1Database, key: string): Promise<boolean> {
+  const row = await one<{ value: string }>(db, "SELECT value FROM `_params` WHERE id = ?", [key]);
+  if (!row) return false;
+  if (Number(row.value) > Date.now()) return true;
+  await run(db, "DELETE FROM `_params` WHERE id = ?", [key]);
+  return false;
+}
+const markResend = (db: D1Database, key: string) => run(db, "INSERT OR REPLACE INTO `_params` (id, value, created, updated) VALUES (?, ?, ?, ?)", [key, String(Date.now() + RESEND_TTL_MS), nowString(), nowString()]);
+const clearResend = (db: D1Database, key: string) => run(db, "DELETE FROM `_params` WHERE id = ?", [key]);
+
+const superCtx = (ctx: RecordContext): RecordContext => ({ ...ctx, superuser: true, hookEvent: undefined, request: { ...ctx.request, context: "default" } });
+const passwordEnabled = (c: Collection) => ((c.options as Record<string, unknown>).passwordAuth as { enabled?: boolean } | undefined)?.enabled !== false;
+const passwordMin = (c: Collection) => { const f = c.fields.find((x) => x.name === "password") as { min?: number } | undefined; return f?.min && f.min > 0 ? f.min : 1; };
+
+export function mountAuthFlows(app: Hono<AppEnv>, deps: { collection: (c: Context<AppEnv>) => Promise<Collection>; ctx: (c: Context<AppEnv>) => Promise<RecordContext> }) {
+  app.post("/api/collections/:collection/request-verification", async (c) => {
+    const collection = await deps.collection(c);
+    if (collection.name === "_superusers") throw badRequest("All superusers are verified by default.");
+    const body = await readBody(c);
+    const email = String(body.email ?? "");
+    if (!email) throw validationFailed({ email: REQUIRED });
+    if (email.length > 255) throw validationFailed({ email: { code: "validation_length_out_of_range", message: "The length must be between 1 and 255.", params: { max: 255, min: 1 } } });
+    if (!isEmail(email)) throw validationFailed({ email: { code: "validation_is_email", message: "Must be a valid email address." } });
+    const row = await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE email = ? LIMIT 1`, [email]);
+    if (!row) return c.body(null, 204);
+    const key = `@limitVerificationEmail_${collection.id}${row.id}`;
+    if (!row.verified && (await resendLimited(c.env.DB, key))) return c.body(null, 204);
+    return requestHook("onRecordRequestVerificationRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, row) }, async () => {
+      if (row.verified) return c.body(null, 204);
+      c.executionCtx.waitUntil((async () => {
+        try { await sendRecordVerification(c.env.DB, collection, row); await markResend(c.env.DB, key); } catch (err) { console.error("voidbase: failed to send verification email", err); }
+      })());
+      return c.body(null, 204);
+    });
+  });
+
+  app.post("/api/collections/:collection/confirm-verification", async (c) => {
+    const collection = await deps.collection(c);
+    if (collection.name === "_superusers") throw badRequest("All superusers are verified by default.");
+    const body = await readBody(c);
+    const token = String(body.token ?? "");
+    if (!token) throw validationFailed({ token: REQUIRED });
+    const claims = unverifiedClaims(token);
+    if (!claims.email) throw validationFailed({ token: { code: "validation_invalid_token_claims", message: "Missing email token claim." } });
+    const auth = await findAuthRecordByToken(c.env.DB, token, "verification");
+    if (!auth) throw validationFailed({ token: { code: "validation_invalid_token", message: "Invalid or expired token." } });
+    if (auth.collection.id !== collection.id) throw validationFailed({ token: { code: "validation_token_collection_mismatch", message: "The provided token is for different auth collection." } });
+    if (String(auth.row.email ?? "") !== String(claims.email)) throw validationFailed({ token: { code: "validation_token_email_mismatch", message: "The record email doesn't match with the requested token claims." } });
+    return requestHook("onRecordConfirmVerificationRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, auth.row) }, async () => {
+      if (!auth.row.verified) {
+        const patch: Record<string, unknown> = { verified: true };
+        if (!passwordEnabled(collection)) { const pw = randomString(30); patch.password = pw; patch.passwordConfirm = pw; }
+        try { await updateRecord(superCtx(await deps.ctx(c)), collection, String(auth.row.id), patch, {} as never); }
+        catch (err) { if (err instanceof ApiError) throw new ApiError(400, "An error occurred while saving the verified state.", err.data as never); throw err; }
+      }
+      await clearResend(c.env.DB, `@limitVerificationEmail_${collection.id}${auth.row.id}`);
+      return c.body(null, 204);
+    });
+  });
+
+  app.post("/api/collections/:collection/request-password-reset", async (c) => {
+    const collection = await deps.collection(c);
+    if (!passwordEnabled(collection)) throw badRequest("The collection is not configured to allow password authentication.");
+    const body = await readBody(c);
+    const email = String(body.email ?? "");
+    if (!email) throw validationFailed({ email: REQUIRED });
+    if (email.length > 255) throw validationFailed({ email: { code: "validation_length_out_of_range", message: "The length must be between 1 and 255.", params: { max: 255, min: 1 } } });
+    if (!isEmail(email)) throw validationFailed({ email: { code: "validation_is_email", message: "Must be a valid email address." } });
+    const row = await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE email = ? LIMIT 1`, [email]);
+    if (!row) return c.body(null, 204);
+    const key = `@limitPasswordResetEmail_${collection.id}${row.id}`;
+    if (await resendLimited(c.env.DB, key)) return c.body(null, 204);
+    return requestHook("onRecordRequestPasswordResetRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, row) }, async () => {
+      c.executionCtx.waitUntil((async () => {
+        try { await sendRecordPasswordReset(c.env.DB, collection, row); await markResend(c.env.DB, key); } catch (err) { console.error("voidbase: failed to send password reset email", err); }
+      })());
+      return c.body(null, 204);
+    });
+  });
+
+  app.post("/api/collections/:collection/confirm-password-reset", async (c) => {
+    const collection = await deps.collection(c);
+    const body = await readBody(c);
+    const token = String(body.token ?? ""), password = String(body.password ?? ""), confirm = String(body.passwordConfirm ?? "");
+    const errs: Record<string, Fe> = {};
+    let auth: Awaited<ReturnType<typeof findAuthRecordByToken>> = null;
+    if (!token) errs.token = REQUIRED;
+    else {
+      auth = await findAuthRecordByToken(c.env.DB, token, "passwordReset");
+      if (!auth) errs.token = { code: "validation_invalid_token", message: "Invalid or expired token." };
+      else if (auth.collection.id !== collection.id) errs.token = { code: "validation_token_collection_mismatch", message: "The provided token is for different auth collection." };
+    }
+    const min = passwordMin(collection);
+    if (!password) errs.password = REQUIRED; else if (password.length < min || password.length > 255) errs.password = { code: "validation_length_out_of_range", message: `The length must be between ${min} and 255.`, params: { max: 255, min } };
+    if (!confirm) errs.passwordConfirm = REQUIRED; else if (confirm !== password) errs.passwordConfirm = { code: "validation_values_mismatch", message: "Values don't match." };
+    if (Object.keys(errs).length) throw validationFailed(errs);
+    const found = auth!;
+    return requestHook("onRecordConfirmPasswordResetRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, found.row) }, async () => {
+      const patch: Record<string, unknown> = { password, passwordConfirm: confirm };
+      if (!found.row.verified && String(found.row.email ?? "") === String(unverifiedClaims(token).email ?? "")) patch.verified = true;
+      try { await updateRecord(superCtx(await deps.ctx(c)), collection, String(found.row.id), patch, {} as never); }
+      catch (err) { if (err instanceof ApiError) throw new ApiError(400, "Failed to set new password.", err.data as never); throw err; }
+      await clearResend(c.env.DB, `@limitPasswordResetEmail_${collection.id}${found.row.id}`);
+      return c.body(null, 204);
+    });
+  });
+
+  app.post("/api/collections/:collection/request-email-change", async (c) => {
+    const collection = await deps.collection(c);
+    if (collection.name === "_superusers") throw badRequest("All superusers can change their emails directly.");
+    const auth = c.get("auth");
+    if (!auth) throw unauthorized("The request requires valid record authorization token.");
+    if (auth.collection.id !== collection.id) throw forbidden(`The request requires auth record from ${auth.collection.name} collection.`); // RequireSameCollectionContextAuth
+    const body = await readBody(c);
+    const newEmail = String(body.newEmail ?? "");
+    if (!newEmail) throw validationFailed({ newEmail: REQUIRED });
+    if (newEmail.length > 255) throw validationFailed({ newEmail: { code: "validation_length_out_of_range", message: "The length must be between 1 and 255.", params: { max: 255, min: 1 } } });
+    if (!isEmail(newEmail)) throw validationFailed({ newEmail: { code: "validation_is_email", message: "Must be a valid email address." } });
+    if (newEmail === String(auth.row.email ?? "")) throw validationFailed({ newEmail: { code: "validation_not_in_invalid", message: "Must not be in list." } });
+    const taken = await one<Row>(c.env.DB, `SELECT id FROM ${ident(collection.name)} WHERE email = ? LIMIT 1`, [newEmail]);
+    if (taken && taken.id !== auth.row.id) throw validationFailed({ newEmail: { code: "validation_invalid_new_email", message: "Invalid new email address." } });
+    return requestHook("onRecordRequestEmailChangeRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, auth.row), newEmail }, async (ev) => {
+      try { await sendRecordChangeEmail(c.env.DB, collection, auth.row, String(ev.newEmail ?? newEmail)); }
+      catch (err) { throw badRequest("Failed to request email change."); void err; }
+      return c.body(null, 204);
+    });
+  });
+
+  app.post("/api/collections/:collection/confirm-email-change", async (c) => {
+    const collection = await deps.collection(c);
+    if (collection.name === "_superusers") throw badRequest("All superusers can change their emails directly.");
+    const body = await readBody(c);
+    const token = String(body.token ?? ""), password = String(body.password ?? "");
+    const errs: Record<string, Fe> = {};
+    let auth: Awaited<ReturnType<typeof findAuthRecordByToken>> = null; let newEmail = "";
+    const parse = async (): Promise<Fe | null> => {
+      newEmail = String(unverifiedClaims(token).newEmail ?? "");
+      if (!newEmail) return { code: "validation_invalid_token_payload", message: "Invalid token payload - newEmail must be set." };
+      auth = await findAuthRecordByToken(c.env.DB, token, "emailChange");
+      if (!auth) return { code: "validation_invalid_token", message: "Invalid or expired token." };
+      if (auth.collection.id !== collection.id) return { code: "validation_token_collection_mismatch", message: "The provided token is for different auth collection." };
+      if (await one(c.env.DB, `SELECT id FROM ${ident(collection.name)} WHERE email = ? LIMIT 1`, [newEmail])) return { code: "validation_invalid_token_email", message: "The new email address is invalid." };
+      return null;
+    };
+    if (!token) errs.token = REQUIRED; else { const e = await parse(); if (e) errs.token = e; }
+    if (!password) errs.password = REQUIRED;
+    else if (password.length > 100) errs.password = { code: "validation_length_out_of_range", message: "The length must be between 1 and 100.", params: { max: 100, min: 1 } };
+    else if (!auth || !(await verifyPassword(password, String((auth as { row: Row }).row.password ?? "")))) errs.password = { code: "validation_invalid_password", message: "Missing or invalid auth record password." };
+    if (Object.keys(errs).length) throw validationFailed(errs);
+    const found = auth! as { row: Row };
+    return requestHook("onRecordConfirmEmailChangeRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, found.row), newEmail }, async (ev) => {
+      try { await updateRecord(superCtx(await deps.ctx(c)), collection, String(found.row.id), { email: String(ev.newEmail ?? newEmail), verified: true }, {} as never); }
+      catch (err) { if (err instanceof ApiError) throw new ApiError(400, "Failed to confirm email change.", err.data as never); throw err; }
+      return c.body(null, 204);
+    });
+  });
+}

package/src/server/auth-response.ts

@@ -0,0 +1,111 @@
+// apis/record_helpers.go recordAuthResponse: every successful authentication (password, OAuth2, OTP, passkey,
+// refresh, impersonate) ends here. Superuser IP allowlist, the collection's authRule, OnRecordAuthRequest, the
+// MFA handshake (401 {mfaId} until a second method confirms), record export with email, expand, login alert.
+import type { Context } from "hono";
+import { newAuthToken } from "./auth";
+import type { Collection } from "./collections/model";
+import { one, run } from "./db";
+import { badRequest, forbidden } from "./errors";
+import { HookRecord } from "./hooks/record";
+import { trigger } from "./hooks/runtime";
+import { nowString, randomId } from "./ids";
+import { sendRecordAuthAlert } from "./mail";
+import { enrich, recordMatchesRule, type RecordContext } from "./records/service";
+import { rowToValues } from "./records/values";
+import { loadSettings } from "./settings";
+import type { AppEnv, Row } from "./types";
+
+const opt = <T>(c: Collection, path: string, fallback: T): T => { let cur: unknown = c.options; for (const k of path.split(".")) { if (!cur || typeof cur !== "object") return fallback; cur = (cur as Record<string, unknown>)[k]; } return (cur === undefined || cur === null ? fallback : cur) as T; };
+
+export interface AuthResponseOptions { token?: string; body?: Record<string, unknown>; meta?: Record<string, unknown> }
+
+export async function recordAuthResponse(c: Context<AppEnv>, ctx: RecordContext, collection: Collection, row: Row, method: string, options: AuthResponseOptions = {}): Promise<Response> {
+  const token = options.token ?? (await newAuthToken({ collection, row }));
+  const db = c.env.DB;
+  if (collection.name === "_superusers") {
+    const settings = await loadSettings(db);
+    if (settings.superuserIPs.length && !ipInList(settings.superuserIPs, realIPWith(settings, c))) throw forbidden();
+  }
+  // authRule: "" lets everyone in, a filter restricts, null (superusers only) blocks regular logins
+  const rawRule = (collection.options as Record<string, unknown>).authRule;
+  const authRule = rawRule === undefined ? "" : (rawRule as string | null);
+  if (authRule === null) { if (!ctx.superuser) throw forbidden("The request doesn't satisfy the collection requirements to authenticate."); }
+  else if (authRule.trim() !== "") {
+    const ok = await recordMatchesRule(ctx, collection, authRule, rowToValues(collection, row));
+    if (!ok) throw forbidden("The request doesn't satisfy the collection requirements to authenticate.");
+  }
+
+  const rec = HookRecord.fromRow(collection, row);
+  const ev = { app: undefined as unknown, collection, record: rec, token, meta: options.meta, authMethod: method, written: false, next: async () => undefined as unknown };
+  let response: Response | null = null;
+  await trigger("onRecordAuthRequest", ev, collection.name, async () => {
+    const mfaId = await checkMFA(c, ctx, collection, row, method, options.body ?? {});
+    if (mfaId) { response = c.json({ mfaId }, 401); return; }
+    const authCtx: RecordContext = { ...ctx, auth: { collection, row }, superuser: ctx.superuser || collection.name === "_superusers" };
+    const own = { ...authCtx, request: { ...authCtx.request, auth: { collection, row } } };
+    const [json] = await enrich(own, collection, [row], { expand: c.req.query("expand") ?? "" });
+    const exported = json as Record<string, unknown>;
+    if (!("email" in exported)) exported.email = row.email ?? ""; // IgnoreEmailVisibility(true)
+    if (method !== "" && opt<boolean>(collection, "authAlert.enabled", false)) {
+      try { await authAlert(c, collection, row); } catch (err) { console.warn("voidbase: failed to send login alert", err); }
+    }
+    const result: Record<string, unknown> = {};
+    if (ev.meta !== undefined && ev.meta !== null) result.meta = ev.meta;
+    result.record = sortKeys(exported);
+    result.token = ev.token;
+    response = c.json(result);
+  });
+  return response ?? c.body(null, 204);
+}
+
+const sortKeys = (o: Record<string, unknown>) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+
+export { realIP } from "./hardening";
+import { ipInList, realIP, realIPWith } from "./hardening";
+
+// checkMFA: first method opens an MFA session (401 {mfaId}); a *different* method within the duration closes it
+async function checkMFA(c: Context<AppEnv>, ctx: RecordContext, collection: Collection, row: Row, method: string, body: Record<string, unknown>): Promise<string> {
+  if (!opt<boolean>(collection, "mfa.enabled", false) || method === "") return "";
+  const rule = opt<string>(collection, "mfa.rule", "");
+  if (rule.trim() !== "") {
+    let wants = true;
+    try { wants = await recordMatchesRule(ctx, collection, rule, rowToValues(collection, row)); } catch { throw badRequest("Failed to authenticate."); }
+    if (!wants) return "";
+  }
+  const mfaId = c.req.query("mfaId") || String(body.mfaId ?? "");
+  const db = c.env.DB;
+  if (!mfaId) {
+    const id = randomId(); const now = nowString();
+    await run(db, "INSERT INTO `_mfas` (id, collectionRef, recordRef, method, created, updated) VALUES (?, ?, ?, ?, ?, ?)", [id, collection.id, String(row.id), method, now, now]);
+    return id;
+  }
+  const mfa = await one<Row>(db, "SELECT * FROM `_mfas` WHERE id = ? LIMIT 1", [mfaId]);
+  const duration = Number(opt<number>(collection, "mfa.duration", 1800)) * 1000;
+  if (!mfa || Date.now() - Date.parse(String(mfa.created).replace(" ", "T")) > duration) {
+    if (mfa) await run(db, "DELETE FROM `_mfas` WHERE id = ?", [mfaId]);
+    throw badRequest("Invalid or expired MFA session.");
+  }
+  if (mfa.recordRef !== row.id || mfa.collectionRef !== collection.id) throw badRequest("Invalid MFA session.");
+  if (mfa.method === method) throw badRequest("A different authentication method is required.");
+  await run(db, "DELETE FROM `_mfas` WHERE id = ?", [mfaId]);
+  return "";
+}
+
+// authAlert: fingerprint = hash(ip + user agent); a new fingerprint on a record with previous origins mails the alert
+async function authAlert(c: Context<AppEnv>, collection: Collection, row: Row) {
+  const db = c.env.DB;
+  const ip = await realIP(c);
+  let ua = c.req.header("User-Agent") ?? "";
+  if (ua.length > 200) ua = ua.slice(0, 200) + "...";
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(ip + ua)));
+  const fingerprint = [...digest.slice(0, 16)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  const info = `${nowString()} - ${ip} ${ua}`;
+  const origins = await (await import("./db")).all<Row>(db, "SELECT * FROM `_authOrigins` WHERE collectionRef = ? AND recordRef = ?", [collection.id, String(row.id)]);
+  const isFirstLogin = origins.length === 0;
+  const known = origins.some((o) => o.fingerprint === fingerprint);
+  if (!known) {
+    const now = nowString();
+    await run(db, "INSERT INTO `_authOrigins` (id, collectionRef, recordRef, fingerprint, created, updated) VALUES (?, ?, ?, ?, ?, ?)", [randomId(), collection.id, String(row.id), fingerprint, now, now]);
+    if (!isFirstLogin && row.email) await sendRecordAuthAlert(db, collection, row, info);
+  }
+}

package/src/server/auth.ts

@@ -0,0 +1,187 @@
+import { parseFields, pick } from "./records/picker";
+import type { Context } from "hono";
+import { findCollection, isAuth, option, SUPERUSERS, type Collection } from "./collections/model";
+import { one } from "./db";
+import { ident } from "./db";
+import { ApiError, badRequest, forbidden, unauthorized, V, validationFailed, type FieldErrors } from "./errors";
+import { decodeJWT, signJWT, verifyJWT } from "./jwt";
+import { verifyPassword } from "./password";
+import { recordToJSON } from "./records/json";
+import { buildAuthURL, providerConfig, s256Challenge } from "./oauth2";
+import catalog from "./collections/oauth2-providers.json";
+import { randomString } from "./ids";
+import { recordAuthResponse } from "./auth-response";
+import { requestHook } from "./hooks/runtime";
+import { CollectionRef, HookRecord } from "./hooks/record";
+import type { AppEnv, AuthRecord, Row } from "./types";
+
+export function tokenFromRequest(req: Request): string {
+  const h = req.headers.get("Authorization") ?? "";
+  return /^bearer /i.test(h) ? h.slice(7) : h;
+}
+
+// Resolve the auth record for a token: decode, load collection + record, verify with tokenKey + collection secret.
+export async function findAuthRecordByToken(db: D1Database, token: string, type = "auth"): Promise<AuthRecord | null> {
+  if (!token) return null;
+  const claims = decodeJWT(token);
+  if (!claims || claims.type !== type || typeof claims.id !== "string" || typeof claims.collectionId !== "string") return null;
+  const collection = await findCollection(db, claims.collectionId);
+  if (!collection || !isAuth(collection)) return null;
+  const row = await one(db, `SELECT * FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [claims.id]);
+  if (!row) return null;
+  // each token type is signed with its own collection secret (core/record_tokens.go)
+  const optionKey = ({ auth: "authToken", verification: "verificationToken", passwordReset: "passwordResetToken", emailChange: "emailChangeToken", file: "fileToken" } as Record<string, string>)[type] ?? "authToken";
+  const secret = option<string>(collection, `${optionKey}.secret`, "");
+  const verified = await verifyJWT(token, String(row.tokenKey ?? "") + secret);
+  return verified ? { collection, row } : null;
+}
+
+export async function loadAuth(c: Context<AppEnv>): Promise<AuthRecord | null> {
+  const token = tokenFromRequest(c.req.raw);
+  return token ? findAuthRecordByToken(c.env.DB, token) : null;
+}
+
+export const isSuperuser = (auth: AuthRecord | null | undefined) => !!auth && auth.collection.name === SUPERUSERS;
+
+export function requireAuth(c: Context<AppEnv>): AuthRecord {
+  const auth = c.get("auth");
+  if (!auth) throw unauthorized("The request requires valid record authorization token.");
+  return auth;
+}
+
+export function requireSuperuser(c: Context<AppEnv>): AuthRecord {
+  const auth = c.get("auth");
+  if (!auth) throw unauthorized("The request requires valid record authorization token.");
+  if (!isSuperuser(auth)) throw forbidden("The authorized record is not allowed to perform this action.");
+  return auth;
+}
+
+export async function newAuthToken(auth: AuthRecord, refreshable = true, durationOverride?: number): Promise<string> {
+  const secret = option<string>(auth.collection, "authToken.secret", "");
+  const duration = durationOverride ?? option<number>(auth.collection, "authToken.duration", 604800);
+  const key = String(auth.row.tokenKey ?? "") + secret;
+  if (!key) throw new ApiError(500, "Missing signing key.");
+  return signJWT({ collectionId: auth.collection.id, id: String(auth.row.id), refreshable, type: "auth" }, key, duration);
+}
+
+export async function authResponse(auth: AuthRecord, meta?: unknown) {
+  const token = await newAuthToken(auth);
+  const record = recordToJSON(auth.collection, auth.row, { auth, own: true });
+  return meta === undefined ? { record, token } : { meta, record, token };
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+async function readBody(c: Context<AppEnv>): Promise<Record<string, unknown>> {
+  const ct = c.req.header("content-type") ?? "";
+  try {
+    if (ct.includes("application/json")) return (await c.req.json()) ?? {};
+    if (ct.includes("form")) return Object.fromEntries((await c.req.formData()).entries());
+    const text = await c.req.text();
+    return text ? JSON.parse(text) : {};
+  } catch {
+    throw badRequest("An error occurred while loading the submitted data.");
+  }
+}
+
+// POST /api/collections/:collection/auth-with-password
+export async function authWithPassword(c: Context<AppEnv>, collection: Collection) {
+  if (!isAuth(collection)) throw c.get("auth") ? forbidden() : unauthorized("The request requires valid record authorization token.");
+  if (!option<boolean>(collection, "passwordAuth.enabled", false)) {
+    throw forbidden("The collection is not configured to allow password authentication.");
+  }
+  const body = await readBody(c);
+  const identity = String(body.identity ?? "");
+  const password = String(body.password ?? "");
+  const identityField = body.identityField ? String(body.identityField) : "";
+  const errors: FieldErrors = {};
+  if (!identity) errors.identity = V.required;
+  else if (identity.length > 255) errors.identity = V.length(1, 255);
+  if (!password) errors.password = V.required;
+  else if (password.length > 255) errors.password = V.length(1, 255);
+  const identityFields = option<string[]>(collection, "passwordAuth.identityFields", ["email"]);
+  if (identityField && !identityFields.includes(identityField)) {
+    errors.identityField = { code: "validation_in_invalid", message: "Must be a valid value." };
+  }
+  if (Object.keys(errors).length) throw validationFailed(errors);
+
+  let row: Row | null = null;
+  const candidates = identityField ? [identityField] : identityFields;
+  for (const name of candidates) {
+    if (name === "email" && !EMAIL_RE.test(identity)) continue;
+    row = await one(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE ${ident(name)} = ? LIMIT 1`, [identity]);
+    if (row) break;
+  }
+  const { recordContextFor } = await import("./app");
+  const ctx = await recordContextFor(c);
+  const original = row ? HookRecord.fromRow(collection, row) : null;
+  return requestHook("onRecordAuthWithPasswordRequest", c, collection.name, { collection: new CollectionRef(collection), record: original, identity, password, identityField }, async (ev) => {
+    // hooks may swap e.record; the password is checked against whatever record they leave
+    let target = row;
+    if (ev.record && ev.record !== original) target = await one(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [String((ev.record as HookRecord).id)]);
+    else if (!ev.record) target = null;
+    const ok = target ? await verifyPassword(String(ev.password ?? ""), String(target.password ?? "")) : await dummyPasswordCheck();
+    if (!target || !ok) throw badRequest("Failed to authenticate.");
+    return recordAuthResponse(c, { ...ctx, request: { ...ctx.request, context: "password" } }, collection, target, "password", { body });
+  });
+}
+
+// Burn roughly the same time as a real check so missing accounts are not distinguishable by timing.
+async function dummyPasswordCheck(): Promise<false> {
+  await verifyPassword("dummy", "$2a$10$KBcKN2Yv4i5cs/Q1I.nfkeBXf1RqxyRmiPJPLHxCXDqmlt6SlP4Ea");
+  return false;
+}
+
+// POST /api/collections/:collection/auth-refresh
+export async function authRefresh(c: Context<AppEnv>, collection: Collection) {
+  const auth = c.get("auth");
+  if (!auth) throw unauthorized("The request requires valid record authorization token.");
+  // RequireSameCollectionContextAuth names the token's own collection in its message
+  if (auth.collection.id !== collection.id) throw forbidden(`The request requires auth record from ${auth.collection.name} collection.`);
+  const { recordContextFor } = await import("./app");
+  const ctx = await recordContextFor(c);
+  return requestHook("onRecordAuthRefreshRequest", c, collection.name, { collection: new CollectionRef(collection), record: HookRecord.fromRow(collection, auth.row) }, () => recordAuthResponse(c, ctx, collection, auth.row, "", {}));
+}
+
+// GET /api/collections/:collection/auth-methods
+const providerLogo = (name: string) => (catalog as { name: string; logo: string }[]).find((p) => p.name === name)?.logo ?? "";
+
+export async function authMethods(c: Context<AppEnv>, collection: Collection) {
+  if (!isAuth(collection)) throw badRequest("The collection is not configured to allow authentication.");
+  const identityFields = option<string[]>(collection, "passwordAuth.identityFields", ["email"]);
+  const mfaEnabled = option<boolean>(collection, "mfa.enabled", false);
+  const otpEnabled = option<boolean>(collection, "otp.enabled", false);
+  const oauth2Enabled = option<boolean>(collection, "oauth2.enabled", false);
+  const providers: Record<string, unknown>[] = [];
+  if (oauth2Enabled) {
+    for (const cfg of option<{ name: string }[]>(collection, "oauth2.providers", [])) {
+      const p = providerConfig(collection, cfg.name);
+      if (!p || !p.authURL || !p.tokenURL) continue; // PocketBase skips providers it cannot init
+      const info: Record<string, unknown> = { name: p.name, displayName: p.displayName, logo: providerLogo(p.name), state: randomString(30), authURL: "", authUrl: "", codeVerifier: "", codeChallenge: "", codeChallengeMethod: "" };
+      const extra: Record<string, string> = {};
+      if (p.name === "apple") extra.response_mode = "form_post";
+      if (p.pkce) {
+        info.codeVerifier = randomString(43);
+        info.codeChallenge = await s256Challenge(String(info.codeVerifier));
+        info.codeChallengeMethod = "S256";
+        extra.code_challenge = String(info.codeChallenge); extra.code_challenge_method = "S256";
+      }
+      info.authURL = buildAuthURL(p, String(info.state), extra) + "&redirect_uri="; // empty redirect_uri so clients can append theirs
+      info.authUrl = info.authURL;
+      providers.push(info);
+    }
+  }
+  const passwordEnabled = option<boolean>(collection, "passwordAuth.enabled", false);
+  const body: Record<string, unknown> = {
+    password: { identityFields, enabled: passwordEnabled },
+    oauth2: { providers, enabled: oauth2Enabled },
+    mfa: { enabled: mfaEnabled, duration: mfaEnabled ? option<number>(collection, "mfa.duration", 0) : 0 },
+    otp: { enabled: otpEnabled, duration: otpEnabled ? option<number>(collection, "otp.duration", 0) : 0 },
+    // legacy fields PocketBase still fills (fillLegacyFields); the SDK strips them with ?fields=mfa,otp,password,oauth2
+    authProviders: oauth2Enabled ? providers.map((p) => ({ ...p, logo: "" })) : null,
+    usernamePassword: passwordEnabled && identityFields.includes("username"),
+    emailPassword: passwordEnabled && identityFields.includes("email"),
+  };
+  const fields = (c.req.query("fields") ?? "").trim();
+  return c.json((fields ? pick(body, parseFields(fields)) : body) as Record<string, unknown>);
+}