@voidbase-cloud/voidbase 0.2.1 → 0.3.0

package/src/node/cloud-init.ts

@@ -7,6 +7,20 @@ const ROOT = resolve(import.meta.dir, "../..");
 
 // mode "package": a visible project importing the voidbase package (voidbase cloud init).
 // mode "internal": a project inside this package at .cloud/<slug>, importing ../../src etc. (voidbase deploy).
+export interface RedirectEntry { source: string; host?: string; path: string; to: string; status: number; line: number }
+// Netlify/Pages-style `_redirects`: `source destination [status]`, `#` comments. A source may carry a host
+// (`https://api.example.com/`), which scopes the rule to that hostname. 3xx rules only (default 302).
+export function parseRedirects(text: string): RedirectEntry[] {
+  const out: RedirectEntry[] = [];
+  text.split("\n").forEach((raw, i) => {
+    const line = raw.replace(/#.*$/, "").trim(); if (!line) return;
+    const [source, to, statusRaw] = line.split(/\s+/); if (!source || !to) return;
+    const status = Number((statusRaw ?? "302").replace(/!$/, "")); if (![301, 302, 303, 307, 308].includes(status)) return;
+    const m = source.match(/^https?:\/\/([^/]+)(\/.*)?$/);
+    out.push({ source, host: m ? m[1]!.toLowerCase() : undefined, path: m ? m[2] || "/" : source, to, status, line: i + 1 });
+  });
+  return out;
+}
 export function writeCloudProject(out: string, mode: "package" | "internal" = "package", extra: { hooksDir?: string; migrationsDir?: string; entry?: string; queue?: string | false; hub?: boolean } = {}): { files: number; out: string } {
   const parentPkg = existsSync("package.json") ? (JSON.parse(readFileSync("package.json", "utf8")) as { dependencies?: Record<string, string> }) : {};
   const spec = parentPkg.dependencies?.["@voidbase-cloud/voidbase"] ?? parentPkg.dependencies?.voidbase ?? "^0.1.0";

package/src/node/deploy-cf.ts

@@ -5,9 +5,10 @@
 // which builds, applies the D1 migrations and uploads the Worker.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { writeCloudProject } from "./cloud-init";
+import { parseRedirects, writeCloudProject, type RedirectEntry } from "./cloud-init";
 import { loadEnv } from "./serve";
-import { CfApi, attachCustomDomain, ensureD1, ensureQueue, ensureR2, rateLimitNamespace, resolveAccount, workersSubdomain } from "../cloud/rest";
+import { loadSecrets, SECRETS_DIR, workerSecretNames } from "./secrets";
+import { CfApi, attachCustomDomain, ensureD1, ensureQueue, ensureR2, findZone, rateLimitNamespace, resolveAccount, workersSubdomain } from "../cloud/rest";
 
 const API = (process.env.CLOUDFLARE_API_BASE ?? "https://api.cloudflare.com/client/v4").replace(/\/$/, "");
 export const TOKEN_ENV = "VOIDBASE_DEPLOY_CF_API_KEY";
@@ -73,14 +74,27 @@ export function loadEnvFiles(files = [".env", ".env.local", "../.env", "../.env.
   return loaded;
 }
 
-export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ name: string; account: string; url: string | null; wranglerConfig: string; project: string }> {
+/** The environment, the token, the account and the worker name a deploy (or `voidbase secrets`) targets. */
+export async function deployTarget(opts: Pick<DeployOptions, "name" | "account" | "log"> = {}): Promise<{ api: CfApi; token: string; account: { id: string; name: string }; name: string; secretsDir: string; secrets: ReturnType<typeof loadSecrets> }> {
   const log = opts.log ?? ((l: string) => console.log(l));
+  // pb_secrets/ first: the declared names, and on a dev machine their values, which count as environment from here
+  // on. The shell outranks secrets.json, and secrets.json outranks the .env files, so a dev placeholder in .env
+  // (VOIDBASE_SUPERUSER_PASSWORD=changeme123) never shadows the real value kept beside the declaration.
+  const secretsDir = resolve(process.env.VOIDBASE_SECRETS_DIR || SECRETS_DIR);
+  const secrets = loadSecrets(secretsDir);
   loadEnv(); const fromFiles = loadEnvFiles(); if (fromFiles.length) log(`from .env: ${fromFiles.join(", ")}`);
+  if (secrets.state.declaration) log(`${secretsDir}: ${secrets.state.declaration.names.length} secret(s) declared, ${secrets.state.provided.length} valued here${secrets.undeclared.length ? `; in secrets.json but not declared (not deployed): ${secrets.undeclared.join(", ")}` : ""}`);
   const token = process.env[TOKEN_ENV] || process.env.CLOUDFLARE_API_TOKEN || ""; // empty means unset
   if (!token) { log(`${TOKEN_ENV} is not set.\n\n${tokenHelp()}`); throw new Error(`${TOKEN_ENV} missing`); }
   const name = slug(opts.name || process.env.VOIDBASE_DEPLOY_NAME || projectName());
   const api = new CfApi(token, API);
   const account = await resolveAccount(api, opts.account || process.env.VOIDBASE_DEPLOY_CF_ACCOUNT_ID || undefined).catch((e: Error) => { throw new Error(`${e.message} (is it ${TOKEN_ENV} with Account Settings read?)`); });
+  return { api, token, account, name, secretsDir, secrets };
+}
+
+export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ name: string; account: string; url: string | null; wranglerConfig: string; project: string }> {
+  const log = opts.log ?? ((l: string) => console.log(l));
+  const { api, token, account, name, secretsDir, secrets: pbSecrets } = await deployTarget(opts);
   log(`account ${account.name} (${account.id}), worker "${name}"`);
   const db = await ensureD1(api, account.id, `${name}-db`); log(`D1 ${name}-db ${db.created ? "created" : "exists"} (${db.uuid})`);
   const bucket = await ensureR2(api, account.id, `${name}-storage`); log(`R2 ${name}-storage ${bucket.created ? "created" : "exists"}`);
@@ -93,8 +107,19 @@ export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ na
   // Workers Free allows 5 cron triggers per account; without the trigger PocketBase's maintenance runs lazily in requests
   const cron = opts.cron ?? !off(process.env.VOIDBASE_DEPLOY_CRON);
   // a custom domain on a zone of the account (wrangler attaches it: DNS record + certificate); workers.dev is then off
-  const domain = String(opts.domain || process.env.VOIDBASE_DEPLOY_DOMAIN || "").trim().replace(/^https?:\/\//, "").replace(/\/.*$/, "").toLowerCase();
-  if (domain && !/^[a-z0-9.-]+\.[a-z]{2,}$/.test(domain)) throw new Error(`invalid custom domain "${domain}"`);
+  // several hostnames may be listed (comma separated); the first is the Worker's URL, all are attached
+  const domains = String(opts.domain || process.env.VOIDBASE_DEPLOY_DOMAIN || "").split(",").map((d) => d.trim().replace(/^https?:\/\//, "").replace(/\/.*$/, "").toLowerCase()).filter(Boolean);
+  for (const d of domains) if (!/^[a-z0-9.-]+\.[a-z]{2,}$/.test(d)) throw new Error(`invalid custom domain "${d}"`);
+  const domain = domains[0] ?? "";
+  // the static site next to the API: --public-dir, VOIDBASE_DEPLOY_PUBLIC_DIR, or ./pb_public when it exists (PocketBase's default)
+  const publicDir = opts.publicDir || process.env.VOIDBASE_DEPLOY_PUBLIC_DIR || (existsSync(resolve("pb_public")) ? "pb_public" : undefined);
+  if (publicDir && !existsSync(resolve(publicDir, "index.html"))) throw new Error(`public dir ${resolve(publicDir)} has no index.html (build the site first)`);
+  // <public dir>/_redirects, Netlify/Pages syntax. Path-only lines go to the assets as Cloudflare's own _redirects (it
+  // only accepts relative sources); host-scoped lines (`https://api.example.com/ /_/ 302`) become zone Redirect Rules
+  // after the upload, which is how one Worker behind several custom domains answers differently per hostname.
+  const redirects = publicDir && existsSync(resolve(publicDir, "_redirects")) ? parseRedirects(readFileSync(resolve(publicDir, "_redirects"), "utf8")) : [];
+  const hostRedirects = redirects.filter((r) => r.host), pathRedirects = redirects.filter((r) => !r.host);
+  if (redirects.length) log(`redirects (${resolve(publicDir!, "_redirects")}): ${redirects.map((r) => `${r.source} -> ${r.to} (${r.status})`).join(", ")}${hostRedirects.length ? `; the ${hostRedirects.length} host-scoped rule(s) become zone Redirect Rules after the upload` : ""}`);
   let queue: string | false = false;
   if (wantQueue) {
     const q = await ensureQueue(api, account.id, `${name}-jobs`);
@@ -143,14 +168,43 @@ export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ na
   const saved = existsSync(credFile) ? (JSON.parse(readFileSync(credFile, "utf8")) as { email: string; password: string }) : null;
   const placeholder = !password || password === "changeme123"; // the local dev default never goes live
   if (placeholder && saved && (!email || email === saved.email)) { email = saved.email; password = saved.password; }
-  if (!email) email = "admin@example.com";
-  if (!password || password === "changeme123") { password = randomPassword(); log(`generated a superuser password for ${email} (saved in ${credFile}; change it after the first login)`); }
-  writeFileSync(credFile, JSON.stringify({ email, password }, null, 2) + "\n", { mode: 0o600 });
+  // what the Worker already holds: a checkout with no credentials of its own (CI) must not replace the superuser
+  // the Worker has with a generated one that only this checkout would know
+  const onWorker = await workerSecretNames(api, account.id, name);
+  const keepSuperuser = placeholder && !saved && onWorker.includes("VOIDBASE_SUPERUSER_EMAIL") && onWorker.includes("VOIDBASE_SUPERUSER_PASSWORD");
+  if (keepSuperuser) log("superuser: no credentials in this checkout, the Worker keeps the ones it has");
+  else {
+    if (!email) email = "admin@example.com";
+    if (!password || password === "changeme123") { password = randomPassword(); log(`generated a superuser password for ${email} (saved in ${credFile}; change it after the first login)`); }
+    writeFileSync(credFile, JSON.stringify({ email, password }, null, 2) + "\n", { mode: 0o600 });
+  }
+
+  // the Worker's secrets: the superuser, VOIDBASE_DEPLOY_SECRETS=X,Y from the environment, and the declared
+  // pb_secrets/ names the Worker does not have yet. A deploy ships code; a value the Worker already holds is
+  // replaced only by `voidbase secrets push`, so a checkout whose secrets.json carries dev values (another OAuth
+  // client, the placeholder password) cannot overwrite production by deploying. A declared name with no value
+  // here must already be on the Worker.
+  const declared = pbSecrets.state.declaration?.names ?? [];
+  const secretMap = new Map<string, string>(keepSuperuser ? [] : [["VOIDBASE_SUPERUSER_EMAIL", email], ["VOIDBASE_SUPERUSER_PASSWORD", password]]);
+  for (const k of extraSecrets) if (process.env[k]) secretMap.set(k, process.env[k]!);
+  const kept: string[] = [];
+  for (const k of declared) {
+    const v = pbSecrets.state.values?.[k]; if (v === undefined) continue;
+    if (onWorker.includes(k)) { kept.push(k); continue; }
+    if (k === "VOIDBASE_SUPERUSER_PASSWORD" && v === "changeme123") { log("secrets: VOIDBASE_SUPERUSER_PASSWORD in secrets.json is the dev placeholder, not stored"); continue; }
+    secretMap.set(k, v);
+  }
+  const missingSecrets = declared.filter((k) => !secretMap.has(k) && !onWorker.includes(k));
+  if (missingSecrets.length) {
+    const msg = `${missingSecrets.length} declared secret(s) have no value in ${secretsDir}/secrets.json and are not on the Worker "${name}" yet: ${missingSecrets.join(", ")}. Push them once from a machine that has them: voidbase secrets push --name ${name}`;
+    if (opts.dryRun) log(`secrets: ${msg}`); else throw new Error(msg);
+  } else if (declared.length) log(`secrets: ${declared.length} declared; ${declared.filter((k) => secretMap.has(k)).length} stored from here, ${kept.length} kept as the Worker has them (voidbase secrets push replaces)`);
+  const secrets = [...secretMap.entries()];
 
   const url = domain ? `https://${domain}` : await workersSubdomain(api, account.id).then((s) => (s ? `https://${name}.${s}.workers.dev` : null));
-  if (domain) log(`custom domain ${domain} (workers.dev off): attached through the Workers Custom Domains API after the upload (Cloudflare adds the DNS record and certificate)`);
+  if (domain) log(`custom domain${domains.length > 1 ? "s" : ""} ${domains.join(", ")} (workers.dev off): attached through the Workers Custom Domains API after the upload (Cloudflare adds the DNS record and certificate)`);
   log(`bindings: D1, R2${hub ? ", realtime hub (Durable Object)" : ""}${queue ? ", Queue" : ""}${rateLimit ? `, rate limit ceiling ${rateLimit.limit}/${rateLimit.period}s per IP` : ""}${analytics ? ", Analytics Engine (needs Analytics Engine enabled once for the account: https://dash.cloudflare.com/" + account.id + "/workers/analytics-engine)" : ""}`);
-  if (opts.dryRun) { log(`dry run: would sync the panel${opts.publicDir ? ` and ${opts.publicDir}` : ""} into ${cloud}/public, put 2 secrets and run void deploy --backend cloudflare (${url ?? "url unknown"})`); return { name, account: account.id, url, wranglerConfig, project: cloud }; }
+  if (opts.dryRun) { log(`dry run: would sync the panel${publicDir ? ` and ${publicDir}` : ""} into ${cloud}/public, put ${secrets.length} secrets (${secrets.map(([k]) => k).join(", ")}) and run void deploy --backend cloudflare (${url ?? "url unknown"})`); return { name, account: account.id, url, wranglerConfig, project: cloud }; }
 
   // the toolchain comes with the voidbase package (void, and wrangler through void)
   const voidDir = resolve(Bun.resolveSync("void/package.json", PKG), "..");
@@ -158,22 +212,65 @@ export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ na
   // values also exported in the shell are stripped from baked vars by the Cloudflare backend, so keep the vars file clean instead
   // the generated project has no node_modules of its own: `void deploy` shells out to `vite build`, so the package's toolchain goes on PATH
   const binDirs = [resolve(PKG, "node_modules/.bin"), resolve(voidDir, "..", ".bin")].filter((d, i, a) => a.indexOf(d) === i);
-  const env: Record<string, string | undefined> = { ...process.env, PATH: `${binDirs.join(":")}:${process.env.PATH ?? ""}`, CLOUDFLARE_API_TOKEN: token, CLOUDFLARE_ACCOUNT_ID: account.id, VOIDBASE_SUPERUSER_EMAIL: email, VOIDBASE_SUPERUSER_PASSWORD: password };
+  const env: Record<string, string | undefined> = { ...process.env, PATH: `${binDirs.join(":")}:${process.env.PATH ?? ""}`, CLOUDFLARE_API_TOKEN: token, CLOUDFLARE_ACCOUNT_ID: account.id, ...(keepSuperuser ? {} : { VOIDBASE_SUPERUSER_EMAIL: email, VOIDBASE_SUPERUSER_PASSWORD: password }) };
   for (const k of Object.keys(baked)) delete env[k];
   const sh = async (cmd: string[], input?: string) => { const p = Bun.spawn(cmd, { cwd: cloud, env: env as Record<string, string>, stdin: input === undefined ? "inherit" : new TextEncoder().encode(input), stdout: "inherit", stderr: "inherit" }); const code = await p.exited; if (code !== 0) throw new Error(`${cmd.join(" ")} exited with ${code}`); };
   mkdirSync(`${cloud}/public`, { recursive: true });
   await sh(["bun", resolve(PKG, "scripts/sync-panel.ts"), "--dest", `${cloud}/public/_`]);
-  if (opts.publicDir) await sh(["bun", resolve(PKG, "scripts/sync-app.ts"), "--dest", `${cloud}/public`], undefined).catch((e) => log(`frontend build not synced: ${e instanceof Error ? e.message : e}`));
-  const secrets: [string, string][] = [["VOIDBASE_SUPERUSER_EMAIL", email], ["VOIDBASE_SUPERUSER_PASSWORD", password], ...extraSecrets.filter((k) => process.env[k]).map((k): [string, string] => [k, process.env[k]!])];
+  if (publicDir) {
+    env.VOIDBASE_APP_DIR = resolve(publicDir); await sh(["bun", resolve(PKG, "scripts/sync-app.ts"), "--dest", `${cloud}/public`], undefined); log(`static site ${resolve(publicDir)} served at / (the panel stays at /_/)`);
+    if (pathRedirects.length) writeFileSync(`${cloud}/public/_redirects`, pathRedirects.map((r) => `${r.path} ${r.to} ${r.status}`).join("\n") + "\n");
+  }
+  if (secrets.length) log(`secrets: storing ${secrets.map(([k]) => k).join(", ")} on the Worker`);
   for (const [k, v] of secrets) await sh(["bun", wrangler, "secret", "put", k, "--name", name], v + "\n");
   await sh([voidBin, "deploy", "--backend", "cloudflare"]);
-  if (domain) {
-    const d = await attachCustomDomain(api, account.id, { hostname: domain, service: name });
+  for (const host of domains) {
+    const d = await attachCustomDomain(api, account.id, { hostname: host, service: name });
     log(`custom domain ${d.hostname} ${d.created ? "attached" : "already attached"} (zone ${d.zone_id}); the certificate can take a minute`);
   }
+  if (hostRedirects.length) await applyZoneRedirects(api, account.id, name, hostRedirects, log);
   if (url) {
     const ok = await fetch(`${url}/api/health`).then((r) => r.status).catch(() => 0);
-    log(`\nlive: ${url}  (health ${ok || "not reachable yet"})\n├─ REST API:  ${url}/api/\n└─ Dashboard: ${url}/_/   sign in as ${email} (password in ${credFile})`);
+    log(`\nlive: ${url}  (health ${ok || "not reachable yet"})\n├─ REST API:  ${url}/api/\n└─ Dashboard: ${url}/_/   sign in as ${keepSuperuser ? "the superuser the Worker already had" : `${email} (password in ${credFile})`}`);
   } else log("deployed; workers.dev subdomain not enabled on this account, add a route or enable it in the dashboard (or VOIDBASE_DEPLOY_DOMAIN=<host> / --domain)");
   return { name, account: account.id, url, wranglerConfig, project: cloud };
 }
+
+// ---- host-scoped redirects as zone Redirect Rules (Rulesets API, phase http_request_dynamic_redirect) --------------
+// One rule per `_redirects` line, tagged `voidbase:<worker>:` in its description so a redeploy replaces exactly its own
+// rules and leaves the zone's other redirect rules alone. Needs the zone permission Single Redirect (edit) on the deploy
+// token ("Dynamic URL Redirects Write" in the API's permission listing, next to the DNS permission the token may already
+// carry for the zone). Without it the deploy logs the rules to create by hand and carries on.
+const quote = (v: string) => JSON.stringify(v);
+export function redirectRule(worker: string, r: RedirectEntry): Record<string, unknown> {
+  const wildcard = r.path.endsWith("/*"); const prefix = wildcard ? r.path.slice(0, -1) : r.path; // "/docs/*" -> "/docs/"
+  const expression = wildcard ? (prefix === "/" ? `(http.host eq ${quote(r.host!)})` : `(http.host eq ${quote(r.host!)} and starts_with(http.request.uri.path, ${quote(prefix)}))`) : `(http.host eq ${quote(r.host!)} and http.request.uri.path eq ${quote(r.path)})`;
+  const absolute = (to: string) => (/^https?:\/\//.test(to) ? to : `https://${r.host}${to.startsWith("/") ? "" : "/"}${to}`);
+  const splat = r.to.includes(":splat");
+  const target_url = splat
+    ? { expression: `concat(${quote(absolute(r.to).replace(":splat", "").replace(/\/$/, ""))}, ${prefix === "/" ? "http.request.uri.path" : `substring(http.request.uri.path, ${prefix.length - 1})`})` }
+    : { value: absolute(r.to) };
+  return { description: `voidbase:${worker}:${r.source}`, expression, action: "redirect", action_parameters: { from_value: { status_code: r.status, target_url, preserve_query_string: true } }, enabled: true };
+}
+export async function applyZoneRedirects(api: CfApi, account: string, worker: string, entries: RedirectEntry[], log: (l: string) => void): Promise<void> {
+  const byZone = new Map<string, { zone: { id: string; name: string }; rules: Record<string, unknown>[] }>();
+  for (const r of entries) {
+    const zone = await findZone(api, r.host!, account);
+    if (!zone) { log(`redirect ${r.source}: no zone on the account covers ${r.host}, rule skipped`); continue; }
+    const slot = byZone.get(zone.id) ?? { zone, rules: [] }; slot.rules.push(redirectRule(worker, r)); byZone.set(zone.id, slot);
+  }
+  for (const { zone, rules } of byZone.values()) {
+    const path = `/zones/${zone.id}/rulesets/phases/http_request_dynamic_redirect/entrypoint`;
+    try {
+      const cur = await api.raw("GET", path); const body = await cur.text();
+      if (cur.status === 403 || cur.status === 401) throw new Error("permission");
+      const existing = cur.ok ? ((JSON.parse(body) as { result?: { rules?: Record<string, unknown>[] } }).result?.rules ?? []) : [];
+      const kept = existing.filter((x) => !String(x.description ?? "").startsWith(`voidbase:${worker}:`));
+      await api.json("PUT", path, { rules: [...kept, ...rules] });
+      log(`zone ${zone.name}: ${rules.length} redirect rule(s) set (${rules.map((x) => String(x.description).split(":").slice(2).join(":")).join(", ")})`);
+    } catch (e) {
+      const why = e instanceof Error && e.message === "permission" ? "the token lacks the zone permission Single Redirect > Edit (API name: Dynamic URL Redirects Write) for the zone" : e instanceof Error ? e.message : String(e);
+      log(`zone ${zone.name}: redirect rules not set (${why}). Add that permission to the token and deploy again, or create them under Rules > Redirect Rules:\n${rules.map((x) => `  ${x.expression} -> ${JSON.stringify((x.action_parameters as { from_value: { target_url: unknown } }).from_value.target_url)}`).join("\n")}`);
+    }
+  }
+}

package/src/node/secrets.ts

@@ -0,0 +1,169 @@
+// pb_secrets/: the app's secrets, declared where the tooling can read them and valued where git cannot see them.
+//
+//   pb_secrets/main.pb.js      the declaration, committed: `secrets({ NAME: "what it is", ... })`. Read, never run.
+//   pb_secrets/secrets.json    the values, git-ignored: `{ "NAME": "value", ... }`. On a dev machine only.
+//
+// `voidbase serve` loads the values into the process environment, so `$os.getenv("NAME")` and the app's own code see
+// them exactly as they will on Cloudflare. `voidbase deploy` stores the values as the Worker's secrets (encrypted,
+// per Worker, so two instances on one account never share one) and refuses to deploy while a declared secret has
+// neither a local value nor one already on the Worker: a CI checkout has no secrets.json, and that is the point --
+// the values are pushed once from a machine that has them (`voidbase secrets push`) 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 ts from "typescript";
+import type { CfApi } from "../cloud/rest";
+
+export const SECRETS_DIR = "pb_secrets";
+export const DECLARATION_FILE = "main.pb.js";
+export const VALUES_FILE = "secrets.json";
+const NAME = /^[A-Z][A-Z0-9_]*$/;
+
+export interface SecretsDeclaration {
+  /** the file the names came from */
+  file: string;
+  /** declared names, in file order */
+  names: string[];
+  /** what each one is, when the declaration says */
+  descriptions: Record<string, string>;
+}
+
+/**
+ * The names a declaration file names, without evaluating it: `secrets({ A: "what A is", B: "" })`, or
+ * `secrets(["A", "B"])`. The same reader serves the adapter's `defineSecrets({...})` in vb_secrets/main.ts.
+ */
+export function parseSecretsDeclaration(code: string, file = DECLARATION_FILE, callee: string | string[] = ["secrets", "defineSecrets"]): SecretsDeclaration {
+  const callees = new Set(Array.isArray(callee) ? callee : [callee]);
+  const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true);
+  const names: string[] = []; const descriptions: Record<string, string> = {};
+  const text = (n: ts.Node | undefined) => (n && (ts.isStringLiteralLike(n) || ts.isIdentifier(n)) ? n.text : null);
+  const add = (name: string | null, description: string | null) => {
+    if (!name) return;
+    if (!NAME.test(name)) throw new Error(`voidbase: ${file}: "${name}" is not a secret name (UPPER_CASE, letters, digits and underscores, like an environment variable)`);
+    if (!names.includes(name)) names.push(name);
+    if (description) descriptions[name] = description;
+  };
+  const visit = (node: ts.Node) => {
+    if (ts.isCallExpression(node)) {
+      const fn = ts.isIdentifier(node.expression) ? node.expression.text : ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : "";
+      const arg = node.arguments[0];
+      if (callees.has(fn) && arg) {
+        if (ts.isObjectLiteralExpression(arg)) {
+          for (const p of arg.properties) {
+            if (ts.isPropertyAssignment(p)) {
+              const init = p.initializer;
+              const description = ts.isStringLiteralLike(init) ? init.text
+                : ts.isObjectLiteralExpression(init) ? text(init.properties.find((q): q is ts.PropertyAssignment => ts.isPropertyAssignment(q) && text(q.name) === "description")?.initializer) : null;
+              add(text(p.name), description);
+            } else if (ts.isShorthandPropertyAssignment(p)) add(p.name.text, null);
+          }
+        } else if (ts.isArrayLiteralExpression(arg)) for (const el of arg.elements) add(text(el), null);
+        else throw new Error(`voidbase: ${file}: ${fn}() takes an object of names ({ NAME: "what it is" }) or an array of names`);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return { file, names, descriptions };
+}
+
+/** The declaration of a pb_secrets/ directory, or null when there is none. */
+export function readSecretsDeclaration(dir = SECRETS_DIR): SecretsDeclaration | null {
+  const file = join(resolve(dir), DECLARATION_FILE);
+  if (!existsSync(file)) return null;
+  return parseSecretsDeclaration(readFileSync(file, "utf8"), file);
+}
+
+/** The 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 secret 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;
+  declaration: SecretsDeclaration | null;
+  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, and how the two compare. */
+export function secretsState(dir = SECRETS_DIR): SecretsState {
+  const declaration = readSecretsDeclaration(dir);
+  const values = readSecretsValues(dir);
+  if (!declaration && values && Object.keys(values).length) {
+    throw new Error(`voidbase: ${join(resolve(dir), VALUES_FILE)} holds ${Object.keys(values).length} secret(s) but nothing declares them. Name them in ${join(dir, DECLARATION_FILE)}:\n  secrets({ ${Object.keys(values).map((k) => `${k}: ""`).join(", ")} })`);
+  }
+  const names = declaration?.names ?? [];
+  const have = new Set(Object.keys(values ?? {}));
+  return {
+    dir: resolve(dir), declaration, values,
+    provided: names.filter((n) => have.has(n)),
+    unprovided: names.filter((n) => !have.has(n)),
+    undeclared: [...have].filter((n) => !names.includes(n)),
+  };
+}
+
+/**
+ * Puts the local values into an environment (the process's, for `voidbase serve` and `voidbase deploy`), never over
+ * a value that is already there. Returns what to tell the user: names loaded, names still missing, names nobody
+ * declared.
+ */
+export function loadSecrets(dir = SECRETS_DIR, into: Record<string, string | undefined> = process.env): { loaded: string[]; missing: string[]; undeclared: string[]; state: SecretsState } {
+  const state = secretsState(dir);
+  const loaded: string[] = [];
+  for (const [k, v] of Object.entries(state.values ?? {})) { if (into[k] === undefined || into[k] === "") { into[k] = v; loaded.push(k); } }
+  const missing = state.unprovided.filter((n) => !into[n]);
+  return { loaded, missing, undeclared: state.undeclared, state };
+}
+
+// ---- 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 nothing in it yet, and how to fill it. */
+export function declarationScaffold(): string {
+  return `/// <reference path="../pb_data/types.d.ts" />
+// The secrets this app needs. This file is read by \`voidbase serve\` and \`voidbase deploy\`, never run: it names the
+// secrets, and pb_secrets/secrets.json (git-ignored) holds their values on your machine:
+//
+//   { "SMTP_PASSWORD": "..." }
+//
+// \`voidbase deploy\` stores the values as this Worker's secrets; \`voidbase secrets push\` does only that. A checkout
+// without secrets.json (CI) deploys as long as every name below is already on the Worker. In hooks: $os.getenv("NAME").
+secrets({
+  // SMTP_PASSWORD: "the mail provider's SMTP password",
+});
+`;
+}

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,27 @@ 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 = loadSecrets(process.env.VOIDBASE_SECRETS_DIR);
   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 secret(s) have no value here (${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.pb.js does not declare; a deploy stores only declared secrets`);
   // 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 });
@@ -50,6 +53,8 @@ async function runPending(db: D1Database, globals: Record<string, unknown>): Pro
       throw err;
     }
     invalidateCollections();
+    // the next migration must see what this one created (PocketBase reloads its collections cache the same way)
+    const store = hookStore.getStore(); if (store) { const fresh = await loadCollections(db); store.collections.clear(); for (const [k, v] of fresh) store.collections.set(k, v); }
     await stmt(db, "INSERT OR IGNORE INTO `_pbMigrations` (file, applied) VALUES (?, ?)", [m.name, Date.now()]).run();
     done.push(m.name);
   }

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>();