@voidbase-cloud/voidbase 0.2.2 → 0.4.0

package/src/env/define.ts

@@ -0,0 +1,195 @@
+// The app's configuration, declared once with Void's validators and stored in each deploy's environment
+// (twelve-factor III: config in the environment, declared in code, never grouped by environment):
+//
+//   // pb_secrets/main.ts (a Void app: vb_secrets/main.ts)
+//   import { defineSecrets, string, number, url, describe } from "@voidbase-cloud/voidbase/secrets";
+//
+//   export default defineSecrets({
+//     SMTP_PASSWORD: string().secret(),
+//     ADMIN_EMAILS: describe(string().default(""), "who may open the admin pages"),
+//     MAX_INSTANCES: number().default(5),
+//     PUBLIC_API_URL: url().optional().public(),
+//   });
+//
+// Every key has an access tier, which decides where its value lives and who can read it:
+//
+//   .secret()   the Worker's encrypted secrets; read by hooks and routes; never listed, never in a build
+//   (plain)     server configuration: the Worker's plain vars; read by hooks and routes; never in a client build
+//   .public()   the Worker's plain vars *and* the client build (`import.meta.env.KEY`): what the browser may know
+//
+// The validators are Void's own (`string()`, `number()`, `boolean()`, `url()`, `email()`, `oneOf()`, `json()`,
+// each with `.optional()`, `.default()`, `.secret()`, `.public()`), the same ones a Void project's env.ts uses, so
+// one vocabulary serves both. Any Standard Schema validator works too (wrap it in `secret()` / `pub()` to tier it).
+//
+// Values come from the deploy's environment: locally `secrets.json` (git-ignored) beside the declaration, then the
+// shell; on Cloudflare the Worker's secrets and vars. `voidbase serve`, `voidbase deploy` and the adapter's build
+// parse them through the validators, so a default is filled in, a number is a number, and a bad or missing value
+// stops the process with the key's name, never its value.
+//
+// This module is imported by the app's own code too (`await definition.read(c.env)` for typed access), so it must
+// stay small: Void's validators and nothing else.
+import { boolean, email, json, number, oneOf, string, url } from "void/env";
+
+export { boolean, email, json, number, oneOf, string, url };
+
+// Standard Schema V1, inlined as the spec allows
+export interface StandardSchema<Output = unknown> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    readonly types?: { readonly input: unknown; readonly output: Output } | undefined;
+  };
+}
+type StandardResult<Output> = { readonly value: Output; readonly issues?: undefined } | { readonly issues: ReadonlyArray<{ readonly message: string }> };
+export type OutputOf<S> = S extends StandardSchema<infer O> ? O : never;
+
+export type Access = "secret" | "server" | "public";
+
+export interface Entry<S extends StandardSchema = StandardSchema> {
+  schema: S;
+  /** the tier; without one, Void's `.secret()` / `.public()` marker on the validator decides, else `server` */
+  access?: Access;
+  description?: string;
+}
+
+/** Void's marker, set by `.secret()` and `.public()` on its validators (a Symbol.for, so the same across copies). */
+const VOID_MARKER = Symbol.for("void.env.secretOverride");
+const markerOf = (schema: unknown): Access | undefined => {
+  const m = schema && typeof schema === "object" ? (schema as Record<symbol, unknown>)[VOID_MARKER] : undefined;
+  return m === "secret" ? "secret" : m === "public" ? "public" : undefined;
+};
+
+const ENTRY = Symbol.for("voidbase.secrets.entry");
+type Marked<S extends StandardSchema> = Entry<S> & { [ENTRY]: true };
+const entry = <S extends StandardSchema>(e: Entry<S>): Marked<S> => ({ ...e, [ENTRY]: true });
+const isEntry = (v: unknown): v is Marked<StandardSchema> => !!v && typeof v === "object" && ENTRY in (v as object);
+
+/** Attaches a description to a validator: shown by `voidbase secrets` and in the deploy's messages. */
+export function describe<S extends StandardSchema>(schema: S, description: string): Marked<S> { return entry({ schema, description }); }
+/** Tiers any Standard Schema validator as a secret (Void's own validators can say `.secret()` instead). */
+export function secret<S extends StandardSchema>(schema: S, description?: string): Marked<S> { return entry({ schema, access: "secret", description }); }
+/** Tiers any Standard Schema validator as server configuration: a plain Worker var, never in a client build. */
+export function server<S extends StandardSchema>(schema: S, description?: string): Marked<S> { return entry({ schema, access: "server", description }); }
+/** Tiers any Standard Schema validator as public: a Worker var the browser may also know (`.public()` on Void's). */
+export function pub<S extends StandardSchema>(schema: S, description?: string): Marked<S> { return entry({ schema, access: "public", description }); }
+
+export type Spec = Record<string, StandardSchema | Entry>;
+type SchemaOf<E> = E extends Entry<infer S> ? S : E extends StandardSchema ? E : never;
+/** The typed configuration a definition parses to. */
+export type Values<T extends Spec> = { [K in keyof T]: OutputOf<SchemaOf<T[K]>> };
+export type ValuesOf<D> = D extends Definition<infer T> ? Values<T> : never;
+
+export interface KeyInfo {
+  name: string;
+  access: Access;
+  description?: string;
+  /** the validator accepts no value at all: it has a default or is optional */
+  optional: boolean;
+  /** the value the validator fills in when none is given, as it will be stored (a string), or undefined */
+  fallback?: string;
+}
+
+/** What parsing a set of raw values produced. Values never appear in `missing` or `invalid`. */
+export interface Evaluation<T extends Spec> {
+  /** every key that parsed, with its typed value */
+  values: Partial<Values<T>>;
+  /** every key that parsed, as the string the environment stores (numbers and booleans stringified, objects as JSON) */
+  stored: Record<string, string>;
+  /** keys with no value and no default */
+  missing: string[];
+  /** keys whose value the validator refused: name and why */
+  invalid: { name: string; message: string }[];
+}
+
+const NAME = /^[A-Z][A-Z0-9_]*$/;
+/** where raw values come from: an environment object, or a lookup (`(name) => $os.getenv(name)` in a hook or route) */
+export type Source = Record<string, unknown> | ((name: string) => unknown);
+
+/** A configuration value as the environment stores it: environments hold strings. */
+export function toStored(v: unknown): string | undefined {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+  if (v instanceof Date) return v.toISOString();
+  return JSON.stringify(v);
+}
+
+const validate = async <O>(schema: StandardSchema<O>, value: unknown): Promise<StandardResult<O>> => schema["~standard"].validate(value);
+
+export class Definition<T extends Spec> {
+  readonly entries: { [K in keyof T]: Required<Pick<Entry<SchemaOf<T[K]>>, "schema" | "access">> & Pick<Entry, "description"> };
+  constructor(spec: T) {
+    const entries = {} as Definition<T>["entries"];
+    for (const [name, v] of Object.entries(spec)) {
+      if (!NAME.test(name)) throw new Error(`voidbase: "${name}" is not a configuration name (UPPER_CASE, letters, digits and underscores, like an environment variable)`);
+      const e: Entry = isEntry(v) ? { schema: v.schema, access: v.access, description: v.description } : { schema: v as StandardSchema };
+      if (!e.schema || typeof e.schema !== "object" || !("~standard" in e.schema)) throw new Error(`voidbase: ${name} needs a validator (string(), number(), url(), ... from @voidbase-cloud/voidbase/secrets, or any Standard Schema)`);
+      (entries as Record<string, unknown>)[name] = { schema: e.schema, access: e.access ?? markerOf(e.schema) ?? "server", description: e.description };
+    }
+    this.entries = entries;
+  }
+  /** the names, in declaration order */
+  get names(): (keyof T & string)[] { return Object.keys(this.entries) as (keyof T & string)[]; }
+  /** the names of one tier, or of several */
+  of(...access: Access[]): (keyof T & string)[] { return this.names.filter((n) => access.includes(this.entries[n].access)); }
+  /** what each key is, without any value */
+  async info(): Promise<KeyInfo[]> {
+    const out: KeyInfo[] = [];
+    for (const name of this.names) {
+      const e = this.entries[name];
+      const empty = await validate(e.schema, undefined);
+      const ok = !empty.issues;
+      out.push({ name, access: e.access, description: e.description, optional: ok, fallback: ok ? toStored((empty as { value: unknown }).value) : undefined });
+    }
+    return out;
+  }
+  /**
+   * Parses raw values (an environment: strings, or nothing) through the validators. Nothing throws: the result says
+   * which keys are missing and which were refused, by name, so a caller can stop with a list instead of one error.
+   * `only` restricts the parse to some tiers (a client build reads `public` and nothing else).
+   */
+  async evaluate(raw: Source, only?: Access[]): Promise<Evaluation<T>> {
+    const values: Record<string, unknown> = {}; const stored: Record<string, string> = {}; const missing: string[] = []; const invalid: { name: string; message: string }[] = [];
+    const get = typeof raw === "function" ? raw : (n: string) => raw[n];
+    for (const name of only ? this.of(...only) : this.names) {
+      const e = this.entries[name];
+      const got = get(name); const input = got === "" ? undefined : got;
+      const r = await validate(e.schema, input);
+      if (r.issues) {
+        if (input === undefined) { missing.push(name); continue; }
+        // a validator may quote what it refused (Void's url() does): the report never carries the value
+        const shown = typeof input === "string" ? input : String(input);
+        invalid.push({ name, message: r.issues.map((i) => (shown ? i.message.split(shown).join("<value>") : i.message)).join("; ") });
+        continue;
+      }
+      if (r.value === undefined) continue; // optional and absent: the app reads undefined, as declared
+      values[name] = r.value; const s = toStored(r.value); if (s !== undefined) stored[name] = s;
+    }
+    return { values: values as Partial<Values<T>>, stored, missing, invalid };
+  }
+  /**
+   * Typed access from the app's own code: `await definition.read((n) => pb.$os.getenv(n))` in a route or hook works
+   * on both runtimes; `read(c.env)` on a Worker, `read(process.env)` on Bun.
+   * Throws with the names of the keys that are missing or refused, never their values.
+   */
+  async read(raw: Source, only?: Access[]): Promise<Values<T>> {
+    const r = await this.evaluate(raw, only);
+    const problems = [...r.missing.map((n) => `${n}: missing`), ...r.invalid.map((i) => `${i.name}: ${i.message}`)];
+    if (problems.length) throw new Error(`voidbase: configuration: ${problems.join(", ")}`);
+    return r.values as Values<T>;
+  }
+}
+
+/**
+ * Declares the app's configuration. The result is the declaration `voidbase serve`, `voidbase deploy` and the
+ * adapter read, and the typed reader the app's code uses:
+ *
+ *     export default defineSecrets({ SMTP_PASSWORD: string().secret(), MAX: number().default(5) });
+ *     // elsewhere: const { MAX } = await definition.read(c.env);   MAX is a number
+ */
+export function defineSecrets<const T extends Spec>(spec: T): Definition<T> {
+  return new Definition(spec);
+}
+
+export const isDefinition = (v: unknown): v is Definition<Spec> => v instanceof Definition || (!!v && typeof v === "object" && typeof (v as Definition<Spec>).evaluate === "function" && !!(v as Definition<Spec>).entries);

package/src/node/assets.ts

@@ -2,10 +2,16 @@
 import { existsSync, statSync } from "node:fs";
 import { join, normalize } from "node:path";
 export function assetsFetcher(opts: { panelDir: string; publicDir?: string }) {
+  // Cloudflare's asset layer resolves an extensionless path against `<path>.html` and `<path>/index.html`
+  // (html_handling "auto-trailing-slash"); a static site generator writes one shape or the other, so the Bun
+  // runtime tries both and a deep link behaves the same on either runtime.
+  const isFile = (p: string) => existsSync(p) && statSync(p).isFile();
   const file = (root: string, rel: string): string | null => {
     const p = normalize(join(root, rel));
     if (!p.startsWith(normalize(root))) return null;
-    if (existsSync(p) && statSync(p).isFile()) return p;
+    if (isFile(p)) return p;
+    const html = p.replace(/\/$/, "") + ".html";
+    if (html !== ".html" && isFile(html)) return html;
     const index = join(p, "index.html");
     return existsSync(index) ? index : null;
   };

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, type LoadedSecrets } 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,28 @@ 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: LoadedSecrets }> {
   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 = await loadSecrets(secretsDir);
+  if (secrets.invalid.length) throw new Error(`${secretsDir}: ${secrets.invalid.map((i) => `${i.name}: ${i.message}`).join(", ")}`);
   loadEnv(); const fromFiles = loadEnvFiles(); if (fromFiles.length) log(`from .env: ${fromFiles.join(", ")}`);
+  if (secrets.state.definition) { const d = secrets.state.definition; log(`${secretsDir}: ${d.names.length} declared (${d.of("secret").length} secret, ${d.of("server").length} server, ${d.of("public").length} public), ${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 +108,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`);
@@ -132,6 +158,16 @@ export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ na
   const extraVars = listed("VOIDBASE_DEPLOY_VARS"), extraSecrets = listed("VOIDBASE_DEPLOY_SECRETS");
   const baked: Record<string, string> = { VOIDBASE_WORKER_NAME: name, VOIDBASE_ACCOUNT_ID: account.id };
   for (const k of ["AUDITLOG", ...extraVars]) if (process.env[k]) baked[k] = process.env[k]!;
+  // the declared server and public values, parsed (defaults filled in): a var is the code's to set on every deploy
+  const definition = pbSecrets.state.definition;
+  const plainKeys = definition ? definition.of("server", "public") : [];
+  for (const k of plainKeys) { const v = pbSecrets.evaluation?.stored[k]; if (v !== undefined) baked[k] = v; }
+  const missingVars = pbSecrets.missing.filter((k) => plainKeys.includes(k));
+  if (missingVars.length) {
+    const msg = `${missingVars.length} declared value(s) have no value in ${secretsDir}/secrets.json or the environment and no default: ${missingVars.join(", ")}`;
+    if (opts.dryRun) log(`vars: ${msg}`); else throw new Error(msg);
+  }
+  if (plainKeys.length) log(`vars: ${plainKeys.filter((k) => baked[k] !== undefined).join(", ") || "none"}${definition!.of("public").length ? ` (public: ${definition!.of("public").join(", ")})` : ""}`);
   writeFileSync(`${cloud}/.env`, Object.entries(baked).map(([k, v]) => `${k}=${v}\n`).join(""));
   log(`project: ${cloud}`);
 
@@ -143,14 +179,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 = definition ? definition.of("secret") : [];
+  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.evaluation?.stored[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 +223,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")}`);
+    }
+  }
+}