npm - @c9up/aurora - Versions diffs - 0.1.25 → 0.1.27 - Mend

@c9up/aurora 0.1.25 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/README.md +92 -0
package/dist/AuroraManager.d.ts +22 -1
package/dist/AuroraManager.js +26 -0
package/dist/browser.d.ts +7 -0
package/dist/browser.js +49 -8
package/dist/form.d.ts +19 -9
package/dist/form.js +5 -2
package/dist/http.d.ts +12 -0
package/dist/http.js +51 -2
package/dist/hydrate.js +44 -0
package/dist/index.d.ts +1 -1
package/dist/live.d.ts +1 -1
package/dist/liveServer.d.ts +12 -0
package/dist/liveServer.js +15 -1
package/dist/relay.js +11 -1
package/dist/render.js +9 -2
package/dist/route.js +9 -1
package/dist/server/renderPage.d.ts +25 -0
package/dist/server/renderPage.js +52 -13
package/dist/server.d.ts +1 -1
package/dist/services/main.js +9 -0
package/dist/url.d.ts +7 -0
package/dist/url.js +15 -3
package/package.json +1 -1
package/src/AuroraManager.ts +49 -0
package/src/browser.ts +57 -8
package/src/form.ts +20 -7
package/src/http.ts +67 -2
package/src/hydrate.ts +74 -0
package/src/index.ts +1 -0
package/src/live.ts +1 -0
package/src/liveServer.ts +25 -2
package/src/relay.ts +9 -1
package/src/render.ts +12 -2
package/src/route.ts +10 -1
package/src/server/renderPage.ts +100 -14
package/src/server.ts +2 -0
package/src/services/main.ts +9 -0
package/src/url.ts +21 -3

package/dist/render.js CHANGED Viewed

@@ -68,10 +68,17 @@ export function mount(result, cleanups, mounted, mountHooks) {
     // the final string. Collect them in a first pass, attach effects
     // after.
     const multiGroups = new Map();
+    // Resolve EVERY slot's node before applying any of them. Applying a text
+    // slot inserts nodes into the fragment, which shifts the child indices the
+    // remaining paths were computed against — so a slot sitting after a nested
+    // template (`${Icon()}${label}`) used to resolve to the wrong node, or to
+    // none, and silently never bound. Fragments exist precisely so a component
+    // needs no wrapper element; they must not cost the slots that follow them.
+    const resolved = tpl.slots.map((slot) => resolvePath(fragment, slot.path));
     for (let i = 0; i < tpl.slots.length; i++) {
         const slot = tpl.slots[i];
-        const node = resolvePath(fragment, slot.path);
-        if (node === null) {
+        const node = resolved[i];
+        if (node === null || node === undefined) {
             // Path didn't resolve — skip this binding rather than crash (see
             // resolvePath). Degrades to a dead binding; the surrounding render
             // (and any command driving it) survives.

package/dist/route.js CHANGED Viewed

@@ -29,9 +29,17 @@ const DEFAULT_SHELL = (body, entry) => `<!doctype html>
 </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) {
+    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/dist/server/renderPage.d.ts CHANGED Viewed

@@ -64,6 +64,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
@@ -85,4 +108,6 @@ export interface RenderPageOptions {
      */
     cookies?: string[];
 }
+export type SharedProps = Record<string, unknown>;
+export type SharedPropsResolver = (ctx: RenderHttpContext) => SharedProps | Promise<SharedProps>;
 export declare function renderPage<P>(ctx: RenderHttpContext, pages: Pages, name: string, props: P, options?: RenderPageOptions): Promise<void>;

package/dist/server/renderPage.js CHANGED Viewed

@@ -22,9 +22,13 @@
  *     </script>
  *   </body>
  */
-import { setCookieStore } from "../browser.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setCookieStoreReader } from "../browser.js";
 import { renderToString } from "../ssr.js";
-import { setRouteManifest } from "../url.js";
+import { setRouteManifestReader } from "../url.js";
+const renderScope = new AsyncLocalStorage();
+setCookieStoreReader(() => renderScope.getStore()?.cookies);
+setRouteManifestReader(() => renderScope.getStore()?.routes);
 function isCookieReadable(request) {
     return (typeof request === "object" &&
         request !== null &&
@@ -44,24 +48,29 @@ function readRequestCookies(request, names) {
     return seed;
 }
 export async function renderPage(ctx, pages, name, props, options = {}) {
-    // 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 = {
+        cookies: options.cookies
+            ? readRequestCookies(ctx.request, options.cookies)
+            : {},
+        routes: options.routes ?? {},
+    };
+    return renderScope.run(scope, () => renderPageInScope(ctx, pages, name, props, options));
+}
+async function renderPageInScope(ctx, pages, name, props, options) {
     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);
+    const tree = await factory(pageProps);
     const body = renderToString(tree);
     const importmap = {
         "@c9up/aurora": "/__assets/aurora/index.js",
         ...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);
     const doc = `<!doctype html>
@@ -73,13 +82,14 @@ export async function renderPage(ctx, pages, name, props, options = {}) {
 ${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'
@@ -93,6 +103,35 @@ hydrate(document.getElementById(data.rootId), () => Page(data.props))
     ctx.response.header("content-type", "text/html; charset=utf-8");
     ctx.response.send(doc);
 }
+async function resolveSharedProps(ctx, shared) {
+    if (!shared)
+        return {};
+    return typeof shared === "function" ? shared(ctx) : shared;
+}
+function mergeProps(shared, props) {
+    if (Object.keys(shared).length === 0)
+        return props;
+    if (isPlainRecord(props))
+        return { ...shared, ...props };
+    return { ...shared, page: props };
+}
+function isPlainRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function normalizeRootTag(tag) {
+    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, className) {
+    const attrs = [`id="${escapeAttr(id)}"`];
+    if (className)
+        attrs.push(`class="${escapeAttr(className)}"`);
+    return ` ${attrs.join(" ")}`;
+}
 function escapeAttr(value) {
     return value
         .replace(/&/g, "&amp;")

package/dist/server.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
 export { type AuroraRequestRenderer, auroraContext, } from "./middleware.js";
 export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";
-export { type RenderHttpContext, type RenderPageOptions, type RenderResponse, renderPage, } from "./server/renderPage.js";
+export { type RenderHttpContext, type RenderPageOptions, type RenderResponse, renderPage, type SharedProps, type SharedPropsResolver, } from "./server/renderPage.js";
 export { type AssetsHttpContext, type AssetsRequest, type AssetsResponse, packageAssetDir, type ServeAssetsOptions, serveAssets, } from "./server/serveAssets.js";

package/dist/services/main.js CHANGED Viewed

@@ -20,6 +20,15 @@ export function getAurora() {
 }
 const aurora = new Proxy({}, {
     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 " +
                 "or `setAurora(myManager)` was called. Wire one of them first.");

package/dist/url.d.ts CHANGED Viewed

@@ -16,6 +16,12 @@
  * injects the same map into the page so the hydrate bootstrap re-sets it client
  * side. Node-free — part of aurora's client runtime.
  */
+type RouteManifestReader = () => Record<string, string> | 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 declare function setRouteManifestReader(reader: RouteManifestReader | undefined): void;
 /**
  * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
  * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
@@ -31,3 +37,4 @@ export declare function getRouteManifest(): Record<string, string>;
  * an unknown route or a missing required param. Mirrors Ream's `router.urlFor`.
  */
 export declare function urlFor(name: string, params?: Record<string, string | number>, query?: Record<string, string | number>): string;
+export {};

package/dist/url.js CHANGED Viewed

@@ -17,6 +17,17 @@
  * side. Node-free — part of aurora's client runtime.
  */
 let manifest = {};
+let routeManifestReader;
+/**
+ * @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 = reader;
+}
+function activeManifest() {
+    return routeManifestReader?.() ?? manifest;
+}
 /**
  * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
  * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
@@ -28,7 +39,7 @@ export function setRouteManifest(routes) {
 }
 /** The currently-installed route manifest (mainly for tests/introspection). */
 export function getRouteManifest() {
-    return { ...manifest };
+    return { ...activeManifest() };
 }
 /**
  * Build a URL for a named route — fills `:param` placeholders, drops unprovided
@@ -36,9 +47,10 @@ export function getRouteManifest() {
  * an unknown route or a missing required param. Mirrors Ream's `router.urlFor`.
  */
 export function urlFor(name, params, query) {
-    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
             ? `Known: ${known.join(", ")}`
             : "No routes registered — was the manifest passed to render() / setRouteManifest() called?"}`);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
   "license": "MIT",
   "type": "module",

package/src/AuroraManager.ts CHANGED Viewed

@@ -19,6 +19,8 @@ import {
 	type RenderHttpContext,
 	type RenderPageOptions,
 	renderPage,
+	type SharedProps,
+	type SharedPropsResolver,
 } from "./server/renderPage.js";
 import {
 	type AssetsHttpContext,
@@ -28,6 +30,21 @@ import {
 export interface AuroraManagerConfig {
 	pages: PagesConfig;
+	/**
+	 * Shared props injected into every `render()` call, matching Adonis/Inertia's
+	 * request-level shared data model. Per-call `options.shared` is merged over it.
+	 */
+	shared?: SharedProps | SharedPropsResolver;
+	/**
+	 * Default root tag/class for rendered pages. Mirrors Inertia's root template
+	 * customization while keeping controllers thin.
+	 */
+	root?: {
+		tag?: string;
+		class?: string;
+	};
+	/** Default asset/version marker serialized into the page payload. */
+	assetsVersion?: string;
 	/**
 	 * Filesystem path to aurora's pre-built `dist/`. Defaults to the
 	 * dist directory shipped with the installed `@c9up/aurora` package.
@@ -104,6 +121,12 @@ export class AuroraManager {
 	readonly cometDistRoot: string | null;
 	/** App-level importmap overrides from `config/aurora.ts`, merged on render. */
 	readonly importmap: Record<string, string>;
+	/** App-level shared props from config/aurora.ts. */
+	readonly shared?: SharedProps | SharedPropsResolver;
+	/** App-level root element defaults from config/aurora.ts. */
+	readonly root?: AuroraManagerConfig["root"];
+	/** App-level asset/version marker. */
+	readonly assetsVersion?: string;
 	constructor(config: AuroraManagerConfig) {
 		this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/__assets");
@@ -112,6 +135,9 @@ export class AuroraManager {
 		this.cometAssetPath = `${this.assetsPrefix}/comet`;
 		this.cometDistRoot = config.cometDistRoot ?? resolveCometDist();
 		this.importmap = config.importmap ?? {};
+		this.shared = config.shared;
+		this.root = config.root;
+		this.assetsVersion = config.assetsVersion;
 		// Pages serve their compiled JS from the same prefix unless the app
 		// pins an explicit urlPrefix.
 		this.pages = new Pages({
@@ -136,6 +162,10 @@ export class AuroraManager {
 	): Promise<void> {
 		return renderPage(ctx, this.pages, name, props, {
 			...options,
+			rootTag: options?.rootTag ?? this.root?.tag,
+			rootClass: options?.rootClass ?? this.root?.class,
+			assetsVersion: options?.assetsVersion ?? this.assetsVersion,
+			shared: mergeSharedResolvers(this.shared, options?.shared),
 			importmap: {
 				"@c9up/aurora": `${this.auroraAssetPath}/index.js`,
 				// The browser-facing subpath (RPC client) needs an explicit entry —
@@ -184,3 +214,22 @@ export class AuroraManager {
 			: null;
 	}
 }
+function mergeSharedResolvers(
+	base: AuroraManagerConfig["shared"],
+	override: RenderPageOptions["shared"],
+): RenderPageOptions["shared"] {
+	if (!base) return override;
+	if (!override) return base;
+	return async (ctx) => ({
+		...(await resolveShared(ctx, base)),
+		...(await resolveShared(ctx, override)),
+	});
+}
+async function resolveShared(
+	ctx: RenderHttpContext,
+	shared: SharedProps | SharedPropsResolver,
+): Promise<SharedProps> {
+	return typeof shared === "function" ? shared(ctx) : shared;
+}

package/src/browser.ts CHANGED Viewed

@@ -12,7 +12,7 @@ import { effect, onCleanup, type Signal, signal } from "./reactive.js";
 /** Navigate to `url` with a full page load. No-op during SSR. */
 export function redirect(url: string): void {
 	if (typeof window !== "undefined") {
-		window.location.href = url;
+		window.location.href = safeNavigationUrl(url);
 	}
 }
@@ -22,7 +22,7 @@ export function redirect(url: string): void {
  */
 export function replace(url: string): void {
 	if (typeof window !== "undefined") {
-		window.location.replace(url);
+		window.location.replace(safeNavigationUrl(url));
 	}
 }
@@ -358,6 +358,22 @@ export function forward(): void {
 	if (typeof window !== "undefined") window.history.forward();
 }
+/**
+ * Drop every C0 control character (U+0000–U+001F).
+ *
+ * Written as a scan rather than a regex: a character class over control
+ * characters is exactly what `noControlCharactersInRegex` flags, and the rule
+ * is right in general — here the stripping is the point, so the loop states it
+ * without needing a suppression.
+ */
+function stripControlChars(value: string): string {
+	let out = "";
+	for (const char of value) {
+		if (char.charCodeAt(0) > 0x1f) out += char;
+	}
+	return out;
+}
 /**
  * SPA navigation: push `url` onto history WITHOUT a full page reload (contrast
  * {@link redirect}, which reloads). Emits a `popstate` event so reactive URL
@@ -366,10 +382,27 @@ export function forward(): void {
  */
 export function navigate(url: string): void {
 	if (typeof window === "undefined") return;
-	window.history.pushState({}, "", url);
+	window.history.pushState({}, "", safeNavigationUrl(url));
 	window.dispatchEvent(new Event("popstate"));
 }
+function safeNavigationUrl(url: string): string {
+	// Browsers strip ASCII tab/newline/CR from ANYWHERE in a URL and trim leading
+	// control chars + whitespace before resolving the scheme, so `java\tscript:`
+	// (or a leading NUL) is evaluated as `javascript:`. A guard that only
+	// `trimStart()`s is trivially bypassed — mirror the browser and strip every
+	// C0 control char before comparing the scheme.
+	const normalized = stripControlChars(url).trimStart().toLowerCase();
+	if (
+		normalized.startsWith("javascript:") ||
+		normalized.startsWith("vbscript:") ||
+		normalized.startsWith("data:")
+	) {
+		throw new Error(`[aurora] blocked unsafe navigation URL: ${url}`);
+	}
+	return url;
+}
 /**
  * A {@link Signal} bound to a single URL query parameter. Reading reflects the
  * current value (`null` when absent); writing updates the URL via `pushState`
@@ -428,14 +461,26 @@ export interface CookieOptions {
  * no view of the request cookies and renders default UI state → a flash /
  * mismatch on hydration (the classic collapsed-sidebar flicker).
  *
- * Module-global by necessity (the page factory reads it ambiently). It is set
- * synchronously immediately before the synchronous render, so read your cookie
- * signals at the TOP of a page (before any `await`) to avoid a cross-request
- * race under concurrent async page factories. In the browser it is unused —
+ * Fallback module-global for manual/server tests. `renderPage()` installs a
+ * request-scoped reader backed by AsyncLocalStorage, so concurrent SSR renders
+ * do not share this mutable object. In the browser it is unused —
  * {@link cookie.get} reads `document.cookie` directly there.
  */
 let cookieSeed: Record<string, string> = {};
+type CookieStoreReader = () => Record<string, string> | undefined;
+let cookieStoreReader: CookieStoreReader | undefined;
+/**
+ * @internal Server-side hook used by `renderPage()` to provide a request-scoped
+ * cookie store without importing Node built-ins from this browser-safe module.
+ */
+export function setCookieStoreReader(
+	reader: CookieStoreReader | undefined,
+): void {
+	cookieStoreReader = reader;
+}
 /**
  * Install the SSR cookie seed (`name → value`). Called by `renderPage` from its
  * `cookies` allowlist; the hydrate bootstrap does NOT call it (the browser reads
@@ -458,7 +503,11 @@ export function getCookieStore(): Record<string, string> {
  */
 export const cookie = {
 	get(name: string): string | null {
-		if (typeof document === "undefined") return cookieSeed[name] ?? null;
+		if (typeof document === "undefined") {
+			const scoped = cookieStoreReader?.();
+			if (scoped && Object.hasOwn(scoped, name)) return scoped[name];
+			return cookieSeed[name] ?? null;
+		}
 		const prefix = `${encodeURIComponent(name)}=`;
 		for (const part of document.cookie.split("; ")) {
 			if (part.startsWith(prefix)) {

package/src/form.ts CHANGED Viewed

@@ -5,7 +5,7 @@
  * `html\`\`` and never hand-roll field state or try/catch.
  *
  * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
- * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * `{ field: message }` map, OR any object with a `.validateResult(values)` method
  * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
  * duck-types `.validate`. With no `validate`, the form simply never reports field
  * errors. Node-free — part of the client barrel.
@@ -35,12 +35,23 @@ import { memo, type ReadSignal, signal } from "./reactive.js";
 /** A field-keyed error map: `{ email: "Invalid", … }`. Absent key ⇒ no error. */
 export type FieldErrors<T> = Partial<Record<keyof T, string>>;
-/** Anything `.validate()`-shaped (a `@c9up/rune` schema satisfies this). */
+/** The synchronous, never-throwing outcome a form schema hands back. */
+export interface FormValidationOutcome {
+	valid: boolean;
+	errors?: ReadonlyArray<{ field?: string; message: string }>;
+}
+/**
+ * Anything schema-shaped (a `@c9up/rune` schema satisfies this).
+ *
+ * Both spellings are accepted, and `validateResult` wins when present: rune
+ * reserves `validate()` for the VineJS contract (async, throwing), and reading
+ * `.valid` off a Promise yields `undefined` — the form would then report itself
+ * invalid with no error to show.
+ */
 export interface FormSchema<T> {
-	validate(values: T): {
-		valid: boolean;
-		errors?: ReadonlyArray<{ field?: string; message: string }>;
-	};
+	validate?(values: T): FormValidationOutcome;
+	validateResult?(values: T): FormValidationOutcome;
 }
 /** Validation source — a function, a schema-like object, or omitted. */
@@ -96,7 +107,9 @@ function computeErrors<T>(
 ): FieldErrors<T> {
 	if (!validate) return {};
 	if (typeof validate === "function") return validate(values);
-	const result = validate.validate(values);
+	const check = validate.validateResult ?? validate.validate;
+	if (typeof check !== "function") return {};
+	const result = check.call(validate, values);
 	if (result.valid) return {};
 	const errors: Record<string, string> = {};
 	for (const issue of result.errors ?? []) {

package/src/http.ts CHANGED Viewed

@@ -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,