Merge pull request #181 from JoviDeCroock/jovi/env-safety

Typed env access (serverEnv/publicEnv) and client-bundle env leak detection

Author: JoviDeCroock

.changeset/env-safety.md

@@ -0,0 +1,24 @@
+---
+"@pracht/core": minor
+"@pracht/vite-plugin": minor
+"@pracht/cli": minor
+"@pracht/adapter-cloudflare": patch
+---
+
+Env var safety: typed env access and client-leak detection.
+
+- `@pracht/core` gains `publicEnv` (safe everywhere, only exposes
+  `PRACHT_PUBLIC_`-prefixed variables) and a server-only
+  `@pracht/core/env/server` entry exporting `serverEnv`/`setServerEnv`. Both
+  are typed once via the existing `Register` declaration-merging pattern
+  (`Register["env"]`). `serverEnv` resolves to `process.env` on Node/Vercel
+  and to the worker env bindings on Cloudflare (installed per request by the
+  adapter; not available at module top level there).
+- The pracht Vite plugin adds `PRACHT_PUBLIC_` to Vite's `envPrefix`, rejects
+  client-side imports of `@pracht/core/env/server` at build time, and ships a
+  new `pracht:env-safety` build check that fails client builds referencing
+  non-public env vars (`process.env.X` / `import.meta.env.X`), naming the
+  variable, chunk, and likely source module. Escape hatch:
+  `pracht({ envSafety: { allow: [...] } })` or `envSafety: false`.
+- `pracht verify` / `pracht doctor` read the env-safety build report and re-run
+  the literal leak scan against an existing `dist/client` build output.

README.md

@@ -23,6 +23,7 @@ Pick SPA, SSR, SSG, or ISG on a route-by-route basis. Ship less JavaScript by de
 - **Vite-native** — instant HMR, fast builds, multi-environment output out of the box.
 - **Performance budgets built in** — `pracht build --analyze` reports per-route client JS (gzip + raw), and per-route `budgets` fail the build when a route ships too much.
 - **Deploy anywhere** — one codebase, one build, three production-ready adapters (Node, Cloudflare Workers, Vercel).
+- **Env safety built in** — typed `serverEnv`/`publicEnv` helpers with a `PRACHT_PUBLIC_` prefix rule, and builds fail when client bundles reference non-public env vars.
 
 ## At a glance
 
@@ -114,6 +115,7 @@ Pracht is built to be operated by coding agents as much as by humans:
 - [docs/STYLING.md](docs/STYLING.md) — CSS Modules, Tailwind, CSS-in-JS limitations
 - [docs/ADAPTERS.md](docs/ADAPTERS.md) — Node, Cloudflare, Vercel deployment paths
 - [docs/MCP.md](docs/MCP.md) — built-in MCP server for coding agents
+- [docs/ENV.md](docs/ENV.md) — typed env access, `PRACHT_PUBLIC_` prefix rule, leak detection
 - [packages/start/README.md](packages/start/README.md) — starter CLI details
 - [packages/preact-worker-facets/README.md](packages/preact-worker-facets/README.md) — experimental Cloudflare Dynamic Worker facets runtime for Preact components
 - [examples/basic](examples/basic), [examples/cloudflare](examples/cloudflare), [examples/docs](examples/docs) — working apps

docs/ARCHITECTURE.md

@@ -511,6 +511,10 @@ The published core package also exposes small browser-oriented entries:
 - `@pracht/core/error-overlay` and `@pracht/core/dev-404` are dev-only entries
   loaded on demand by the Vite dev middleware (via `ssrLoadModule`); no
   production entry point or generated server entry imports them.
+- `@pracht/core/env` exposes `publicEnv` (client-safe, `PRACHT_PUBLIC_`-prefixed
+  vars only); `@pracht/core/env/server` exposes `serverEnv` and is server-only —
+  the vite plugin rejects client-side imports of it at build time, and its
+  browser condition points at a throwing stub as a backstop for other bundlers.
 - The root `@pracht/core` export has a browser condition that points at a
   client-safe public entry for route and shell modules.
 
@@ -554,6 +558,26 @@ from the route id (see [docs/DATA_LOADING.md](DATA_LOADING.md#useroutedata)).
 
 ---
 
+## Environment Variable Safety
+
+Pracht separates env access into `serverEnv` (`@pracht/core/env/server`,
+server-only, resolved per adapter) and `publicEnv` (`@pracht/core`, only
+`PRACHT_PUBLIC_`-prefixed variables, inlined into client bundles via Vite's
+`envPrefix`). Both are typed once through the `Register` declaration-merging
+pattern (`Register["env"]`).
+
+At build time the `pracht:env-safety` plugin scans client output chunks — and
+the transformed sources of first-party modules included in them — for
+references to non-public env vars and fails the build naming the variable,
+chunk, and likely source module. `pracht({ envSafety: { allow: [...] } })` is
+the escape hatch; successful client builds emit an env-safety report under
+`dist/client/_pracht/`, and `pracht verify` uses that report plus a literal
+chunk scan against `dist/client`.
+
+See [docs/ENV.md](ENV.md) for the full model and per-adapter behavior.
+
+---
+
 ## Hydration
 
 Server-rendered HTML includes a non-executable JSON script tag with serialized

docs/ENV.md

@@ -0,0 +1,122 @@
+# Environment Variables
+
+Pracht ships a typed, safe-by-default environment model: server secrets stay on
+the server, client-visible configuration is explicitly opt-in via a naming
+prefix, and the build fails when a non-public variable is referenced in client
+code.
+
+---
+
+## The model
+
+| Surface     | Import                      | Contents                              | Where it works        |
+| ----------- | --------------------------- | ------------------------------------- | --------------------- |
+| `serverEnv` | `@pracht/core/env/server`   | The full platform env                 | Server code only      |
+| `publicEnv` | `@pracht/core` (any entry)  | Only `PRACHT_PUBLIC_`-prefixed vars   | Everywhere            |
+
+```ts
+// Server code (loaders, middleware, API routes, src/server/**):
+import { serverEnv } from "@pracht/core/env/server";
+const db = connect(serverEnv.DATABASE_URL);
+
+// Anywhere (values are public, inlined into the client bundle at build time):
+import { publicEnv } from "@pracht/core";
+const api = publicEnv.PRACHT_PUBLIC_API_BASE;
+```
+
+### The prefix rule
+
+Only variables prefixed with `PRACHT_PUBLIC_` are exposed through `publicEnv`.
+The pracht Vite plugin adds `PRACHT_PUBLIC_` to Vite's
+[`envPrefix`](https://vite.dev/config/shared-options#envprefix) (alongside the
+default `VITE_`), so prefixed variables are also available directly as
+`import.meta.env.PRACHT_PUBLIC_*` in dev and statically inlined at build time.
+Because values are inlined, never put a secret behind the prefix.
+
+`publicEnv` reads `import.meta.env` when Vite provides it and falls back to
+`process.env` outside Vite (plain Node entries, tests). It is a snapshot of
+build-time values on the client; prefer reading it over `import.meta.env` for
+the typing below.
+
+## Typing your env once
+
+Declare the env shape via the same `Register` declaration-merging pattern used
+for routes and context:
+
+```ts
+// src/env.d.ts
+declare module "@pracht/core" {
+  interface Register {
+    env: {
+      DATABASE_URL: string;
+      SESSION_SECRET: string;
+      PRACHT_PUBLIC_APP_NAME: string;
+      PRACHT_PUBLIC_API_BASE: string;
+    };
+  }
+}
+```
+
+`serverEnv` is then typed as the full shape, and `publicEnv` automatically
+narrows to the `PRACHT_PUBLIC_`-prefixed subset — referencing
+`publicEnv.DATABASE_URL` is a type error. Without a registration both fall back
+to `Record<string, string | undefined>`.
+
+## Per-adapter behavior of `serverEnv`
+
+- **Node** (`@pracht/adapter-node`): resolves to `process.env`. Available at
+  module top level.
+- **Vercel** (`@pracht/adapter-vercel`): resolves to `process.env`, which the
+  Vercel runtime populates in both Node and edge functions. Available at module
+  top level.
+- **Cloudflare** (`@pracht/adapter-cloudflare`): there is no ambient env on
+  Workers — bindings arrive per request. The adapter installs the worker `env`
+  bindings (via `setServerEnv`) when a request enters the fetch handler, so
+  `serverEnv` works inside loaders, middleware, and API routes. It does **not**
+  work at module top level (before the first request it throws with a message
+  explaining this). Non-string bindings (KV, D1, …) are reachable through
+  `serverEnv` too, but `context.env` remains the canonical way to access
+  bindings.
+
+Custom setups can call `setServerEnv(env)` (exported from
+`@pracht/core/env/server` and `@pracht/core/server`) to install another source.
+
+## Client-leak detection
+
+During `pracht build` the plugin scans every client chunk for references to
+`process.env.X` / `import.meta.env.X` (including `["X"]` bracket access) where
+`X` is not `PRACHT_PUBLIC_`- or `VITE_`-prefixed and not a Vite built-in
+(`MODE`, `DEV`, `PROD`, `SSR`, `BASE_URL`, plus `NODE_ENV`, which Vite
+statically replaces).
+References are matched both in the rendered chunks and in the transformed
+sources of first-party modules that end up in a chunk — bundlers rewrite
+`process.env` in client output, so the source-level signal is what catches
+most mistakes. A hit fails the build naming the variable, the chunk, and the
+likely source module.
+
+Importing `@pracht/core/env/server` from client code also fails the build
+immediately. Route files may import it freely for `loader`/`headers`/
+`getStaticPaths` — the client transform strips those exports and the import
+with them (see `docs/ARCHITECTURE.md`, client module transform).
+
+`pracht verify` (and `pracht doctor`) read the build-time env-safety report
+emitted to `dist/client/_pracht/env-safety.json` and also re-run the literal
+chunk scan against an existing `dist/client` output when one is present.
+
+### Escape hatch
+
+Intentional, known-safe references can be allowlisted, or the check disabled:
+
+```ts
+pracht({
+  envSafety: { allow: ["SENTRY_RELEASE"] },
+  // envSafety: false, // disable entirely (not recommended)
+});
+```
+
+### Limits
+
+The check detects *references*, not values: a secret returned from a loader
+still reaches the client through hydration state, and a value inlined via a
+custom `define` is invisible to the scan. Use the `audit-secrets` skill for
+dataflow-level review of loader return values.

e2e/env-safety.test.ts

@@ -0,0 +1,112 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { expect, test } from "@playwright/test";
+
+// Coverage for the env safety feature — builds a copy of examples/basic with a
+// route component that references a non-public env var and asserts the client
+// build fails naming the variable, then that the envSafety allowlist escape
+// hatch lets the same build pass.
+const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const fixtureDir = resolve(repoRoot, "examples/basic");
+const cliEntry = resolve(repoRoot, "packages/cli/bin/pracht.js");
+
+const LEAKED_ENV_VAR = "PRACHT_E2E_SECRET_TOKEN";
+
+function prepareLeakyProject(): { tempDir: string; exampleDir: string } {
+  const tempRoot = resolve(repoRoot, ".tmp");
+  mkdirSync(tempRoot, { recursive: true });
+  const tempDir = mkdtempSync(resolve(tempRoot, "pracht-env-safety-"));
+  const exampleDir = resolve(tempDir, "project");
+
+  cpSync(fixtureDir, exampleDir, {
+    filter(source) {
+      return ![".vercel", "dist", "test-results"].some((entry) =>
+        source.includes(`/examples/basic/${entry}`),
+      );
+    },
+    recursive: true,
+  });
+
+  writeFileSync(
+    resolve(exampleDir, "src/routes/env-leak.tsx"),
+    [
+      `export function Component() {`,
+      `  return <p>{process.env.${LEAKED_ENV_VAR}}</p>;`,
+      `}`,
+      ``,
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const routesPath = resolve(exampleDir, "src/routes.ts");
+  const routesSource = readFileSync(routesPath, "utf-8");
+  writeFileSync(
+    routesPath,
+    routesSource.replace(
+      'route("/", () => import("./routes/home.tsx"), { id: "home", render: "ssg" }),',
+      `route("/", () => import("./routes/home.tsx"), { id: "home", render: "ssg" }),\n      route("/env-leak", () => import("./routes/env-leak.tsx"), { id: "env-leak", render: "ssr" }),`,
+    ),
+    "utf-8",
+  );
+
+  return { tempDir, exampleDir };
+}
+
+function runBuild(exampleDir: string): void {
+  execFileSync(process.execPath, [cliEntry, "build"], {
+    cwd: exampleDir,
+    env: {
+      ...process.env,
+      NODE_OPTIONS: "--experimental-strip-types",
+      PRACHT_ADAPTER: "node",
+    },
+    stdio: "pipe",
+  });
+}
+
+test("client builds fail when a chunk references a non-public env var", async () => {
+  test.setTimeout(120_000);
+
+  const { tempDir, exampleDir } = prepareLeakyProject();
+
+  try {
+    let failure: Error & { stderr?: Buffer } = new Error("build unexpectedly succeeded");
+    try {
+      runBuild(exampleDir);
+    } catch (error) {
+      failure = error as Error & { stderr?: Buffer };
+    }
+
+    const output = `${failure.message}\n${failure.stderr?.toString() ?? ""}`;
+    expect(output).toContain("Environment variable leak detected");
+    expect(output).toContain(`process.env.${LEAKED_ENV_VAR}`);
+  } finally {
+    rmSync(tempDir, { force: true, recursive: true });
+  }
+});
+
+test("envSafety allowlist lets an intentional env reference through", async () => {
+  test.setTimeout(120_000);
+
+  const { tempDir, exampleDir } = prepareLeakyProject();
+
+  try {
+    const configPath = resolve(exampleDir, "vite.config.ts");
+    const configSource = readFileSync(configPath, "utf-8");
+    writeFileSync(
+      configPath,
+      configSource.replace(
+        "pracht({ adapter: await resolveAdapter() })",
+        `pracht({ adapter: await resolveAdapter(), envSafety: { allow: [${JSON.stringify(LEAKED_ENV_VAR)}] } })`,
+      ),
+      "utf-8",
+    );
+
+    expect(() => runBuild(exampleDir)).not.toThrow();
+  } finally {
+    rmSync(tempDir, { force: true, recursive: true });
+  }
+});

examples/docs/src/routes.ts

@@ -56,6 +56,10 @@ export const app = defineApp({
         id: "styling",
         render: "ssg",
       }),
+      route("/docs/env", () => import("./routes/docs/env.md"), {
+        id: "env",
+        render: "ssg",
+      }),
       route("/docs/cli", () => import("./routes/docs/cli.md"), {
         id: "cli",
         render: "ssg",

examples/docs/src/routes/docs/cli.md

@@ -3,8 +3,8 @@ title: CLI
 lead: The <code>@pracht/cli</code> package provides development, build, scaffolding, and doctor commands for your app.
 breadcrumb: CLI
 prev:
-  href: /docs/styling
-  title: Styling
+  href: /docs/env
+  title: Environment Variables
 next:
   href: /docs/deployment
   title: Deployment