@pylonsync/functions 0.3.271 → 0.3.272

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.271",
+  "version": "0.3.272",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -46,4 +46,7 @@ export type {
   AuthMode,
   AuthRequirement,
   FnDefinition,
+  RequireMember,
+  RequireMemberOptions,
+  MemberRow,
 } from "./types";

package/src/member.test.ts

@@ -0,0 +1,96 @@
+// Unit tests for `ctx.requireMember` (the org membership / role gate). The
+// motivating bug class: actions + mutations bypass entity read policies, so a
+// function that trusts an attacker-supplied orgId is an IDOR unless it
+// re-checks membership. These assert the gate rejects non-members + wrong
+// roles, and reads the right entity/fields.
+import { describe, expect, test } from "bun:test";
+import { makeRequireMember } from "./member";
+
+// A spy `read` that records its (entity, filter) and returns canned rows.
+function spyRead(rows: any[]) {
+  const calls: Array<{ entity: string; filter: Record<string, unknown> }> = [];
+  const read = async (entity: string, filter: Record<string, unknown>) => {
+    calls.push({ entity, filter });
+    return rows;
+  };
+  return { read, calls };
+}
+
+async function codeOf(fn: () => Promise<unknown>): Promise<string | undefined> {
+  try {
+    await fn();
+    return undefined;
+  } catch (e: any) {
+    return e?.code;
+  }
+}
+
+describe("ctx.requireMember", () => {
+  test("UNAUTHENTICATED when there is no signed-in user", async () => {
+    const { read, calls } = spyRead([{ role: "owner" }]);
+    const requireMember = makeRequireMember(null, read);
+    expect(await codeOf(() => requireMember("org_1"))).toBe("UNAUTHENTICATED");
+    // Must short-circuit BEFORE touching the database.
+    expect(calls).toEqual([]);
+  });
+
+  test("MISSING_ORG when orgId is empty", async () => {
+    const { read } = spyRead([{ role: "owner" }]);
+    const requireMember = makeRequireMember("u1", read);
+    expect(await codeOf(() => requireMember(""))).toBe("MISSING_ORG");
+  });
+
+  test("FORBIDDEN when the caller is not a member (no row)", async () => {
+    const { read } = spyRead([]);
+    const requireMember = makeRequireMember("u1", read);
+    expect(await codeOf(() => requireMember("org_1"))).toBe("FORBIDDEN");
+  });
+
+  test("returns the membership row for any member when no role is required", async () => {
+    const row = { id: "m1", role: "member", userId: "u1", orgId: "org_1" };
+    const { read, calls } = spyRead([row]);
+    const requireMember = makeRequireMember("u1", read);
+    expect(await requireMember("org_1")).toEqual(row);
+    // Reads the conventional OrgMember entity keyed on (orgId, userId).
+    expect(calls).toEqual([
+      { entity: "OrgMember", filter: { orgId: "org_1", userId: "u1" } },
+    ]);
+  });
+
+  test("role gate: FORBIDDEN when the member's role isn't allowed", async () => {
+    const { read } = spyRead([{ role: "member" }]);
+    const requireMember = makeRequireMember("u1", read);
+    expect(
+      await codeOf(() => requireMember("org_1", { role: ["owner", "admin"] })),
+    ).toBe("FORBIDDEN");
+  });
+
+  test("role gate: passes when the member's role IS allowed (string or array)", async () => {
+    const owner = { id: "m1", role: "owner" };
+    expect(
+      await makeRequireMember("u1", spyRead([owner]).read)("org_1", {
+        role: "owner",
+      }),
+    ).toEqual(owner);
+    expect(
+      await makeRequireMember("u1", spyRead([owner]).read)("org_1", {
+        role: ["owner", "admin"],
+      }),
+    ).toEqual(owner);
+  });
+
+  test("honors a custom membership entity + field names", async () => {
+    const { read, calls } = spyRead([{ tier: "admin" }]);
+    const requireMember = makeRequireMember("u1", read);
+    await requireMember("team_9", {
+      entity: "TeamMember",
+      orgField: "teamId",
+      userField: "memberId",
+      roleField: "tier",
+      role: "admin",
+    });
+    expect(calls).toEqual([
+      { entity: "TeamMember", filter: { teamId: "team_9", memberId: "u1" } },
+    ]);
+  });
+});

package/src/member.ts

@@ -0,0 +1,47 @@
+// `ctx.requireMember` — the org membership / role authorization gate.
+//
+// Pure + dependency-injected so it's unit-testable and works across all three
+// ctx types: query/mutation read membership via `ctx.db.query`, actions (which
+// have no `ctx.db`) via `ctx.runQuery` to the built-in `__pylonMemberLookup`.
+// runtime.ts wires the appropriate `read` per ctx; member.test.ts drives this
+// directly.
+
+import type { MemberRow, RequireMember } from "./types";
+
+/**
+ * Build `ctx.requireMember(orgId, opts)` bound to a membership `read`. Errors
+ * carry `.code` (UNAUTHENTICATED / MISSING_ORG / FORBIDDEN) the same way
+ * `ctx.error` does — self-contained so it also works on the query ctx, which
+ * has no `ctx.error`.
+ */
+export function makeRequireMember(
+  userId: string | null | undefined,
+  read: (entity: string, filter: Record<string, unknown>) => Promise<any[]>,
+): RequireMember {
+  const fail = (code: string, message: string): never => {
+    const e = new Error(message);
+    (e as any).code = code;
+    throw e;
+  };
+  return async (orgId, opts) => {
+    if (!userId) fail("UNAUTHENTICATED", "log in first");
+    if (!orgId) fail("MISSING_ORG", "orgId is required");
+    const entity = opts?.entity ?? "OrgMember";
+    const orgField = opts?.orgField ?? "orgId";
+    const userField = opts?.userField ?? "userId";
+    const roleField = opts?.roleField ?? "role";
+    const rows = await read(entity, {
+      [orgField]: orgId,
+      [userField]: userId as string,
+    });
+    const row = rows && rows[0];
+    if (!row) fail("FORBIDDEN", "you are not a member of this organization");
+    if (opts?.role !== undefined) {
+      const allowed = Array.isArray(opts.role) ? opts.role : [opts.role];
+      if (!allowed.includes((row as any)[roleField])) {
+        fail("FORBIDDEN", `requires one of: ${allowed.join(", ")}`);
+      }
+    }
+    return row as MemberRow;
+  };
+}

package/src/runtime.ts

@@ -31,6 +31,7 @@ import type {
   FnDefinition,
   AuthInfo,
 } from "./types";
+import { makeRequireMember } from "./member";
 import { validateArgs } from "./validators";
 import { readdirSync } from "fs";
 import { join, basename } from "path";
@@ -741,6 +742,15 @@ function buildActionCtx(
       (err as any).code = code;
       return err;
     },
+    // Actions have no ctx.db; read membership via the built-in internal query.
+    requireMember: makeRequireMember(auth.userId, (entity, filter) =>
+      rpc(callId, {
+        type: "run_fn",
+        fn_name: "__pylonMemberLookup",
+        fn_type: "query",
+        args: { entity, filter },
+      }) as Promise<any[]>,
+    ),
     request: normalizedRequest,
   };
 }
@@ -751,6 +761,19 @@ function buildActionCtx(
 
 const registry = new Map<string, FnDefinition>();
 
+// Built-in internal query backing `ctx.requireMember` on ACTION ctx — actions
+// have no `ctx.db`, so they read membership via `runQuery` to this. Registered
+// before app fns load (so the host sees it in the registration list and an
+// action's runQuery dispatches back here); app fns load by filename basename so
+// they can't collide with this reserved name. The read is policy-gated like any
+// ctx.db read, which is fine: a member can always read their own membership row.
+registry.set("__pylonMemberLookup", {
+  type: "query",
+  internal: true,
+  handler: async (ctx: any, args: any) =>
+    ctx.db.query(args.entity, { ...(args.filter ?? {}), $limit: 1 }),
+} as FnDefinition);
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -845,15 +868,25 @@ async function handleCall(msg: CallMessage): Promise<void> {
 
   let ctx: QueryCtx | MutationCtx | ActionCtx;
   switch (def.type) {
-    case "query":
+    case "query": {
       // ctx.llm is intentionally absent on queries — reactive
       // re-runs would re-bill the LLM call on every dep change.
       // Move LLM calls into actions / mutations.
-      ctx = { db: buildDbReader(msg.call_id), auth, env };
+      const reader = buildDbReader(msg.call_id);
+      ctx = {
+        db: reader,
+        auth,
+        env,
+        requireMember: makeRequireMember(auth.userId, (entity, filter) =>
+          reader.query(entity, { ...filter, $limit: 1 }),
+        ),
+      };
       break;
-    case "mutation":
+    }
+    case "mutation": {
+      const writer = buildDbWriter(msg.call_id);
       ctx = {
-        db: buildDbWriter(msg.call_id),
+        db: writer,
         auth,
         stream,
         scheduler,
@@ -865,8 +898,12 @@ async function handleCall(msg: CallMessage): Promise<void> {
           (err as any).code = code;
           return err;
         },
+        requireMember: makeRequireMember(auth.userId, (entity, filter) =>
+          writer.query(entity, { ...filter, $limit: 1 }),
+        ),
       };
       break;
+    }
     case "action":
       ctx = buildActionCtx(
         msg.call_id,

package/src/ssr-client-boundary.ts

@@ -0,0 +1,251 @@
+// SSR client-runtime not-found / error boundary.
+//
+// Extracted from `CLIENT_RUNTIME_SOURCE` in ssr-client-bundler.ts so its
+// RENDER behavior is testable with a real React renderer — the inline copy
+// was a string literal, so nothing could render it, and two real regressions
+// (a client-thrown notFound() blanking the page, then rendering with the
+// wrong props and redirecting to /login) shipped because unit/build tests
+// couldn't reach render-time behavior.
+//
+// The bundler writes this module's SOURCE next to the generated client
+// runtime (as `.pylon/client-boundary.ts`) and the runtime imports
+// `createPylonBoundary` from "./client-boundary", wiring its own internals
+// (loadManifest / loadRouteEntry / navigate / buildTree / the active page
+// props) in as deps. ssr-client-boundary.test.ts imports the same factory and
+// drives it directly. ONE source of truth, no inline drift.
+//
+// Browser-safe by construction: imports ONLY "react" and touches NO DOM
+// globals — every browser capability (the manifest, navigation, the current
+// href) arrives through injected deps. So it bundles cleanly into the client
+// chunk AND typechecks without a DOM lib.
+
+import { Component, createElement, useEffect, useState } from "react";
+
+/**
+ * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
+ * for a route by walking its component path up to the app root, returning the
+ * first manifest route key that exists. Nearest ancestor wins — the same model
+ * the server's `findBoundary` uses, but driven off the client build manifest's
+ * route keys so the client runtime needs no extra server round-trip.
+ *
+ * `component` is a cwd-relative path with "/" separators and no extension
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
+ * `Object.keys(manifest.routes)`.
+ */
+export function nearestBoundaryComponent(
+  component: string,
+  fileName: "not-found" | "error",
+  routeKeys: Iterable<string>,
+): string | null {
+  const keys = routeKeys instanceof Set ? routeKeys : new Set(routeKeys);
+  let dir = String(component);
+  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
+  while (dir) {
+    const key = `${dir}/${fileName}`;
+    if (keys.has(key)) return key;
+    const slash = dir.lastIndexOf("/");
+    dir = slash >= 0 ? dir.slice(0, slash) : "";
+  }
+  return null;
+}
+
+/** Runtime internals the boundary needs, injected so the module stays
+ *  browser-safe AND unit-testable. */
+export interface BoundaryDeps {
+  /** Resolve the client build manifest (`{ routes: {...} }`). */
+  loadManifest: () => Promise<{ routes?: Record<string, unknown> } | null>;
+  /** Dynamically load a route entry → its Page + Layout chain. */
+  loadRouteEntry: (component: string) => Promise<{ Page: any; Layouts: any[] }>;
+  /** Client-side navigation — used by an error boundary's reset(). */
+  navigate: (href: string, opts?: { replace?: boolean }) => void;
+  /** Wrap a Page in its Layout chain with props (the runtime's buildTree). */
+  buildTree: (Page: any, Layouts: any[], props: any) => any;
+  /** The props the active page was rendered with (auth, serverData, …). */
+  getPageProps: () => any;
+  /** Current same-origin href, for an error boundary's reset() re-navigation. */
+  getResetHref: () => string;
+}
+
+/**
+ * Build the client error / not-found boundary against the runtime's internals.
+ * Returns `withBoundary(tree, component, navEpoch)` — the transparent root
+ * wrapper the runtime puts around every page — plus `PylonBoundary` for tests.
+ *
+ * Behavior: a `notFound()` (digest "PYLON_NOT_FOUND") or any error thrown
+ * during a descendant's render is caught; the nearest not-found.tsx / error.tsx
+ * for the active route is resolved from the manifest, loaded, and rendered in
+ * its own layout chain WITH the page's props (so an auth-guarding layout sees
+ * the real auth and doesn't redirect away). Resets on navigation via a changing
+ * `navEpoch` prop — not a key — so layouts keep their state across nav.
+ */
+export function createPylonBoundary(deps: BoundaryDeps) {
+  const {
+    loadManifest,
+    loadRouteEntry,
+    navigate,
+    buildTree,
+    getPageProps,
+    getResetHref,
+  } = deps;
+
+  async function resolveBoundaryComponent(
+    component: string,
+    fileName: "not-found" | "error",
+  ): Promise<string | null> {
+    const manifest = await loadManifest();
+    if (!manifest || !manifest.routes || !component) return null;
+    return nearestBoundaryComponent(
+      component,
+      fileName,
+      Object.keys(manifest.routes),
+    );
+  }
+
+  // Last-resort body when the app ships no not-found.tsx / error.tsx anywhere.
+  // Renders a full <html> document so it can replace the document root cleanly
+  // (the normal path renders the app's boundary wrapped in the root layout,
+  // which also owns <html>).
+  function DefaultBoundary(props: any) {
+    const isNF = props.kind === "not-found";
+    return createElement(
+      "html",
+      { lang: "en" },
+      createElement(
+        "head",
+        null,
+        createElement("meta", { charSet: "utf-8" }),
+        createElement(
+          "title",
+          null,
+          isNF ? "404 — Not found" : "Something went wrong",
+        ),
+      ),
+      createElement(
+        "body",
+        {
+          style: {
+            margin: 0,
+            minHeight: "100vh",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            fontFamily: "system-ui, -apple-system, sans-serif",
+          },
+        },
+        createElement(
+          "div",
+          { style: { textAlign: "center", padding: "2rem" } },
+          createElement(
+            "h1",
+            { style: { fontSize: "1.375rem", margin: "0 0 0.5rem" } },
+            isNF ? "404 — Not found" : "Something went wrong",
+          ),
+          createElement(
+            "p",
+            { style: { color: "#666", margin: "0 0 1.25rem" } },
+            isNF
+              ? "This page doesn't exist or was moved."
+              : "An unexpected error occurred.",
+          ),
+          createElement(
+            "a",
+            { href: "/", style: { color: "#0969da", textDecoration: "none" } },
+            "← Go home",
+          ),
+        ),
+      ),
+    );
+  }
+
+  // Lazily resolves + renders the boundary component in its own layout chain.
+  // Renders nothing for the brief moment before the (usually already-cached)
+  // entry loads, then the styled boundary — far better than a permanent blank.
+  function BoundaryView(props: any) {
+    const { component, kind, error, reset } = props;
+    const [resolved, setResolved] = useState<any>(null);
+    useEffect(() => {
+      let cancelled = false;
+      const fileName = kind === "not-found" ? "not-found" : "error";
+      (async () => {
+        const comp = await resolveBoundaryComponent(component, fileName);
+        if (cancelled) return;
+        if (!comp) {
+          setResolved({ missing: true });
+          return;
+        }
+        try {
+          const entry = await loadRouteEntry(comp);
+          if (!cancelled) setResolved({ entry });
+        } catch {
+          if (!cancelled) setResolved({ missing: true });
+        }
+      })();
+      return () => {
+        cancelled = true;
+      };
+    }, [component, kind]);
+    if (!resolved) return null;
+    if (resolved.missing) return createElement(DefaultBoundary, { kind });
+    // Reuse the page's props (auth, serverData, params, url, …) so the
+    // boundary's layout chain renders with the SAME context the page had — an
+    // auth-guarding layout that reads props.auth must not see undefined and
+    // redirect away. error.tsx gets the SAFE error projection (message + digest
+    // only, never a raw Error/stack — matches the server boundary's #270).
+    const bProps: any = { ...getPageProps(), reset };
+    if (kind === "error" && error) {
+      bProps.error = {
+        message: String((error && error.message) || error),
+        digest: error && error.digest,
+      };
+    }
+    return buildTree(resolved.entry.Page, resolved.entry.Layouts, bProps);
+  }
+
+  class PylonBoundary extends Component<any, { err: any }> {
+    constructor(p: any) {
+      super(p);
+      this.state = { err: null };
+    }
+    static getDerivedStateFromError(err: any) {
+      return { err };
+    }
+    componentDidUpdate(prev: any) {
+      // A navigation bumps navEpoch — clear a prior error so the freshly
+      // rendered children (the new page) show instead of the stale boundary.
+      if (prev.navEpoch !== this.props.navEpoch && this.state.err) {
+        this.setState({ err: null });
+      }
+    }
+    componentDidCatch(err: any) {
+      // notFound() is expected control flow, not a crash — keep it quiet.
+      // Genuine errors stay loud.
+      if (!(err && err.digest === "PYLON_NOT_FOUND")) {
+        // eslint-disable-next-line no-console
+        console.error("[pylon ssr] render error caught by boundary:", err);
+      }
+    }
+    render() {
+      const err = this.state.err;
+      if (!err) return this.props.children;
+      const kind = err.digest === "PYLON_NOT_FOUND" ? "not-found" : "error";
+      const self = this;
+      return createElement(BoundaryView, {
+        component: this.props.component,
+        kind,
+        error: err,
+        reset() {
+          self.setState({ err: null });
+          navigate(getResetHref(), { replace: true });
+        },
+      });
+    }
+  }
+
+  // Wrap a page tree in the root boundary. navEpoch (a prop, not a key) lets the
+  // boundary clear its error on navigation without remounting the layouts.
+  function withBoundary(tree: any, component: string, navEpoch: number) {
+    return createElement(PylonBoundary, { navEpoch, component }, tree);
+  }
+
+  return { withBoundary, PylonBoundary };
+}

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

@@ -23,9 +23,9 @@ import * as os from "node:os";
 
 import {
   buildClientBundle,
-  nearestBoundaryComponent,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
+import { nearestBoundaryComponent } from "./ssr-client-boundary";
 
 // State that needs cleanup between tests.
 let originalCwd: string | null = null;

package/src/ssr-client-bundler.ts

@@ -177,39 +177,6 @@ function discoverRoutes(
   }));
 }
 
-/**
- * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
- * for a route by walking its component path up to the app root, returning the
- * first manifest route key that exists. Nearest ancestor wins — the same model
- * the server's `findBoundary` uses, but driven off the client build manifest's
- * route keys so the client runtime needs no extra server round-trip.
- *
- * Exported as the CANONICAL spec for the client error boundary: the runtime in
- * `CLIENT_RUNTIME_SOURCE` inlines this exact walk (it can't import across the
- * bundle), and `ssr-client-bundler.test.ts` exercises this function so a
- * regression in the algorithm is caught here.
- *
- * `component` is a cwd-relative path with "/" separators and no extension
- * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
- * `Object.keys(manifest.routes)`.
- */
-export function nearestBoundaryComponent(
-  component: string,
-  fileName: "not-found" | "error",
-  routeKeys: Iterable<string>,
-): string | null {
-  const keys = routeKeys instanceof Set ? routeKeys : new Set(routeKeys);
-  let dir = String(component);
-  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
-  while (dir) {
-    const key = `${dir}/${fileName}`;
-    if (keys.has(key)) return key;
-    const slash = dir.lastIndexOf("/");
-    dir = slash >= 0 ? dir.slice(0, slash) : "";
-  }
-  return null;
-}
-
 /**
  * The shared hydration dispatcher + router. ONE module, imported
  * by every per-route entry. Bun's splitter sees N entries reach
@@ -237,8 +204,9 @@ export function nearestBoundaryComponent(
 const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
-import { Component, createElement, useEffect, useState } from "react";
+import { createElement } from "react";
 import { hydrateRoot } from "react-dom/client";
+import { createPylonBoundary } from "./client-boundary";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
@@ -278,166 +246,19 @@ let navEpoch = 0;
 // (for instance) redirect to /login instead of showing the not-found page.
 let currentPageProps = {};
 
-// Walk up the active route's component path to the nearest boundary module
-// (<dir>/not-found or <dir>/error) present in the manifest. Manifest route
-// keys are cwd-relative component paths with "/" separators (e.g.
-// "web/app/dashboard/not-found"), so no platform normalization is needed.
-// MUST stay in lockstep with the exported nearestBoundaryComponent() — that
-// function is the tested spec for this exact walk.
-async function resolveBoundaryComponent(component, fileName) {
-  const manifest = await loadManifest();
-  if (!manifest || !manifest.routes || !component) return null;
-  let dir = String(component);
-  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
-  while (dir) {
-    const key = dir + "/" + fileName;
-    if (manifest.routes[key]) return key;
-    const slash = dir.lastIndexOf("/");
-    dir = slash >= 0 ? dir.slice(0, slash) : "";
-  }
-  return null;
-}
-
-// Last-resort body when the app ships no not-found.tsx / error.tsx anywhere.
-// Renders a full <html> document so it can replace the document root cleanly
-// (the normal path renders the app's boundary wrapped in the root layout,
-// which also owns <html>).
-function DefaultBoundary(props) {
-  const isNF = props.kind === "not-found";
-  return createElement(
-    "html",
-    { lang: "en" },
-    createElement(
-      "head",
-      null,
-      createElement("meta", { charSet: "utf-8" }),
-      createElement("title", null, isNF ? "404 — Not found" : "Something went wrong"),
-    ),
-    createElement(
-      "body",
-      {
-        style: {
-          margin: 0,
-          minHeight: "100vh",
-          display: "flex",
-          alignItems: "center",
-          justifyContent: "center",
-          fontFamily: "system-ui, -apple-system, sans-serif",
-        },
-      },
-      createElement(
-        "div",
-        { style: { textAlign: "center", padding: "2rem" } },
-        createElement(
-          "h1",
-          { style: { fontSize: "1.375rem", margin: "0 0 0.5rem" } },
-          isNF ? "404 — Not found" : "Something went wrong",
-        ),
-        createElement(
-          "p",
-          { style: { color: "#666", margin: "0 0 1.25rem" } },
-          isNF
-            ? "This page doesn't exist or was moved."
-            : "An unexpected error occurred.",
-        ),
-        createElement(
-          "a",
-          { href: "/", style: { color: "#0969da", textDecoration: "none" } },
-          "\\u2190 Go home",
-        ),
-      ),
-    ),
-  );
-}
-
-// Lazily resolves + renders the boundary component in its own layout chain.
-// Renders nothing for the brief moment before the (usually already-cached)
-// entry loads, then the styled boundary — far better than a permanent blank.
-function BoundaryView(props) {
-  const { component, kind, error, reset } = props;
-  const [resolved, setResolved] = useState(null);
-  useEffect(() => {
-    let cancelled = false;
-    const fileName = kind === "not-found" ? "not-found" : "error";
-    (async () => {
-      const comp = await resolveBoundaryComponent(component, fileName);
-      if (cancelled) return;
-      if (!comp) {
-        setResolved({ missing: true });
-        return;
-      }
-      try {
-        const entry = await loadRouteEntry(comp);
-        if (!cancelled) setResolved({ entry });
-      } catch {
-        if (!cancelled) setResolved({ missing: true });
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [component, kind]);
-  if (!resolved) return null;
-  if (resolved.missing) return createElement(DefaultBoundary, { kind });
-  // Reuse the page's props (auth, serverData, params, url, …) so the boundary's
-  // layout chain renders with the SAME context the page had — an auth-guarding
-  // layout that reads props.auth must not see undefined and redirect away. Add
-  // reset (+ the SAFE error projection for error.tsx — message + digest only,
-  // never a raw Error/stack, matching the server boundary's #270 posture).
-  const bProps = { ...currentPageProps, reset };
-  if (kind === "error" && error) {
-    bProps.error = {
-      message: String((error && error.message) || error),
-      digest: error && error.digest,
-    };
-  }
-  return buildTree(resolved.entry.Page, resolved.entry.Layouts, bProps);
-}
-
-class PylonBoundary extends Component {
-  constructor(p) {
-    super(p);
-    this.state = { err: null };
-  }
-  static getDerivedStateFromError(err) {
-    return { err };
-  }
-  componentDidUpdate(prev) {
-    // A navigation bumps navEpoch — clear a prior error so the freshly
-    // rendered children (the new page) show instead of the stale boundary.
-    if (prev.navEpoch !== this.props.navEpoch && this.state.err) {
-      this.setState({ err: null });
-    }
-  }
-  componentDidCatch(err) {
-    // notFound() is expected control flow, not a crash — keep it quiet.
-    // Genuine errors stay loud.
-    if (!(err && err.digest === "PYLON_NOT_FOUND")) {
-      console.error("[pylon ssr] render error caught by boundary:", err);
-    }
-  }
-  render() {
-    const err = this.state.err;
-    if (!err) return this.props.children;
-    const kind = err.digest === "PYLON_NOT_FOUND" ? "not-found" : "error";
-    const self = this;
-    return createElement(BoundaryView, {
-      component: this.props.component,
-      kind,
-      error: err,
-      reset() {
-        self.setState({ err: null });
-        navigate(location.pathname + location.search, { replace: true });
-      },
-    });
-  }
-}
-
-// Wrap a page tree in the root boundary. navEpoch (a prop, not a key) lets the
-// boundary clear its error on navigation without remounting the layouts.
-function withBoundary(tree, component) {
-  return createElement(PylonBoundary, { navEpoch, component }, tree);
-}
+// The not-found / error boundary lives in a real module (./client-boundary,
+// emitted next to this file by the bundler) so its render behavior is
+// unit-testable instead of buried in this string. Wire the runtime's
+// internals in as deps; the returned withBoundary(tree, component, navEpoch)
+// wraps every page tree as the transparent root error boundary.
+const { withBoundary } = createPylonBoundary({
+  loadManifest,
+  loadRouteEntry,
+  navigate,
+  buildTree,
+  getPageProps: () => currentPageProps,
+  getResetHref: () => location.pathname + location.search,
+});
 
 // Deterministic stringify — MUST match stableStringify in ssr-runtime.ts so
 // a serverData call's cache key is identical on server and client.
@@ -641,6 +462,7 @@ export function hydrate(component, Page, Layouts) {
     const tree = withBoundary(
       buildTree(Page, Layouts, currentPageProps),
       data.component,
+      navEpoch,
     );
     activeRoot = hydrateRoot(document, tree);
     installNavHandlers();
@@ -723,6 +545,7 @@ async function navigate(href, opts) {
   const tree = withBoundary(
     buildTree(route.Page, route.Layouts, currentPageProps),
     data.component,
+    navEpoch,
   );
   activeRoot.render(tree);
   const target = url.pathname + url.search;
@@ -1081,6 +904,21 @@ async function _doBuildInner(
     const runtimePath = path.join(stageDir, "client-runtime.ts");
     fs.writeFileSync(runtimePath, CLIENT_RUNTIME_SOURCE, "utf8");
 
+    // Emit the not-found/error boundary as a sibling module the runtime
+    // imports (`./client-boundary`). Its source is this package's real
+    // ssr-client-boundary.ts — ONE source of truth, unit-tested directly,
+    // rather than an inline string in CLIENT_RUNTIME_SOURCE that nothing
+    // could render. Bun pulls it into the shared chunk via the runtime's
+    // static `import { createPylonBoundary } from "./client-boundary"`.
+    fs.writeFileSync(
+      path.join(stageDir, "client-boundary.ts"),
+      fs.readFileSync(
+        path.join(import.meta.dir, "ssr-client-boundary.ts"),
+        "utf8",
+      ),
+      "utf8",
+    );
+
     const entryPaths: string[] = [];
     // entryPath (absolute) → component path (for manifest lookup).
     const entryToComponent = new Map<string, string>();

package/src/ssr-runtime-boundary.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Render integration test for the SSR client not-found / error boundary.
+ *
+ * Covers the two regressions that shipped because unit + build tests can't
+ * reach RENDER-time behavior (they only check pure functions + that the chunk
+ * contains the wiring):
+ *   - 0.3.270: a client-thrown notFound() blanked the whole page (the client
+ *     runtime had no error boundary at all).
+ *   - 0.3.271: the boundary rendered not-found.tsx + its layout chain with a
+ *     MINIMAL props object, so an auth-guarding layout (`if (!auth?.user_id)
+ *     redirect("/login")`) saw no auth and bounced to /login instead of
+ *     showing the not-found page.
+ *
+ * Drives the REAL `createPylonBoundary` with a real React renderer (happy-dom
+ * + react-dom/client). Isolated file because it registers DOM globals.
+ *
+ * NAMING — this file MUST sort AFTER ssr-client-bundler.test.ts (the only test
+ * that runs `Bun.build`). `bun test` runs files in order in one process, and
+ * once react-dom is loaded a later `Bun.build` fails to read `scheduler`
+ * ("Unexpected reading file"). ssr-hydration.test.ts depends on the same
+ * ordering; "ssr-runtime-*" sorts after "ssr-client-bundler". Don't rename to
+ * sort before the bundler test.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import React from "react";
+
+import { createPylonBoundary } from "./ssr-client-boundary";
+
+// --- DOM globals react-dom/client touches; saved + restored per file. --------
+const DOM_GLOBAL_KEYS = [
+  "window",
+  "document",
+  "navigator",
+  "HTMLElement",
+  "Node",
+  "Event",
+  "MutationObserver",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+];
+let savedGlobals: Record<string, any> | null = null;
+
+function registerDom(win: any) {
+  const g = globalThis as any;
+  savedGlobals = {};
+  for (const k of DOM_GLOBAL_KEYS) savedGlobals[k] = g[k];
+  g.window = win;
+  g.document = win.document;
+  g.navigator = win.navigator;
+  g.HTMLElement = win.HTMLElement;
+  g.Node = win.Node;
+  g.Event = win.Event;
+  g.MutationObserver = win.MutationObserver;
+  g.requestAnimationFrame = (cb: any) => setTimeout(() => cb(Date.now()), 0);
+  g.cancelAnimationFrame = (id: any) => clearTimeout(id);
+}
+
+afterEach(() => {
+  if (!savedGlobals) return;
+  const g = globalThis as any;
+  for (const k of DOM_GLOBAL_KEYS) {
+    if (savedGlobals[k] === undefined) delete g[k];
+    else g[k] = savedGlobals[k];
+  }
+  savedGlobals = null;
+});
+
+// A client notFound(): same digest @pylonsync/react's notFound() stamps on the
+// error it throws (NotFoundError.digest === "PYLON_NOT_FOUND").
+class NotFoundError extends Error {
+  readonly digest = "PYLON_NOT_FOUND";
+  constructor() {
+    super("PYLON_NOT_FOUND");
+  }
+}
+
+// The runtime's buildTree: wrap a Page in its Layout chain (root → leaf).
+const buildTree = (Page: any, Layouts: any[], props: any) =>
+  Layouts.reduceRight(
+    (child: any, L: any) => React.createElement(L, props, child),
+    React.createElement(Page, props),
+  );
+
+// Mount a tree into a fresh happy-dom root, flush effects, return innerHTML.
+// console.error is captured because React logs boundary-caught errors + an
+// act() advisory; neither is a failure here.
+async function mount(tree: any): Promise<string> {
+  const win = new Window({ url: "http://localhost/dashboard" });
+  registerDom(win);
+  const container = win.document.createElement("div");
+  win.document.body.appendChild(container);
+  const orig = console.error;
+  console.error = () => {};
+  try {
+    const { createRoot } = await import("react-dom/client");
+    const root = createRoot(container as any);
+    root.render(tree);
+    await new Promise((r) => setTimeout(r, 80));
+    return (container as any).innerHTML as string;
+  } finally {
+    console.error = orig;
+  }
+}
+
+describe("createPylonBoundary (render integration)", () => {
+  test("client-thrown notFound() renders the not-found page WITH the page's props — auth flows through, no /login redirect", async () => {
+    const redirects: string[] = [];
+    // Mirrors app/dashboard/layout.tsx: redirect to /login when no auth.
+    function AuthGuardLayout(props: any) {
+      if (!props.auth?.user_id) {
+        redirects.push("/login");
+        return null;
+      }
+      return props.children;
+    }
+    function NotFound(props: any) {
+      return React.createElement(
+        "div",
+        { "data-nf": "1" },
+        "NOT FOUND user=" + (props.auth?.user_id ?? "none"),
+      );
+    }
+    function ThrowingPage(): any {
+      throw new NotFoundError();
+    }
+
+    const { withBoundary } = createPylonBoundary({
+      loadManifest: async () => ({ routes: { "app/dashboard/not-found": {} } }),
+      loadRouteEntry: async () => ({ Page: NotFound, Layouts: [AuthGuardLayout] }),
+      navigate: () => {},
+      buildTree,
+      getPageProps: () => ({ auth: { user_id: "u1" }, params: {}, url: "/d" }),
+      getResetHref: () => "/d",
+    });
+
+    const html = await mount(
+      withBoundary(buildTree(ThrowingPage, [], {}), "app/dashboard/orgs/[s]/page", 0),
+    );
+
+    // Caught the throw + rendered the not-found page (NOT a blank page):
+    expect(html).toContain("NOT FOUND");
+    // ...with the page's auth in props (the 0.3.271 fix) so the auth-guard
+    // layout rendered its children instead of redirecting to /login:
+    expect(html).toContain("user=u1");
+    expect(redirects).toEqual([]);
+  });
+
+  test("negative control: with NO auth in the page props the auth-guard layout redirects — proves the test detects the missing-props bug class", async () => {
+    const redirects: string[] = [];
+    function AuthGuardLayout(props: any) {
+      if (!props.auth?.user_id) {
+        redirects.push("/login");
+        return null;
+      }
+      return props.children;
+    }
+    function NotFound() {
+      return React.createElement("div", null, "NOT FOUND");
+    }
+    function ThrowingPage(): any {
+      throw new NotFoundError();
+    }
+
+    const { withBoundary } = createPylonBoundary({
+      loadManifest: async () => ({ routes: { "app/dashboard/not-found": {} } }),
+      loadRouteEntry: async () => ({ Page: NotFound, Layouts: [AuthGuardLayout] }),
+      navigate: () => {},
+      buildTree,
+      // No auth — what the 0.3.270 boundary's minimal props object produced.
+      getPageProps: () => ({}),
+      getResetHref: () => "/d",
+    });
+
+    const html = await mount(
+      withBoundary(buildTree(ThrowingPage, [], {}), "app/dashboard/x/page", 0),
+    );
+    expect(html).not.toContain("NOT FOUND");
+    expect(redirects).toContain("/login");
+  });
+
+  test("a non-notFound error resolves the error boundary, with a SAFE error projection (message + digest only)", async () => {
+    let seenError: any = null;
+    function ErrorPage(props: any) {
+      seenError = props.error;
+      return React.createElement("div", null, "ERR:" + (props.error?.message ?? ""));
+    }
+    function Boom(): any {
+      const e: any = new Error("kaboom");
+      e.stack = "secret-stack-do-not-leak";
+      throw e;
+    }
+    const { withBoundary } = createPylonBoundary({
+      loadManifest: async () => ({ routes: { "app/error": {} } }),
+      loadRouteEntry: async () => ({ Page: ErrorPage, Layouts: [] }),
+      navigate: () => {},
+      buildTree,
+      getPageProps: () => ({ auth: { user_id: "u1" } }),
+      getResetHref: () => "/d",
+    });
+    const html = await mount(withBoundary(buildTree(Boom, [], {}), "app/x/page", 0));
+    expect(html).toContain("ERR:kaboom");
+    // The raw Error (and its stack) must NEVER reach the boundary props.
+    expect(seenError).toEqual({ message: "kaboom", digest: undefined });
+    expect(JSON.stringify(seenError)).not.toContain("secret-stack");
+  });
+
+  test("no boundary module in the manifest → styled default 404, never a blank page", async () => {
+    function ThrowingPage(): any {
+      throw new NotFoundError();
+    }
+    const { withBoundary } = createPylonBoundary({
+      loadManifest: async () => ({ routes: { "app/page": {} } }), // no not-found anywhere
+      loadRouteEntry: async () => {
+        throw new Error("should not be called");
+      },
+      buildTree,
+      navigate: () => {},
+      getPageProps: () => ({ auth: { user_id: "u1" } }),
+      getResetHref: () => "/d",
+    });
+    const html = await mount(withBoundary(buildTree(ThrowingPage, [], {}), "app/x/page", 0));
+    expect(html).toContain("404 — Not found");
+  });
+});

package/src/types.ts

@@ -467,6 +467,59 @@ export interface Connections {
 // Context objects — what handlers receive
 // ---------------------------------------------------------------------------
 
+/** Options for `ctx.requireMember()`. */
+export interface RequireMemberOptions {
+  /**
+   * Allowed role(s). The caller's membership role must be one of these.
+   * Omit to require ANY membership regardless of role.
+   */
+  role?: string | string[];
+  /**
+   * The membership entity to check. Default `"OrgMember"` — the same entity
+   * the framework's org/tenant machinery uses. Override for a custom model.
+   */
+  entity?: string;
+  /** Field on the membership entity holding the org/tenant id. Default `"orgId"`. */
+  orgField?: string;
+  /** Field holding the user id. Default `"userId"`. */
+  userField?: string;
+  /** Field holding the role. Default `"role"`. */
+  roleField?: string;
+}
+
+/** The membership row returned by `ctx.requireMember()`. */
+export type MemberRow = Record<string, unknown> & { role?: string };
+
+/**
+ * Assert the caller is a member of `orgId` (optionally with one of `role`),
+ * returning the membership row. Throws a typed error otherwise:
+ * `UNAUTHENTICATED` (no signed-in user), `MISSING_ORG` (no orgId), or
+ * `FORBIDDEN` (not a member / wrong role).
+ *
+ * This is the authoritative authorization gate for org-scoped writes —
+ * actions + mutations BYPASS entity read policies, so a function that trusts
+ * an attacker-supplied `orgId`/`projectId` is an IDOR unless it re-checks
+ * membership. `requireMember` makes the safe path the default path.
+ *
+ * ```ts
+ * export default mutation({
+ *   args: { orgId: v.id("Organization"), name: v.string() },
+ *   async handler(ctx, args) {
+ *     await ctx.requireMember(args.orgId, { role: ["owner", "admin"] });
+ *     // …safe to mutate org-scoped data now…
+ *   },
+ * });
+ * ```
+ *
+ * The membership entity must let the caller read their OWN membership row
+ * (the standard `auth.userId == data.userId` read policy) — the check runs
+ * with the caller's identity.
+ */
+export type RequireMember = (
+  orgId: string,
+  opts?: RequireMemberOptions,
+) => Promise<MemberRow>;
+
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -481,6 +534,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   auth: AuthInfo<R>;
   /** Environment variables / secrets. */
   env: Record<string, string>;
+  /** Assert org membership (optionally a role) — see {@link RequireMember}. */
+  requireMember: RequireMember;
 }
 
 /** Context for mutation handlers (read + write, transactional). */
@@ -497,6 +552,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   connections: Connections;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
+  /** Assert org membership (optionally a role) — see {@link RequireMember}. */
+  requireMember: RequireMember;
 }
 
 /** Context for action handlers (external I/O, non-transactional). */
@@ -524,6 +581,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   ): Promise<T>;
   /** Create a typed error. */
   error(code: string, message: string): Error;
+  /** Assert org membership (optionally a role) — see {@link RequireMember}. */
+  requireMember: RequireMember;
   /**
    * HTTP request metadata — present only when the action was invoked via
    * a `defineRoute` HTTP binding. Missing when the action is called from