@octanejs/app-core 0.0.9 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/app-core",
-  "version": "0.0.9",
+  "version": "0.0.13",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -75,14 +75,14 @@
     }
   },
   "dependencies": {
-    "@ripple-ts/adapter": "^0.3.108",
+    "@ripple-ts/adapter": "^0.3.112",
     "esbuild": "^0.28.1"
   },
   "peerDependencies": {
-    "octane": "0.1.13"
+    "octane": "0.1.17"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "octane": "0.1.13"
+    "octane": "0.1.17"
   }
 }

package/src/constants.js

@@ -1,5 +1,7 @@
 // @ts-check
 export const DEFAULT_OUTDIR = 'dist';
 export const ENTRY_FILENAME = 'entry.js';
+/** Default upper bound for an encoded server-function request body. */
+export const DEFAULT_RPC_MAX_BODY_BYTES = 1_048_576;
 /** Context.state key a middleware sets to apply a per-request CSP nonce. */
 export const OCTANE_NONCE_STATE_KEY = 'octane.nonce';

package/src/index.js

@@ -16,3 +16,4 @@ export {
 	is_rpc_request,
 	runMiddlewareChain,
 } from './middleware.js';
+export { handleRpcRequest } from './server/rpc.js';

package/src/resolve-config.js

@@ -15,7 +15,34 @@
 
 import { normalizeRendererConfig } from 'octane/compiler/renderers';
 
-import { DEFAULT_OUTDIR } from './constants.js';
+import { DEFAULT_OUTDIR, DEFAULT_RPC_MAX_BODY_BYTES } from './constants.js';
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalize_rpc_origin(value) {
+	if (typeof value !== 'string') {
+		throw new Error('[octane] server.rpc.allowedOrigins must contain only HTTP or HTTPS origins.');
+	}
+
+	try {
+		const origin = new URL(value);
+		if (
+			(origin.protocol !== 'http:' && origin.protocol !== 'https:') ||
+			origin.username !== '' ||
+			origin.password !== '' ||
+			origin.pathname !== '/' ||
+			origin.search !== '' ||
+			origin.hash !== ''
+		) {
+			throw new Error('Not an HTTP or HTTPS origin');
+		}
+		return origin.origin;
+	} catch {
+		throw new Error('[octane] server.rpc.allowedOrigins must contain only HTTP or HTTPS origins.');
+	}
+}
 
 /**
  * @param {unknown} route
@@ -176,6 +203,24 @@ export function resolveOctaneConfig(raw, options = {}) {
 		throw new Error("[octane] server.render must be 'streaming' or 'buffered'.");
 	}
 
+	const rawRpc = raw.server?.rpc;
+	if (
+		rawRpc !== undefined &&
+		(rawRpc === null || typeof rawRpc !== 'object' || Array.isArray(rawRpc))
+	) {
+		throw new Error('[octane] server.rpc must be an object when provided.');
+	}
+	if (
+		rawRpc?.maxBodyBytes !== undefined &&
+		(!Number.isSafeInteger(rawRpc.maxBodyBytes) || rawRpc.maxBodyBytes <= 0)
+	) {
+		throw new Error('[octane] server.rpc.maxBodyBytes must be a positive safe integer.');
+	}
+	if (rawRpc?.allowedOrigins !== undefined && !Array.isArray(rawRpc.allowedOrigins)) {
+		throw new Error('[octane] server.rpc.allowedOrigins must be an array.');
+	}
+	const allowedRpcOrigins = [...new Set((rawRpc?.allowedOrigins ?? []).map(normalize_rpc_origin))];
+
 	// ------------------------------------------------------------------
 	// Apply defaults
 	// ------------------------------------------------------------------
@@ -201,6 +246,10 @@ export function resolveOctaneConfig(raw, options = {}) {
 		server: {
 			trustProxy: raw.server?.trustProxy ?? false,
 			render: raw.server?.render ?? 'streaming',
+			rpc: {
+				allowedOrigins: allowedRpcOrigins,
+				maxBodyBytes: rawRpc?.maxBodyBytes ?? DEFAULT_RPC_MAX_BODY_BYTES,
+			},
 		},
 	};
 }

package/src/server/production.js

@@ -24,6 +24,7 @@
 
 import { createRouter } from './router.js';
 import { createContext, runMiddlewareChain } from './middleware.js';
+import { handleRpcRequest } from './rpc.js';
 import { handleServerRoute } from './server-route.js';
 import { composeHtmlStream } from './html-stream.js';
 import {
@@ -48,12 +49,7 @@ import {
 	get_route_entry_export_name,
 	get_route_entry_path,
 } from '../routes.js';
-import {
-	patch_global_fetch,
-	build_rpc_lookup,
-	is_rpc_request,
-	handle_rpc_request,
-} from '@ripple-ts/adapter/rpc';
+import { patch_global_fetch, build_rpc_lookup, is_rpc_request } from '@ripple-ts/adapter/rpc';
 
 export { resolveOctaneConfig } from '../resolve-config.js';
 
@@ -127,6 +123,7 @@ export function createHandler(manifest, deps) {
 	const router = createRouter(manifest.routes);
 	const globalMiddlewares = manifest.middlewares ?? [];
 	const trustProxy = manifest.trustProxy ?? false;
+	const rpcPolicy = manifest.rpc;
 	const runtime = manifest.runtime;
 	validateSsrTemplate(htmlTemplate);
 	// Also pin the built-template contract up front. The marker is emitted by
@@ -158,17 +155,7 @@ export function createHandler(manifest, deps) {
 					headers: { 'Content-Type': 'application/json' },
 				});
 			}
-			/** @type {import('@ripple-ts/adapter/rpc').AsyncContext<{ origin?: string, platform?: unknown }>} */
-			const requestAsyncContext =
-				platform === undefined
-					? asyncContext
-					: {
-							run(store, fn) {
-								return asyncContext.run({ ...store, platform }, fn);
-							},
-							getStore: () => asyncContext.getStore(),
-						};
-			return handle_rpc_request(request, {
+			return handleRpcRequest(request, {
 				resolveFunction(/** @type {string} */ hash) {
 					const entry = rpcLookup.get(hash);
 					if (!entry) return null;
@@ -176,8 +163,12 @@ export function createHandler(manifest, deps) {
 					return typeof fn === 'function' ? fn : null;
 				},
 				executeServerFunction,
-				asyncContext: requestAsyncContext,
+				asyncContext,
 				trustProxy,
+				middlewares: globalMiddlewares,
+				allowedOrigins: rpcPolicy?.allowedOrigins,
+				maxBodyBytes: rpcPolicy?.maxBodyBytes,
+				platform,
 			});
 		}
 
@@ -288,39 +279,67 @@ export function createHandler(manifest, deps) {
 		}
 
 		const headContent = [...preloadTags, dataScript].join('\n');
-		const html = applyHydrationNonce(htmlTemplate, nonce).replace('<!--ssr-head-->', headContent);
+		const noncedTemplate = applyHydrationNonce(htmlTemplate, nonce);
 
 		const status = route.status ?? 200;
 		const headers = { 'Content-Type': 'text/html; charset=utf-8' };
 
-		const [prefix, suffix] = splitSsrTemplate(html);
+		// `headChannel: 'separate'` below: this handler renders the ROUTE into the
+		// template's `<div id="root">`, not a document, so core's default fold has
+		// no `</head>` to target and would prepend hoisted `<title>`/`<meta>`/
+		// `<link>` into the body, where a title loses to the template's and a
+		// canonical or description is ignored. Splicing at `<!--ssr-head-->`
+		// instead is also what makes hydration's `document.head` adoption find the
+		// ownership markers rather than creating duplicates.
+		//
+		// The replacement is a FUNCTION, not a string: a string replacement makes
+		// `$&`, `` $` ``, `$'` and `$1` in the inserted text expand against the
+		// match, and this text now carries author-controlled metadata as well as
+		// the serialized route data.
+		/** @param {string} hoistedHead */
+		const splitAroundBody = (hoistedHead) =>
+			splitSsrTemplate(noncedTemplate.replace('<!--ssr-head-->', () => headContent + hoistedHead));
 
 		if (manifest.render === 'buffered') {
 			// Await-everything fallback (`prerender` from octane/static): no
 			// streaming, one document. The deduped scoped-style tags lead the body
 			// markup inside #root — the same position they hold in the streamed
 			// shell — so hydrateRoot's leading-style skip applies unchanged.
-			const { html: body, css } = await prerender(RootComponent, undefined, {
+			const {
+				html: body,
+				css,
+				head,
+			} = await prerender(RootComponent, undefined, {
 				nonce: nonce ?? undefined,
+				headChannel: 'separate',
 				signal: context.request.signal,
 				onError(/** @type {unknown} */ error) {
 					console.error('[octane] SSR render error:', error);
 				},
 			});
+			const [prefix, suffix] = splitAroundBody(head ?? '');
 			return new Response(prefix + css + body + suffix, { status, headers });
 		}
 
 		// Streaming (default): shell flushes at first await, suspense segments
 		// stream out-of-order behind it — identical to dev.
+		let hoistedHead = '';
 		/** @type {ReadableStream<Uint8Array>} */
 		const renderStream = await renderToReadableStream(RootComponent, undefined, {
 			nonce: nonce ?? undefined,
+			headChannel: 'separate',
+			// Fires before the shell is written, so the metadata is in hand before
+			// the template prefix (which carries `<head>`) is composed below.
+			onHeadReady(/** @type {string} */ head) {
+				hoistedHead = head;
+			},
 			signal: context.request.signal,
 			onError(/** @type {unknown} */ error) {
 				console.error('[octane] SSR render error:', error);
 			},
 		});
 
+		const [prefix, suffix] = splitAroundBody(hoistedHead);
 		const body = composeHtmlStream(prefix, renderStream, suffix);
 
 		return new Response(body, { status, headers });

package/src/server/rpc.js

@@ -0,0 +1,254 @@
+// @ts-check
+/**
+ * Bundler-neutral, security-owning server-function request boundary.
+ *
+ * The Ripple adapter owns the existing wire path, hash lookup, proxy-origin
+ * derivation, and request-scoped fetch primitives. Octane owns which requests
+ * may cross its server-function boundary, the bounded body reader, application
+ * authorization middleware, and production-safe error disclosure.
+ */
+
+import { derive_origin } from '@ripple-ts/adapter/rpc';
+
+import { DEFAULT_RPC_MAX_BODY_BYTES } from '../constants.js';
+import { createContext, runMiddlewareChain } from './middleware.js';
+
+const RPC_PATH_PREFIX = '/_$_ripple_rpc_$_/';
+
+/**
+ * @param {number} status
+ * @param {string} message
+ * @param {HeadersInit} [headers]
+ * @returns {Response}
+ */
+function rpcError(status, message, headers) {
+	return new Response(JSON.stringify({ error: message }), {
+		status,
+		headers: { 'Content-Type': 'application/json; charset=utf-8', ...headers },
+	});
+}
+
+/**
+ * @param {Request} request
+ * @param {boolean} trustProxy
+ * @param {readonly string[]} allowedOrigins
+ * @returns {string | null}
+ */
+function allowedRequestOrigin(request, trustProxy, allowedOrigins) {
+	let requestOrigin;
+	try {
+		requestOrigin = new URL(derive_origin(request, trustProxy)).origin;
+	} catch {
+		return null;
+	}
+
+	const browserOrigin = request.headers.get('origin');
+	if (browserOrigin === null) {
+		return request.headers.get('sec-fetch-site')?.toLowerCase() === 'cross-site'
+			? null
+			: requestOrigin;
+	}
+
+	let normalizedBrowserOrigin;
+	try {
+		normalizedBrowserOrigin = new URL(browserOrigin).origin;
+	} catch {
+		return null;
+	}
+	if (normalizedBrowserOrigin !== browserOrigin) return null;
+
+	return normalizedBrowserOrigin === requestOrigin ||
+		allowedOrigins.includes(normalizedBrowserOrigin)
+		? requestOrigin
+		: null;
+}
+
+/**
+ * @param {Response} response
+ * @param {string | null} origin
+ * @returns {Response}
+ */
+function withRpcCors(response, origin) {
+	if (origin === null) return response;
+
+	const headers = new Headers(response.headers);
+	headers.set('Access-Control-Allow-Origin', origin);
+	headers.append('Vary', 'Origin');
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}
+
+/**
+ * @param {Request} request
+ * @param {number} maxBodyBytes
+ * @returns {Promise<{ body: string } | { error: Response }>}
+ */
+async function readBoundedRpcBody(request, maxBodyBytes) {
+	const contentLength = request.headers.get('content-length');
+	if (contentLength !== null) {
+		if (!/^\d+$/.test(contentLength)) {
+			return { error: rpcError(400, 'Invalid RPC request') };
+		}
+		const declaredLength = Number(contentLength);
+		if (!Number.isSafeInteger(declaredLength) || declaredLength > maxBodyBytes) {
+			return { error: rpcError(413, 'RPC request exceeds the maximum body size') };
+		}
+	}
+
+	if (request.body === null || request.signal.aborted) {
+		return { error: rpcError(400, 'Invalid RPC request') };
+	}
+
+	const reader = request.body.getReader();
+	const decoder = new TextDecoder('utf-8', { fatal: true });
+	let bytesRead = 0;
+	let body = '';
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			bytesRead += value.byteLength;
+			if (bytesRead > maxBodyBytes) {
+				try {
+					await reader.cancel();
+				} catch {
+					// A hostile stream cannot downgrade an oversized request into another status.
+				}
+				return { error: rpcError(413, 'RPC request exceeds the maximum body size') };
+			}
+			body += decoder.decode(value, { stream: true });
+		}
+		body += decoder.decode();
+	} catch {
+		return { error: rpcError(400, 'Invalid RPC request') };
+	} finally {
+		reader.releaseLock();
+	}
+
+	try {
+		if (!Array.isArray(JSON.parse(body))) {
+			return { error: rpcError(400, 'Invalid server function arguments') };
+		}
+	} catch {
+		return { error: rpcError(400, 'Invalid server function arguments') };
+	}
+
+	return { body };
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isInvalidRpcPayload(error) {
+	return (
+		typeof error === 'object' &&
+		error !== null &&
+		'code' in error &&
+		error.code === 'OCTANE_INVALID_RPC_PAYLOAD'
+	);
+}
+
+/**
+ * Validate and execute an Octane server function behind application middleware.
+ *
+ * @param {Request} request
+ * @param {import('@octanejs/app-core').RpcRequestOptions} options
+ * @returns {Promise<Response>}
+ */
+export async function handleRpcRequest(request, options) {
+	if (request.method === 'OPTIONS') {
+		const origin = allowedRequestOrigin(
+			request,
+			options.trustProxy ?? false,
+			options.allowedOrigins ?? [],
+		);
+		const browserOrigin = request.headers.get('origin');
+		if (origin === null || browserOrigin === null || browserOrigin === origin) {
+			return rpcError(403, 'Cross-origin RPC requests are not allowed');
+		}
+		if (request.headers.get('access-control-request-method') !== 'POST') {
+			return rpcError(405, 'RPC requests require POST', { Allow: 'POST' });
+		}
+
+		return new Response(null, {
+			status: 204,
+			headers: {
+				'Access-Control-Allow-Origin': browserOrigin,
+				'Access-Control-Allow-Methods': 'POST',
+				'Access-Control-Allow-Headers':
+					request.headers.get('access-control-request-headers') ?? 'content-type',
+				Vary: 'Origin, Access-Control-Request-Headers',
+			},
+		});
+	}
+
+	if (request.method !== 'POST') {
+		return rpcError(405, 'RPC requests require POST', { Allow: 'POST' });
+	}
+
+	const contentType = request.headers.get('content-type');
+	if (contentType === null || !/^application\/json(?:\s*;|\s*$)/i.test(contentType)) {
+		return rpcError(415, 'RPC requests require application/json');
+	}
+
+	const hash = new URL(request.url).pathname.slice(RPC_PATH_PREFIX.length);
+	if (!/^[a-f0-9]{8}$/.test(hash)) {
+		return rpcError(400, 'Invalid RPC request');
+	}
+
+	const origin = allowedRequestOrigin(
+		request,
+		options.trustProxy ?? false,
+		options.allowedOrigins ?? [],
+	);
+	if (origin === null) {
+		return rpcError(403, 'Cross-origin RPC requests are not allowed');
+	}
+	const browserOrigin = request.headers.get('origin');
+	const corsOrigin = browserOrigin === origin ? null : browserOrigin;
+
+	const context = createContext(request, {}, options.platform);
+	const store =
+		options.platform === undefined ? { origin } : { origin, platform: options.platform };
+
+	try {
+		const response = await options.asyncContext.run(store, async () =>
+			runMiddlewareChain(
+				context,
+				options.middlewares ?? [],
+				[],
+				async () => {
+					const fn = await options.resolveFunction(hash);
+					if (fn === null) return rpcError(404, 'RPC function not found');
+					const payload = await readBoundedRpcBody(
+						request,
+						options.maxBodyBytes ?? DEFAULT_RPC_MAX_BODY_BYTES,
+					);
+					if ('error' in payload) return payload.error;
+					try {
+						const result = await options.executeServerFunction(fn, payload.body);
+						return new Response(result, {
+							status: 200,
+							headers: { 'Content-Type': 'application/json; charset=utf-8' },
+						});
+					} catch (error) {
+						if (isInvalidRpcPayload(error)) {
+							return rpcError(400, 'Invalid server function arguments');
+						}
+						throw error;
+					}
+				},
+				[],
+			),
+		);
+		return withRpcCors(response, corsOrigin);
+	} catch (error) {
+		console.error('[octane] RPC request error:', error);
+		return withRpcCors(rpcError(500, 'Internal Server Error'), corsOrigin);
+	}
+}

package/src/server/server-entry.js

@@ -277,6 +277,7 @@ export const manifest = {
 	layouts,
 	middlewares: octaneConfig.middlewares,
 	trustProxy: octaneConfig.server.trustProxy,
+	rpc: octaneConfig.server.rpc,
 	render: octaneConfig.server.render,
 	rootBoundary,
 	rootBoundaryEntries,
@@ -387,6 +388,7 @@ export const handler = createHandler(
 		layouts,
 		middlewares: octaneConfig.middlewares,
 		trustProxy: octaneConfig.server.trustProxy,
+		rpc: octaneConfig.server.rpc,
 		render: octaneConfig.server.render,
 		rootBoundary,
 		rootBoundaryEntries,

package/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { RuntimePrimitives } from '@ripple-ts/adapter';
+import type { AsyncContext } from '@ripple-ts/adapter/rpc';
 
 // ============================================================================
 // Shared app/config exports
@@ -138,6 +139,21 @@ export function handleServerRoute(
 ): Promise<Response>;
 export function is_rpc_request(pathname: string): boolean;
 
+/** Security policy and execution dependencies for a server-function request. */
+export interface RpcRequestOptions {
+	resolveFunction: (hash: string) => Function | null | Promise<Function | null>;
+	executeServerFunction: (fn: Function, body: string) => Promise<string>;
+	asyncContext: AsyncContext<{ origin?: string; platform?: unknown }>;
+	trustProxy?: boolean;
+	middlewares?: Middleware[];
+	allowedOrigins?: readonly string[];
+	maxBodyBytes?: number;
+	platform?: unknown;
+}
+
+/** Apply Octane's security policy and global middleware to a server function. */
+export function handleRpcRequest(request: Request, options: RpcRequestOptions): Promise<Response>;
+
 // ============================================================================
 // Configuration
 // ============================================================================
@@ -339,6 +355,13 @@ export interface OctaneConfigOptions {
 		 * @default false
 		 */
 		trustProxy?: boolean;
+		/** Security policy for compiler-generated `module server` requests. */
+		rpc?: {
+			/** Additional exact HTTP(S) origins permitted to call server functions. */
+			allowedOrigins?: string[];
+			/** Maximum encoded request size in bytes. @default 1048576 */
+			maxBodyBytes?: number;
+		};
 		/**
 		 * Production SSR mode: 'streaming' (default) flushes the shell at
 		 * first await and streams suspense segments out-of-order (same engine
@@ -378,6 +401,12 @@ export interface ResolvedOctaneConfig {
 	server: {
 		/** @default false */
 		trustProxy: boolean;
+		rpc: {
+			/** Additional normalized HTTP(S) origins. @default [] */
+			allowedOrigins: string[];
+			/** Maximum encoded request size in bytes. @default 1048576 */
+			maxBodyBytes: number;
+		};
 		/** @default 'streaming' */
 		render: 'streaming' | 'buffered';
 	};

package/types/production.d.ts

@@ -29,6 +29,8 @@ export interface ServerManifest {
 	middlewares: Middleware[];
 	/** Trust X-Forwarded-* headers when deriving origin for RPC fetch */
 	trustProxy?: boolean;
+	/** Validated `module server` origin and body-size policy. */
+	rpc?: Partial<ResolvedOctaneConfig['server']['rpc']>;
 	/** 'streaming' (default) renders via renderToReadableStream; 'buffered' awaits everything via prerender */
 	render?: 'streaming' | 'buffered';
 	/** Resolved server-compiled global boundary components. */