@voidbase-cloud/voidbase 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 Entries after 0.1.0 are compiled by release-please from the Conventional Commits merged since the previous release
 (docs/releasing.md); 0.1.0 was written by hand.
 
+## [0.4.0](https://github.com/voidbase-cloud/voidbase/compare/v0.3.0...v0.4.0) (2026-09-07)
+
+
+### Features
+
+* **deploy:** one configuration declaration with Void's validators, tiered secret / server / public ([e5ee202](https://github.com/voidbase-cloud/voidbase/commit/e5ee20261520fbfba8e90d80ff4f7aa07bf6bc78))
+
 ## [0.3.0](https://github.com/voidbase-cloud/voidbase/compare/v0.2.2...v0.3.0) (2026-09-07)
 
 

package/README.md

@@ -103,11 +103,12 @@ provider variables.
 
 `voidbase token` prints a Cloudflare dashboard link that creates `VOIDBASE_DEPLOY_CF_API_KEY` with the right
 permissions pre-selected; with that variable set, `voidbase deploy` provisions D1 and R2, generates the Void project
-inside the package (`node_modules/voidbase/.cloud/<name>`), stores the superuser and the secrets `pb_secrets/`
-declares as the Worker's secrets, and uploads the Worker. Your directory stays `pb_hooks` + `pb_migrations` +
-`pb_secrets` + `pb_data`, like a PocketBase folder: `pb_secrets/main.pb.js` names the secrets, the git-ignored
-`pb_secrets/secrets.json` holds them, and CI deploys with nothing but the deploy token once `voidbase secrets push`
-has stored them. See [docs/deploy.md](docs/deploy.md).
+inside the package (`node_modules/voidbase/.cloud/<name>`), stores the superuser and what `pb_secrets/` declares
+as the Worker's secrets and vars, and uploads the Worker. Your directory stays `pb_hooks` + `pb_migrations` +
+`pb_secrets` + `pb_data`, like a PocketBase folder: `pb_secrets/main.ts` declares the configuration with Void's
+validators (secret, server or public), the git-ignored `pb_secrets/secrets.json` holds the local values, and CI
+deploys with nothing but the deploy token once `voidbase secrets push` has stored the secrets. See
+[docs/deploy.md](docs/deploy.md).
 
 ## Continuous integration
 

package/bin/voidbase.ts

@@ -43,8 +43,9 @@ const HELP = `voidbase - PocketBase-compatible backend: a single Bun process loc
                                      stores the superuser as worker secrets and runs void deploy --backend cloudflare
   deploy --void                      deploy to the Void platform instead (void auth login first)
   token                              print the Cloudflare dashboard link that creates VOIDBASE_DEPLOY_CF_API_KEY
-  secrets [list] [--dir pb_secrets]  the secrets pb_secrets/main.pb.js declares: which have a value in secrets.json (git-ignored)
-  secrets push [--name worker]       and which are on the Worker; push stores the local values as the Worker's secrets
+  secrets [list] [--dir pb_secrets]  what pb_secrets/main.ts declares (secret / server / public), which have a value in
+  secrets push [--name worker]       secrets.json (git-ignored) or a default, which secrets the Worker has; push stores the
+                                     local secrets on the Worker (vars are set by every deploy)
   update [--dir pb_data] [--backup]  prebuilt executable only: fetch the latest GitHub release for this platform, verify
                                      its checksum and replace the executable (--backup zips pb_data first)
   version                            print the version
@@ -90,23 +91,31 @@ switch (cmd) {
     const { secretsState, putWorkerSecrets, workerSecretNames, SECRETS_DIR } = await import("../src/node/secrets");
     const { deployTarget } = await import("../src/node/deploy-cf");
     const dir = resolve(flags.dir ?? process.env.VOIDBASE_SECRETS_DIR ?? SECRETS_DIR);
-    const state = secretsState(dir);
-    if (!state.declaration) { console.log(`${dir}/main.pb.js does not exist: no secrets declared (voidbase init writes one)`); break; }
+    const state = await secretsState(dir);
+    if (!state.definition) { console.log(`${dir}/main.ts does not exist: nothing declared (voidbase init writes one)`); break; }
+    const def = state.definition; const secretNames = def.of("secret");
     if (sub === "push") {
       const { api, account, name } = await deployTarget({ name: flags.name, account: flags.account, log: () => undefined });
-      const values: Record<string, string> = {}; for (const k of state.provided) values[k] = state.values![k]!;
-      if (!Object.keys(values).length) { console.log(`nothing to push: none of ${state.declaration.names.join(", ")} has a value in ${dir}/secrets.json`); break; }
+      // only the secret tier is pushed: vars are the code's, set by every deploy
+      const ev = await def.evaluate({ ...(state.values ?? {}) }, ["secret"]);
+      if (ev.invalid.length) throw new Error(`${dir}/secrets.json: ${ev.invalid.map((i) => `${i.name}: ${i.message}`).join(", ")}`);
+      const values: Record<string, string> = {}; for (const k of secretNames) if (state.provided.includes(k) && ev.stored[k] !== undefined) values[k] = ev.stored[k]!;
+      if (!Object.keys(values).length) { console.log(`nothing to push: none of ${secretNames.join(", ") || "(no secrets declared)"} has a value in ${dir}/secrets.json`); break; }
       const before = await workerSecretNames(api, account.id, name);
       const done = await putWorkerSecrets(api, account.id, name, values).catch((e: Error) => { throw new Error(`${e.message}\n  (the Worker "${name}" must exist: voidbase deploy creates it and stores the secrets itself)`); });
       console.log(`pushed ${done.length} secret(s) to worker "${name}" (account ${account.name}): ${done.map((k) => `${k}${before.includes(k) ? " (replaced)" : ""}`).join(", ")}`);
-      if (state.unprovided.length) console.log(`no local value, left as they are: ${state.unprovided.join(", ")}`);
+      const left = secretNames.filter((k) => !values[k]); if (left.length) console.log(`no local value, left as they are: ${left.join(", ")}`);
       break;
     }
     // list (default): a row per declared name
     let onWorker: string[] | null = null; let worker = "";
     try { const t = await deployTarget({ name: flags.name, account: flags.account, log: () => undefined }); worker = t.name; onWorker = await workerSecretNames(t.api, t.account.id, t.name); } catch { /* no token here: local view only */ }
-    console.log(`${dir}: ${state.declaration.names.length} declared${state.values ? `, ${state.provided.length} valued in secrets.json` : ", no secrets.json"}${onWorker ? `, worker "${worker}" has ${onWorker.filter((k) => state.declaration!.names.includes(k)).length} of them` : " (set VOIDBASE_DEPLOY_CF_API_KEY to compare with the Worker)"}`);
-    for (const k of state.declaration.names) console.log(`  ${k.padEnd(32)} ${state.provided.includes(k) ? "local value" : "no local value"}${onWorker ? `  ${onWorker.includes(k) ? "on the worker" : "NOT on the worker"}` : ""}${state.declaration.descriptions[k] ? `  ${state.declaration.descriptions[k]}` : ""}`);
+    console.log(`${dir}: ${def.names.length} declared (${secretNames.length} secret, ${def.of("server").length} server, ${def.of("public").length} public)${state.values ? `, ${state.provided.length} valued in secrets.json` : ", no secrets.json"}${onWorker ? `, worker "${worker}" has ${onWorker.filter((k) => secretNames.includes(k)).length} of the secrets` : " (set VOIDBASE_DEPLOY_CF_API_KEY to compare with the Worker)"}`);
+    for (const i of state.info) {
+      const where = state.provided.includes(i.name) ? "local value" : i.fallback !== undefined ? `default ${i.access === "secret" ? "(set)" : JSON.stringify(i.fallback)}` : i.optional ? "optional, unset" : "no local value";
+      const worker = onWorker && i.access === "secret" ? `  ${onWorker.includes(i.name) ? "on the worker" : "NOT on the worker"}` : "";
+      console.log(`  ${i.name.padEnd(30)} ${i.access.padEnd(7)} ${where.padEnd(18)}${worker}${i.description ? `  ${i.description}` : ""}`);
+    }
     if (state.undeclared.length) console.log(`  in secrets.json but not declared (never deployed): ${state.undeclared.join(", ")}`);
     break;
   }
@@ -158,7 +167,7 @@ switch (cmd) {
     mkdirSync(`${dir}/pb_hooks`, { recursive: true }); mkdirSync(`${dir}/pb_migrations`, { recursive: true }); mkdirSync(`${dir}/pb_secrets`, { recursive: true });
     { // pb_secrets/main.pb.js declares the secrets; secrets.json holds their values and never enters git
       const { declarationScaffold } = await import("../src/node/secrets");
-      if (!existsSync(`${dir}/pb_secrets/main.pb.js`)) writeFileSync(`${dir}/pb_secrets/main.pb.js`, declarationScaffold());
+      if (!existsSync(`${dir}/pb_secrets/main.ts`)) writeFileSync(`${dir}/pb_secrets/main.ts`, declarationScaffold());
       const gi = `${dir}/.gitignore`; const have = existsSync(gi) ? await Bun.file(gi).text() : "";
       const lines = ["pb_data/", "pb_secrets/secrets.json"].filter((l) => !have.split("\n").some((x) => x.trim() === l || x.trim() === l.replace(/\/$/, "")));
       if (lines.length) writeFileSync(gi, `${have}${have && !have.endsWith("\n") ? "\n" : ""}${lines.join("\n")}\n`);

package/docs/adapter.md

@@ -23,7 +23,7 @@ export default defineConfig({ plugins: [voidPlugin(), voidbaseAdapter()] });
   .gitignore          pb_data/
   pb_hooks/           routes/, middleware/, vb_hooks/, crons/ and queues/, compiled
   pb_migrations/      the project's vb_migrations/, plus one file per Drizzle migration
-  pb_secrets/         the project's vb_secrets/: the declaration in PocketBase's shape, the values beside it
+  pb_secrets/         the project's vb_secrets/: the declaration re-exported, the local values beside it
   pb_public/          the client build, served at /
   pb_data/            created on first run
   void-entry.ts       what the bundler builds into pb_hooks/void-app.js
@@ -48,7 +48,7 @@ The project root is Void's, with three additions, all optional and all named for
 | --- | --- |
 | `vb_hooks/` | PocketBase's hooks, one per file, registered once when the app mounts |
 | `vb_migrations/` | PocketBase JS migrations, copied into the generated `pb_migrations/` beside the ones generated from `db/migrations` |
-| `vb_secrets/` | `main.ts` declares the app's secrets with `defineSecrets`; `secrets.json` (git-ignored) holds their values |
+| `vb_secrets/` | `main.ts` declares the app's configuration with `defineSecrets` and Void's validators, tiered secret / server / public; `secrets.json` (git-ignored) holds the local values |
 
 They sit at the project root beside Void's own `db/`, which `vb_migrations/` is the counterpart of. Everything else
 is Void's, and means what Void means by it: `routes/`, `middleware/`, `crons/` and `queues/` are the server code,
@@ -149,30 +149,39 @@ process, so a registration made then is held and replayed, or dropped with the p
 (`pb.$app` and the rest) outside a request, a cron tick or a hook still throws.
 
 
-### Secrets
+### Configuration and secrets
 
-The secrets the app needs are named in `vb_secrets/main.ts`, where the build can read them without running anything,
-and valued in `vb_secrets/secrets.json`, which stays out of git (add it to `.gitignore`; the generated app's own
-`.gitignore` already lists its copy):
+The app's configuration is declared in `vb_secrets/main.ts`, with the validators a Void `env.ts` uses, and valued in
+`vb_secrets/secrets.json`, which stays out of git (add it to `.gitignore`; the generated app's own `.gitignore`
+already lists its copy):
 
 ```ts
 // vb_secrets/main.ts
-import { defineSecrets } from "@voidbase-cloud/voidbase/adapter";
+import { defineSecrets, describe, string, number, url } from "@voidbase-cloud/voidbase/secrets";
 
 export default defineSecrets({
-  SMTP_PASSWORD: "the mail provider's SMTP password",
-  CF_OAUTH_CLIENT_SECRET: "the OAuth app's client secret",
+  SMTP_PASSWORD: describe(string().secret(), "the mail provider's SMTP password"),   // the Worker's secrets
+  MAX_INSTANCES: number().default(5),                                                 // a Worker var
+  PUBLIC_API_URL: url().optional().public(),                                          // a var the browser gets too
 });
 ```
 
-The adapter writes them into `.voidbase/pb_secrets/` in PocketBase's shape (`main.pb.js` with `secrets({...})`,
-`secrets.json` copied beside it), which is what `voidbase serve` and `voidbase deploy` read: locally the values
-enter the process environment, on Cloudflare they become the Worker's secrets (a deploy stores what the Worker
-lacks, `voidbase secrets push` replaces), and a deploy refuses to go ahead while a declared secret has no value
-anywhere. The app reads them like any other binding: `c.env.SMTP_PASSWORD` in
-a route, `pb.$os.getenv("SMTP_PASSWORD")` in a hook. A value in `secrets.json` that `main.ts` does not declare
-fails the build, by name: it would silently never reach the Worker. Details and the `voidbase secrets` commands:
-`docs/deploy.md`.
+One declaration serves the three places the app runs. The Worker: `voidbase deploy` stores secrets as the Worker's
+secrets and the rest as its vars, and refuses to deploy while a value is invalid or missing everywhere. The build:
+every `public` key is inlined into the client as `import.meta.env.KEY`, parsed and defaulted, and no other key can
+reach it. The static site therefore knows exactly what it was declared to know. Locally, `bun .voidbase/main.ts`
+parses `secrets.json` and the shell into the environment, defaults included. Routes and hooks read
+`c.env.SMTP_PASSWORD` or `pb.$os.getenv("SMTP_PASSWORD")`, or the typed values through the same declaration:
+
+```ts
+import config from "../../vb_secrets/main";
+const { MAX_INSTANCES } = await config.read((n) => pb.$os.getenv(n));   // a number, on both runtimes
+```
+
+The adapter writes a re-export into `.voidbase/pb_secrets/main.ts`, where `voidbase serve` and `voidbase deploy`
+look for the declaration, and copies `secrets.json` beside it. A value in `secrets.json` that `main.ts` does not
+declare fails the build, by name: it would silently never reach the Worker. Details, the tiers and the `voidbase
+secrets` commands: `docs/deploy.md`.
 
 ## What maps to what
 
@@ -182,7 +191,7 @@ fails the build, by name: it would silently never reach the Worker. Details and
 | `routes/**/*.ts` | `.voidbase/pb_hooks/void-app.js` | `[id]` → `:id`, `[...rest]` → catch-all, `(group)/` stripped, `_file.ts` ignored, `.dev.ts` / `.prod.ts` honoured |
 | `middleware/*.ts` | `routerUse(...)`, in file order | every request, as in Void (see below) |
 | `vb_hooks/*.ts` | the hook each file names, registered once | `onBootstrap`, `onRecordCreate`, the mailer hooks |
-| `vb_secrets/main.ts` + `secrets.json` | `.voidbase/pb_secrets/main.pb.js` + `secrets.json` | `voidbase deploy` stores the values as the Worker's secrets; `bun .voidbase/main.ts` loads them (see below) |
+| `vb_secrets/main.ts` + `secrets.json` | `.voidbase/pb_secrets/main.ts` (a re-export) + `secrets.json` | secrets to the Worker's secrets, the rest to its vars, `public` keys into the client build (see below) |
 | `crons/*.ts` | `cronAdd(<file name>, cron, handler)` | listed by `GET /api/crons`, runnable with `POST /api/crons/<name>` |
 | `queues/*.ts` | a voidbase job per message | `void/queues` and `c.env.QUEUE_<NAME>` produce; the consumer runs on the jobs queue, or inline where there is none |
 | `db/schema.ts` + `void/db` | Drizzle over voidbase's D1 | the same database PocketBase's collections live in |

package/docs/deploy.md

@@ -71,7 +71,7 @@ What it does, in order: resolves the account through the token, creates `<name>-
 ids and, when the directory has a `main.ts` exporting `register(app)`, composes it into the Worker; stores the
 superuser as worker secrets (from `VOIDBASE_SUPERUSER_*` / `PB_SUPERUSER_*`, or a generated
 password saved in `pb_data/.superuser-credentials`; the local dev default `changeme123` never goes live) together
-with the secrets `pb_secrets/` declares (below), syncs
+with the secrets and vars `pb_secrets/` declares (below), syncs
 the admin panel and your frontend build into that project, and runs `void deploy --backend cloudflare`,
 which builds, applies the D1 migrations and uploads the Worker with its cron trigger. It ends with the
 `https://<name>.<your-subdomain>.workers.dev` URL and a health check. Re-running is idempotent: existing resources
@@ -104,39 +104,62 @@ account. Cloudflare still requires the account to have a workers.dev subdomain b
 | `HUB` (Durable Object `VoidbaseHub`, SQLite-backed, in this Worker) | the realtime hub: every SSE connection holds one hibernatable socket to it, writes publish to it, so events arrive in tens of milliseconds instead of the D1 poll's second, and idle apps cost nothing (the object sleeps). Free plan included | `--no-hub` / `VOIDBASE_DEPLOY_HUB=0` keeps the D1 poll |
 | Smart Placement | the Worker runs next to its D1 database | always on |
 
-### Secrets: `pb_secrets/`
+### Configuration and secrets: `pb_secrets/`
 
-The app's own secrets (an SMTP password, OAuth client secrets, `VOIDBASE_ENCRYPTION_KEY`) have a directory, in
-PocketBase's naming:
+The app's configuration is declared once, in code, with Void's validators, and valued in each deploy's environment
+(twelve-factor III): locally a git-ignored file, on Cloudflare the Worker's own secrets and vars.
+
+```ts
+// pb_secrets/main.ts                                   committed
+import { defineSecrets, describe, string, number, url } from "@voidbase-cloud/voidbase/secrets";
+
+export default defineSecrets({
+  SMTP_PASSWORD: describe(string().secret(), "the mail provider's password"),
+  ADMIN_EMAILS: string().default(""),
+  MAX_UPLOAD_MB: number().default(10),
+  PUBLIC_SITE_URL: url().optional().public(),
+});
+```
 
 ```
-pb_secrets/main.pb.js      secrets({ SMTP_PASSWORD: "the mail provider's password", ... })   committed
-pb_secrets/secrets.json    { "SMTP_PASSWORD": "..." }                                       git-ignored
+pb_secrets/secrets.json    { "SMTP_PASSWORD": "...", "ADMIN_EMAILS": "me@example.com" }    git-ignored
 ```
 
-`main.pb.js` names the secrets and is read, never run (`voidbase init` writes an empty one and the `.gitignore`
-lines). `secrets.json` holds the values on your machine; the shell outranks it, and it outranks the `.env` files,
-so a dev placeholder such as `VOIDBASE_SUPERUSER_PASSWORD=changeme123` never shadows it. `voidbase serve` loads them into the environment, so
-`$os.getenv("SMTP_PASSWORD")` and the app's own code see the same names locally as on Cloudflare. `voidbase deploy`
-stores the declared values the Worker does not have yet as the Worker's secrets (encrypted, per Worker: two
-instances never share one) next to the superuser, and refuses to deploy while a declared secret has neither a local
-value nor one already on the Worker. A value the Worker already holds is left alone by a deploy: a deploy ships
-code, and a checkout whose `secrets.json` carries dev values (another OAuth client, the placeholder password) must
-not overwrite production by deploying. Replacing is explicit:
+Every key has an access tier, which decides where its value lives and who can read it:
+
+| tier | declared as | lives in | readable by |
+| --- | --- | --- | --- |
+| secret | `string().secret()` (or `secret(schema)`) | the Worker's encrypted secrets | hooks and routes; never listed, never in a build |
+| server | a bare validator | the Worker's plain vars | hooks and routes; never in a client build |
+| public | `.public()` (or `pub(schema)`) | the Worker's vars and the client build (`import.meta.env.KEY`) | everyone, the browser included |
+
+The validators are the ones a Void project's `env.ts` uses (`string()`, `number()`, `boolean()`, `url()`,
+`email()`, `oneOf()`, `json()`, each with `.optional()` and `.default()`), and any Standard Schema validator works
+inside `secret()` / `server()` / `pub()`. A value is parsed through its validator wherever it is read, 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.
+In hooks, `$os.getenv("NAME")` (the stored string); in TypeScript, `await definition.read((n) => $os.getenv(n))`
+gives the typed values.
+
+`voidbase init` writes an empty declaration and the `.gitignore` lines. `voidbase serve` parses `secrets.json` and
+the shell and puts the result, defaults included, into the environment (the shell outranks the file, the file
+outranks `.env`). `voidbase deploy` stores every server and public value as the Worker's vars on every deploy (a var
+is the code's to set), stores the secrets the Worker does not have yet as its secrets, and refuses to deploy while a
+value is invalid or a required one is missing everywhere. A secret the Worker already holds is left alone by a
+deploy: a deploy ships code, and a checkout whose `secrets.json` carries dev values (another OAuth client, the
+placeholder password) must not overwrite production by deploying. Replacing is explicit:
 
 ```bash
-voidbase secrets              # each declared name: local value or not, on the Worker or not
-voidbase secrets push         # store the local values on the Worker (replacing), without redeploying
+voidbase secrets              # each key: tier, local value or default, and for secrets whether the Worker has it
+voidbase secrets push         # store the local secrets on the Worker (replacing), without redeploying
 ```
 
-That is also what makes CI simple: a checkout without `secrets.json` deploys with nothing but the deploy token,
-because the values were pushed once from a machine that has them. The superuser follows the same rule: a checkout
-without credentials of its own keeps the superuser the Worker has.
-
-A value in `secrets.json` that `main.pb.js` does not declare is never deployed (the list says so). `VOIDBASE_DEPLOY_SECRETS=A,B`
-still stores environment variables as secrets for a deploy driven purely by the shell. 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.
+That is what makes CI simple: a checkout without `secrets.json` deploys with nothing but the deploy token, because
+the secrets were pushed once from a machine that has them and the plain values come from the declared defaults or the
+build's environment. The superuser follows the same rule: a checkout without credentials of its own keeps the
+superuser the Worker has. A value in `secrets.json` that the declaration does not name is never deployed (the list
+says so). `VOIDBASE_DEPLOY_VARS=A,B` and `VOIDBASE_DEPLOY_SECRETS=X,Y` still bake or store plain environment variables
+for a deploy driven purely by the shell. 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.
 
 ### Every instance is isolated
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidbase-cloud/voidbase",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "PocketBase-compatible backend on Cloudflare Workers (D1, R2, Queues, Durable Objects) via Void, or a single Bun process",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,8 @@
     "./cloud": "./src/cloud/rest.ts",
     "./bundle": "./src/node/bundle.ts",
     "./adapter": "./src/adapter/runtime.ts",
-    "./adapter/plugin": "./src/adapter/index.ts"
+    "./adapter/plugin": "./src/adapter/index.ts",
+    "./secrets": "./src/env/define.ts"
   },
   "imports": {
     "#platform/env": {

package/src/adapter/codegen.ts

@@ -198,11 +198,10 @@ const OUT = ".voidbase";
 export const hasServerCode = (m: VoidManifest) => !!(m.routes.length || m.middleware.length || m.crons.length || m.queues.length);
 
 /** Writes the whole generated app under `<root>/.voidbase`. Everything in there is build output. */
-/** pb_secrets/main.pb.js: what vb_secrets/main.ts declared, as the declaration `voidbase deploy` and `voidbase serve` read. */
+/** pb_secrets/main.ts: the project's declaration, re-exported where `voidbase serve` and `voidbase deploy` look for it. */
 export function generateSecretsDeclaration(d: SecretsDeclaration): string {
-  const lines = [BANNER, "//", `// The secrets the app declares in ${d.file}. Read by voidbase serve and voidbase deploy, never run; the values`, "// live in secrets.json beside this file (git-ignored) and, once deployed, as the Worker's secrets.", "secrets({"];
-  for (const n of d.names) lines.push(`  ${n}: ${JSON.stringify(d.descriptions[n] ?? "")},`);
-  lines.push("});", "");
+  const target = "../" + importPath(d.file.replace(/\.(ts|js|mjs)$/, "")); // pb_secrets/ is one level below .voidbase/
+  const lines = [BANNER, "//", `// The app's configuration is declared in ${d.file}: ${d.names.map((n) => `${n} (${d.access[n]})`).join(", ") || "nothing yet"}.`, "// voidbase serve and voidbase deploy import it from here; the local values are in secrets.json beside this file.", `export { default } from "${target}";`, ""];
   return lines.join("\n");
 }
 
@@ -257,10 +256,11 @@ export function writeVoidbaseApp(m: VoidManifest, opts: GenerateOptions & { migr
   }
   if (existsSync(migrationsOut) && !readdirSync(migrationsOut).length) rmSync(migrationsOut, { recursive: true, force: true });
 
-  // pb_secrets: the declaration vb_secrets/main.ts makes, in the shape `voidbase deploy` reads, and the values beside it
+  // pb_secrets: the declaration vb_secrets/main.ts makes, where `voidbase serve` and `voidbase deploy` look for it
+  // (a re-export: the validators and their types stay the project's), and the local values beside it
   drop("pb_secrets");
   if (m.secrets) {
-    put("pb_secrets/main.pb.js", generateSecretsDeclaration(m.secrets));
+    put("pb_secrets/main.ts", generateSecretsDeclaration(m.secrets));
     const values = join(m.root, m.extras.secretsDir!, "secrets.json");
     if (existsSync(values)) { cpSync(values, join(m.root, OUT, "pb_secrets/secrets.json")); written.push(`${OUT}/pb_secrets/secrets.json`); }
   }

package/src/adapter/plugin.ts

@@ -14,7 +14,8 @@ import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFile
 import { join, resolve } from "node:path";
 import { bundleHookApp } from "./bundle";
 import { generateHookWrapper, hasServerCode, writeVoidbaseApp, type GenerateOptions } from "./codegen";
-import { scanVoidApp, type VoidManifest } from "./scan";
+import { scanVoidApp, SECRETS_DIR, type VoidManifest } from "./scan";
+import { loadDefinition, readSecretsValues } from "../node/secrets";
 
 export interface AdapterOptions extends GenerateOptions {
   /** where the built site goes inside the generated app; voidbase serves it at `/` */
@@ -90,6 +91,20 @@ export function voidbaseAdapter(options: AdapterOptions = {}) {
     name: "voidbase-adapter",
     // after voidPlugin, so the manifest sees whatever it generated into .void/
     enforce: "post" as const,
+    // the browser's share of the configuration: every `public` key of vb_secrets/main.ts, parsed from the local
+    // values and the shell, inlined as import.meta.env.KEY. Secrets and server keys never enter the client build.
+    async config(cfg: { root?: string }) {
+      const projectRoot = cfg.root ? resolve(cfg.root) : root;
+      const loaded = await report(() => loadDefinition(join(projectRoot, SECRETS_DIR)));
+      if (!loaded) return undefined;
+      const raw: Record<string, unknown> = { ...(readSecretsValues(join(projectRoot, SECRETS_DIR)) ?? {}) };
+      for (const k of loaded.definition.of("public")) if (process.env[k]) raw[k] = process.env[k];
+      const ev = await loaded.definition.evaluate(raw, ["public"]);
+      if (ev.invalid.length) throw new Error(`voidbase: ${SECRETS_DIR}: ${ev.invalid.map((i) => `${i.name}: ${i.message}`).join(", ")}`);
+      const define: Record<string, string> = {};
+      for (const [k, v] of Object.entries(ev.stored)) define[`import.meta.env.${k}`] = JSON.stringify(v);
+      return { define };
+    },
     configResolved(config: { root: string; build?: { outDir?: string }; environments?: Record<string, { build?: { outDir?: string } }> }) {
       root = config.root ?? root;
       const fromEnv = config.environments?.client?.build?.outDir;

package/src/adapter/scan.ts

@@ -5,7 +5,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, relative, resolve } from "node:path";
 import ts from "typescript";
 import { EVENT_HOOKS } from "../../hooks-plugin";
-import { parseSecretsDeclaration, readSecretsValues, VALUES_FILE, type SecretsDeclaration } from "../node/secrets";
+import { DECLARATION_FILES, parseSecretsDeclaration, readSecretsValues, VALUES_FILE, type SecretsDeclaration } from "../node/secrets";
 
 const CODE = new Set([".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs"]);
 export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "ALL"] as const;
@@ -36,7 +36,7 @@ export interface VoidMigration { file: string; name: string }
 export interface VoidbaseExtras {
   /** vb_migrations/: PocketBase JS migrations, copied in beside the ones generated from db/migrations */
   migrationsDir?: string;
-  /** vb_secrets/: main.ts declares the secrets (defineSecrets), secrets.json (git-ignored) holds their values */
+  /** vb_secrets/: main.ts declares the configuration (defineSecrets), secrets.json (git-ignored) holds the local values */
   secretsDir?: string;
 }
 /** The two directories this adapter adds to a Void app, both named for the voidbase thing they are, both sitting
@@ -71,7 +71,7 @@ export interface VoidManifest {
   crons: VoidModule[];
   queues: VoidQueue[];
   migrations: VoidMigration[];
-  /** vb_secrets/main.ts: the secrets the app declares (their values are never part of the manifest) */
+  /** vb_secrets/main.ts: the configuration the app declares, names and tiers only (values are never part of the manifest) */
   secrets: SecretsDeclaration | null;
   /** the app's own voidbase side (vb_migrations/, vb_secrets/) */
   extras: VoidbaseExtras;
@@ -237,16 +237,17 @@ export function scanVoidApp(opts: ScanOptions = {}): VoidManifest {
     secretsDir: isDir(join(root, SECRETS_DIR)) ? SECRETS_DIR : undefined,
   };
 
-  // vb_secrets/: main.ts names the secrets (`export default defineSecrets({ NAME: "what it is" })`), read without
-  // running it; secrets.json beside it is the git-ignored values file. Values that nothing declares are a build
-  // error: they would silently never reach the Worker.
+  // vb_secrets/: main.ts declares the configuration (`export default defineSecrets({ NAME: string().secret(), ... })`),
+  // read here without running it (names and tiers; the validators run where values are parsed); secrets.json
+  // beside it is the git-ignored local values file. Values that nothing declares are a build error: they would
+  // silently never reach the Worker.
   let secrets: SecretsDeclaration | null = null;
   if (extras.secretsDir) {
-    const decl = ["main.ts", "main.js"].map((f) => join(root, SECRETS_DIR, f)).find((f) => existsSync(f));
+    const decl = DECLARATION_FILES.map((f) => join(root, SECRETS_DIR, f)).find((f) => existsSync(f));
     const values = readSecretsValues(join(root, SECRETS_DIR));
-    if (!decl && values && Object.keys(values).length) throw new Error(`voidbase: ${SECRETS_DIR}/${VALUES_FILE} holds ${Object.keys(values).join(", ")} but ${SECRETS_DIR}/main.ts does not exist to declare them:\n  export default defineSecrets({ ${Object.keys(values).map((k) => `${k}: ""`).join(", ")} })`);
+    if (!decl && values && Object.keys(values).length) throw new Error(`voidbase: ${SECRETS_DIR}/${VALUES_FILE} holds ${Object.keys(values).join(", ")} but ${SECRETS_DIR}/main.ts does not exist to declare them:\n  export default defineSecrets({ ${Object.keys(values).map((k) => `${k}: string().secret()`).join(", ")} })`);
     if (decl) {
-      secrets = parseSecretsDeclaration(readFileSync(decl, "utf8"), relative(root, decl), "defineSecrets");
+      secrets = parseSecretsDeclaration(readFileSync(decl, "utf8"), relative(root, decl));
       const undeclared = Object.keys(values ?? {}).filter((k) => !secrets!.names.includes(k));
       if (undeclared.length) throw new Error(`voidbase: ${SECRETS_DIR}/${VALUES_FILE} holds ${undeclared.join(", ")}, which ${relative(root, decl)} does not declare. Add them to defineSecrets({...}) or remove them: an undeclared value never reaches the Worker.`);
     }

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/deploy-cf.ts

@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseRedirects, writeCloudProject, type RedirectEntry } from "./cloud-init";
 import { loadEnv } from "./serve";
-import { loadSecrets, SECRETS_DIR, workerSecretNames } from "./secrets";
+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(/\/$/, "");
@@ -75,15 +75,16 @@ export function loadEnvFiles(files = [".env", ".env.local", "../.env", "../.env.
 }
 
 /** 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> }> {
+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 = loadSecrets(secretsDir);
+  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.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(", ")}` : ""}`);
+  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());
@@ -157,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}`);
 
@@ -184,12 +195,12 @@ export async function deployToCloudflare(opts: DeployOptions = {}): Promise<{ na
   // 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 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.state.values?.[k]; if (v === undefined) continue;
+    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);

package/src/node/secrets.ts

@@ -1,81 +1,124 @@
-// pb_secrets/: the app's secrets, declared where the tooling can read them and valued where git cannot see them.
+// pb_secrets/: the app's configuration, declared where the tooling can read it and valued where git cannot see it.
 //
-//   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.
+//   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.
 //
-// `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.
+// 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_FILE = "main.pb.js";
+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 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.
+ * 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 = DECLARATION_FILE, callee: string | string[] = ["secrets", "defineSecrets"]): SecretsDeclaration {
-  const callees = new Set(Array.isArray(callee) ? callee : [callee]);
+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 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) => {
+  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 secret name (UPPER_CASE, letters, digits and underscores, like an environment variable)`);
+    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);
-    if (description) descriptions[name] = description;
+    access[name] = c.access; if (c.description) descriptions[name] = c.description;
   };
+  let found = false;
   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 : "";
+    if (ts.isCallExpression(node) && calleeName(node) === "defineSecrets") {
+      found = true;
       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`);
+      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);
-  return { file, names, descriptions };
+  if (!found) throw new Error(`voidbase: ${file} does not call defineSecrets(): export default defineSecrets({ ... })`);
+  return { file, names, access, descriptions };
 }
 
-/** The declaration of a pb_secrets/ directory, or null when there is none. */
+/** 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 = join(resolve(dir), DECLARATION_FILE);
-  if (!existsSync(file)) return null;
-  return parseSecretsDeclaration(readFileSync(file, "utf8"), file);
+  const file = declarationFile(dir);
+  return file ? parseSecretsDeclaration(readFileSync(file, "utf8"), file) : null;
 }
 
-/** The values of a pb_secrets/ directory (`secrets.json`), or null when the file is absent. Every value is a string. */
+// ---- 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;
@@ -84,7 +127,7 @@ export function readSecretsValues(dir = SECRETS_DIR): Record<string, string> | n
   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 (!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);
   }
@@ -93,7 +136,12 @@ export function readSecretsValues(dir = SECRETS_DIR): Record<string, string> | n
 
 export interface SecretsState {
   dir: string;
-  declaration: SecretsDeclaration | null;
+  /** 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[];
@@ -103,34 +151,51 @@ export interface SecretsState {
   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);
+/** 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 (!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(", ")} })`);
+  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 = declaration?.names ?? [];
+  const names = loaded?.definition.names ?? [];
   const have = new Set(Object.keys(values ?? {}));
   return {
-    dir: resolve(dir), declaration, values,
+    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[];
+}
+
 /**
- * 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.
+ * 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 function loadSecrets(dir = SECRETS_DIR, into: Record<string, string | undefined> = process.env): { loaded: string[]; missing: string[]; undeclared: string[]; state: SecretsState } {
-  const state = secretsState(dir);
+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(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 };
+  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) -----------------------------
@@ -152,18 +217,21 @@ export async function putWorkerSecrets(api: CfApi, account: string, worker: stri
   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:
+/** 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.
 //
-//   { "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",
+//   .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

@@ -58,14 +58,15 @@ export async function openLocal(opts: ServeOptions) {
   // 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);
+  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 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`);
+  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();

package/tsconfig.json

@@ -27,6 +27,7 @@
   "exclude": [
     "bin",
     "hooks-plugin.ts",
+    "src/env/define.ts",
     "scripts",
     "src/adapter/codegen.ts",
     "src/adapter/index.ts",

package/tsconfig.node.json

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