@c9up/aurora 0.1.24 → 0.1.26

package/src/http.ts

@@ -29,6 +29,13 @@ export interface HttpClientOptions {
 	token?: string | null | (() => string | null | undefined);
 	/** Default `credentials` mode (e.g. `"include"` to send cookies). */
 	credentials?: RequestCredentials;
+	/**
+	 * Allow default bearer/default Authorization headers to be sent to absolute
+	 * cross-origin URLs. Default `false`: same-origin API clients should not leak
+	 * credentials if an untrusted value becomes the request URL. Per-request
+	 * `headers.Authorization` is still treated as explicit caller intent.
+	 */
+	allowCrossOriginAuth?: boolean;
 	/**
 	 * Default timeout in ms — the request is aborted (rejecting with a
 	 * `TimeoutError`) if it doesn't settle in time. Combined with a per-request
@@ -50,6 +57,11 @@ export interface HttpRequestOptions<T = unknown> {
 	timeout?: number;
 	/** `credentials` mode for this request. */
 	credentials?: RequestCredentials;
+	/**
+	 * Per-request override for sending managed auth headers to cross-origin
+	 * absolute URLs. Default inherits the client option (`false` by default).
+	 */
+	allowCrossOriginAuth?: boolean;
 	/**
 	 * Runtime validator/mapper for the parsed body. When provided, the return
 	 * type is whatever it returns — no unchecked cast. When omitted, the parsed
@@ -131,6 +143,36 @@ function hasHeader(headers: Record<string, string>, name: string): boolean {
 	return false;
 }
 
+/** Delete every case variant of a header from a plain header record. */
+function deleteHeader(headers: Record<string, string>, name: string): void {
+	const lower = name.toLowerCase();
+	for (const key of Object.keys(headers)) {
+		if (key.toLowerCase() === lower) delete headers[key];
+	}
+}
+
+function originOf(value: string): string | null {
+	try {
+		if (/^[a-z][a-z\d+\-.]*:\/\//i.test(value)) return new URL(value).origin;
+		if (typeof window !== "undefined")
+			return new URL(value, window.location.href).origin;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+function isCrossOriginAbsoluteUrl(url: string, baseURL: string): boolean {
+	if (!/^[a-z][a-z\d+\-.]*:\/\//i.test(url)) return false;
+	const targetOrigin = originOf(url);
+	if (targetOrigin === null) return true;
+	const baseOrigin = baseURL ? originOf(baseURL) : null;
+	if (baseOrigin !== null) return targetOrigin !== baseOrigin;
+	if (typeof window !== "undefined")
+		return targetOrigin !== window.location.origin;
+	return true;
+}
+
 /** Merge abort signals into one (whichever fires first wins). `undefined` if none. */
 function combineSignals(
 	signals: ReadonlyArray<AbortSignal | undefined>,
@@ -168,6 +210,7 @@ export class HttpClient {
 	readonly #token?: string | null | (() => string | null | undefined);
 	readonly #credentials?: RequestCredentials;
 	readonly #timeout?: number;
+	readonly #allowCrossOriginAuth: boolean;
 
 	constructor(options: HttpClientOptions = {}) {
 		this.#baseURL = options.baseURL ?? "";
@@ -175,6 +218,7 @@ export class HttpClient {
 		this.#token = options.token;
 		this.#credentials = options.credentials;
 		this.#timeout = options.timeout;
+		this.#allowCrossOriginAuth = options.allowCrossOriginAuth ?? false;
 	}
 
 	/** Set a default header for every subsequent request (case-insensitive replace). Chainable. */
@@ -284,6 +328,8 @@ export class HttpClient {
 			token: options.token ?? this.#token,
 			credentials: options.credentials ?? this.#credentials,
 			timeout: options.timeout ?? this.#timeout,
+			allowCrossOriginAuth:
+				options.allowCrossOriginAuth ?? this.#allowCrossOriginAuth,
 		});
 	}
 
@@ -313,12 +359,31 @@ export class HttpClient {
 		body: unknown,
 		options: HttpRequestOptions,
 	): Promise<Response> {
+		const finalUrl = this.#buildUrl(url, options.query);
+		const crossOrigin = isCrossOriginAbsoluteUrl(finalUrl, this.#baseURL);
+		const allowCrossOriginAuth =
+			options.allowCrossOriginAuth ?? this.#allowCrossOriginAuth;
+		const explicitRequestAuth =
+			options.headers !== undefined &&
+			hasHeader(options.headers, "authorization");
 		const headers: Record<string, string> = {
 			...this.#headers,
 			...options.headers,
 		};
+		if (
+			crossOrigin &&
+			!allowCrossOriginAuth &&
+			!explicitRequestAuth &&
+			hasHeader(this.#headers, "authorization")
+		) {
+			deleteHeader(headers, "authorization");
+		}
 		const token = this.#resolveToken(options.token);
-		if (token != null && !hasHeader(headers, "authorization")) {
+		if (
+			token != null &&
+			!hasHeader(headers, "authorization") &&
+			(!crossOrigin || allowCrossOriginAuth)
+		) {
 			headers.Authorization = `Bearer ${token}`;
 		}
 
@@ -341,7 +406,7 @@ export class HttpClient {
 			timeout !== undefined ? AbortSignal.timeout(timeout) : undefined,
 		]);
 
-		return fetch(this.#buildUrl(url, options.query), {
+		return fetch(finalUrl, {
 			method,
 			headers,
 			body: payload,

package/src/index.ts

@@ -100,6 +100,7 @@ export {
 } from "./liveRouter.js";
 export {
 	DEFAULT_LIVE_EVENT_PATH,
+	type LiveEventBody,
 	type LiveHttpContext,
 	type LiveHttpRouter,
 	type WireLiveEventsOptions,

package/src/live.ts

@@ -39,6 +39,7 @@ export {
 } from "./liveRouter.js";
 export {
 	DEFAULT_LIVE_EVENT_PATH,
+	type LiveEventBody,
 	type LiveHttpContext,
 	type LiveHttpRouter,
 	type WireLiveEventsOptions,

package/src/liveServer.ts

@@ -29,9 +29,19 @@ export interface LiveHttpContext {
 export interface WireLiveEventsOptions {
 	/** Route path for inbound events (must match the client transport). */
 	path?: string;
+	/**
+	 * Optional per-request guard. Return `false` to reject the event with 403.
+	 * Use this to enforce the same auth/CSRF/owner policy as the page that mounted
+	 * the live session. When omitted, aurora preserves the framework-agnostic
+	 * legacy behavior and expects the host route/middleware to guard the endpoint.
+	 */
+	authorize?: (
+		ctx: LiveHttpContext,
+		body: LiveEventBody,
+	) => boolean | Promise<boolean>;
 }
 
-interface LiveEventBody {
+export interface LiveEventBody {
 	id: string;
 	event: string;
 	payload?: unknown;
@@ -57,13 +67,26 @@ export function wireLiveEvents(
 	options: WireLiveEventsOptions = {},
 ): void {
 	const path = options.path ?? DEFAULT_LIVE_EVENT_PATH;
-	router.post(path, (ctx) => {
+	router.post(path, async (ctx) => {
 		const body = ctx.request.body();
 		if (!isLiveEventBody(body)) {
 			ctx.response.status(400);
 			ctx.response.json({ error: "live event requires { id, event }" });
 			return;
 		}
+		let authorized = true;
+		if (options.authorize) {
+			try {
+				authorized = await options.authorize(ctx, body);
+			} catch {
+				authorized = false;
+			}
+		}
+		if (!authorized) {
+			ctx.response.status(403);
+			ctx.response.json({ error: "forbidden live event" });
+			return;
+		}
 		const handled = live.event(body.id, body.event, body.payload);
 		if (!handled) {
 			ctx.response.status(404);

package/src/relay.ts

@@ -345,7 +345,15 @@ async function postHandshake(url: string, channel: string): Promise<void> {
 function retrieveXsrfToken(): string | null {
 	if (typeof document === "undefined") return null;
 	const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]*)/);
-	return match ? decodeURIComponent(match[1]) : null;
+	if (!match) return null;
+	try {
+		return decodeURIComponent(match[1]);
+	} catch {
+		// A malformed cookie must not break subscribe/unsubscribe handshakes. The
+		// server will reject an invalid token normally; the client should not throw
+		// before it even sends the request.
+		return match[1];
+	}
 }
 
 function safeJson<T>(raw: unknown): T | null {

package/src/route.ts

@@ -72,10 +72,19 @@ const DEFAULT_SHELL = (body: string, entry: string): string =>
 </head>
 <body>
 <div id="aurora-root">${body}</div>
-<script type="module" src="${entry}"></script>
+<script type="module" src="${escapeAttr(entry)}"></script>
 </body>
 </html>`;
 
+function escapeAttr(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
 /**
  * Build a Ream-compatible route handler that SSR-renders the given
  * factory and serves the full HTML document.

package/src/server/renderPage.ts

@@ -23,10 +23,11 @@
  *   </body>
  */
 
-import { setCookieStore } from "../browser.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setCookieStoreReader } from "../browser.js";
 import type { Pages } from "../Pages.js";
 import { renderToString } from "../ssr.js";
-import { setRouteManifest } from "../url.js";
+import { setRouteManifestReader } from "../url.js";
 
 /**
  * Structural slice of the host framework's response. Same shape
@@ -70,6 +71,29 @@ export interface RenderPageOptions {
 	 * targets.
 	 */
 	rootId?: string;
+	/**
+	 * Root element tag for the SSR + hydrated tree. Defaults to `div`.
+	 * Mirrors Inertia's root tag customization (`@inertia({ as: ... })`) while
+	 * keeping aurora independent from a template engine.
+	 */
+	rootTag?: string;
+	/**
+	 * Optional class attribute on the root element. Mirrors
+	 * `@inertia({ class: ... })`.
+	 */
+	rootClass?: string;
+	/**
+	 * Shared props merged into every page render before invoking the page factory.
+	 * Use this for global data such as user, flash and validation errors. A
+	 * function receives the current HTTP context and may be async, matching
+	 * Adonis/Inertia's request middleware `share()` model.
+	 */
+	shared?: SharedProps | SharedPropsResolver;
+	/**
+	 * Asset/version marker serialized with the page payload. Apps can use this to
+	 * detect stale client state when their frontend build changes.
+	 */
+	assetsVersion?: string;
 	/**
 	 * Named-route manifest (`name → path-pattern`) for the isomorphic
 	 * `urlFor()` helper — build it with Ream's `router.namedManifest()`. It is
@@ -92,11 +116,26 @@ export interface RenderPageOptions {
 	cookies?: string[];
 }
 
+export type SharedProps = Record<string, unknown>;
+export type SharedPropsResolver = (
+	ctx: RenderHttpContext,
+) => SharedProps | Promise<SharedProps>;
+
 /** A request that can read a cookie by name — the structural slice we need. */
 interface CookieReadableRequest {
 	cookie(name: string): string | null;
 }
 
+interface RenderScope {
+	cookies: Record<string, string>;
+	routes: Record<string, string>;
+}
+
+const renderScope = new AsyncLocalStorage<RenderScope>();
+
+setCookieStoreReader(() => renderScope.getStore()?.cookies);
+setRouteManifestReader(() => renderScope.getStore()?.routes);
+
 function isCookieReadable(request: unknown): request is CookieReadableRequest {
 	return (
 		typeof request === "object" &&
@@ -127,21 +166,31 @@ export async function renderPage<P>(
 	props: P,
 	options: RenderPageOptions = {},
 ): Promise<void> {
-	// Install the route manifest BEFORE rendering so a page calling `urlFor`
-	// during SSR resolves against the same map the client will get.
-	if (options.routes) setRouteManifest(options.routes);
-
-	// Seed the request's UI cookies so the page reads the SAME state server-side
-	// that the browser will after hydration. Set synchronously right before the
-	// (synchronous) render — read cookie signals at the top of the page.
-	setCookieStore(
-		options.cookies ? readRequestCookies(ctx.request, options.cookies) : {},
+	const scope: RenderScope = {
+		cookies: options.cookies
+			? readRequestCookies(ctx.request, options.cookies)
+			: {},
+		routes: options.routes ?? {},
+	};
+
+	return renderScope.run(scope, () =>
+		renderPageInScope(ctx, pages, name, props, options),
 	);
+}
 
+async function renderPageInScope<P>(
+	ctx: RenderHttpContext,
+	pages: Pages,
+	name: string,
+	props: P,
+	options: RenderPageOptions,
+): Promise<void> {
 	const factory = await pages.resolve(name);
+	const shared = await resolveSharedProps(ctx, options.shared);
+	const pageProps = mergeProps(shared, props);
 	// The factory must be invoked the SAME way client-side for hydrate
 	// to find matching slots — `Page(props)` is the contract.
-	const tree = await factory(props as never);
+	const tree = await factory(pageProps as never);
 	const body = renderToString(tree);
 
 	const importmap = {
@@ -149,6 +198,8 @@ export async function renderPage<P>(
 		...options.importmap,
 	};
 	const rootId = options.rootId ?? "aurora-root";
+	const rootTag = normalizeRootTag(options.rootTag ?? "div");
+	const rootClass = options.rootClass;
 	const lang = options.lang ?? "en";
 	const pageUrl = pages.urlFor(name);
 
@@ -161,13 +212,14 @@ export async function renderPage<P>(
 ${options.headExtra ?? ""}
 </head>
 <body>
-<div id="${escapeAttr(rootId)}">${body}</div>
+<${rootTag}${rootAttrs(rootId, rootClass)}>${body}</${rootTag}>
 <script id="aurora-page-data" type="application/json">${escapeJsonForScript({
 		name,
-		props,
+		props: pageProps,
 		url: pageUrl,
 		rootId,
 		routes: options.routes ?? {},
+		version: options.assetsVersion ?? null,
 	})}</script>
 <script type="module">
 import { hydrate, setRouteManifest } from '@c9up/aurora'
@@ -183,6 +235,40 @@ hydrate(document.getElementById(data.rootId), () => Page(data.props))
 	ctx.response.send(doc);
 }
 
+async function resolveSharedProps(
+	ctx: RenderHttpContext,
+	shared: RenderPageOptions["shared"],
+): Promise<SharedProps> {
+	if (!shared) return {};
+	return typeof shared === "function" ? shared(ctx) : shared;
+}
+
+function mergeProps<P>(shared: SharedProps, props: P): P | SharedProps {
+	if (Object.keys(shared).length === 0) return props;
+	if (isPlainRecord(props)) return { ...shared, ...props };
+	return { ...shared, page: props };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		Object.getPrototypeOf(value) === Object.prototype
+	);
+}
+
+function normalizeRootTag(tag: string): string {
+	if (/^[a-z][a-z0-9-]*$/i.test(tag)) return tag.toLowerCase();
+	throw new Error(`[aurora] illegal root tag: ${JSON.stringify(tag)}`);
+}
+
+function rootAttrs(id: string, className: string | undefined): string {
+	const attrs = [`id="${escapeAttr(id)}"`];
+	if (className) attrs.push(`class="${escapeAttr(className)}"`);
+	return ` ${attrs.join(" ")}`;
+}
+
 function escapeAttr(value: string): string {
 	return value
 		.replace(/&/g, "&amp;")

package/src/server.ts

@@ -16,6 +16,8 @@ export {
 	type RenderPageOptions,
 	type RenderResponse,
 	renderPage,
+	type SharedProps,
+	type SharedPropsResolver,
 } from "./server/renderPage.js";
 export {
 	type AssetsHttpContext,

package/src/services/main.ts

@@ -26,6 +26,15 @@ export function getAurora(): AuroraManager | undefined {
 
 const aurora: AuroraManager = new Proxy({} as AuroraManager, {
 	get(_target, prop) {
+		// A module loader inspects what it imports before anyone uses it: it reads
+		// `then` to decide whether the namespace is thenable, and various symbols
+		// for interop and formatting. Throwing on those turns a plain
+		// `import { setX } from ".../services/main"` into a crash at import time,
+		// far from any real use. They are not members of what this stands in for,
+		// so answer undefined and let a genuine access be the one that reports.
+		if (typeof prop === "symbol" || prop === "then") {
+			return undefined;
+		}
 		if (!instance) {
 			throw new Error(
 				"[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +

package/src/url.ts

@@ -19,6 +19,23 @@
 
 let manifest: Record<string, string> = {};
 
+type RouteManifestReader = () => Record<string, string> | undefined;
+let routeManifestReader: RouteManifestReader | undefined;
+
+/**
+ * @internal Server-side hook used by `renderPage()` to provide a request-scoped
+ * route manifest without importing Node built-ins from this browser-safe module.
+ */
+export function setRouteManifestReader(
+	reader: RouteManifestReader | undefined,
+): void {
+	routeManifestReader = reader;
+}
+
+function activeManifest(): Record<string, string> {
+	return routeManifestReader?.() ?? manifest;
+}
+
 /**
  * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
  * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
@@ -31,7 +48,7 @@ export function setRouteManifest(routes: Record<string, string>): void {
 
 /** The currently-installed route manifest (mainly for tests/introspection). */
 export function getRouteManifest(): Record<string, string> {
-	return { ...manifest };
+	return { ...activeManifest() };
 }
 
 /**
@@ -44,9 +61,10 @@ export function urlFor(
 	params?: Record<string, string | number>,
 	query?: Record<string, string | number>,
 ): string {
-	const pattern = manifest[name];
+	const routes = activeManifest();
+	const pattern = routes[name];
 	if (pattern === undefined) {
-		const known = Object.keys(manifest);
+		const known = Object.keys(routes);
 		throw new Error(
 			`[aurora] urlFor: unknown route '${name}'. ${
 				known.length > 0