@pylonsync/functions 0.3.310 → 0.3.312

package/dist/server-only.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker import that pins a module to the SERVER. Put it at the top of any
+ * module that must never reach the browser — one holding secrets, server
+ * config, or node-only APIs:
+ *
+ *   import "@pylonsync/functions/server-only";
+ *
+ *   export const stripeKey = process.env.STRIPE_SECRET_KEY!;
+ *
+ * Page (`page.tsx`) and layout (`layout.tsx`) modules — and everything they
+ * transitively import — are bundled for client hydration, so a plain literal or
+ * server config in that graph would ship to the browser. If a module marked
+ * with this import is pulled into a client-reachable page, the SSR client
+ * bundler REFUSES to build and names the offending importer (see the
+ * `pylon-server-only` plugin in `ssr-client-bundler.ts`).
+ *
+ * On the server this is an inert no-op. There is nothing to call — importing it
+ * is the whole contract.
+ */
+export {};

package/dist/ssr-client-bundler.d.ts

@@ -14,6 +14,16 @@ interface BundleClientMessage {
      */
     app_dir?: string;
 }
+/**
+ * Fail the CLIENT bundle when a `server-only` module is resolved — meaning it
+ * was pulled into a page/layout's client graph. Page/layout modules (and their
+ * transitive imports) are bundled for hydration, so a literal secret or server
+ * config in that graph would ship to the browser (the `process.env.*` `define`
+ * only neutralizes env reads). Authors mark such modules with
+ * `import "@pylonsync/functions/server-only"`; this turns an accidental client
+ * import into a loud build failure that names the offending importer.
+ */
+export declare function assertNotServerOnly(specifier: string, importer: string): void;
 /**
  * Manifest schema. One entry per route, indexed by the same
  * project-relative component path the SSR side passes through.

package/dist/ssr-runtime.d.ts

@@ -101,6 +101,7 @@ export interface SsrCookieOptions {
     expires?: Date | string;
     /** Defaults to true (secure default). Pass false for a client-readable cookie. */
     httpOnly?: boolean;
+    /** Defaults to true in prod / false in dev. Forced true when sameSite="none". */
     secure?: boolean;
     /** Defaults to "lax". */
     sameSite?: "strict" | "lax" | "none";
@@ -341,6 +342,14 @@ export declare function applyAutoSocialImages(component: string, headers: Record
  * marker + probe are in place before the deferred client entry boots the sync
  * engine. `<` is escaped so the JSON can't break out of the script.
  */
+/**
+ * Escape a JSON string so it can't break out of a `<script>` element: `<`
+ * closes a `</script>` (or `<!--`, `<script`); U+2028/U+2029 are JS statement
+ * terminators (valid in JSON, not in a JS string literal). Applied to every
+ * server-serialized blob embedded in a script tag \u2014 the `application/json`
+ * data blobs AND the executable fallback warning.
+ */
+export declare function escapeScriptJson(json: string): string;
 export declare function buildDevHudChunk(devInfo: Record<string, unknown>): string;
 /**
  * Build the hydration tail appended after React's stream EOFs: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.310",
+  "version": "0.3.312",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -14,6 +14,10 @@
       "types": "./dist/runtime.d.ts",
       "default": "./src/runtime.ts"
     },
+    "./server-only": {
+      "types": "./dist/server-only.d.ts",
+      "default": "./src/server-only.ts"
+    },
     "./client-bundler": {
       "types": "./dist/ssr-client-bundler.d.ts",
       "default": "./src/ssr-client-bundler.ts"

package/src/server-only.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker import that pins a module to the SERVER. Put it at the top of any
+ * module that must never reach the browser — one holding secrets, server
+ * config, or node-only APIs:
+ *
+ *   import "@pylonsync/functions/server-only";
+ *
+ *   export const stripeKey = process.env.STRIPE_SECRET_KEY!;
+ *
+ * Page (`page.tsx`) and layout (`layout.tsx`) modules — and everything they
+ * transitively import — are bundled for client hydration, so a plain literal or
+ * server config in that graph would ship to the browser. If a module marked
+ * with this import is pulled into a client-reachable page, the SSR client
+ * bundler REFUSES to build and names the offending importer (see the
+ * `pylon-server-only` plugin in `ssr-client-bundler.ts`).
+ *
+ * On the server this is an inert no-op. There is nothing to call — importing it
+ * is the whole contract.
+ */
+export {};

package/src/ssr-client-bundler.test.ts

@@ -24,6 +24,7 @@ import * as os from "node:os";
 import {
   buildClientBundle,
   buildTailwind,
+  assertNotServerOnly,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 import { nearestBoundaryComponent } from "./ssr-client-boundary";
@@ -430,3 +431,60 @@ describe("Tailwind compile is concurrency-safe", () => {
     expect(stranded).toEqual([]);
   }, 20_000);
 });
+
+describe("server-only guard (secrets can't leak into the client bundle)", () => {
+  test("assertNotServerOnly throws for server-only specifiers, passes others", () => {
+    expect(() =>
+      assertNotServerOnly("@pylonsync/functions/server-only", "app/page.tsx"),
+    ).toThrow(/server-only/i);
+    expect(() => assertNotServerOnly("server-only", "app/x/layout.tsx")).toThrow(
+      /server-only/i,
+    );
+    // The importer is named so the author can find the offending module.
+    expect(() => assertNotServerOnly("server-only", "app/secrets.ts")).toThrow(
+      /app\/secrets\.ts/,
+    );
+    // Ordinary imports pass untouched.
+    expect(() => assertNotServerOnly("react", "app/page.tsx")).not.toThrow();
+    expect(() => assertNotServerOnly("@/lib/utils", "app/page.tsx")).not.toThrow();
+  });
+
+  test("a real client build importing a server-only module FAILS via the guard", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-server-only-"));
+    const entry = path.join(dir, "entry.ts");
+    fs.writeFileSync(entry, `import "server-only";\nexport const x = 1;\n`);
+    // Same plugin the bundler installs. `guardFired` proves the guard's
+    // onResolve ran for the marker (Bun runs plugin resolution BEFORE default
+    // resolution) — distinguishing a real guard rejection from an unrelated
+    // "module not found". Bun surfaces the plugin throw as a failed build.
+    let guardFired = false;
+    let failed = false;
+    try {
+      const result = await Bun.build({
+        entrypoints: [entry],
+        outdir: path.join(dir, "out"),
+        target: "browser",
+        plugins: [
+          {
+            name: "pylon-server-only",
+            setup(build: any) {
+              build.onResolve(
+                { filter: /^(@pylonsync\/functions\/server-only|server-only)$/ },
+                (args: any) => {
+                  guardFired = true;
+                  assertNotServerOnly(args.path, args.importer);
+                },
+              );
+            },
+          },
+        ],
+      } as any);
+      failed = !result.success;
+    } catch {
+      failed = true;
+    }
+    expect(guardFired).toBe(true);
+    expect(failed).toBe(true);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/ssr-client-bundler.ts

@@ -101,10 +101,46 @@ declare const Bun: {
         };
     publicPath?: string;
     root?: string;
+    plugins?: Array<{
+      name: string;
+      setup(build: {
+        onResolve(
+          opts: { filter: RegExp; namespace?: string },
+          callback: (args: { path: string; importer: string }) => void,
+        ): void;
+      }): void;
+    }>;
   }): Promise<BunBuildOutput>;
   file(path: string): { exists(): Promise<boolean> };
 };
 
+/**
+ * Specifiers marking a module as SERVER-ONLY: `@pylonsync/functions/server-only`
+ * (in-ecosystem) or the bare `server-only` (Next.js compat). A module that
+ * imports one must never reach the browser.
+ */
+const SERVER_ONLY_RE = /^(@pylonsync\/functions\/server-only|server-only)$/;
+
+/**
+ * Fail the CLIENT bundle when a `server-only` module is resolved — meaning it
+ * was pulled into a page/layout's client graph. Page/layout modules (and their
+ * transitive imports) are bundled for hydration, so a literal secret or server
+ * config in that graph would ship to the browser (the `process.env.*` `define`
+ * only neutralizes env reads). Authors mark such modules with
+ * `import "@pylonsync/functions/server-only"`; this turns an accidental client
+ * import into a loud build failure that names the offending importer.
+ */
+export function assertNotServerOnly(specifier: string, importer: string): void {
+  if (SERVER_ONLY_RE.test(specifier)) {
+    throw new Error(
+      `pylon: "${specifier}" is server-only but was imported into the client bundle by ` +
+        `${importer || "a page/layout module"}. Page/layout modules (and everything they import) ship to ` +
+        `the browser — move server-only code (secrets, server config, node-only APIs) into a server function ` +
+        `(functions/) or a route.ts handler and pass only the rendered values as props.`,
+    );
+  }
+}
+
 /**
  * Synchronously walk the route dir (`<appDirRel>` under cwd, e.g.
  * `app` or `web/app`) and return one entry per discovered page, each
@@ -1240,6 +1276,19 @@ async function _doBuildInner(
         chunk: "chunks/[name]-[hash].js",
         asset: "assets/[name]-[hash][ext]",
       },
+      // Refuse to bundle a server-only module into a client-reachable page —
+      // secrets / server config in a page's import graph would otherwise ship
+      // to the browser.
+      plugins: [
+        {
+          name: "pylon-server-only",
+          setup(build) {
+            build.onResolve({ filter: SERVER_ONLY_RE }, (args) => {
+              assertNotServerOnly(args.path, args.importer);
+            });
+          },
+        },
+      ],
     });
 
     if (!result.success) {
@@ -1281,6 +1330,52 @@ async function _doBuildInner(
       }
     }
 
+    // loro-crdt's web build locates its WASM sibling at RUNTIME via
+    // `new URL("loro_wasm_bg.wasm", import.meta.url)` — the file never
+    // appears in the static import graph, so Bun doesn't emit it and every
+    // CRDT-using page 404s on /_pylon/build/loro_wasm_bg.wasm during
+    // hydration. When any built output references the wasm by name, copy
+    // the binary next to the entries AND into chunks/ so the runtime URL
+    // resolves from either an entry or a split chunk.
+    try {
+      const referencesLoroWasm = result.outputs.some((o) => {
+        if (!o.path.endsWith(".js")) return false;
+        try {
+          return fs.readFileSync(o.path, "utf8").includes("loro_wasm_bg.wasm");
+        } catch {
+          return false;
+        }
+      });
+      if (referencesLoroWasm) {
+        const loroPkg = (Bun as any).resolveSync(
+          "loro-crdt/package.json",
+          cwd,
+        ) as string;
+        // The wasm must come from the SAME build variant whose JS glue got
+        // bundled — the wasm-bindgen import namespaces differ between
+        // variants (mixing them fails instantiation with `Import #0 "wbg"`).
+        // `target: "browser"` resolves the package's "browser" condition, so
+        // prefer browser/; web/ is the fallback for older package layouts.
+        const loroDir = path.dirname(loroPkg);
+        const wasmSrc = ["browser", "web"]
+          .map((v) => path.join(loroDir, v, "loro_wasm_bg.wasm"))
+          .find((p) => fs.existsSync(p));
+        if (wasmSrc) {
+          fs.copyFileSync(wasmSrc, path.join(outdir, "loro_wasm_bg.wasm"));
+          const chunksDir = path.join(outdir, "chunks");
+          if (fs.existsSync(chunksDir)) {
+            fs.copyFileSync(
+              wasmSrc,
+              path.join(chunksDir, "loro_wasm_bg.wasm"),
+            );
+          }
+        }
+      }
+    } catch {
+      // Best-effort: failing to copy just reproduces the 404 this guards
+      // against; the build itself is fine.
+    }
+
     // Scan a built JS file for static `import` literals pointing
     // at `./chunks/<file>.js` and return them resolved to outdir-
     // relative paths. Bun's minified output uses simple double

package/src/ssr-form-runtime.ts

@@ -19,6 +19,7 @@ import {
   PylonRouteControl,
   finalizeHeaders,
   importModule,
+  isDevMode,
   type ResponseState,
 } from "./ssr-runtime";
 import { buildDbWriter } from "./runtime";
@@ -81,8 +82,9 @@ function makeFormFields(raw: Record<string, string | string[]>): FormFields {
 // the list drives the 405 `Allow` header advertising which a route.ts exports.
 const HANDLER_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
 const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64");
-const isDev = () =>
-  process.env.PYLON_DEV_MODE === "1" || process.env.PYLON_DEV_MODE === "true";
+// Share ONE dev-mode parse with ssr-runtime (case-insensitive "1"/"true") so
+// the form path and the render path never disagree on whether to leak stacks.
+const isDev = isDevMode;
 
 export async function handleForm(
   msg: HandleFormMessage,

package/src/ssr-runtime.test.ts

@@ -15,6 +15,7 @@ import {
   asRouteControl,
   PylonRouteControl,
   finalizeHeaders,
+  escapeScriptJson,
   makeResponseController,
   makeReadTrackingProxy,
   makeRevocableReadTrackingProxy,
@@ -750,3 +751,68 @@ describe("isSafeRedirect — open-redirect guard for response.redirect()", () =>
     expect(isSafeRedirect("https://app.example.com/x", {})).toBe(false);
   });
 });
+
+describe("script-escaping + secure cookies", () => {
+  test("escapeScriptJson neutralizes a </script> breakout", () => {
+    const out = escapeScriptJson(JSON.stringify("</script><script>alert(1)</script>"));
+    expect(out).not.toContain("<");
+    expect(out).toContain("\\u003c");
+  });
+
+  test("buildHydrationTail fallback warn script escapes manifestErr", () => {
+    const tail = buildHydrationTail({
+      component: "app/x/page",
+      layouts: [],
+      props: {},
+      ssrData: {},
+      manifestRoute: null,
+      publicPrefix: "/_pylon/build/",
+      manifestErr: 'no entry for "</script><script>evil</script>"',
+    });
+    const warn = tail.slice(tail.indexOf("console.warn"));
+    // The executable fallback must escape the error — no raw injected tag.
+    expect(warn).not.toContain("<script>evil");
+    expect(warn).toContain("\\u003c");
+  });
+
+  test("serializeCookie: Secure defaults + SameSite=None forces Secure", () => {
+    const mk = () => {
+      const s = { status: 200, headers: {}, cookies: [] as string[] };
+      return { s, r: makeResponseController(s) };
+    };
+    const prev = process.env.PYLON_DEV_MODE;
+    try {
+      // Prod (dev off): Secure defaults ON.
+      delete process.env.PYLON_DEV_MODE;
+      {
+        const { s, r } = mk();
+        r.setCookie("a", "1");
+        expect(s.cookies[0]).toContain("; Secure");
+        expect(s.cookies[0]).toContain("; HttpOnly");
+      }
+      // Explicit secure:false (non-None) wins even in prod.
+      {
+        const { s, r } = mk();
+        r.setCookie("a", "1", { secure: false });
+        expect(s.cookies[0]).not.toContain("; Secure");
+      }
+      // Dev: Secure defaults OFF so http://localhost keeps the cookie.
+      process.env.PYLON_DEV_MODE = "1";
+      {
+        const { s, r } = mk();
+        r.setCookie("a", "1");
+        expect(s.cookies[0]).not.toContain("; Secure");
+      }
+      // SameSite=None forces Secure even in dev (browsers drop it otherwise).
+      {
+        const { s, r } = mk();
+        r.setCookie("a", "1", { sameSite: "none" });
+        expect(s.cookies[0]).toContain("; Secure");
+        expect(s.cookies[0]).toContain("SameSite=None");
+      }
+    } finally {
+      if (prev === undefined) delete process.env.PYLON_DEV_MODE;
+      else process.env.PYLON_DEV_MODE = prev;
+    }
+  });
+});

package/src/ssr-runtime.ts

@@ -146,6 +146,7 @@ export interface SsrCookieOptions {
   expires?: Date | string;
   /** Defaults to true (secure default). Pass false for a client-readable cookie. */
   httpOnly?: boolean;
+  /** Defaults to true in prod / false in dev. Forced true when sameSite="none". */
   secure?: boolean;
   /** Defaults to "lax". */
   sameSite?: "strict" | "lax" | "none";
@@ -194,8 +195,13 @@ function serializeCookie(
     c += `; Domain=${opts.domain}`;
   }
   if (opts.httpOnly !== false) c += `; HttpOnly`;
-  if (opts.secure) c += `; Secure`;
   const ss = opts.sameSite ?? "lax";
+  // `Secure` defaults ON in prod (mirrors the framework session cookie), OFF in
+  // dev so an http://localhost cookie isn't dropped. `SameSite=None` REQUIRES
+  // `Secure` — browsers silently drop a None cookie without it — so force it
+  // there regardless of the caller / dev mode.
+  const secure = ss === "none" ? true : (opts.secure ?? !isDevMode());
+  if (secure) c += `; Secure`;
   c += `; SameSite=${ss[0].toUpperCase()}${ss.slice(1)}`;
   return c;
 }
@@ -1517,11 +1523,22 @@ function pylonDevHud() {
  * marker + probe are in place before the deferred client entry boots the sync
  * engine. `<` is escaped so the JSON can't break out of the script.
  */
-export function buildDevHudChunk(devInfo: Record<string, unknown>): string {
-  const json = JSON.stringify(devInfo)
+/**
+ * Escape a JSON string so it can't break out of a `<script>` element: `<`
+ * closes a `</script>` (or `<!--`, `<script`); U+2028/U+2029 are JS statement
+ * terminators (valid in JSON, not in a JS string literal). Applied to every
+ * server-serialized blob embedded in a script tag \u2014 the `application/json`
+ * data blobs AND the executable fallback warning.
+ */
+export function escapeScriptJson(json: string): string {
+  return json
     .replace(/</g, "\\u003c")
     .replace(/\u2028/g, "\\u2028")
     .replace(/\u2029/g, "\\u2029");
+}
+
+export function buildDevHudChunk(devInfo: Record<string, unknown>): string {
+  const json = escapeScriptJson(JSON.stringify(devInfo));
   return (
     `<script id="__PYLON_DEV__" type="application/json">${json}</script>` +
     `<script>(${pylonDevHud.toString()})();</script>`
@@ -1661,13 +1678,7 @@ export function buildHydrationTail(args: {
     ssrData: args.ssrData,
   };
   if (args.kind) hydrationPayload.kind = args.kind;
-  // Escape `<` (closes a </script> breakout) + U+2028/U+2029 (JSON-valid but
-  // JS statement terminators). Regex form keeps the separators visible in
-  // source rather than as invisible literals.
-  const json = JSON.stringify(hydrationPayload)
-    .replace(/</g, "\\u003c")
-    .replace(/\u2028/g, "\\u2028")
-    .replace(/\u2029/g, "\\u2029");
+  const json = escapeScriptJson(JSON.stringify(hydrationPayload));
   let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
   if (args.manifestRoute) {
     // A cross-origin CDN module (`public_prefix` is an absolute http(s) URL) is
@@ -1677,7 +1688,10 @@ export function buildHydrationTail(args: {
     const co = /^https?:\/\//i.test(args.publicPrefix) ? " crossorigin" : "";
     tail += `<script type="module"${co} src="${args.publicPrefix}${args.manifestRoute.file}"></script>`;
   } else {
-    tail += `<script>console.warn(${JSON.stringify(`[pylon ssr] hydration disabled: ${args.manifestErr}`)})</script>`;
+    // Executable script → the serialized message MUST be script-escaped
+    // (`manifestErr` is server-derived today, but this is the one script sink
+    // that would otherwise skip the `<`-escape every other blob applies).
+    tail += `<script>console.warn(${escapeScriptJson(JSON.stringify(`[pylon ssr] hydration disabled: ${args.manifestErr}`))})</script>`;
   }
   if (isDevMode()) tail += DEV_LIVE_RELOAD_SNIPPET;
   return tail;