@voidbase-cloud/voidbase 0.1.0

package/src/server/oauth2/index.ts

@@ -0,0 +1,198 @@
+// OAuth2 (apis/record_auth_with_oauth2*.go): auth-with-oauth2 code exchange with PKCE, external-auth linking,
+// record creation with createData and the collection's mappedFields, and the browser flow's /api/oauth2-redirect
+// which hands {state, code} to the waiting realtime client through the change feed (topic "@oauth2").
+import type { Context, Hono } from "hono";
+import { recordAuthResponse } from "../auth-response";
+import { requestHook } from "../hooks/runtime";
+import { CollectionRef, HookRecord } from "../hooks/record";
+import type { Collection } from "../collections/model";
+import { ident, one, run, stmt } from "../db";
+import { ApiError, badRequest, forbidden } from "../errors";
+import { nowString, randomId, randomString } from "../ids";
+import { hashPassword } from "../password";
+import { createRecord, type RecordContext } from "../records/service";
+import type { AppEnv, Row } from "../types";
+import { fetchProviderUser, PROVIDER_DEFAULTS, type AuthUser, type Token } from "./providers";
+import { hubActive, publishToClient } from "../realtime/hub-client";
+
+export interface ProviderConfig { name: string; clientId: string; clientSecret?: string; authURL?: string; tokenURL?: string; userInfoURL?: string; displayName?: string; pkce?: boolean | null; extra?: Record<string, unknown> }
+interface OAuth2Options { enabled?: boolean; providers?: ProviderConfig[]; mappedFields?: { id?: string; name?: string; username?: string; avatarURL?: string } }
+
+export const oauth2Options = (c: Collection): OAuth2Options => ((c.options as Record<string, unknown>).oauth2 ?? {}) as OAuth2Options;
+export function providerConfig(c: Collection, name: string): ProviderConfig | null {
+  const p = (oauth2Options(c).providers ?? []).find((x) => x.name === name);
+  if (!p) return null;
+  const d = PROVIDER_DEFAULTS[name];
+  return { ...p, displayName: p.displayName || d?.displayName || name, authURL: p.authURL || d?.authURL, tokenURL: p.tokenURL || d?.tokenURL, userInfoURL: p.userInfoURL || d?.userInfoURL, pkce: typeof p.pkce === "boolean" ? p.pkce : (d?.pkce ?? false) };
+}
+// a provider's extra.scopes (array) replaces the catalog default: Cloudflare's resource scopes are chosen per OAuth client
+export const providerScopes = (p: ProviderConfig | string) => {
+  const name = typeof p === "string" ? p : p.name;
+  const extra = typeof p === "string" ? undefined : (p.extra?.scopes as unknown);
+  if (Array.isArray(extra) && extra.every((s) => typeof s === "string")) return extra as string[];
+  if (typeof extra === "string" && extra.trim()) return extra.split(/[\s,]+/).filter(Boolean);
+  return PROVIDER_DEFAULTS[name]?.scopes ?? [];
+};
+
+const b64url = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+export async function s256Challenge(verifier: string): Promise<string> {
+  return b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+}
+// golang.org/x/oauth2 AuthCodeURL: the parameters come out of url.Values.Encode(), i.e. sorted by key
+export function buildAuthURL(p: ProviderConfig, state: string, extra: Record<string, string>): string {
+  const u = new URL(p.authURL ?? "");
+  const params: Record<string, string> = { response_type: "code", client_id: p.clientId, state, ...extra };
+  const scopes = providerScopes(p);
+  if (scopes.length) params.scope = scopes.join(" ");
+  const encoded = Object.keys(params).sort().map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(params[k]!).replace(/%20/g, "+")}`).join("&");
+  return `${u.origin}${u.pathname}?${u.search ? u.search.slice(1) + "&" : ""}${encoded}`;
+}
+
+// oauth2.Config.Exchange with AuthStyleAutoDetect: client credentials in the Authorization header first, in the body second
+async function fetchToken(p: ProviderConfig, code: string, redirectURL: string, codeVerifier: string): Promise<Token> {
+  if (!p.tokenURL) throw new Error("missing tokenURL");
+  const form = new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectURL });
+  if (p.pkce && codeVerifier) form.set("code_verifier", codeVerifier);
+  const attempt = async (style: "header" | "body") => {
+    const body = new URLSearchParams(form);
+    const headers: Record<string, string> = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+    if (style === "header") headers.authorization = "Basic " + btoa(`${encodeURIComponent(p.clientId)}:${encodeURIComponent(p.clientSecret ?? "")}`);
+    else { body.set("client_id", p.clientId); body.set("client_secret", p.clientSecret ?? ""); }
+    return fetch(p.tokenURL!, { method: "POST", headers, body });
+  };
+  let res = await attempt("header");
+  if (res.status === 401 || res.status === 400) res = await attempt("body");
+  const text = await res.text();
+  if (!res.ok) throw new Error(`oauth2: cannot fetch token: ${res.status}\nResponse: ${text}`);
+  let token: Token;
+  try { token = JSON.parse(text) as Token; } catch { token = Object.fromEntries(new URLSearchParams(text)) as unknown as Token; if (token.expires_in) token.expires_in = Number(token.expires_in); }
+  if (!token.access_token) throw new Error("oauth2: server response missing access_token");
+  return token;
+}
+
+async function fetchAuthUser(p: ProviderConfig, token: Token): Promise<AuthUser> {
+  const user = await fetchProviderUser({ name: p.name, clientId: p.clientId, clientSecret: p.clientSecret ?? "", userInfoURL: p.userInfoURL ?? "", extra: p.extra ?? {} }, token);
+  if (p.name.startsWith("oidc") && !p.userInfoURL && token.id_token) { // audience check like PocketBase's id_token parser
+    const aud = (user.rawUser as { aud?: unknown }).aud;
+    if (!(aud === p.clientId || (Array.isArray(aud) && aud.includes(p.clientId)))) throw new Error("id_token audience mismatch");
+  }
+  return user;
+}
+
+// POST /api/collections/:collection/auth-with-oauth2
+export async function authWithOAuth2(c: Context<AppEnv>, collection: Collection, ctx: RecordContext): Promise<Response> {
+  const opts = oauth2Options(collection);
+  if (!opts.enabled) throw forbidden("The collection is not configured to allow OAuth2 authentication.");
+  let body: Record<string, unknown> = {};
+  try { body = (await c.req.json()) ?? {}; } catch { throw badRequest("An error occurred while loading the submitted data."); }
+  const providerName = String(body.provider ?? "");
+  const code = String(body.code ?? "");
+  const errs: Record<string, { code: string; message: string; params?: Record<string, unknown> }> = {};
+  if (!code) errs.code = { code: "validation_required", message: "Cannot be blank." };
+  if (!providerName) errs.provider = { code: "validation_required", message: "Cannot be blank." };
+  else if (!providerConfig(collection, providerName)) errs.provider = { code: "validation_invalid_provider", message: `Provider with name ${providerName} is missing or is not enabled.`, params: { name: providerName } };
+  if (Object.keys(errs).length) throw new ApiError(400, "An error occurred while loading the submitted data.", errs);
+  const provider = providerConfig(collection, providerName)!;
+  const redirectURL = String(body.redirectURL ?? body.redirectUrl ?? "");
+  let token: Token;
+  try { token = await fetchToken(provider, code, redirectURL, String(body.codeVerifier ?? "")); } catch (err) { console.warn("voidbase: oauth2 token", err); throw badRequest("Failed to fetch OAuth2 token."); }
+  let user: AuthUser;
+  try { user = await fetchAuthUser(provider, token); } catch (err) { console.warn("voidbase: oauth2 user", err); throw badRequest("Failed to fetch OAuth2 user."); }
+
+  const db = c.env.DB;
+  const table = ident(collection.name);
+  const fallback = ctx.auth && ctx.auth.collection.id === collection.id ? ctx.auth.row : null;
+  let external = await one<Row>(db, "SELECT * FROM `_externalAuths` WHERE collectionRef = ? AND provider = ? AND providerId = ? LIMIT 1", [collection.id, providerName, user.id]);
+  let row: Row | null = null;
+  if (external) row = await one<Row>(db, `SELECT * FROM ${table} WHERE id = ? LIMIT 1`, [external.recordRef]);
+  else if (fallback) row = fallback;
+  else if (user.email) row = await one<Row>(db, `SELECT * FROM ${table} WHERE email = ? LIMIT 1`, [user.email]);
+  const isNew = !row;
+  return requestHook("onRecordAuthWithOAuth2Request", c, collection.name, { collection: new CollectionRef(collection), providerName, providerClient: null, oAuth2User: user, createData: (body.createData as Record<string, unknown>) ?? {}, record: row ? HookRecord.fromRow(collection, row) : null, isNewRecord: isNew }, async (ev) => {
+
+    try {
+      if (!row) {
+        if (collection.name === "_superusers") throw new Error("superusers are not allowed to sign-up with OAuth2");
+        const payload: Record<string, unknown> = { ...((ev.createData as Record<string, unknown>) ?? {}) };
+        if (!payload.email) payload.email = user.email;
+        const mf = opts.mappedFields ?? {};
+        if (mf.id && !(mf.id in payload)) payload[mf.id] = user.id;
+        if (mf.name && !(mf.name in payload)) payload[mf.name] = user.name;
+        if (mf.username && !(mf.username in payload) && user.username && canAssignUsername(collection, user.username)) payload[mf.username] = user.username;
+        if (mf.avatarURL && !(mf.avatarURL in payload) && user.avatarURL) {
+          const f = collection.fields.find((x) => x.name === mf.avatarURL);
+          if (f && f.type !== "file") payload[mf.avatarURL] = user.avatarURL; // file avatars need a fetch through the record form; kept for auth.providers
+        }
+        if (!payload.id) payload.id = randomId();
+        // forms/record_upsert.go: an OAuth2 sign-up without a password gets a random one
+        if (!payload.password) { payload.password = randomString(30); payload.passwordConfirm = payload.password; }
+        await createRecord({ ...ctx, request: { ...ctx.request, context: "oauth2" } }, collection, payload as never, {} as never);
+        row = await one<Row>(db, `SELECT * FROM ${table} WHERE id = ? LIMIT 1`, [payload.id]);
+        if (!row) throw new Error("failed to create OAuth2 auth record");
+        if (row.email === user.email && !row.verified) { await run(db, `UPDATE ${table} SET verified = 1, updated = ? WHERE id = ?`, [nowString(), row.id]); row.verified = 1; }
+      } else {
+        const sets: string[] = []; const params: unknown[] = [];
+        const isLogged = fallback !== null && fallback.id === row.id;
+        const verified = !!row.verified && row.verified !== 0 && row.verified !== "0" && row.verified !== "false";
+        if (!isLogged && !verified) { sets.push("password = ?", "tokenKey = ?"); params.push(await hashPassword(randomString(30)), randomString(50)); }
+        if (!verified) { await run(db, "DELETE FROM `_externalAuths` WHERE collectionRef = ? AND recordRef = ?", [collection.id, row.id]); external = null; }
+        if (!row.email && user.email) { sets.push("email = ?"); params.push(user.email); row.email = user.email; }
+        if (!verified && (!row.email || row.email === user.email)) { sets.push("verified = 1"); row.verified = 1; }
+        if (sets.length) { sets.push("updated = ?"); params.push(nowString()); await run(db, `UPDATE ${table} SET ${sets.join(", ")} WHERE id = ?`, [...params, row.id]); }
+      }
+      if (!external) {
+        const now = nowString();
+        await run(db, "INSERT INTO `_externalAuths` (id, collectionRef, recordRef, provider, providerId, created, updated) VALUES (?, ?, ?, ?, ?, ?, ?)", [randomId(), collection.id, row.id, providerName, user.id, now, now]);
+      }
+    } catch (err) {
+      if (err instanceof ApiError) throw err;
+      console.warn("voidbase: oauth2 submit", err);
+      throw badRequest("Failed to authenticate.");
+    }
+    const fresh = (await one<Row>(db, `SELECT * FROM ${table} WHERE id = ? LIMIT 1`, [row.id])) ?? row;
+    const meta: Record<string, unknown> = { ...user, avatarUrl: user.avatarURL, isNew }; // avatarUrl: deprecated alias PocketBase still returns
+
+  return recordAuthResponse(c, ctx, collection, fresh, "oauth2", { meta: sortKeys(meta), body });
+  });
+}
+
+const sortKeys = (o: Record<string, unknown>) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+function canAssignUsername(collection: Collection, username: string): boolean {
+  const f = collection.fields.find((x) => x.name === oauth2Options(collection).mappedFields?.username);
+  if (!f || f.type !== "text") return false;
+  const pattern = String((f as { pattern?: string }).pattern ?? "");
+  if (pattern) { try { if (!new RegExp(pattern).test(username)) return false; } catch { /* keep */ } }
+  const min = Number((f as { min?: number }).min ?? 0), max = Number((f as { max?: number }).max ?? 0);
+  if (min && username.length < min) return false;
+  if (max && username.length > max) return false;
+  return true;
+}
+
+// GET|POST /api/oauth2-redirect: the provider sends the browser back here; we forward {state, code, error} to the
+// realtime client whose id is the state (through the change feed, so any isolate can deliver it) and redirect
+// to the panel's "you can close this window" page.
+const FAILURE = "../_/#/auth/oauth2-redirect-failure", SUCCESS = "../_/#/auth/oauth2-redirect-success";
+export function mountOAuth2Redirect(app: Hono<AppEnv>) {
+  const handler = async (c: Context<AppEnv>) => {
+    const status = c.req.method === "GET" ? 307 : 303;
+    let data: { state: string; code: string; error?: string } = { state: "", code: "" };
+    if (c.req.method === "POST") {
+      const ct = c.req.header("content-type") ?? "";
+      const body = (ct.includes("json") ? await c.req.json().catch(() => ({})) : Object.fromEntries((await c.req.formData().catch(() => new FormData())).entries())) as Record<string, unknown>;
+      data = { state: String(body.state ?? ""), code: String(body.code ?? ""), error: body.error ? String(body.error) : undefined };
+    } else data = { state: c.req.query("state") ?? "", code: c.req.query("code") ?? "", error: c.req.query("error") || undefined };
+    if (!data.state) return c.redirect(FAILURE, status);
+    const client = await one<{ subscriptions: string }>(c.env.DB, "SELECT subscriptions FROM `_realtime_clients` WHERE id = ?", [data.state]);
+    const subs = client ? (JSON.parse(client.subscriptions || "[]") as string[]) : [];
+    if (!client || !subs.includes("@oauth2")) return c.redirect(FAILURE, status);
+    const payload: Record<string, unknown> = { state: data.state, code: data.code };
+    if (data.error) payload.error = data.error;
+    // the stream drops its @oauth2 subscription itself once it has delivered the message
+    if (hubActive()) await publishToClient(data.state, "@oauth2", payload);
+    else await stmt(c.env.DB, "INSERT INTO `_changes` (collection, recordId, action, data, created) VALUES ('@oauth2', ?, 'message', ?, ?)", [data.state, JSON.stringify(payload), nowString()]).run();
+    if (data.error || !data.code) return c.redirect(FAILURE, status);
+    return c.redirect(SUCCESS, status);
+  };
+  app.get("/api/oauth2-redirect", handler);
+  app.post("/api/oauth2-redirect", handler);
+}

package/src/server/oauth2/providers.ts

@@ -0,0 +1,153 @@
+// OAuth2 provider catalog (PocketBase tools/auth): endpoints, scopes, PKCE defaults and the user-info fetch and
+// mapping for every provider PocketBase ships. Email is only taken when the provider vouches for it.
+export interface ProviderDefaults { displayName: string; pkce: boolean; scopes: string[]; authURL?: string; tokenURL?: string; userInfoURL?: string }
+export interface AuthUser { expiry: string; rawUser: Record<string, unknown>; id: string; name: string; username: string; avatarURL: string; accessToken: string; refreshToken: string; email: string }
+export interface Token { access_token: string; token_type?: string; refresh_token?: string; expires_in?: number; id_token?: string; [k: string]: unknown }
+export interface ProviderContext { name: string; clientId: string; clientSecret: string; userInfoURL: string; extra: Record<string, unknown> }
+type Raw = Record<string, unknown>;
+
+const oidc: ProviderDefaults = { displayName: "OIDC", pkce: true, scopes: ["openid", "email", "profile"] };
+// Cloudflare OAuth (developers.cloudflare.com/fundamentals/oauth): plain OIDC on dash.cloudflare.com whose userinfo
+// carries only `sub`, so identity comes from the API's GET /user. Resource scopes (API token permission names such
+// as workers-platform.write) are added per provider with extra.scopes; extra.apiBase overrides the API for tests.
+export const CF_API_BASE = "https://api.cloudflare.com/client/v4";
+const cloudflare: ProviderDefaults = { displayName: "Cloudflare", pkce: true, scopes: ["openid", "offline_access"], authURL: "https://dash.cloudflare.com/oauth2/auth", tokenURL: "https://dash.cloudflare.com/oauth2/token", userInfoURL: "https://dash.cloudflare.com/oauth2/userinfo" };
+export const PROVIDER_DEFAULTS: Record<string, ProviderDefaults> = {
+  oidc, oidc2: oidc, oidc3: oidc, cloudflare,
+  apple: { displayName: "Apple", pkce: true, scopes: ["name", "email"], authURL: "https://appleid.apple.com/auth/authorize", tokenURL: "https://appleid.apple.com/auth/token" },
+  bitbucket: { displayName: "Bitbucket", pkce: false, scopes: ["account"], authURL: "https://bitbucket.org/site/oauth2/authorize", tokenURL: "https://bitbucket.org/site/oauth2/access_token", userInfoURL: "https://api.bitbucket.org/2.0/user" },
+  box: { displayName: "Box", pkce: true, scopes: ["root_readonly"], authURL: "https://account.box.com/api/oauth2/authorize", tokenURL: "https://api.box.com/oauth2/token", userInfoURL: "https://api.box.com/2.0/users/me" },
+  discord: { displayName: "Discord", pkce: true, scopes: ["identify", "email"], authURL: "https://discord.com/api/oauth2/authorize", tokenURL: "https://discord.com/api/oauth2/token", userInfoURL: "https://discord.com/api/users/@me" },
+  facebook: { displayName: "Facebook", pkce: true, scopes: ["email"], authURL: "https://www.facebook.com/v3.2/dialog/oauth", tokenURL: "https://graph.facebook.com/v3.2/oauth/access_token", userInfoURL: "https://graph.facebook.com/me?fields=name,email,picture.type(large)" },
+  gitea: { displayName: "Gitea/Forgejo", pkce: true, scopes: ["read:user", "user:email"], authURL: "https://gitea.com/login/oauth/authorize", tokenURL: "https://gitea.com/login/oauth/access_token", userInfoURL: "https://gitea.com/api/v1/user" },
+  gitee: { displayName: "Gitee", pkce: true, scopes: ["user_info", "emails"], authURL: "https://gitee.com/oauth/authorize", tokenURL: "https://gitee.com/oauth/token", userInfoURL: "https://gitee.com/api/v5/user" },
+  github: { displayName: "GitHub", pkce: true, scopes: ["read:user", "user:email"], authURL: "https://github.com/login/oauth/authorize", tokenURL: "https://github.com/login/oauth/access_token", userInfoURL: "https://api.github.com/user" },
+  gitlab: { displayName: "GitLab", pkce: true, scopes: ["read_user"], authURL: "https://gitlab.com/oauth/authorize", tokenURL: "https://gitlab.com/oauth/token", userInfoURL: "https://gitlab.com/api/v4/user" },
+  google: { displayName: "Google", pkce: true, scopes: ["https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/userinfo.email"], authURL: "https://accounts.google.com/o/oauth2/v2/auth", tokenURL: "https://oauth2.googleapis.com/token", userInfoURL: "https://www.googleapis.com/oauth2/v3/userinfo" },
+  instagram: { displayName: "Instagram", pkce: true, scopes: ["instagram_business_basic"], authURL: "https://www.instagram.com/oauth/authorize", tokenURL: "https://api.instagram.com/oauth/access_token", userInfoURL: "https://graph.instagram.com/me?fields=id,username,account_type,user_id,name,profile_picture_url,followers_count,follows_count,media_count" },
+  kakao: { displayName: "Kakao", pkce: true, scopes: ["account_email", "profile_nickname", "profile_image"], authURL: "https://kauth.kakao.com/oauth/authorize", tokenURL: "https://kauth.kakao.com/oauth/token", userInfoURL: "https://kapi.kakao.com/v2/user/me" },
+  lark: { displayName: "Lark", pkce: true, scopes: [], authURL: "https://accounts.feishu.cn/open-apis/authen/v1/authorize", tokenURL: "https://open.feishu.cn/open-apis/authen/v2/oauth/token", userInfoURL: "https://open.feishu.cn/open-apis/authen/v1/user_info" },
+  linear: { displayName: "Linear", pkce: false, scopes: ["read"], authURL: "https://linear.app/oauth/authorize", tokenURL: "https://api.linear.app/oauth/token", userInfoURL: "https://api.linear.app/graphql" },
+  livechat: { displayName: "LiveChat", pkce: true, scopes: [], authURL: "https://accounts.livechat.com/", tokenURL: "https://accounts.livechat.com/token", userInfoURL: "https://accounts.livechat.com/v2/accounts/me" },
+  mailcow: { displayName: "mailcow", pkce: true, scopes: ["profile"] },
+  microsoft: { displayName: "Microsoft", pkce: true, scopes: ["User.Read"], authURL: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize", tokenURL: "https://login.microsoftonline.com/common/oauth2/v2.0/token", userInfoURL: "https://graph.microsoft.com/v1.0/me" },
+  monday: { displayName: "monday.com", pkce: true, scopes: ["me:read"], authURL: "https://auth.monday.com/oauth2/authorize", tokenURL: "https://auth.monday.com/oauth2/token", userInfoURL: "https://api.monday.com/v2" },
+  notion: { displayName: "Notion", pkce: true, scopes: [], authURL: "https://api.notion.com/v1/oauth/authorize", tokenURL: "https://api.notion.com/v1/oauth/token", userInfoURL: "https://api.notion.com/v1/users/me" },
+  patreon: { displayName: "Patreon", pkce: true, scopes: ["identity", "identity[email]"], authURL: "https://www.patreon.com/oauth2/authorize", tokenURL: "https://www.patreon.com/api/oauth2/token", userInfoURL: "https://www.patreon.com/api/oauth2/v2/identity?fields%5Buser%5D=full_name,email,vanity,image_url,is_email_verified" },
+  planningcenter: { displayName: "Planning Center", pkce: true, scopes: ["people"], authURL: "https://api.planningcenteronline.com/oauth/authorize", tokenURL: "https://api.planningcenteronline.com/oauth/token", userInfoURL: "https://api.planningcenteronline.com/people/v2/me" },
+  spotify: { displayName: "Spotify", pkce: true, scopes: ["user-read-private"], authURL: "https://accounts.spotify.com/authorize", tokenURL: "https://accounts.spotify.com/api/token", userInfoURL: "https://api.spotify.com/v1/me" },
+  strava: { displayName: "Strava", pkce: true, scopes: ["profile:read_all"], authURL: "https://www.strava.com/oauth/authorize", tokenURL: "https://www.strava.com/api/v3/oauth/token", userInfoURL: "https://www.strava.com/api/v3/athlete" },
+  trakt: { displayName: "Trakt", pkce: true, scopes: [], authURL: "https://trakt.tv/oauth/authorize", tokenURL: "https://api.trakt.tv/oauth/token", userInfoURL: "https://api.trakt.tv/users/settings" },
+  twitch: { displayName: "Twitch", pkce: true, scopes: ["user:read:email"], authURL: "https://id.twitch.tv/oauth2/authorize", tokenURL: "https://id.twitch.tv/oauth2/token", userInfoURL: "https://api.twitch.tv/helix/users" },
+  twitter: { displayName: "X/Twitter", pkce: true, scopes: ["users.read", "users.email", "tweet.read"], authURL: "https://x.com/i/oauth2/authorize", tokenURL: "https://api.x.com/2/oauth2/token", userInfoURL: "https://api.x.com/2/users/me?user.fields=id,name,username,profile_image_url,confirmed_email" },
+  vk: { displayName: "ВКонтакте", pkce: false, scopes: ["email"], authURL: "https://oauth.vk.com/authorize", tokenURL: "https://oauth.vk.com/access_token", userInfoURL: "https://api.vk.com/method/users.get?fields=photo_max,screen_name&v=5.131" },
+  wakatime: { displayName: "WakaTime", pkce: true, scopes: ["email"], authURL: "https://wakatime.com/oauth/authorize", tokenURL: "https://wakatime.com/oauth/token", userInfoURL: "https://wakatime.com/api/v1/users/current" },
+  yandex: { displayName: "Yandex", pkce: true, scopes: ["login:email", "login:avatar", "login:info"], authURL: "https://oauth.yandex.com/authorize", tokenURL: "https://oauth.yandex.com/token", userInfoURL: "https://login.yandex.ru/info" },
+};
+
+const str = (v: unknown) => (v === null || v === undefined ? "" : String(v));
+const truthy = (v: unknown) => v === true || v === "true" || v === 1 || v === "1";
+const get = (o: unknown, ...path: string[]): unknown => path.reduce<unknown>((cur, k) => (cur && typeof cur === "object" ? (cur as Raw)[k] : undefined), o);
+const isEmail = (v: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+const jwtClaims = (jwt: string): Raw => { try { const p = jwt.split(".")[1] ?? ""; return JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(p.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(p.length / 4) * 4, "=")), (ch) => ch.charCodeAt(0)))) as Raw; } catch { return {}; } };
+
+async function getJSON(url: string, token: Token, headers: Record<string, string> = {}): Promise<Raw> {
+  const res = await fetch(url, { headers: { authorization: `Bearer ${token.access_token}`, accept: "application/json", ...headers } });
+  const text = await res.text();
+  if (res.status >= 400) throw new Error(`failed to fetch OAuth2 user profile via ${url} (${res.status}):\n${text}`);
+  return JSON.parse(text) as Raw;
+}
+async function graphQL(url: string, token: Token, query: string, headers: Record<string, string> = {}): Promise<Raw> {
+  const res = await fetch(url, { method: "POST", headers: { authorization: `Bearer ${token.access_token}`, "content-type": "application/json", accept: "application/json", ...headers }, body: JSON.stringify({ query }) });
+  const text = await res.text();
+  if (res.status >= 400) throw new Error(`failed to fetch OAuth2 user profile via ${url} (${res.status}):\n${text}`);
+  return JSON.parse(text) as Raw;
+}
+
+// the raw user-info document (most providers: GET userInfoURL with the bearer token)
+export async function fetchRawUser(p: ProviderContext, token: Token): Promise<Raw> {
+  switch (p.name) {
+    case "apple": case "oidc": case "oidc2": case "oidc3": case "mailcow":
+      if (p.userInfoURL) return getJSON(p.userInfoURL, token);
+      if (!token.id_token) throw new Error("empty id_token");
+      return jwtClaims(String(token.id_token));
+    case "cloudflare": {
+      const info = p.userInfoURL ? await getJSON(p.userInfoURL, token) : (token.id_token ? jwtClaims(String(token.id_token)) : {});
+      const base = String(p.extra.apiBase || CF_API_BASE).replace(/\/$/, "");
+      const me = await getJSON(`${base}/user`, token);
+      return { ...info, cf_user: (me.result ?? me) as Raw };
+    }
+    case "linear": return graphQL(p.userInfoURL, token, "query { viewer { id displayName name email avatarUrl active } }");
+    case "monday": return graphQL(p.userInfoURL, token, "query { me { id enabled name email is_verified photo_small } }");
+    case "twitch": return getJSON(p.userInfoURL, token, { "Client-Id": p.clientId });
+    case "trakt": return getJSON(p.userInfoURL, token, { "trakt-api-key": p.clientId, "trakt-api-version": "2" });
+    case "notion": return getJSON(p.userInfoURL, token, { "Notion-Version": "2022-06-28" });
+    default:
+      if (!p.userInfoURL) throw new Error("missing userInfoURL");
+      return getJSON(p.userInfoURL, token);
+  }
+}
+
+// providers whose verified email lives on a second endpoint
+async function extraEmail(p: ProviderContext, token: Token): Promise<string> {
+  const pick = (list: unknown, ok: (e: Raw) => boolean, key = "email") => { for (const e of (Array.isArray(list) ? list : []) as Raw[]) if (ok(e)) return str(e[key]); return ""; };
+  try {
+    switch (p.name) {
+      case "github": return pick(await getJSON(`${p.userInfoURL}/emails`, token), (e) => truthy(e.primary) && truthy(e.verified));
+      case "gitea": return pick(await getJSON(`${p.userInfoURL}/emails`, token), (e) => truthy(e.primary) && truthy(e.verified));
+      case "gitee": return pick(await getJSON(p.userInfoURL.replace(/\/user$/, "/emails"), token), (e) => (Array.isArray(e.scope) ? (e.scope as string[]).includes("primary") : truthy(e.primary)) && (e.state === "confirmed" || truthy(e.confirmed)));
+      case "bitbucket": return pick(get(await getJSON(`${p.userInfoURL}/emails`, token), "values"), (e) => truthy(e.is_primary) && truthy(e.is_confirmed));
+      default: return "";
+    }
+  } catch { return ""; }
+}
+
+export async function fetchProviderUser(p: ProviderContext, token: Token): Promise<AuthUser> {
+  const raw = await fetchRawUser(p, token);
+  const u = mapUser(p, raw, token);
+  if (!u.email && ["github", "gitea", "gitee", "bitbucket"].includes(p.name)) u.email = await extraEmail(p, token);
+  const expiry = token.expires_in ? new Date(Date.now() + Number(token.expires_in) * 1000) : null;
+  return { ...u, rawUser: raw, accessToken: token.access_token, refreshToken: str(token.refresh_token), expiry: expiry ? expiry.toISOString().replace("T", " ").replace(/\.(\d{3})Z$/, ".$1Z") : "" };
+}
+
+// tools/auth/<provider>.go FetchAuthUser mappings
+export function mapUser(p: ProviderContext, raw: Raw, token: Token): Omit<AuthUser, "expiry" | "accessToken" | "refreshToken" | "rawUser"> {
+  const base = { id: "", name: "", username: "", avatarURL: "", email: "" };
+  switch (p.name) {
+    case "google": return { ...base, id: str(raw.sub), name: str(raw.name), avatarURL: str(raw.picture), email: truthy(raw.email_verified) ? str(raw.email) : "" };
+    case "apple": return { ...base, id: str(raw.sub), name: str(raw.name), email: truthy(raw.email_verified) ? str(raw.email) : "" };
+    case "bitbucket": if (raw.account_status !== "active") throw new Error("Bitbucket user account is not active"); return { ...base, id: str(raw.uuid), name: str(raw.display_name), username: str(raw.username), avatarURL: str(get(raw, "links", "avatar", "href")) };
+    case "box": if (raw.status !== "active") throw new Error(`Box user account is not active (status: ${str(raw.status)})`); return { ...base, id: str(raw.id), name: str(raw.name), avatarURL: str(raw.avatar_url), email: str(raw.login) };
+    case "discord": {
+      const id = str(raw.id); let name = str(raw.global_name) || str(raw.username);
+      const disc = str(raw.discriminator); if (!raw.global_name && disc && disc !== "0") name += "#" + disc;
+      return { ...base, id, name, username: str(raw.username), avatarURL: raw.avatar ? `https://cdn.discordapp.com/avatars/${id}/${str(raw.avatar)}.png` : "", email: truthy(raw.verified) ? str(raw.email) : "" };
+    }
+    case "cloudflare": { const u = (raw.cf_user ?? {}) as Raw; const name = `${str(u.first_name)} ${str(u.last_name)}`.trim(); return { ...base, id: str(raw.sub) || str(u.id), name, username: str(u.username), email: str(u.email) }; }
+    case "facebook": return { ...base, id: str(raw.id), name: str(raw.name), email: str(raw.email), avatarURL: str(get(raw, "picture", "data", "url")) };
+    case "gitea": if (!truthy(raw.active)) throw new Error("the Gitea user is not active"); return { ...base, id: str(raw.id), name: str(raw.full_name), username: str(raw.login), avatarURL: str(raw.avatar_url) };
+    case "gitee": return { ...base, id: str(raw.id), name: str(raw.name), username: str(raw.login), avatarURL: str(raw.avatar_url), email: raw.email && isEmail(str(raw.email)) ? str(raw.email) : "" };
+    case "github": return { ...base, id: str(raw.id), name: str(raw.name), username: str(raw.login), avatarURL: str(raw.avatar_url) };
+    case "gitlab": return { ...base, id: str(raw.id), name: str(raw.name), username: str(raw.username), avatarURL: str(raw.avatar_url), email: raw.confirmed_at && !Number.isNaN(Date.parse(str(raw.confirmed_at))) ? str(raw.email) : "" };
+    case "instagram": return { ...base, id: str(raw.user_id), name: str(raw.name), username: str(raw.username), avatarURL: str(raw.profile_picture_url) };
+    case "kakao": { const acc = (raw.kakao_account ?? {}) as Raw; return { ...base, id: str(raw.id), username: str(get(raw, "properties", "nickname")), avatarURL: str(get(raw, "properties", "profile_image")), email: truthy(acc.is_email_valid) && truthy(acc.is_email_verified) ? str(acc.email) : "" }; }
+    case "lark": return { ...base, id: str(get(raw, "data", "union_id")), name: str(get(raw, "data", "name")), avatarURL: str(get(raw, "data", "avatar_url")) };
+    case "linear": { const v = (get(raw, "data", "viewer") ?? {}) as Raw; if (!truthy(v.active)) throw new Error("the Linear user is not active"); return { ...base, id: str(v.id), name: str(v.name), username: str(v.displayName), email: str(v.email), avatarURL: str(v.avatarUrl) }; }
+    case "livechat": return { ...base, id: str(raw.account_id), name: str(raw.name), avatarURL: str(raw.avatar_url), email: truthy(raw.email_verified) ? str(raw.email) : "" };
+    case "mailcow": { if (Number(raw.active) !== 1) throw new Error("the mailcow user is not active"); const username = str(raw.username); return { ...base, id: str(raw.id), name: str(raw.full_name), username: username.includes("@") ? username.split("@")[0]! : username, email: str(raw.email) }; }
+    case "microsoft": { const claims = token.id_token ? jwtClaims(String(token.id_token)) : {}; return { ...base, id: str(raw.id), name: str(raw.displayName), email: str(claims.email) || str(raw.mail) }; }
+    case "monday": { const me = (get(raw, "data", "me") ?? {}) as Raw; if (!truthy(me.enabled)) throw new Error("the monday.com user is not enabled"); return { ...base, id: str(me.id), name: str(me.name), avatarURL: str(me.photo_small), email: truthy(me.is_verified) ? str(me.email) : "" }; }
+    case "notion": { const u = (get(raw, "bot", "owner", "user") ?? {}) as Raw; return { ...base, id: str(u.id), name: str(u.name), email: str(get(u, "person", "email")), avatarURL: str(u.avatar_url) }; }
+    case "patreon": { const a = (get(raw, "data", "attributes") ?? {}) as Raw; return { ...base, id: str(get(raw, "data", "id")), username: str(a.vanity), name: str(a.full_name), avatarURL: str(a.image_url), email: truthy(a.is_email_verified) ? str(a.email) : "" }; }
+    case "planningcenter": { const a = (get(raw, "data", "attributes") ?? {}) as Raw; if (a.status !== "active") throw new Error("the Planning Center user is not active"); return { ...base, id: str(get(raw, "data", "id")), name: str(a.name), avatarURL: str(a.avatar) }; }
+    case "spotify": { const images = Array.isArray(raw.images) ? (raw.images as Raw[]) : []; return { ...base, id: str(raw.id), name: str(raw.display_name), avatarURL: str(images[0]?.url) }; }
+    case "strava": return { ...base, id: raw.id ? str(raw.id) : "", name: `${str(raw.firstname)} ${str(raw.lastname)}`, username: str(raw.username), avatarURL: str(raw.profile) };
+    case "trakt": { const u = (raw.user ?? {}) as Raw; return { ...base, id: str(get(u, "ids", "uuid")), username: str(u.username), name: str(u.name), avatarURL: str(get(u, "images", "avatar", "full")) }; }
+    case "twitch": { const d = (Array.isArray(raw.data) ? (raw.data as Raw[])[0] : undefined); if (!d) throw new Error("failed to fetch Twitch user"); return { ...base, id: str(d.id), name: str(d.display_name), username: str(d.login), email: str(d.email), avatarURL: str(d.profile_image_url) }; }
+    case "twitter": { const d = (raw.data ?? {}) as Raw; return { ...base, id: str(d.id), name: str(d.name), username: str(d.username), email: str(d.confirmed_email), avatarURL: str(d.profile_image_url) }; }
+    case "vk": { const r = (Array.isArray(raw.response) ? (raw.response as Raw[])[0] : undefined); if (!r) throw new Error("failed to fetch VK user"); return { ...base, id: str(r.id), name: `${str(r.first_name)} ${str(r.last_name)}`.trim(), username: str(r.screen_name), avatarURL: str(r.photo_max), email: token.email ? str(token.email) : "" }; }
+    case "wakatime": { const d = (raw.data ?? {}) as Raw; return { ...base, id: str(d.id), name: str(d.display_name), username: str(d.username), email: truthy(d.is_email_confirmed) ? str(d.email) : "", avatarURL: truthy(d.photo_public) ? str(d.photo) : "" }; }
+    case "yandex": return { ...base, id: str(raw.id), name: str(raw.real_name), username: str(raw.login), email: str(raw.default_email), avatarURL: !truthy(raw.is_avatar_empty) && raw.default_avatar_id ? `https://avatars.yandex.net/get-yapic/${str(raw.default_avatar_id)}/islands-200` : "" };
+    default: return { ...base, id: str(raw.sub), name: str(raw.name), username: str(raw.preferred_username), avatarURL: str(raw.picture), email: truthy(raw.email_verified) ? str(raw.email) : "" }; // oidc
+  }
+}

package/src/server/password.ts

@@ -0,0 +1,17 @@
+import bcrypt from "bcryptjs";
+
+// PocketBase uses bcrypt with bcrypt.DefaultCost (10) unless the field sets a cost.
+export const DEFAULT_COST = 10;
+
+export function hashPassword(plain: string, cost = DEFAULT_COST): Promise<string> {
+  return bcrypt.hash(plain, cost);
+}
+
+export async function verifyPassword(plain: string, hash: string): Promise<boolean> {
+  if (!hash) return false;
+  try {
+    return await bcrypt.compare(plain, hash);
+  } catch {
+    return false;
+  }
+}

package/src/server/realtime/hub-client.ts

@@ -0,0 +1,50 @@
+// The Worker side of the realtime hub (src/server/hub.ts): a per-instance Durable Object reached through the HUB
+// binding the deploy declares. Record writes publish change events to it, each SSE connection holds one hibernatable
+// WebSocket to it, and subscription changes made on another isolate are relayed through it. Without the binding
+// (the Bun runtime, or a deploy without the hub) everything falls back to the D1 change feed and its poll loop.
+import { logger } from "#platform/log";
+import type { Bindings, Row } from "../types";
+
+export interface ChangeEvent { collection: string; recordId: string; action: "create" | "update" | "delete" | "message"; data?: Row | null }
+export type HubMessage =
+  | { t: "changes"; changes: ChangeEvent[] }
+  | { t: "subs"; subscriptions: string[]; token: string }
+  | { t: "message"; event: string; data: unknown };
+
+let hub: DurableObjectNamespace | undefined;
+export function attachHub(env: Bindings): void { hub = env.HUB; }
+export const hubActive = (): boolean => !!hub;
+
+const stub = () => hub!.get(hub!.idFromName("hub"));
+const post = async (path: string, body: unknown): Promise<Response> => stub().fetch(`https://hub${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+
+/** Fans the changes out to every connected client that subscribed to one of their collections. */
+export async function publishChanges(changes: ChangeEvent[]): Promise<void> {
+  if (!hub || !changes.length) return;
+  try { const r = await post("/publish", { changes }); if (!r.ok) logger.error("voidbase: hub publish failed", { status: r.status }); }
+  catch (err) { logger.error("voidbase: hub publish failed", { error: err instanceof Error ? err.message : String(err) }); }
+}
+/** One-off message to one client (the OAuth2 redirect hand-off). */
+export async function publishToClient(clientId: string, event: string, data: unknown): Promise<boolean> {
+  if (!hub) return false;
+  const r = await post("/client", { clientId, event, data });
+  return r.ok && ((await r.json()) as { delivered: number }).delivered > 0;
+}
+/** Tells the isolate holding the client's stream about its new subscriptions (set through any isolate). */
+export async function controlClient(clientId: string, subscriptions: string[], token: string): Promise<void> {
+  if (!hub) return;
+  try { await post("/control", { clientId, subscriptions, token }); } catch (err) { logger.error("voidbase: hub control failed", { error: err instanceof Error ? err.message : String(err) }); }
+}
+
+/** Opens this connection's socket to the hub (owned by the SSE request, like the stream it feeds). */
+export async function openHubSocket(clientId: string): Promise<WebSocket> {
+  const res = await stub().fetch(`https://hub/ws?client=${encodeURIComponent(clientId)}`, { headers: { upgrade: "websocket" } });
+  const ws = (res as Response & { webSocket?: WebSocket | null }).webSocket;
+  if (!ws) throw new Error(`hub refused the socket (${res.status})`);
+  ws.accept();
+  return ws;
+}
+/** The collections this connection wants (names), so the hub skips everything else; "*" when it cannot say. */
+export function sendFilter(ws: WebSocket, collections: string[] | "*"): void {
+  try { ws.send(JSON.stringify({ t: "filter", collections })); } catch { /* closing */ }
+}