fix(security): close the destructured server-value leak and fail closed on unstubable server hooks

docs/api-reference/veryfront/errors.md

@@ -145,6 +145,7 @@ throw INVALID_WIDGET.create({ detail: "The widget id is malformed." });
 | `SECURITY_VIOLATION`                   | Path traversal / secure-fs violations (replaces SecurityError)                                                                                                                                                                                                                                                                                 | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/error-registry/general.ts#L77)     |
 | `SEMAPHORE_TIMEOUT`                    |                                                                                                                                                                                                                                                                                                                                                | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/error-registry/server.ts#L60)      |
 | `SERVER_ERROR_CATALOG`                 |                                                                                                                                                                                                                                                                                                                                                | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/catalog/server-errors.ts#L4)       |
+| `SERVER_EXPORT_STRIP_FAILED`           |                                                                                                                                                                                                                                                                                                                                                | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/error-registry/build.ts#L75)       |
 | `SERVER_ONLY_IN_CLIENT`                |                                                                                                                                                                                                                                                                                                                                                | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/error-registry/boundary.ts#L11)    |
 | `SERVER_START_ERROR`                   |                                                                                                                                                                                                                                                                                                                                                | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/error-registry/server.ts#L12)      |
 | `SERVICE_OVERLOADED`                   |                                                                                                                                                                                                                                                                                                                                                | [source](https://github.com/veryfront/veryfront-code/blob/main/src/errors/error-registry/server.ts#L44)      |

docs/guides/data-fetching.md

@@ -45,6 +45,93 @@ entirely, including their top-level side effects. Put client initialization in a
 separate client-referenced module or a bare side-effect import that is not only
 used by a server data hook.
 
+### Declare server data hooks directly
+
+Veryfront must find a local declaration for each server data export so it can
+empty it before the module reaches the browser. Declare the hook in the route
+module as a function declaration or as an initializer on a `const`, `let`, or
+`var`:
+
+```tsx
+// Supported
+export async function getServerData(ctx: DataContext) {
+  return { props: { query: ctx.query.toString() } };
+}
+
+// Also supported
+export const getStaticData = async () => ({ props: { generated: true } });
+```
+
+These forms have no declaration to empty and fail the build with
+`server-export-strip-failed`:
+
+```tsx
+// Not supported: the hook is a re-exported import
+import { loadIt } from "./loader.ts";
+export { loadIt as getServerData };
+
+// Not supported: the hook is a class
+export class getServerData {}
+```
+
+Move the import inside a directly declared hook to migrate:
+
+```tsx
+export async function getServerData(ctx: DataContext) {
+  const { loadIt } = await import("./loader.ts");
+  return loadIt(ctx);
+}
+```
+
+The same build error reports a value that only a stripped hook reads when that
+value is declared in a position Veryfront cannot remove, such as a loop head:
+
+```tsx
+// Not supported: the binding is declared by the loop, not at module scope
+for (var KEY of getEnv("SECRET_KEY")) {}
+
+// Supported
+const KEY = getEnv("SECRET_KEY");
+```
+
+### Modules that rewrite the Object intrinsic
+
+Compiled input carries name registrations such as `__name(loadUser, "loadUser")`.
+Veryfront reads them as build metadata, which is what lets it see that
+`loadUser` is read only by a stripped hook and remove it along with the server
+import and the secret behind it.
+
+A module that rewrites `Object.defineProperty`, or reaches it through
+`.constructor`, `__proto__`, `eval`, or `Function`, makes that reading
+unprovable. Veryfront must not delete a call the module can observe, and it must
+not emit a module that still holds a server-only binding, so the build fails
+with `server-export-strip-failed`.
+
+```tsx
+// Not supported: the module rebinds Object, so the name registration
+// cannot be proven to be compiler metadata
+const Object = globalThis.Object;
+
+export async function getServerData() {
+  return { props: { user: await loadUser() } };
+}
+```
+
+Move the code that reaches or rewrites the intrinsic into a module that exports
+no server data hook, then import what you need from it:
+
+```tsx
+import { isPlainObject } from "../lib/is-plain-object.ts";
+
+export async function getServerData() {
+  return { props: { user: await loadUser() } };
+}
+```
+
+Ordinary client code that reads `.constructor` or `__proto__` on a value, such
+as an `isPlainObject` helper or `error.constructor.name` logging, does not
+trigger this failure.
+
 The `props` you return are passed to the page component. To read the same props
 data from a layout or nested component without prop-drilling, use
 `usePageContext().data` (see

docs/guides/errors.md

@@ -170,6 +170,13 @@ Compilation failed.
 - **HTTP status:** 500
 - **What to do:** Review compiler output for specific errors
 
+### server-export-strip-failed
+
+Server-only export cannot be removed from the client build.
+
+- **HTTP status:** 500
+- **What to do:** Declare the hook directly in the route module and keep its values module scope
+
 ## Runtime
 
 Raised while executing project code.

src/errors/catalog/build-errors.test.ts

@@ -16,6 +16,7 @@ describe("errors/catalog/build-errors", () => {
         "ssg-generation-error",
         "sourcemap-error",
         "compilation-error",
+        "server-export-strip-failed",
       ];
 
       for (const slug of expectedSlugs) {
@@ -38,8 +39,8 @@ describe("errors/catalog/build-errors", () => {
       }
     });
 
-    it("should have 9 entries", () => {
-      assertEquals(Object.keys(BUILD_ERROR_CATALOG).length, 9);
+    it("should have 10 entries", () => {
+      assertEquals(Object.keys(BUILD_ERROR_CATALOG).length, 10);
     });
 
     it("build-failed should have tips", () => {
@@ -52,5 +53,28 @@ describe("errors/catalog/build-errors", () => {
       const solution = BUILD_ERROR_CATALOG["mdx-compile-error"]!;
       assertEquals(typeof solution.example, "string");
     });
+
+    it("documents server export stripping remediation", () => {
+      const solution = BUILD_ERROR_CATALOG["server-export-strip-failed"]!;
+      assertEquals(
+        solution.title,
+        "Server-only export cannot be removed from the client build",
+      );
+      assertEquals(solution.message.includes("getServerData"), true);
+      assertEquals(
+        solution.steps?.includes(
+          "Declare the hook directly as a function declaration or a const, let, or var declaration",
+        ),
+        true,
+      );
+      assertEquals(
+        solution.steps?.includes(
+          "Keep a browser-needed value in a client-referenced module before importing it into the hook",
+        ),
+        true,
+      );
+      assertEquals(solution.example?.includes("export { loadIt as getServerData };"), true);
+      assertEquals(solution.example?.includes("export async function getServerData(ctx)"), true);
+    });
   });
 });

src/errors/catalog/build-errors.ts

@@ -110,4 +110,36 @@ title: My Post
       "Verify TypeScript configuration",
     ],
   ),
+
+  "server-export-strip-failed": createErrorSolution("server-export-strip-failed", {
+    title: "Server-only export cannot be removed from the client build",
+    message:
+      "A route module exports getServerData, getStaticData, or getStaticPaths in a form the " +
+      "client build cannot empty. Emitting the module would send the loader, its imports, and " +
+      "the values it reads to the browser, so the build stops instead.",
+    steps: [
+      "Declare the hook directly as a function declaration or a const, let, or var declaration",
+      "Replace a re-export such as `export { loadIt as getServerData }` with a direct declaration",
+      "Replace a class or an alias export of the hook with an exported async function",
+      "Declare any value the hook reads once, at module scope, not inside a loop head",
+      "Keep a browser-needed value in a client-referenced module before importing it into the hook",
+      "Move code that rewrites or reaches the `Object` intrinsic into a module with no server data hook",
+    ],
+    tips: [
+      "The error message names the export and the declaration form that blocked the removal",
+      "A hook declared directly is stripped from the client bundle with everything only it read",
+      "A module that rewrites `Object.defineProperty`, or reaches it through `.constructor`, " +
+      "`__proto__`, `eval` or `Function`, stops the build from proving which name registrations " +
+      "the compiler emitted, so a server-only binding one of them names cannot be removed",
+    ],
+    example: `// Not supported: no local declaration to empty
+import { loadIt } from "./loader.ts";
+export { loadIt as getServerData };
+
+// Supported
+export async function getServerData(ctx) {
+  const { loadIt } = await import("./loader.ts");
+  return loadIt(ctx);
+}`,
+  }),
 });

src/errors/error-registry.test.ts

@@ -29,9 +29,9 @@ describe("error-registry", () => {
       assertEquals(slugs.length, uniqueSlugs.size, "Duplicate slugs detected");
     });
 
-    it("should have 113 registered errors", () => {
+    it("should have 114 registered errors", () => {
       const slugs = getAllSlugs();
-      assertEquals(slugs.length, 113);
+      assertEquals(slugs.length, 114);
     });
   });
 
@@ -180,7 +180,7 @@ describe("error-registry", () => {
 
     it("should return BUILD errors", () => {
       const errors = getErrorsByCategory("BUILD");
-      assertEquals(errors.length, 9);
+      assertEquals(errors.length, 10);
       for (const error of errors) {
         assertEquals(error.category, "BUILD");
       }
@@ -322,7 +322,7 @@ describe("error-registry", () => {
   describe("error categories coverage", () => {
     const expectedCategoryCounts: Record<string, number> = {
       CONFIG: 12,
-      BUILD: 9,
+      BUILD: 10,
       RUNTIME: 11,
       ROUTE: 6,
       MODULE: 8,

src/errors/error-registry/build.ts

@@ -72,6 +72,14 @@ export const COMPILATION_ERROR = defineError({
   suggestion: "Review compiler output for specific errors",
 });
 
+export const SERVER_EXPORT_STRIP_FAILED = defineError({
+  slug: "server-export-strip-failed",
+  category: "BUILD",
+  status: 500,
+  title: "Server-only export cannot be removed from the client build",
+  suggestion: "Declare the hook directly in the route module and keep its values module scope",
+});
+
 /** Registry fragment for BUILD errors (slug → definition). */
 export const BUILD_REGISTRY = {
   "build-failed": BUILD_FAILED,
@@ -83,4 +91,5 @@ export const BUILD_REGISTRY = {
   "ssg-generation-error": SSG_GENERATION_ERROR,
   "sourcemap-error": SOURCEMAP_ERROR,
   "compilation-error": COMPILATION_ERROR,
+  "server-export-strip-failed": SERVER_EXPORT_STRIP_FAILED,
 } as const;

src/errors/index.ts

@@ -137,6 +137,7 @@ export {
   SCHEDULE_CONFIG_INVALID,
   SECURITY_VIOLATION,
   SEMAPHORE_TIMEOUT,
+  SERVER_EXPORT_STRIP_FAILED,
   SERVER_ONLY_IN_CLIENT,
   SERVER_START_ERROR,
   SERVICE_OVERLOADED,

src/server/handlers/dev/dashboard/api.test.ts

@@ -214,10 +214,10 @@ describe("Dashboard API - GET endpoints", () => {
     assertEquals("errors" in body, true);
     assertEquals("categories" in body, true);
     assertEquals("count" in body, true);
-    assertEquals(body.count, 66);
+    assertEquals(body.count, 67);
     assertEquals(body.categories, {
       config: 7,
-      build: 9,
+      build: 10,
       runtime: 7,
       route: 6,
       server: 8,