@voidbase-cloud/voidbase 0.2.2 → 0.4.0

package/src/node/secrets.ts

@@ -0,0 +1,237 @@
+// pb_secrets/: the app's configuration, declared where the tooling can read it and valued where git cannot see it.
+//
+//   pb_secrets/main.ts        the declaration, committed: `export default defineSecrets({ NAME: string().secret(), ... })`
+//   pb_secrets/secrets.json   the local values, git-ignored: `{ "NAME": "value", ... }`. On a dev machine only.
+//
+// The declaration (src/env/define.ts) gives every key a validator and an access tier: `secret` (the Worker's
+// encrypted secrets), `server` (plain Worker vars) or `public` (Worker vars the client build inlines too).
+// `voidbase serve` parses the local values and the shell through the validators and puts the result into the
+// process environment, so `$os.getenv("NAME")` and the app's own code see what they will see on Cloudflare.
+// `voidbase deploy` stores secrets the Worker lacks as its secrets and every server/public value as its vars, and
+// refuses to deploy while a value is invalid or a required one is missing everywhere: a CI checkout has no
+// secrets.json, and that is the point -- the secrets are pushed once from a machine that has them (`voidbase
+// secrets push`), the plain values come from the deploy's environment or the declared defaults, and the pipeline
+// needs nothing but the deploy token.
+//
+// Cloudflare's account-level Secrets Store is deliberately not used: one store is shared by every Worker of the
+// account, and its bindings are read asynchronously, which `$os.getenv` is not.
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import ts from "typescript";
+import type { CfApi } from "../cloud/rest";
+import { isDefinition, type Access, type Definition, type Evaluation, type KeyInfo, type Spec } from "../env/define";
+
+export const SECRETS_DIR = "pb_secrets";
+export const DECLARATION_FILES = ["main.ts", "main.js", "main.mjs"];
+export const VALUES_FILE = "secrets.json";
+const NAME = /^[A-Z][A-Z0-9_]*$/;
+
+// ---- the declaration, read from the source without running it (what the adapter's scan needs) -------------------
+
+export interface SecretsDeclaration {
+  /** the file the names came from */
+  file: string;
+  /** declared names, in file order */
+  names: string[];
+  /** the tier of each name */
+  access: Record<string, Access>;
+  /** what each one is, when the declaration says */
+  descriptions: Record<string, string>;
+}
+
+/**
+ * The names, tiers and descriptions a declaration file declares, without evaluating it:
+ *
+ *     export default defineSecrets({
+ *       SMTP_PASSWORD: string().secret(),                       -> secret
+ *       ADMIN_EMAILS: describe(string().default(""), "who..."), -> server, described
+ *       API_URL: url().optional().public(),                     -> public
+ *       OTHER: secret(zodSchema, "..."),                        -> secret, described
+ *     })
+ */
+export function parseSecretsDeclaration(code: string, file = "pb_secrets/main.ts"): SecretsDeclaration {
+  const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true);
+  const names: string[] = []; const access: Record<string, Access> = {}; const descriptions: Record<string, string> = {};
+  const literal = (n: ts.Node | undefined) => (n && ts.isStringLiteralLike(n) ? n.text : null);
+  const calleeName = (c: ts.CallExpression) => (ts.isIdentifier(c.expression) ? c.expression.text : ts.isPropertyAccessExpression(c.expression) ? c.expression.name.text : "");
+  // the tier and description of one value expression: wrappers first, then Void's .secret()/.public() chain
+  const classify = (expr: ts.Expression): { access: Access; description: string | null } => {
+    let description: string | null = null; let tier: Access | null = null;
+    let node: ts.Expression = expr;
+    while (ts.isCallExpression(node)) {
+      const fn = calleeName(node);
+      if (fn === "describe") { description ??= literal(node.arguments[1]); node = node.arguments[0] ?? node; if (node === expr) break; continue; }
+      if (fn === "secret" || fn === "server" || fn === "pub" || fn === "public") {
+        if (ts.isIdentifier(node.expression)) { tier ??= fn === "pub" ? "public" : (fn as Access); description ??= literal(node.arguments[1]); node = node.arguments[0] ?? node; if (!node || node === expr) break; continue; }
+        tier ??= fn === "secret" ? "secret" : "public"; // Void's .secret() / .public() on a validator chain
+      }
+      node = ts.isPropertyAccessExpression(node.expression) ? node.expression.expression : node.expression;
+      if (!ts.isCallExpression(node)) break;
+    }
+    return { access: tier ?? "server", description };
+  };
+  const add = (name: string | null, expr: ts.Expression | undefined) => {
+    if (!name) return;
+    if (!NAME.test(name)) throw new Error(`voidbase: ${file}: "${name}" is not a configuration name (UPPER_CASE, letters, digits and underscores, like an environment variable)`);
+    const c = expr ? classify(expr) : { access: "server" as Access, description: null };
+    if (!names.includes(name)) names.push(name);
+    access[name] = c.access; if (c.description) descriptions[name] = c.description;
+  };
+  let found = false;
+  const visit = (node: ts.Node) => {
+    if (ts.isCallExpression(node) && calleeName(node) === "defineSecrets") {
+      found = true;
+      const arg = node.arguments[0];
+      if (!arg || !ts.isObjectLiteralExpression(arg)) throw new Error(`voidbase: ${file}: defineSecrets() takes an object literal: { NAME: string().secret(), ... }`);
+      for (const p of arg.properties) {
+        if (ts.isPropertyAssignment(p)) add(ts.isStringLiteralLike(p.name) || ts.isIdentifier(p.name) ? p.name.text : null, p.initializer);
+        else if (ts.isShorthandPropertyAssignment(p)) add(p.name.text, undefined);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  if (!found) throw new Error(`voidbase: ${file} does not call defineSecrets(): export default defineSecrets({ ... })`);
+  return { file, names, access, descriptions };
+}
+
+/** The declaration file of a pb_secrets/ directory, or null. */
+export function declarationFile(dir = SECRETS_DIR): string | null {
+  return DECLARATION_FILES.map((f) => join(resolve(dir), f)).find((f) => existsSync(f)) ?? null;
+}
+
+/** The declaration of a pb_secrets/ directory, read statically, or null when there is none. */
+export function readSecretsDeclaration(dir = SECRETS_DIR): SecretsDeclaration | null {
+  const file = declarationFile(dir);
+  return file ? parseSecretsDeclaration(readFileSync(file, "utf8"), file) : null;
+}
+
+// ---- the declaration, imported (what serve, deploy and the build need: the validators themselves) ---------------
+
+/** Imports the declaration module and returns its definition, or null when the directory has none. */
+export async function loadDefinition(dir = SECRETS_DIR): Promise<{ file: string; definition: Definition<Spec> } | null> {
+  const file = declarationFile(dir);
+  if (!file) return null;
+  const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
+  if (!isDefinition(mod.default)) throw new Error(`voidbase: ${file} must export defineSecrets({ ... }) as its default export`);
+  return { file, definition: mod.default };
+}
+
+/** The local values of a pb_secrets/ directory (`secrets.json`), or null when the file is absent. Every value is a string. */
+export function readSecretsValues(dir = SECRETS_DIR): Record<string, string> | null {
+  const file = join(resolve(dir), VALUES_FILE);
+  if (!existsSync(file)) return null;
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(file, "utf8")); } catch (e) { throw new Error(`voidbase: ${file} is not JSON: ${e instanceof Error ? e.message : String(e)}`); }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`voidbase: ${file} must be an object: { "NAME": "value" }`);
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+    if (!NAME.test(k)) throw new Error(`voidbase: ${file}: "${k}" is not a configuration name (UPPER_CASE, letters, digits and underscores)`);
+    if (v === null || v === undefined) continue;
+    out[k] = typeof v === "string" ? v : typeof v === "object" ? JSON.stringify(v) : String(v);
+  }
+  return out;
+}
+
+export interface SecretsState {
+  dir: string;
+  /** the declaration file, or null when there is none */
+  file: string | null;
+  definition: Definition<Spec> | null;
+  /** what each key is: tier, description, default */
+  info: KeyInfo[];
+  /** the local values, or null when there is no secrets.json */
+  values: Record<string, string> | null;
+  /** declared names with a local value */
+  provided: string[];
+  /** declared names without a local value */
+  unprovided: string[];
+  /** local values that no declaration names */
+  undeclared: string[];
+}
+
+/** What a pb_secrets/ directory declares and holds locally, and how the two compare. */
+export async function secretsState(dir = SECRETS_DIR): Promise<SecretsState> {
+  const loaded = await loadDefinition(dir);
+  const values = readSecretsValues(dir);
+  if (!loaded && values && Object.keys(values).length) {
+    throw new Error(`voidbase: ${join(resolve(dir), VALUES_FILE)} holds ${Object.keys(values).length} value(s) but nothing declares them. Name them in ${join(dir, "main.ts")}:\n  export default defineSecrets({ ${Object.keys(values).map((k) => `${k}: string().secret()`).join(", ")} })`);
+  }
+  const names = loaded?.definition.names ?? [];
+  const have = new Set(Object.keys(values ?? {}));
+  return {
+    dir: resolve(dir), file: loaded?.file ?? null, definition: loaded?.definition ?? null, info: loaded ? await loaded.definition.info() : [], values,
+    provided: names.filter((n) => have.has(n)),
+    unprovided: names.filter((n) => !have.has(n)),
+    undeclared: [...have].filter((n) => !names.includes(n)),
+  };
+}
+
+export interface LoadedSecrets {
+  state: SecretsState;
+  /** the parse of the local values under the environment (the environment wins) */
+  evaluation: Evaluation<Spec> | null;
+  /** names this call put into the environment (from the file or a default) */
+  loaded: string[];
+  /** declared names with no value anywhere and no default */
+  missing: string[];
+  /** declared names whose value was refused, by name and reason */
+  invalid: { name: string; message: string }[];
+  /** local values that no declaration names */
+  undeclared: string[];
+}
+
+/**
+ * Parses the local values and the environment through the declaration and puts every stored value (defaults
+ * included) into the environment, never over a value that is already there. Nothing throws for a missing or
+ * refused value: the caller decides (serve warns, deploy stops).
+ */
+export async function loadSecrets(dir = SECRETS_DIR, into: Record<string, string | undefined> = process.env): Promise<LoadedSecrets> {
+  const state = await secretsState(dir);
+  if (!state.definition) return { state, evaluation: null, loaded: [], missing: [], invalid: [], undeclared: state.undeclared };
+  const raw: Record<string, unknown> = { ...(state.values ?? {}) };
+  for (const n of state.definition.names) if (into[n] !== undefined && into[n] !== "") raw[n] = into[n];
+  const evaluation = await state.definition.evaluate(raw);
+  const loaded: string[] = [];
+  for (const [k, v] of Object.entries(evaluation.stored)) if (into[k] === undefined || into[k] === "") { into[k] = v; loaded.push(k); }
+  return { state, evaluation, loaded, missing: evaluation.missing, invalid: evaluation.invalid, undeclared: state.undeclared };
+}
+
+// ---- the Worker's secrets, through the Workers API (what `wrangler secret put` calls) -----------------------------
+
+/** The names of the secrets a Worker has; an empty list when the Worker does not exist yet. */
+export async function workerSecretNames(api: CfApi, account: string, worker: string): Promise<string[]> {
+  // 10007: no such script yet (the first deploy creates it); CfApi tolerates error codes, not HTTP statuses
+  const res = await api.json<{ name: string; type: string }[]>("GET", `/accounts/${account}/workers/scripts/${encodeURIComponent(worker)}/secrets`, undefined, [10007]);
+  return (res.result ?? []).map((s) => s.name);
+}
+
+/** Stores secrets on a Worker, one call each (each becomes the current version's binding). The Worker must exist. */
+export async function putWorkerSecrets(api: CfApi, account: string, worker: string, secrets: Record<string, string>): Promise<string[]> {
+  const done: string[] = [];
+  for (const [name, text] of Object.entries(secrets)) {
+    await api.json("PUT", `/accounts/${account}/workers/scripts/${encodeURIComponent(worker)}/secrets`, { name, text, type: "secret_text" });
+    done.push(name);
+  }
+  return done;
+}
+
+/** The scaffold `voidbase init` writes: a declaration with an example of each tier, and how the values arrive. */
+export function declarationScaffold(pkg = "@voidbase-cloud/voidbase"): string {
+  return `// The app's configuration: declared here, valued in pb_secrets/secrets.json (git-ignored) on your machine and in
+// the Worker's secrets and vars once deployed. Read by \`voidbase serve\` and \`voidbase deploy\`; in hooks,
+// $os.getenv("NAME"); in TypeScript, \`await definition.read(env)\` gives the typed values.
+//
+//   .secret()   the Worker's encrypted secrets, never listed, never in a build (\`voidbase secrets push\` stores them)
+//   (plain)     server configuration: a plain Worker var, hooks and routes only
+//   .public()   a Worker var the browser may know too: a client build inlines it as import.meta.env.NAME
+import { defineSecrets, describe, string, number } from "${pkg}/secrets";
+
+export default defineSecrets({
+  // SMTP_PASSWORD: describe(string().secret(), "the mail provider's SMTP password"),
+  // MAX_UPLOAD_MB: number().default(10),
+  // PUBLIC_SITE_URL: string().optional().public(),
+});
+`;
+}

package/src/node/serve.ts

@@ -9,7 +9,9 @@ import { assetsFetcher } from "./assets";
 import { ensurePanelDir } from "./panel";
 import { embedded } from "./embedded";
 
-export interface ServeOptions { http?: string; dir?: string; hooksDir?: string; migrationsDir?: string; publicDir?: string; quiet?: boolean }
+export interface ServeOptions { http?: string; dir?: string; hooksDir?: string; migrationsDir?: string;
+  /** pb_secrets/: the declaration and the git-ignored values (VOIDBASE_SECRETS_DIR) */
+  secretsDir?: string; publicDir?: string; quiet?: boolean }
 const PKG = resolve(import.meta.dir, "../..");
 
 // system tables: the same SQL migrations Void applies on Cloudflare
@@ -37,6 +39,8 @@ export function applySystemMigrations(db: ReturnType<typeof openDatabase>, migra
 // Bun loads ./.env itself; a project that keeps its environment one level up (the SvelteKit starter) gets that too.
 // PB_* names from the PocketBase starter convention are accepted as aliases of the VOIDBASE_* ones.
 const ENV_ALIASES: Record<string, string> = { PB_SUPERUSER_EMAIL: "VOIDBASE_SUPERUSER_EMAIL", PB_SUPERUSER_PASSWORD: "VOIDBASE_SUPERUSER_PASSWORD", PB_USER_EMAIL: "VOIDBASE_USER_EMAIL", PB_USER_PASSWORD: "VOIDBASE_USER_PASSWORD", PB_ENCRYPTION_KEY: "VOIDBASE_ENCRYPTION_KEY" };
+import { loadSecrets } from "./secrets";
+
 export function loadEnv(files = [".env", ".env.local", "../.env", "../.env.local"]): void {
   for (const f of files) {
     if (!existsSync(f)) continue;
@@ -50,18 +54,28 @@ export function loadEnv(files = [".env", ".env.local", "../.env", "../.env.local
 }
 
 export async function openLocal(opts: ServeOptions) {
+  // pb_secrets/secrets.json (git-ignored) into the environment before the .env files, so $os.getenv and the app see
+  // the same names as on Cloudflare, where the deploy stored them as the Worker's secrets (src/node/secrets.ts):
+  // the shell outranks secrets.json, which outranks a dev placeholder in .env
+  process.env.VOIDBASE_SECRETS_DIR = resolve(opts.secretsDir ?? process.env.VOIDBASE_SECRETS_DIR ?? "pb_secrets");
+  const secrets = await loadSecrets(process.env.VOIDBASE_SECRETS_DIR);
+  if (secrets.invalid.length) throw new Error(`voidbase: ${process.env.VOIDBASE_SECRETS_DIR}: ${secrets.invalid.map((i) => `${i.name}: ${i.message}`).join(", ")}`);
   loadEnv();
   const dir = resolve(opts.dir ?? "pb_data");
   mkdirSync(dir, { recursive: true });
   process.env.VOIDBASE_HOOKS_DIR = resolve(opts.hooksDir ?? process.env.VOIDBASE_HOOKS_DIR ?? "pb_hooks");
   process.env.VOIDBASE_MIGRATIONS_DIR = resolve(opts.migrationsDir ?? process.env.VOIDBASE_MIGRATIONS_DIR ?? "pb_migrations");
+  if (secrets.missing.length && !opts.quiet) console.warn(`voidbase: ${secrets.missing.length} declared value(s) missing and without a default (${process.env.VOIDBASE_SECRETS_DIR}/secrets.json): ${secrets.missing.join(", ")}`);
+  if (secrets.undeclared.length && !opts.quiet) console.warn(`voidbase: ${process.env.VOIDBASE_SECRETS_DIR}/secrets.json holds ${secrets.undeclared.join(", ")}, which main.ts does not declare; a deploy stores only declared values`);
   // pb_data/types.d.ts for editor support in pb_hooks (PocketBase's JSVM typings); a standalone executable carries
   // the typings and the system migrations itself (src/node/embedded.ts)
   const emb = await embedded();
   try { if (!existsSync(`${dir}/types.d.ts`)) writeFileSync(`${dir}/types.d.ts`, emb?.typesDts ?? readFileSync(`${PKG}/types/pb_data.d.ts`, "utf8")); } catch { /* optional */ }
   const sqlite = openDatabase(`${dir}/data.db`);
   applySystemMigrations(sqlite, emb?.migrations ?? readSystemMigrations());
-  const env = { DB: d1(sqlite), STORAGE: fsBucket(`${dir}/storage`), ASSETS: assetsFetcher({ panelDir: await ensurePanelDir(), publicDir: opts.publicDir ? resolve(opts.publicDir) : undefined }) };
+  // PocketBase serves ./pb_public at / when the directory exists (--publicDir); a build there is a full static host
+  const publicDir = opts.publicDir ? resolve(opts.publicDir) : existsSync(resolve("pb_public")) ? resolve("pb_public") : undefined;
+  const env = { DB: d1(sqlite), STORAGE: fsBucket(`${dir}/storage`), ASSETS: assetsFetcher({ panelDir: await ensurePanelDir(), publicDir }) };
   return { dir, sqlite, env };
 }
 

package/src/server/api.ts

@@ -4,8 +4,8 @@
 import type { Context, Hono } from "hono";
 import { app } from "./app";
 import { hookGlobals } from "./hooks";
-import type { RequestEvent } from "./hooks/runtime";
-import type { AppEnv } from "./types";
+import { hookStore, type RequestEvent } from "./hooks/runtime";
+import type { AppEnv, Bindings } from "./types";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type HookGlobals = Record<string, any>;
@@ -20,6 +20,11 @@ export interface VoidbaseApp {
   /** $app, $apis, $os, $security, routerAdd, routerUse, cronAdd, cronRemove, on* event registrations, Record, Collection, ... */
   hooks: HookGlobals;
 }
+/** The bindings of the request, cron tick or migration currently running (the hook store's env), or undefined
+ * outside one. Extensions that are handed no context (a cron callback, a queue consumer) read them here. */
+export function currentBindings(): Bindings | undefined {
+  return hookStore.getStore()?.env as Bindings | undefined;
+}
 export function appApi(): VoidbaseApp {
   const hooks = hookGlobals() as HookGlobals;
   const late = (method: string): LateRegister => (path, handler) => hooks.routerAdd(method, path, (e: RequestEvent) => handler(e.c));

package/src/server/app.ts

@@ -7,7 +7,7 @@ import type { Field } from "./collections/fields";
 import { createRecord, deleteRecord, listRecords, updateRecord, viewRecord, type ListQuery, type RecordContext } from "./records/service";
 import { fromColumn, toColumn } from "./records/values";
 import { expandRecords } from "./records/expand";
-import { hookGlobals, hookMiddleware, loadHooks, mountHookRoutes } from "./hooks";
+import { globalHookMiddleware, hookGlobals, hookMiddleware, loadHooks, mountHookRoutes } from "./hooks";
 import { requestHook, requestHookResult, trigger } from "./hooks/runtime";
 import { logger } from "#platform/log";
 import { env as voidEnv } from "#platform/env";
@@ -46,6 +46,7 @@ import { ApiError, badRequest, forbidden, notFound } from "./errors";
 import { randomIdSuffix, randomString } from "./ids";
 import { createCollection, deleteCollection, importCollections, inferViewFields, truncateCollection, updateCollection } from "./collections/service";
 import { loadSettings, publicSettings } from "./settings";
+import { mountWebAuthn } from "./webauthn";
 import type { AppEnv, Row } from "./types";
 
 export const app = new Hono<AppEnv>();
@@ -79,6 +80,8 @@ app.use("*", requestLogger());
 app.use("*", bodyLimitMiddleware());
 app.use("*", rateLimitMiddleware());
 app.use("*", hookMiddleware() as never);
+// PocketBase's routerUse: the app's own global middleware, around every request (see src/adapter for Void's middleware/)
+app.use("*", globalHookMiddleware() as never);
 
 app.onError((err, c) => {
   if (err instanceof ApiError) return err.response();
@@ -471,6 +474,8 @@ function sortBy<T extends object>(items: T[], sort: string, allowed: string[]):
 }
 
 // --- passkeys (the starter's Go webauthn routes, native here) ---------------
+// mounted for every app; the routes answer only where a `passkeys` collection exists
+mountWebAuthn(app);
 mountOAuth2Redirect(app);
 mountSettingsApi(app);
 const authDeps = {

package/src/server/hooks/index.ts

@@ -3,12 +3,13 @@ import { logger } from "#platform/log";
 import type { Hono, MiddlewareHandler } from "hono";
 import { files, hooks, hooksDir, modules } from "#platform/hooks";
 import { loadCollections } from "../collections/model";
+import { dispatch, registerJobHandler, type Job } from "../jobs";
 import { loadSettings } from "../settings";
 import type { AppEnv } from "../types";
 import { CollectionRef, HookRecord } from "./record";
 import {
   $apis, $app, $dbx, $filesystem, $http, $security, BadRequestError, ForbiddenError, InternalServerError, MailerMessage, NotFoundError,
-  RecordUpsertFormFactory, RequestEvent, UnauthorizedError, ValidationError, authToHookRecord, cronAdd, cronRemove, hookStore,
+  RecordUpsertFormFactory, RequestEvent, UnauthorizedError, ValidationError, authToHookRecord, cronAdd, cronRemove, globalMiddlewares, hookStore,
   crons, eventHooks, makeOs, onEvent, routerAdd, routerUse, routes, type HookMiddleware,
 } from "./runtime";
 import { ApiError } from "../errors";
@@ -28,6 +29,10 @@ function buildGlobals(): Record<string, unknown> {
   const g: Record<string, unknown> = {
     $app, $apis, $http, $os, $filesystem, $security,
     $mails: {}, $template: { loadFiles: () => ({ render: () => "" }) }, $dbx,
+    // voidbase extensions a hook cannot get at otherwise: the Cloudflare bindings of the request, cron tick or
+    // migration running now, and the background jobs queue
+    $env: () => (hookStore.getStore()?.env ?? {}) as Record<string, unknown>,
+    $jobs: { queueJob: (job: Job) => dispatch(job), onJob: (type: Job["type"], fn: Parameters<typeof registerJobHandler>[1]) => registerJobHandler(type, fn) },
     routerAdd, routerUse, cronAdd, cronRemove,
     migrate: () => { /* migrations are applied by the migrations runner, not at hook load */ },
     Record: class Record extends HookRecord { constructor(collection: CollectionRef, data?: { [k: string]: unknown }) { super(collection, data ?? {}); } },
@@ -136,6 +141,27 @@ export function mountHookRoutes(app: Hono<AppEnv>) {
   });
 }
 
+/** PocketBase's routerUse middleware, around every request voidbase serves (its own endpoints included). */
+export function globalHookMiddleware(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (!globalMiddlewares.length) return next();
+    const ev = new RequestEvent(c, authToHookRecord(c.get("auth")));
+    let i = 0, reachedRoute = false;
+    const step = async (): Promise<unknown> => {
+      const mw = globalMiddlewares[i++];
+      if (!mw) { reachedRoute = true; await next(); return undefined; }
+      return (typeof mw === "function" ? mw : mw.func)(ev);
+    };
+    ev.next = step;
+    const result = await step();
+    if (result instanceof Response) return result;
+    if (ev.written) return ev.written;
+    // a middleware that stopped the chain without answering: an empty 204, as a hook route in the same state gets
+    if (!reachedRoute) return c.body(null, 204);
+    return undefined;
+  };
+}
+
 // Per-request state for $app and friends.
 export function hookMiddleware(): MiddlewareHandler<AppEnv> {
   return async (c, next) => {

package/src/server/hooks/migrations.ts

@@ -5,7 +5,7 @@
 import { migrations } from "#platform/migrations";
 import { invalidateCollections, loadCollections } from "../collections/model";
 import { importCollections } from "../collections/service";
-import { all, stmt } from "../db";
+import { all, run, stmt } from "../db";
 import { loadSettings } from "../settings";
 import type { RecordContext } from "../records/service";
 import type { AppEnv } from "../types";
@@ -34,6 +34,9 @@ async function runPending(db: D1Database, globals: Record<string, unknown>): Pro
   const applied = new Set((await all<{ file: string }>(db, "SELECT file FROM `_pbMigrations`")).map((r) => r.file));
   const own: Record<string, unknown> = {
     importCollections: (list: Record<string, unknown>[], deleteMissing = false) => importCollections(db, list, deleteMissing),
+    // raw DDL/DML for migrations that are not about collections (a Void app's Drizzle migrations, see src/adapter):
+    // voidbase-specific, PocketBase spells this app.db().newQuery(sql).execute()
+    execSQL: (sql: string, params: unknown[] = []) => run(db, sql, params),
   };
   const $app = (globals.$app ?? {}) as Record<string, unknown>;
   const app = new Proxy(own, { get: (t, k) => (k in t ? t[k as string] : $app[k as string]), has: (t, k) => k in t || k in $app });

package/src/server/hooks/runtime.ts

@@ -1,6 +1,10 @@
 // The JSVM-compatible global API for pb_hooks files, plus the registries their calls populate.
 // Per-request state ($app's database, the request) is carried by AsyncLocalStorage.
 import { AsyncLocalStorage } from "node:async_hooks";
+// A generated pb_hooks bundle (src/adapter) cannot import anything: the hook sandbox resolves only its sibling
+// files. Void's runtime needs AsyncLocalStorage, so the bundle reads it here, from the one place both runtimes
+// already have it (Bun natively, Workers through nodejs_compat).
+(globalThis as { AsyncLocalStorage?: unknown }).AsyncLocalStorage ??= AsyncLocalStorage;
 import type { Context } from "hono";
 import type { Collection } from "../collections/model";
 import { ApiError } from "../errors";
@@ -299,7 +303,9 @@ export const $security = {
 
 export function makeOs(files: Record<string, string>, hooksDir: string) {
   return {
-    getenv: (name: string) => { const v = store()?.env[name]; return v == null ? "" : String(v); },
+    // the bindings first (a Worker's vars and secrets), then the process environment (Bun; a Worker has none
+    // without nodejs_compat), which is what PocketBase's $os.getenv reads
+    getenv: (name: string) => { const v = store()?.env[name]; if (v != null) return String(v); const p = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[name]; return p == null ? "" : String(p); },
     readFile: (path: string) => {
       const rel = path.startsWith(hooksDir) ? path.slice(hooksDir.length).replace(/^\/+/, "") : path;
       const text = files[rel];
@@ -316,7 +322,9 @@ export function makeOs(files: Record<string, string>, hooksDir: string) {
 export function routerAdd(method: string, path: string, handler: HookFn, ...middlewares: HookMiddleware[]) {
   routes.push({ method: method.toUpperCase() === "ANY" ? "ALL" : method.toUpperCase(), path: toHonoPath(path), handler, middlewares });
 }
-export function routerUse(..._middlewares: HookMiddleware[]) { /* global hook middleware: milestone six */ }
+/** Global middleware, PocketBase's `routerUse`: runs on every request, before the route that answers it. */
+export const globalMiddlewares: HookMiddleware[] = [];
+export function routerUse(...middlewares: HookMiddleware[]) { globalMiddlewares.push(...middlewares); }
 export function cronAdd(id: string, expr: string, fn: () => unknown) { crons.set(id, { expr, fn }); }
 export function cronRemove(id: string) { crons.delete(id); }
 

package/src/server/jobs.ts

@@ -8,7 +8,9 @@ import type { Bindings } from "./types";
 
 export type Job =
   | { type: "mail"; message: MailMessage; text: string }
-  | { type: "backup"; name: string };
+  | { type: "backup"; name: string }
+  // a message for one of the app's own queues (a Void app's queues/<name>.ts, mounted by src/adapter)
+  | { type: "queue"; queue: string; body: unknown };
 export type JobHandler<T extends Job = Job> = (env: Bindings, job: T) => Promise<void>;
 
 const handlers = new Map<Job["type"], JobHandler>();

package/src/server/webauthn.ts

@@ -3,7 +3,9 @@
 // Credentials live in the app's `passkeys` collection (user, credential_id, credentials) exactly like the Go code;
 // the pending challenge lives in _params (the Go version keeps it in memory, which a Worker cannot rely on).
 import type { Context, Hono } from "hono";
-import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
+// loaded on the first passkey request rather than at startup: @simplewebauthn/server is half a megabyte, and most
+// apps have no `passkeys` collection and never reach these routes
+const webauthn = () => import("@simplewebauthn/server");
 import { recordAuthResponse } from "./auth-response";
 import { loadCollections } from "./collections/model";
 import { all, ident, one, run } from "./db";
@@ -78,14 +80,29 @@ async function takeSession(db: D1Database, userId: string): Promise<string | nul
   return s.expires > Date.now() ? s.challenge : null;
 }
 
-export function mountWebAuthn(app: Pick<Hono<AppEnv>, "get" | "post"> | { get: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => void; post: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => void }) {
+type Router = Pick<Hono<AppEnv>, "get" | "post"> | { get: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => void; post: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => void };
+
+/**
+ * Mounts the four passkey endpoints. voidbase's own app mounts them, so an app gets them for free; the export is
+ * for anyone putting them on a router of their own.
+ *
+ * They answer only when the app has a `passkeys` collection. Without one there is nowhere to keep a credential, so
+ * the feature is off and the endpoints are not there.
+ */
+export function mountWebAuthn(router: Router) {
+  const gated = (h: (c: Context<AppEnv>) => Promise<Response>) => async (c: Context<AppEnv>) => {
+    if (!(await loadCollections(c.env.DB)).has("passkeys")) return c.json({ status: 404, message: "Not Found.", data: {} }, 404);
+    return h(c);
+  };
+  const app = { get: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => router.get(p, gated(h) as never), post: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => router.post(p, gated(h) as never) };
+
   app.get("/api/webauthn/registration-options", async (c) => {
     const user = await findUser(c.env.DB, c.req.query("usernameOrEmail") ?? "");
     if (!user) return c.json(RESPONSES.failed, 400);
     try {
       const rp = await relyingParty(c);
       const existing = await credentialsOf(c.env.DB, String(user.id));
-      const options = await generateRegistrationOptions({
+      const options = await (await webauthn()).generateRegistrationOptions({
         rpName: rp.rpName, rpID: rp.rpID,
         userID: new TextEncoder().encode(String(user.id)),
         userName: String(user.username || user.email || user.id),
@@ -110,7 +127,7 @@ export function mountWebAuthn(app: Pick<Hono<AppEnv>, "get" | "post"> | { get: (
       const challenge = await takeSession(c.env.DB, String(user.id));
       if (!challenge) return c.json(RESPONSES.reg_error, 500);
       const { usernameOrEmail: _u, ...response } = body;
-      const verification = await verifyRegistrationResponse({ response: response as never, expectedChallenge: challenge, expectedOrigin: rp.origin, expectedRPID: rp.rpID, requireUserVerification: false });
+      const verification = await (await webauthn()).verifyRegistrationResponse({ response: response as never, expectedChallenge: challenge, expectedOrigin: rp.origin, expectedRPID: rp.rpID, requireUserVerification: false });
       if (!verification.verified || !verification.registrationInfo) return c.json(RESPONSES.reg_error, 500);
       const info = verification.registrationInfo;
       const cred: StoredCredential = {
@@ -131,7 +148,7 @@ export function mountWebAuthn(app: Pick<Hono<AppEnv>, "get" | "post"> | { get: (
     try {
       const rp = await relyingParty(c);
       const creds = await credentialsOf(c.env.DB, String(user.id));
-      const options = await generateAuthenticationOptions({ rpID: rp.rpID, userVerification: "preferred", allowCredentials: creds.map((e) => ({ id: e.cred.id, transports: e.cred.transports })) });
+      const options = await (await webauthn()).generateAuthenticationOptions({ rpID: rp.rpID, userVerification: "preferred", allowCredentials: creds.map((e) => ({ id: e.cred.id, transports: e.cred.transports })) });
       await putSession(c.env.DB, String(user.id), options.challenge);
       return c.json({ publicKey: options });
     } catch (err) {
@@ -151,7 +168,7 @@ export function mountWebAuthn(app: Pick<Hono<AppEnv>, "get" | "post"> | { get: (
       const { usernameOrEmail: _u, ...response } = body;
       const match = (await credentialsOf(c.env.DB, String(user.id))).find((e) => e.cred.id === response.id);
       if (!match) return c.json(RESPONSES.login_error, 500);
-      const verification = await verifyAuthenticationResponse({
+      const verification = await (await webauthn()).verifyAuthenticationResponse({
         response: response as never, expectedChallenge: challenge, expectedOrigin: rp.origin, expectedRPID: rp.rpID, requireUserVerification: false,
         credential: { id: match.cred.id, publicKey: b64url.decode(match.cred.publicKey), counter: match.cred.counter, transports: match.cred.transports },
       });

package/tsconfig.json

@@ -27,7 +27,12 @@
   "exclude": [
     "bin",
     "hooks-plugin.ts",
+    "src/env/define.ts",
     "scripts",
+    "src/adapter/codegen.ts",
+    "src/adapter/index.ts",
+    "src/adapter/plugin.ts",
+    "src/adapter/scan.ts",
     "src/node",
     "src/platform/node",
     "surface",

package/tsconfig.node.json

@@ -22,6 +22,8 @@
     "src/platform/node",
     "src/server",
     "hooks-plugin.ts",
-    "bin"
+    "src/env/define.ts",
+    "bin",
+    "src/adapter"
   ]
 }