@nifrajs/web 2.1.0 → 2.3.0

package/dist/draft.js

@@ -1,8 +1,8 @@
 /**
- * Draft / preview mode — let an editor see unpublished content by flipping a signed cookie that
+ * Draft / preview mode - let an editor see unpublished content by flipping a signed cookie that
  * loaders read (`ctx.draft`) and ISR bypasses (fresh render, never cached). The cookie is **HMAC-signed**
- * (so a visitor can't forge it) and **HttpOnly** (JS can't read it). You gate `enableDraft` yourself —
- * behind an editor login or a `?token=` check — exactly like Next's `draftMode().enable()`.
+ * (so a visitor can't forge it) and **HttpOnly** (JS can't read it). You gate `enableDraft` yourself -
+ * behind an editor login or a `?token=` check - exactly like Next's `draftMode().enable()`.
  *
  *   // a route you've protected (e.g. checked ?token= against a secret):
  *   app.get("/api/draft", async (c) => {
@@ -14,28 +14,41 @@
  *   createWebApp({ ..., draftSecret: env.DRAFT_SECRET })   // → loaders get ctx.draft
  *   withISR(app, { ..., draftSecret: env.DRAFT_SECRET })   // → editors bypass the cache
  */
-import { parseCookies, signValue, unsignValue } from "@nifrajs/core/server";
+import { parseCookies, serializeCookie, signValue, unsignValue, } from "@nifrajs/core/server";
+import { timingSafeEqual } from "./internal/timing-safe-equal.js";
 /** The cookie name nifra uses for draft/preview mode. */
 export const DRAFT_COOKIE = "__nifra_draft";
-// The signed cookie's payload is a fixed marker — a *valid signature* (not the value) is the signal
+// The signed cookie's payload is a fixed marker - a *valid signature* (not the value) is the signal
 // that the server issued this via enableDraft(). Nothing secret is stored in it.
 const DRAFT_MARKER = "1";
 /**
  * Turn draft mode **on** for this client by setting a signed, HttpOnly `__nifra_draft` cookie. Call it
- * from a route you've already authorized. `secret` signs the cookie — pass the SAME secret to
+ * from a route you've already authorized. `secret` signs the cookie - pass the SAME secret to
  * `createWebApp({ draftSecret })` and `withISR({ draftSecret })` so the framework can verify it.
  */
 export async function enableDraft(c, secret, options = {}) {
     const signed = await signValue(DRAFT_MARKER, secret);
+    c.set.cookie(DRAFT_COOKIE, signed, draftCookieOptions(options));
+}
+/**
+ * The attributes draft mode always sets. Shared by {@link enableDraft} (which writes through
+ * `c.set.cookie`) and {@link previewEndpoint} (which serializes its own `Set-Cookie`), so the two
+ * can't drift on the properties that make the cookie unforgeable and unreadable from JS.
+ *
+ * `secure` is resolved here rather than left to the caller: `serializeCookie` is pure and applies
+ * **no** security defaults, so the `previewEndpoint` path would silently emit a cookie without
+ * `Secure` - over plain HTTP that hands the draft cookie to any network observer. Passing it
+ * explicitly makes both paths identical instead of one inheriting a default the other never sees.
+ */
+function draftCookieOptions(options) {
     // Explicit security attributes (don't lean on the context default): signed + HttpOnly + SameSite=Lax.
-    const cookieOptions = {
+    return {
         httpOnly: true,
         sameSite: "lax",
         path: options.path ?? "/",
         maxAge: options.maxAgeSeconds ?? 3600,
-        ...(options.secure === undefined ? {} : { secure: options.secure }),
+        secure: options.secure ?? true,
     };
-    c.set.cookie(DRAFT_COOKIE, signed, cookieOptions);
 }
 /** Turn draft mode **off**: clear the `__nifra_draft` cookie. Match the `path` used in `enableDraft`. */
 export function disableDraft(c, options = {}) {
@@ -52,4 +65,74 @@ export async function isDraftEnabled(request, secret) {
         return false;
     return (await unsignValue(cookie, secret)) !== null;
 }
+/**
+ * Accept only a same-site destination, or `null`.
+ *
+ * A redirect target that arrives in the query string is attacker-controlled: anyone can mint a link
+ * to your own preview route and choose where the editor lands. "Starts with `/`" is the check people
+ * write and it is not enough - `//evil.com` is a protocol-relative URL and `/\evil.com` is normalized
+ * to one by browsers, so both start with a slash and navigate off-site. Control characters are refused
+ * as well, since a newline in a `Location` header splits the response.
+ */
+function safeRedirectPath(value) {
+    if (!value.startsWith("/"))
+        return null;
+    if (value.startsWith("//") || value.startsWith("/\\"))
+        return null;
+    // Escaped rather than written literally: raw control bytes in source make the file read as binary
+    // to ordinary tooling (grep, diffs) and are one reformat away from being silently mangled.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point - this IS the check that refuses them.
+    if (/[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    return value;
+}
+/**
+ * A **preview / draft-mode entry point** - a `fetch` handler that checks a preview token, turns draft
+ * mode on, and redirects the editor to the page they wanted. `GET` with `?token=<secret>&to=/some/path`;
+ * mount it on a nifra route, e.g. `app.get("/api/preview", (c) => handler(c.req))`.
+ *
+ * This is the link-borne sibling of `revalidateEndpoint`. It exists because the alternative - telling
+ * you to gate the route yourself - means hand-rolling two checks that are easy to get subtly wrong and
+ * that fail silently when you do: the token compare must not exit early on the first wrong character,
+ * and the `?to=` destination must not be allowed to point off-site. Both are handled here.
+ *
+ * A CMS "Preview" button is a plain link, so the token has to ride the query string. That has a cost
+ * no endpoint can remove - the secret lands in server logs, the `Referer` header, and browser history.
+ * Use a preview token minted for that purpose, rotate it, and never reuse a token that grants anything
+ * beyond draft mode.
+ *
+ * Wrong or missing token → `401`; an off-site `to` → `400`; success → `302` with the signed cookie and
+ * `Cache-Control: no-store`, so no shared cache can ever replay one editor's draft session to a visitor.
+ */
+export function previewEndpoint(options) {
+    const tokenParam = options.tokenParam ?? "token";
+    const redirectParam = options.redirectParam ?? "to";
+    const fallbackPath = options.fallbackPath ?? "/";
+    // Fail at construction, not on the request that happens to omit `?to=`: a misconfigured fallback is
+    // a deploy-time mistake and should surface at boot rather than as a rare 400 in production.
+    if (safeRedirectPath(fallbackPath) === null) {
+        throw new Error(`[nifra] previewEndpoint fallbackPath must be a site-relative path, got ${JSON.stringify(fallbackPath)}`);
+    }
+    const cookieOptions = draftCookieOptions(options.cookie ?? {});
+    return async (request) => {
+        const url = new URL(request.url);
+        if (!timingSafeEqual(url.searchParams.get(tokenParam) ?? "", options.secret)) {
+            return Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
+        }
+        const requested = url.searchParams.get(redirectParam);
+        const destination = requested === null ? fallbackPath : safeRedirectPath(requested);
+        if (destination === null) {
+            return Response.json({ ok: false, error: "invalid_redirect" }, { status: 400 });
+        }
+        const signed = await signValue(DRAFT_MARKER, options.draftSecret);
+        return new Response(null, {
+            status: 302,
+            headers: {
+                location: destination,
+                "set-cookie": serializeCookie(DRAFT_COOKIE, signed, cookieOptions),
+                "cache-control": "no-store",
+            },
+        });
+    };
+}
 //# sourceMappingURL=draft.js.map

package/dist/draft.js.map

@@ -1 +1 @@
-{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAsB,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAE/F,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAA;AAE3C,oGAAoG;AACpG,iFAAiF;AACjF,MAAM,YAAY,GAAG,GAAG,CAAA;AAmBxB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,CAAwC,EACxC,MAAc,EACd,UAA8B,EAAE;IAEhC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;IACpD,sGAAsG;IACtG,MAAM,aAAa,GAAkB;QACnC,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG;QACzB,MAAM,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI;QACrC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KACpE,CAAA;IACD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC,CAAA;AACnD,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,YAAY,CAC1B,CAAwC,EACxC,UAAsC,EAAE;IAExC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,MAAc;IACnE,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAA;IACxE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACtC,OAAO,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,CAAA;AACrD,CAAC"}
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"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"}

package/dist/fn-state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `@nifrajs/web/fn-state` - the pending/error state around a server-function call.
+ *
+ * Calling a server function needs no binding: the client stub is `(input) => Promise<Output>`, and a
+ * click handler can await it. What a component usually wants on top is whether a call is in flight,
+ * what came back, and what went wrong - which is state, and state is the part every framework spells
+ * differently.
+ *
+ * So the state machine lives here, framework-agnostic, and each adapter contributes only its
+ * subscription primitive. Five copies of "is it pending" would drift, and the drift would be five
+ * subtly different answers to the same question.
+ *
+ * ## Two behaviours worth stating
+ *
+ * **The last call wins.** Concurrent calls are not queued or cancelled; a response that is no longer
+ * the newest is discarded rather than written. Without that, a slow first call landing after a fast
+ * second one would overwrite fresh data with stale - the classic out-of-order bug, and one that only
+ * appears under load, which is to say in production.
+ *
+ * **`call` still rejects.** The error is recorded for rendering AND the promise rejects, so `await`
+ * behaves the way `await` should and a caller who wants to branch can. A caller who only renders from
+ * state should attach a `.catch(() => {})`, the same as `useFetcher`'s `submit`.
+ */
+/** What a component renders from. */
+export interface ServerFnState<Output> {
+    /** A call is in flight. */
+    readonly pending: boolean;
+    /** The most recent successful result, kept across a later pending call so the UI need not flicker. */
+    readonly data: Output | undefined;
+    /** The most recent failure, cleared when a call succeeds. */
+    readonly error: Error | undefined;
+}
+/** A subscribable call site. One per component instance, created by the framework binding. */
+export interface ServerFnStore<Input, Output> {
+    /** Register a listener; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The current state. The SAME object is returned until something changes, because
+     * `useSyncExternalStore` and its equivalents compare by reference - a fresh object each call is an
+     * infinite render loop.
+     */
+    snapshot(): ServerFnState<Output>;
+    /** Invoke the server function. Records state, and rejects on failure. */
+    call(input: Input): Promise<Output>;
+    /** Back to idle, discarding data and error. */
+    reset(): void;
+}
+/** The idle state, shared so a server render and the first client render agree by reference. */
+export declare function idleServerFnState<Output>(): ServerFnState<Output>;
+/**
+ * Wrap a server function (or any async function) in a subscribable pending/error state.
+ *
+ * Framework-free by design: the adapters call this and subscribe with their own primitive.
+ */
+export declare function createServerFnStore<Input, Output>(fn: (input: Input) => Promise<Output> | Output): ServerFnStore<Input, Output>;
+//# sourceMappingURL=fn-state.d.ts.map

package/dist/fn-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn-state.d.ts","sourceRoot":"","sources":["../src/fn-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qCAAqC;AACrC,MAAM,WAAW,aAAa,CAAC,MAAM;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sGAAsG;IACtG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;CAClC;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,MAAM;IAC1C,oDAAoD;IACpD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C;;;;OAIG;IACH,QAAQ,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IACjC,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnC,+CAA+C;IAC/C,KAAK,IAAI,IAAI,CAAA;CACd;AAID,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,KAAK,aAAa,CAAC,MAAM,CAAC,CAEjE;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAC/C,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,GAC7C,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAuC9B"}

package/dist/fn-state.js

@@ -0,0 +1,77 @@
+/**
+ * `@nifrajs/web/fn-state` - the pending/error state around a server-function call.
+ *
+ * Calling a server function needs no binding: the client stub is `(input) => Promise<Output>`, and a
+ * click handler can await it. What a component usually wants on top is whether a call is in flight,
+ * what came back, and what went wrong - which is state, and state is the part every framework spells
+ * differently.
+ *
+ * So the state machine lives here, framework-agnostic, and each adapter contributes only its
+ * subscription primitive. Five copies of "is it pending" would drift, and the drift would be five
+ * subtly different answers to the same question.
+ *
+ * ## Two behaviours worth stating
+ *
+ * **The last call wins.** Concurrent calls are not queued or cancelled; a response that is no longer
+ * the newest is discarded rather than written. Without that, a slow first call landing after a fast
+ * second one would overwrite fresh data with stale - the classic out-of-order bug, and one that only
+ * appears under load, which is to say in production.
+ *
+ * **`call` still rejects.** The error is recorded for rendering AND the promise rejects, so `await`
+ * behaves the way `await` should and a caller who wants to branch can. A caller who only renders from
+ * state should attach a `.catch(() => {})`, the same as `useFetcher`'s `submit`.
+ */
+const IDLE = { pending: false, data: undefined, error: undefined };
+/** The idle state, shared so a server render and the first client render agree by reference. */
+export function idleServerFnState() {
+    return IDLE;
+}
+const asError = (cause) => cause instanceof Error ? cause : new Error(String(cause), { cause });
+/**
+ * Wrap a server function (or any async function) in a subscribable pending/error state.
+ *
+ * Framework-free by design: the adapters call this and subscribe with their own primitive.
+ */
+export function createServerFnStore(fn) {
+    const listeners = new Set();
+    let state = idleServerFnState();
+    /** Identifies the newest call, so an older one landing later cannot write over it. */
+    let generation = 0;
+    const set = (next) => {
+        state = next;
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        snapshot: () => state,
+        async call(input) {
+            const mine = ++generation;
+            // `data` is deliberately kept while pending: dropping it makes a list blank on every refetch.
+            set({ pending: true, data: state.data, error: undefined });
+            try {
+                const data = await fn(input);
+                if (mine === generation)
+                    set({ pending: false, data, error: undefined });
+                return data;
+            }
+            catch (cause) {
+                const error = asError(cause);
+                if (mine === generation)
+                    set({ pending: false, data: state.data, error });
+                throw error;
+            }
+        },
+        reset() {
+            // Bump the generation so a call already in flight cannot resurrect the state it was reset from.
+            generation += 1;
+            set(idleServerFnState());
+        },
+    };
+}
+//# sourceMappingURL=fn-state.js.map

package/dist/fn-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn-state.js","sourceRoot":"","sources":["../src/fn-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA4BH,MAAM,IAAI,GAAyB,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;AAExF,gGAAgG;AAChG,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAA6B,CAAA;AACtC,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,KAAc,EAAS,EAAE,CACxC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;AAEtE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,EAA8C;IAE9C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IACvC,IAAI,KAAK,GAA0B,iBAAiB,EAAU,CAAA;IAC9D,sFAAsF;IACtF,IAAI,UAAU,GAAG,CAAC,CAAA;IAElB,MAAM,GAAG,GAAG,CAAC,IAA2B,EAAQ,EAAE;QAChD,KAAK,GAAG,IAAI,CAAA;QACZ,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,EAAE,CAAA;IAC9C,CAAC,CAAA;IAED,OAAO;QACL,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC5B,CAAC,CAAA;QACH,CAAC;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;QACrB,KAAK,CAAC,IAAI,CAAC,KAAK;YACd,MAAM,IAAI,GAAG,EAAE,UAAU,CAAA;YACzB,8FAA8F;YAC9F,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;YAC1D,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;gBAC5B,IAAI,IAAI,KAAK,UAAU;oBAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;gBACxE,OAAO,IAAI,CAAA;YACb,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC5B,IAAI,IAAI,KAAK,UAAU;oBAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;gBACzE,MAAM,KAAK,CAAA;YACb,CAAC;QACH,CAAC;QACD,KAAK;YACH,gGAAgG;YAChG,UAAU,IAAI,CAAC,CAAA;YACf,GAAG,CAAC,iBAAiB,EAAU,CAAC,CAAA;QAClC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/fn.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `@nifrajs/web/fn` - server functions: write a function, call it from a component.
+ *
+ * ## Every server function is a public endpoint
+ *
+ * This is the first thing to internalise, because the API deliberately reads like a local call. A
+ * mounted function is an HTTP route anyone can POST to, with arguments entirely under the caller's
+ * control. Its id has to be in the client bundle for the browser to call it, so there is no obscurity
+ * to lean on. Treat one exactly as you would a hand-written `app.post`.
+ *
+ * What follows from that, and what this module does about it:
+ *
+ *   - **Input is validated, always.** `input` is not optional decoration; without a schema a function
+ *     takes no arguments at all. Unvalidated arguments on a public endpoint are mass assignment.
+ *   - **`application/json` only.** A cross-origin HTML form can only send urlencoded, multipart or
+ *     text/plain, so requiring JSON forces a CORS preflight the browser blocks. Both alternatives were
+ *     measured rather than assumed: a body schema alone still accepts a cross-origin urlencoded form
+ *     (200, attacker-controlled fields), and `c.boundedJson` alone accepts the `text/plain` trick where
+ *     a form's `name=value` is crafted to parse as JSON. Neither is sufficient by itself.
+ *   - **Same-origin only.** A present `Origin` must match the request's own host. Defence in depth
+ *     behind the JSON requirement, and it costs one comparison. Server functions exist for your own
+ *     frontend; a different origin calling your backend is the typed-client story, not this one.
+ *   - **No closures.** A function is a module-level export taking explicit arguments. Next serialises
+ *     closed-over variables to the browser and back, which it now has to encrypt; refusing the feature
+ *     removes the whole class rather than defending it.
+ *
+ * ## The client half
+ *
+ * A `*.fn.ts` module is never bundled for the browser. The client build replaces it with one stub per
+ * export, each POSTing to the route below, so the bodies and everything they import stay on the server.
+ *
+ * One pipeline cannot do this: `nifra dev --bun`. Bun's dev-server bundler accepts no plugins - a
+ * runtime `Bun.plugin` onLoad does not reach it, which was measured rather than assumed - so a `*.fn`
+ * module there would ship WHOLE, secrets included. That command refuses to start on an app containing
+ * one, the same way it already refuses CSS Modules. `nifra build` and `nifra dev` (Vite) are unaffected.
+ *
+ * ## Why this is not a new lane
+ *
+ * A mounted function registers through the ordinary public `register()`, so it is a route like any
+ * other and inherits the body cap, schema validation, capability declarations, the effect ledger, and
+ * `nifra assure`. Nothing here touches the kernel or the request path, so an app that mounts none of
+ * them pays exactly nothing - which is the whole reason to build it this way rather than as a
+ * bespoke dispatcher.
+ */
+import { type Context, type RouteSchema, type StandardSchemaV1 } from "@nifrajs/core/server";
+/** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
+export declare const SERVER_FN_PREFIX = "/_nifra/fn";
+type MaybePromise<T> = T | Promise<T>;
+/** What a server function declares about itself. */
+export interface ServerFnConfig<Input> {
+    /**
+     * Validates the single argument. Omit it and the function takes no argument - never "any argument":
+     * the caller controls this value completely, so an unvalidated one is an open door.
+     */
+    readonly input?: StandardSchemaV1<unknown, Input>;
+    /** Effect tokens, forwarded to the route so `nifra assure` and the effect ledger see them. */
+    readonly capabilities?: readonly string[];
+}
+/**
+ * A declared server function. Callable directly on the server (the same value your own server-side
+ * code can await); on the client, phase 2's build transform replaces this module with typed stubs
+ * that POST to the mounted route.
+ *
+ * This is the SERVER declaration type, so context is required. Client builds replace the module with
+ * a one-argument {@link ClientServerFn}; UI bindings accept either shape and adapt at that boundary.
+ * Keeping the types separate prevents a direct server call from type-checking while handing the
+ * declaration `undefined` for a context its implementation requires.
+ */
+export interface ServerFn<Input, Output> {
+    (input: Input, context: Context): MaybePromise<Output>;
+    readonly [SERVER_FN]: ServerFnConfig<Input>;
+}
+/** The one-argument callable emitted into a client bundle for a {@link ServerFn}. */
+export type ClientServerFn<Input, Output> = (input: Input) => MaybePromise<Output>;
+/** A UI binding boundary: source declarations and generated client stubs are both accepted. */
+export type ServerFnReference<Input, Output> = ServerFn<Input, Output> | ClientServerFn<Input, Output>;
+/** Brand identifying a value produced by {@link serverFn}, so mounting cannot pick up stray exports. */
+export declare const SERVER_FN: unique symbol;
+/**
+ * Declare a server function.
+ *
+ *     export const addTodo = serverFn(
+ *       { input: t.object({ text: t.string({ minLength: 1 }) }), capabilities: ["db.write"] },
+ *       async ({ text }, c) => db.todos.insert({ text }),
+ *     )
+ *
+ * The second argument receives the validated input and the ordinary nifra `Context` - `c.env`,
+ * `c.clientIp`, `c.budget`, cookies, and the capability guard are all present, because this is a route.
+ */
+export declare function serverFn<Input = void, Output = unknown>(config: ServerFnConfig<Input>, fn: (input: Input, context: Context) => MaybePromise<Output>): ServerFn<Input, Output>;
+/** The minimum a server needs to expose for functions to be mounted onto it. */
+export interface ServerFnHost {
+    register(method: "POST", path: string, schema: RouteSchema | undefined, handler: (context: never) => unknown): void;
+}
+/** Every server function a module exports, keyed by export name. */
+export type ServerFnModule = Readonly<Record<string, unknown>>;
+/**
+ * Mount a module's server functions under `namespace`, returning a plugin for `app.use(...)`.
+ *
+ *     import * as todos from "./actions/todos.fn"
+ *     app.use(serverFunctions("todos", todos))   // -> POST /_nifra/fn/todos/addTodo
+ *
+ * The namespace is explicit rather than derived from the file path: a path-derived one would put the
+ * build machine's layout in a public URL, and this keeps the route readable in logs and greppable in
+ * the codebase. Phase 2's transform supplies it automatically from the file's location in the project.
+ *
+ * Exports that are not server functions are ignored, so `export type` and helpers can live alongside.
+ */
+export declare function serverFunctions<S extends ServerFnHost>(namespace: string, module: ServerFnModule): (app: S) => S;
+export {};
+//# sourceMappingURL=fn.d.ts.map

package/dist/fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn.d.ts","sourceRoot":"","sources":["../src/fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAA;AAE7B,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC,oDAAoD;AACpD,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACjD,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ,CAAC,KAAK,EAAE,MAAM;IACrC,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;IACtD,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAA;CAC5C;AAED,qFAAqF;AACrF,MAAM,MAAM,cAAc,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,CAAC,MAAM,CAAC,CAAA;AAElF,+FAA+F;AAC/F,MAAM,MAAM,iBAAiB,CAAC,KAAK,EAAE,MAAM,IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GACvB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEjC,wGAAwG;AACxG,eAAO,MAAM,SAAS,EAAE,OAAO,MAA6C,CAAA;AAE5E;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,KAAK,GAAG,IAAI,EAAE,MAAM,GAAG,OAAO,EACrD,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,EAC7B,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,YAAY,CAAC,MAAM,CAAC,GAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAEzB;AAiBD,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,OAAO,GACnC,IAAI,CAAA;CACR;AAED,oEAAoE;AACpE,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE9D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,GACrB,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CA4Cf"}

package/dist/fn.js

@@ -0,0 +1,125 @@
+/**
+ * `@nifrajs/web/fn` - server functions: write a function, call it from a component.
+ *
+ * ## Every server function is a public endpoint
+ *
+ * This is the first thing to internalise, because the API deliberately reads like a local call. A
+ * mounted function is an HTTP route anyone can POST to, with arguments entirely under the caller's
+ * control. Its id has to be in the client bundle for the browser to call it, so there is no obscurity
+ * to lean on. Treat one exactly as you would a hand-written `app.post`.
+ *
+ * What follows from that, and what this module does about it:
+ *
+ *   - **Input is validated, always.** `input` is not optional decoration; without a schema a function
+ *     takes no arguments at all. Unvalidated arguments on a public endpoint are mass assignment.
+ *   - **`application/json` only.** A cross-origin HTML form can only send urlencoded, multipart or
+ *     text/plain, so requiring JSON forces a CORS preflight the browser blocks. Both alternatives were
+ *     measured rather than assumed: a body schema alone still accepts a cross-origin urlencoded form
+ *     (200, attacker-controlled fields), and `c.boundedJson` alone accepts the `text/plain` trick where
+ *     a form's `name=value` is crafted to parse as JSON. Neither is sufficient by itself.
+ *   - **Same-origin only.** A present `Origin` must match the request's own host. Defence in depth
+ *     behind the JSON requirement, and it costs one comparison. Server functions exist for your own
+ *     frontend; a different origin calling your backend is the typed-client story, not this one.
+ *   - **No closures.** A function is a module-level export taking explicit arguments. Next serialises
+ *     closed-over variables to the browser and back, which it now has to encrypt; refusing the feature
+ *     removes the whole class rather than defending it.
+ *
+ * ## The client half
+ *
+ * A `*.fn.ts` module is never bundled for the browser. The client build replaces it with one stub per
+ * export, each POSTing to the route below, so the bodies and everything they import stay on the server.
+ *
+ * One pipeline cannot do this: `nifra dev --bun`. Bun's dev-server bundler accepts no plugins - a
+ * runtime `Bun.plugin` onLoad does not reach it, which was measured rather than assumed - so a `*.fn`
+ * module there would ship WHOLE, secrets included. That command refuses to start on an app containing
+ * one, the same way it already refuses CSS Modules. `nifra build` and `nifra dev` (Vite) are unaffected.
+ *
+ * ## Why this is not a new lane
+ *
+ * A mounted function registers through the ordinary public `register()`, so it is a route like any
+ * other and inherits the body cap, schema validation, capability declarations, the effect ledger, and
+ * `nifra assure`. Nothing here touches the kernel or the request path, so an app that mounts none of
+ * them pays exactly nothing - which is the whole reason to build it this way rather than as a
+ * bespoke dispatcher.
+ */
+import { isSameOriginRequest, } from "@nifrajs/core/server";
+/** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
+export const SERVER_FN_PREFIX = "/_nifra/fn";
+/** Brand identifying a value produced by {@link serverFn}, so mounting cannot pick up stray exports. */
+export const SERVER_FN = Symbol.for("@nifrajs/web/server-fn");
+/**
+ * Declare a server function.
+ *
+ *     export const addTodo = serverFn(
+ *       { input: t.object({ text: t.string({ minLength: 1 }) }), capabilities: ["db.write"] },
+ *       async ({ text }, c) => db.todos.insert({ text }),
+ *     )
+ *
+ * The second argument receives the validated input and the ordinary nifra `Context` - `c.env`,
+ * `c.clientIp`, `c.budget`, cookies, and the capability guard are all present, because this is a route.
+ */
+export function serverFn(config, fn) {
+    return Object.assign(fn, { [SERVER_FN]: config });
+}
+const isServerFn = (value) => typeof value === "function" && SERVER_FN in value;
+/** A namespace segment: lowercase, dot/dash separated. Constrained so a mount cannot invent a path. */
+const NAMESPACE = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+/** An export name that is safe in a URL path without escaping. */
+const EXPORT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * Same-origin, from `@nifrajs/core` so this seam and the WebSocket handshake cannot answer differently
+ * for one request. Host must match; the Origin's scheme may be equal or stronger, never weaker - which
+ * is what keeps a TLS-terminating proxy working without reading a forwarded header.
+ */
+const sameOrigin = isSameOriginRequest;
+/**
+ * Mount a module's server functions under `namespace`, returning a plugin for `app.use(...)`.
+ *
+ *     import * as todos from "./actions/todos.fn"
+ *     app.use(serverFunctions("todos", todos))   // -> POST /_nifra/fn/todos/addTodo
+ *
+ * The namespace is explicit rather than derived from the file path: a path-derived one would put the
+ * build machine's layout in a public URL, and this keeps the route readable in logs and greppable in
+ * the codebase. Phase 2's transform supplies it automatically from the file's location in the project.
+ *
+ * Exports that are not server functions are ignored, so `export type` and helpers can live alongside.
+ */
+export function serverFunctions(namespace, module) {
+    if (!NAMESPACE.test(namespace)) {
+        throw new Error(`[nifra/fn] invalid server-function namespace ${JSON.stringify(namespace)} - use lowercase dot/dash segments (it becomes a URL path).`);
+    }
+    const mounted = Object.entries(module).filter((entry) => isServerFn(entry[1]));
+    const apply = (app) => {
+        for (const [name, fn] of mounted) {
+            if (!EXPORT_NAME.test(name)) {
+                throw new Error(`[nifra/fn] server function ${JSON.stringify(name)} in namespace ${JSON.stringify(namespace)} is not a valid identifier.`);
+            }
+            const config = fn[SERVER_FN];
+            const schema = {
+                ...(config.input !== undefined ? { body: config.input } : {}),
+                ...(config.capabilities !== undefined ? { capabilities: config.capabilities } : {}),
+            };
+            app.register("POST", `${SERVER_FN_PREFIX}/${namespace}/${name}`, schema, ((c) => {
+                // Ordered cheapest-first, and BEFORE the declared function runs. The body has already been
+                // parsed by the schema layer, but parsing is not a side effect - nothing the caller asked for
+                // has happened yet, so rejecting here is a complete refusal.
+                const request = c.req;
+                const contentType = request.headers.get("content-type") ?? "";
+                if (!contentType.includes("application/json")) {
+                    // A form cannot send this content type cross-origin without a preflight. Rejecting anything
+                    // else is what makes form-driven CSRF against a server function impossible rather than
+                    // merely unlikely.
+                    return c.json({ ok: false, error: "unsupported_media_type" }, 415);
+                }
+                const origin = request.headers.get("origin");
+                if (origin !== null && !sameOrigin(origin, request)) {
+                    return c.json({ ok: false, error: "forbidden_origin" }, 403);
+                }
+                return fn(config.input === undefined ? undefined : c.body, c);
+            }));
+        }
+        return app;
+    };
+    return Object.assign(apply, { pluginName: `nifra:server-fn:${namespace}` });
+}
+//# sourceMappingURL=fn.js.map

package/dist/fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn.js","sourceRoot":"","sources":["../src/fn.ts"],"names":[],"mappings":"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"}

package/dist/fonts-google.d.ts

@@ -1,12 +1,12 @@
 /**
- * Build-time Google Fonts automation — the `next/font/google` equivalent. At **build time** (never on
+ * Build-time Google Fonts automation - the `next/font/google` equivalent. At **build time** (never on
  * the request path) it: builds the Google Fonts CSS2 URL, downloads the stylesheet, parses the
  * `@font-face` rules, downloads each `.woff2`, content-hashes it, writes it next to your assets, and
  * hands back a **self-hosted** `@font-face` stylesheet + the matching `<link rel="preload">`s. The
- * result is identical to dropping the files in yourself and calling {@link fontFace} — no runtime CDN
+ * result is identical to dropping the files in yourself and calling {@link fontFace} - no runtime CDN
  * hotlink, no layout shift, hashed filenames for immutable caching.
  *
- *   // fonts.build.ts — run once at build time (e.g. a prebuild step)
+ *   // fonts.build.ts - run once at build time (e.g. a prebuild step)
  *   import { loadGoogleFont } from "@nifrajs/web/fonts"
  *   const inter = await loadGoogleFont(
  *     { family: "Inter", weights: [400, 700], subsets: ["latin"] },
@@ -16,7 +16,7 @@
  *   // inter.preloads → spread into a root layout's `meta.link`
  *
  * Security: this fetches remote content and writes it to disk, so every input is validated and the
- * font-file host is **allowlisted to `fonts.gstatic.com` over https** — a tampered/MITM'd stylesheet
+ * font-file host is **allowlisted to `fonts.gstatic.com` over https** - a tampered/MITM'd stylesheet
  * cannot make the build fetch an arbitrary URL (SSRF) or write an attacker-chosen blob. Downloads are
  * size-capped. Filenames are derived only from validated tokens + a content hash (no path traversal).
  */
@@ -26,7 +26,7 @@ import type { LinkDescriptor } from "./manifest.js";
 export interface GoogleFontOptions {
     /** Family name exactly as Google lists it, e.g. `"Inter"`, `"Open Sans"`, `"Roboto Mono"`. */
     readonly family: string;
-    /** Weights to request — numbers (`400`), numeric strings, a variable range (`"100 900"`), or the
+    /** Weights to request - numbers (`400`), numeric strings, a variable range (`"100 900"`), or the
      * keywords `"normal"`/`"bold"`. Defaults to `[400]`. */
     readonly weights?: readonly (number | string)[];
     /** Styles to request. Defaults to `["normal"]`. */
@@ -38,7 +38,7 @@ export interface GoogleFontOptions {
     /** `font-display` strategy for the generated faces. Defaults to `"swap"`. */
     readonly display?: FontDisplay;
     /** Glyph subsetting: request only the glyphs needed to render exactly this text (Google's `&text=`).
-     * Ideal for a logo/heading font — produces one tiny file. */
+     * Ideal for a logo/heading font - produces one tiny file. */
     readonly text?: string;
     /** CLS metric overrides forwarded to every generated `@font-face` (the layout-shift fix). */
     readonly sizeAdjust?: string;
@@ -77,7 +77,7 @@ export interface LoadGoogleFontResult {
     readonly css: string;
     /** Every file written to `outDir`. */
     readonly assets: readonly FontAsset[];
-    /** `fontPreload()` link-attribute sets — spread the ones you want into a layout's `meta.link`.
+    /** `fontPreload()` link-attribute sets - spread the ones you want into a layout's `meta.link`.
      * Preloading *every* weight/subset is wasteful; usually preload just the primary subset + weight. */
     readonly preloads: readonly LinkDescriptor[];
 }
@@ -93,13 +93,13 @@ export interface LoadGoogleFontIO {
     /** Per-file download cap in bytes. Defaults to 5 MB (real woff2 are well under 1 MB). */
     readonly maxBytesPerFile?: number;
 }
-/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL — the only host we'll download from. */
+/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL - the only host we'll download from. */
 export declare function isAllowedFontUrl(raw: string): boolean;
 /** Build the Google Fonts CSS2 request URL. Pure + fully validated, so it's safe to feed a dynamic
  * family/weights/text. Exported for advanced callers who fetch + parse the stylesheet themselves. */
 export declare function googleFontsCssUrl(options: GoogleFontOptions): string;
 /** Parse Google's stylesheet into structured faces, capturing the `/* subset *​/` label that precedes
- * each `@font-face`. Pure — exported so callers can run their own download/write pipeline. */
+ * each `@font-face`. Pure - exported so callers can run their own download/write pipeline. */
 export declare function parseGoogleFontCss(css: string): ParsedFontFace[];
 /**
  * Download a Google font, self-host it, and return a CLS-safe `@font-face` stylesheet + preloads.