@jk2908/solas 0.3.8 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0 - 2026-05-11
+
+- Added CSRF protection for server actions and `+endpoint` handlers, plus a new `trustedOrigins` config option for tightly scoped cross-origin browser submissions. The checks are proxy-aware and use browser request headers when available.
+- Added Vite `base` support across server routing, prerendering, and browser navigation, so apps mounted under a subpath resolve routes and generated asset URLs correctly.
+- Changed static file handling so copied `public` files are served from the application root, while framework-generated files now live under the reserved `/_solas/*` path.
+- Breaking: removed the `solas` CLI compatibility layer and switched the documented app scripts to Bun-backed Vite commands (`bunx --bun vite dev`, `build`, and `preview`).
+- Moved Solas post-build work into the Vite plugin lifecycle, so prerendering, runtime manifest emission, sitemap generation, and precompression now run after the full app build instead of through an outer CLI wrapper.
+- Added `Solas.Runtime.Manifest` and `Solas.Runtime.loadManifest(...)` for runtime artifact and public-file lookups, while keeping artifact-specific manifest types and helpers under `Prerender.Artifact`. The runtime manifest now lives at `dist/.solas/runtime-manifest.json` instead of under `.solas/ppr`.
+- Stopped serialising stack traces in `HttpExceptionLike`, so server-rendered error payloads no longer include stacks.
+
+## 0.3.9 - 2026-05-07
+
+- Split shared `BrowserRouter` navigation types and target-building helpers into a dedicated internal module, so generated environments and type-only imports no longer need to pull through the full browser router runtime.
+- Made the `solas()` plugin config argument optional.
+
 ## 0.3.8 - 2026-04-30
 
 - Improved route module type safety for params, metadata, and static params, and ensured HTTP error boundaries receive route params too.

package/README.md

@@ -288,6 +288,32 @@ export default defineConfig({
 })
 ```
 
+### `trustedOrigins`
+
+Use `trustedOrigins` to allow specific origins to make cross-origin browser submissions to your app.
+
+Default: `[]`
+
+Solas protects server actions and `+endpoint` handlers against CSRF.
+
+Server actions are always `POST` requests. `+endpoint` handlers are protected on `POST`, `PUT`, `PATCH`, and `DELETE` requests.
+
+By default, only same-origin browser requests are allowed. Add a trusted origin when a third-party service needs to submit through the user's browser, such as a payment gateway or identity provider.
+
+Each value must be a complete origin including protocol:
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			trustedOrigins: ['https://payments.example.com', 'https://login.example.com'],
+		}),
+	],
+})
+```
+
+Only add origins you completely trust. These origins are treated as allowed browser sources for unsafe requests.
+
 ### `sitemap`
 
 Use `sitemap` to generate a `sitemap.xml` at build time.
@@ -372,15 +398,49 @@ Add scripts to your app:
 ```json
 {
 	"scripts": {
-		"dev": "solas dev",
-		"build": "solas build",
-		"preview": "solas preview"
+		"dev": "bunx --bun vite dev",
+		"build": "bunx --bun vite build",
+		"preview": "bunx --bun vite preview"
 	}
 }
 ```
 
 ## Commands
 
-- `solas dev` starts the development server.
-- `solas build` creates a production build, prerenders configured routes, and writes compressed assets when enabled.
-- `solas preview` serves the built app for local verification.
+- `bunx --bun vite dev` starts the development server.
+- `bunx --bun vite build` creates a production build. Solas finalizes that build by prerendering configured routes, writing the runtime manifest, generating `sitemap.xml` when enabled, and precompressing output when enabled.
+- `bunx --bun vite preview` serves the built app for local verification.
+
+## Security
+
+### CSRF
+
+Solas protects server actions and `+endpoint` handlers against CSRF.
+
+Server actions are always `POST` requests. `+endpoint` handlers are protected on browser-initiated `POST`, `PUT`, `PATCH`, and `DELETE` requests.
+
+By default, browser requests must be same-origin.
+
+When available, Solas checks browser provenance using:
+
+- `Sec-Fetch-Site`
+- `Origin`
+- `Referer`
+
+Solas also considers the effective request origin when your app is behind a proxy by using `X-Forwarded-Host`, `X-Forwarded-Proto`, and `config.url` when present.
+
+If you need to allow a trusted third-party browser POST source, configure it explicitly:
+
+```ts
+export default defineConfig({
+	plugins: [
+		solas({
+			trustedOrigins: ['https://payments.example.com'],
+		}),
+	],
+})
+```
+
+Requests from non-browser callers that do not send browser provenance headers are allowed by default, so typical server-to-server integrations and webhooks continue to work.
+
+Cookie-backed app mutations should keep the default same-origin protection and only use `trustedOrigins` for narrowly scoped integrations that genuinely need cross-origin browser submissions.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { type PluginOption } from 'vite';
 import type { PluginConfig } from './types.js';
-declare function solas(c: PluginConfig): PluginOption[];
+declare function solas(c?: PluginConfig): PluginOption[];
 export default solas;
 export type * from './solas.d.ts';
 export { Solas } from './solas.js';

package/dist/index.js

@@ -12,17 +12,20 @@ import { writeBrowserEntry, writeRSCEntry, writeSSREntry, } from './internal/cod
 import { writeManifest } from './internal/codegen/manifest.js';
 import { writeMaps } from './internal/codegen/maps.js';
 import { writeTypes } from './internal/codegen/types.js';
+import { postbuild } from './internal/postbuild.js';
+import { collect as collectPublicFiles } from './internal/public-files.js';
 import { Solas } from './solas.js';
 const DEFAULT_CONFIG = {
     precompress: true,
     prerender: false,
+    trustedOrigins: [],
     trailingSlash: 'never',
 };
 function solas(c) {
     const config = Solas.Config.validate({
         ...DEFAULT_CONFIG,
         ...c,
-        url: c.url ?? process.env.VITE_APP_URL?.toString(),
+        url: c?.url ?? process.env.VITE_APP_URL?.toString(),
     });
     if (config.logger?.level)
         Logger.defaultLevel = config.logger.level;
@@ -219,7 +222,11 @@ function solas(c) {
             }
             viteConfig.build ??= {};
             viteConfig.build.outDir = Solas.Config.OUT_DIR;
+            // keep framework files under one reserved url prefix
+            viteConfig.build.assetsDir = Solas.Config.ASSETS_DIR;
             viteConfig.build.emptyOutDir = true;
+            // let users move the source public folder if they want
+            viteConfig.publicDir ??= Solas.Config.PUBLIC_DIR;
             viteConfig.server ??= {};
             viteConfig.server.port = config.port ?? viteConfig.server.port ?? 8787;
             viteConfig.define ??= {};
@@ -293,13 +300,20 @@ function solas(c) {
             // write build manifest
             const generatedDir = path.join(process.cwd(), Solas.Config.GENERATED_DIR);
             await Bun.write(path.join(generatedDir, 'build.json'), JSON.stringify({
+                base: resolvedViteConfig?.base ?? '/',
+                publicFiles: await collectPublicFiles(resolvedViteConfig?.publicDir),
                 prerenderRoutes: Array.from(buildContext.prerenderRoutes),
                 sitemapRoutes,
                 precompress: config.precompress,
                 trailingSlash: config.trailingSlash,
                 url: config.url,
             }));
-            logger.info('[closeBundle]', 'vite build complete');
+        },
+        buildApp: {
+            order: 'post',
+            async handler() {
+                await postbuild(resolvedViteConfig?.root ?? process.cwd());
+            },
         },
     };
     return [

package/dist/internal/browser-router/link.d.ts

@@ -1,4 +1,4 @@
-import { BrowserRouter } from './router.js';
+import { BrowserRouter } from './shared.js';
 type AnchorProps = React.ComponentPropsWithRef<'a'> & {
     href: string;
 };

package/dist/internal/browser-router/link.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from 'react';
-import { BrowserRouter } from './router.js';
+import { BrowserRouter } from './shared.js';
 import { useRouter } from './use-router.js';
 function guard(path, prefetcher) {
     const connection = window.navigator.connection;

package/dist/internal/browser-router/router.d.ts

@@ -1,169 +1,6 @@
 import type { RscPayload } from '../env/rsc.js';
-import { Solas } from '../../solas.js';
-export declare namespace BrowserRouter {
-    export type Params = Record<string, string>;
-    export type Query = Record<string, string | number | boolean>;
-    export type Path = keyof Solas.Routes & string;
-    type Replace = {
-        replace?: boolean;
-    };
-    export type GoOptions = {
-        replace?: boolean;
-        query?: Query;
-        params?: Params;
-    };
-    /**
-     * These targets are used as-is. They are not matched against the route table,
-     * so this covers normal external URLs and hash-only links
-     */
-    export type ExternalTarget = `${string}:${string}` | `//${string}` | `#${string}`;
-    export function isHashOnlyTarget(target: string): boolean;
-    export function isExternalTarget(target: string, origin: string): boolean;
-    /**
-     * Turn a route pattern into the real path shape a caller can use. In practice,
-     * every ':param' or '*' part becomes a plain string slot
-     *
-     * @example
-     * ```ts
-     * // '/p/:id' becomes '/p/${string}'
-     * // '/test/*' becomes '/test/${string}'
-     * // '/posts' stays '/posts'
-     * ```
-     *
-     * @example
-     * ```ts
-     * type A = ResolvedPath<'/posts/:id'>
-     * // '/posts/${string}'
-     * ```
-     *
-     * @example
-     * ```ts
-     * type B = ResolvedPath<'/docs/*'>
-     * // '/docs/${string}'
-     * ```
-     */
-    export type ResolvedPath<TPath extends string> = TPath extends `${infer Start}:${string}/${infer Rest}` ? `${Start}${string}/${ResolvedPath<Rest>}` : TPath extends `${infer Start}:${string}` ? `${Start}${string}` : TPath extends `${infer Start}*${infer Rest}` ? `${Start}${string}${ResolvedPath<Rest>}` : TPath;
-    /**
-     * Once we have a real path, also allow the usual query-string and hash forms
-     *
-     * @example
-     * ```ts
-     * type A = TargetSuffix<'/posts/123'>
-     * // '/posts/123' | '/posts/123?${string}' | '/posts/123#${string}' | '/posts/123?${string}#${string}'
-     * ```
-     */
-    export type TargetSuffix<TPath extends string> = TPath | `${TPath}?${string}` | `${TPath}#${string}` | `${TPath}?${string}#${string}`;
-    /**
-     * This is the final string form a caller can navigate to. It can be an external
-     * URL, or a concrete URL that matches one of the  known routes
-     *
-     * @example
-     * ```ts
-     * type A = Target
-     * // 'https://example.com'
-     * // '#intro'
-     * // '/posts/123'
-     * // '/posts/123?draft=true'
-     * ```
-     */
-    export type Target = ExternalTarget | TargetSuffix<ResolvedPath<Path>>;
-    /**
-     * Extra options for callers who already have a finished target string
-     *
-     * @example
-     * ```ts
-     * const a: TargetConfig = { query: { page: 2 } }
-     * // params is rejected here because the path is already complete
-     * ```
-     */
-    type TargetConfig = {
-        params?: never;
-        query?: Query;
-    };
-    /**
-     * Extra options for callers who pass a route pattern and params separately.
-     * If the route definition says that route needs params, this type makes
-     * those params required. If the route has no params, it rejects them
-     *
-     * @example
-     * ```ts
-     * // if Solas.Routes['/posts/:id'] is { params: { id: string } }
-     * type A = PatternConfig<'/posts/:id'>
-     * // { query?: Query } & { params: { id: string } }
-     * ```
-     *
-     * @example
-     * ```ts
-     * // if Solas.Routes['/about'] has no params field
-     * type B = PatternConfig<'/about'>
-     * // { query?: Query } & { params?: never }
-     * ```
-     */
-    type PatternConfig<TPath extends Path> = {
-        query?: Query;
-    } & (Solas.Routes[TPath] extends {
-        params: infer TParams extends Params;
-    } ? {
-        params: TParams;
-    } : {
-        params?: never;
-    });
-    /**
-     * Typed <Link /> props, using `href` instead of the internal `to` name
-     *
-     * `query` is always allowed
-     * `params` are only allowed when `href` is a known route pattern
-     *
-     * @example
-     * ```ts
-     * const a: LinkProps = { href: '/posts/:id', params: { id: '123' } }
-     * const b: LinkProps = { href: '/posts/123?draft=true' }
-     * ```
-     */
-    export type LinkProps = ({
-        href: Target;
-    } & TargetConfig) | (keyof Solas.Routes extends never ? never : {
-        [TPath in Path]: {
-            href: TPath;
-        } & PatternConfig<TPath>;
-    }[Path]);
-    /**
-     * Typed input for router.go(), using the same route rules as <Link />
-     *
-     * @example
-     * ```ts
-     * go('/p/post-2')
-     * go('/?foo=bar', { replace: true })
-     * ```
-     *
-     * @example
-     * ```ts
-     * go('/p/:id', { params: { id: 'post-2' }, replace: true })
-     * ```
-     *
-     * The last overload is the fallback for plain `string` values. The
-     * `string extends TTo` check stops that fallback from taking over
-     * when TypeScript already knows the caller passed a more specific
-     * string literal
-     *
-     * @example
-     * ```ts
-     * declare const dynamicPath: string
-     * go(dynamicPath, { replace: true })
-     * ```
-     */
-    export type Go = {
-        <TTo extends Path>(to: TTo, opts?: PatternConfig<TTo> & Replace): Promise<string>;
-        <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
-        <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;
-    };
-    /**
-     * Convert a route pattern and params into a real path string. This is used internally
-     * to implement <Link /> and router.go
-     */
-    export function toTarget(path: string, params?: Record<string, string>, query?: BrowserRouter.Query): string;
-    export {};
-}
+import { BrowserRouter } from './shared.js';
+export { BrowserRouter } from './shared.js';
 export declare const BrowserRouterContext: import("react").Context<{
     go: BrowserRouter.Go;
     prefetch: (path: string) => void;

package/dist/internal/browser-router/router.js

@@ -4,70 +4,9 @@ import { createContext, useCallback, useEffect, useMemo, useRef } from 'react';
 import { createFromFetch } from '@vitejs/plugin-rsc/browser';
 import { Logger } from '../../utils/logger.js';
 import { Solas } from '../../solas.js';
-import { Prefetcher } from './../prefetcher.js';
-export { BrowserRouter };
-var BrowserRouter;
-(function (BrowserRouter) {
-    function isHashOnlyTarget(target) {
-        return target.startsWith('#');
-    }
-    BrowserRouter.isHashOnlyTarget = isHashOnlyTarget;
-    function isExternalTarget(target, origin) {
-        if (isHashOnlyTarget(target))
-            return false;
-        try {
-            return new URL(target, origin).origin !== origin;
-        }
-        catch {
-            return false;
-        }
-    }
-    BrowserRouter.isExternalTarget = isExternalTarget;
-    /**
-     * Convert a route pattern and params into a real path string. This is used internally
-     * to implement <Link /> and router.go
-     */
-    function toTarget(path, params, query) {
-        // keep track of which params were consumed by named `:param` slots
-        const used = new Set();
-        // replace each named route param with its URL-encoded value
-        let to = path.replaceAll(/:([A-Za-z0-9_]+)/g, (_, key) => {
-            const value = params?.[key];
-            if (value == null) {
-                throw new Error(`[Link]: missing route param: ${key}`);
-            }
-            used.add(key);
-            return encodeURIComponent(value);
-        });
-        if (to.includes('*')) {
-            // wildcard routes use the one param that was not already matched by a named slot
-            const remaining = Object.entries(params ?? {}).filter(([key]) => !used.has(key));
-            if (remaining.length !== 1) {
-                throw new Error('[Link]: wildcard routes require exactly one unmatched param');
-            }
-            // encode each path segment separately so embedded '/' still acts like a path separator
-            to = to.replace('*', remaining[0][1].split('/').map(encodeURIComponent).join('/'));
-        }
-        if (!query)
-            return to;
-        // split the URL up so new query params can be merged without losing an existing hash
-        const hashIndex = to.indexOf('#');
-        const hash = hashIndex >= 0 ? to.slice(hashIndex) : '';
-        const pathWithSearch = hashIndex >= 0 ? to.slice(0, hashIndex) : to;
-        const searchIndex = pathWithSearch.indexOf('?');
-        const pathname = searchIndex >= 0 ? pathWithSearch.slice(0, searchIndex) : pathWithSearch;
-        const currentSearch = searchIndex >= 0 ? pathWithSearch.slice(searchIndex + 1) : '';
-        const search = new URLSearchParams(currentSearch);
-        // later values win, so passed query props overwrite any existing query string values
-        for (const [key, value] of Object.entries(query)) {
-            search.set(key, String(value));
-        }
-        const value = search.toString();
-        // rebuild the URL in the same order: pathname, optional query string, then hash
-        return `${pathname}${value.length > 0 ? `?${value}` : ''}${hash}`;
-    }
-    BrowserRouter.toTarget = toTarget;
-})(BrowserRouter || (BrowserRouter = {}));
+import { Prefetcher } from '../prefetcher.js';
+import { BrowserRouter } from './shared.js';
+export { BrowserRouter } from './shared.js';
 export const BrowserRouterContext = createContext({
     go: async () => '',
     prefetch: () => { },
@@ -80,28 +19,16 @@ const DEFAULT_GO_CONFIG = {
 const logger = new Logger();
 const prefetcher = new Prefetcher();
 export function BrowserRouterProvider({ children, setPayload, isNavigating = false, url, }) {
-    // id to track active navigations
     const id = useRef(0);
-    // abort controller for in-flight navigation
     const controller = useRef(null);
-    /**
-     * Navigate to a new route
-     * @param to the destination url (absolute or relative to origin)
-     * @param opts navigation options
-     * @returns the path that was navigated to (relative to origin)
-     */
     const go = useCallback(async (to, opts = {}) => {
-        // increment navigation id to invalidate any in-flight navigations
         id.current += 1;
         const navigationId = id.current;
-        // fallback for abort/error paths
         const currentPath = window.location.pathname + window.location.search;
         let path = currentPath;
         const replace = opts?.replace ?? DEFAULT_GO_CONFIG.replace;
         controller.current?.abort();
         controller.current = null;
-        // distinguish an actual prior prefetch from a cache entry we create
-        // opportunistically for this navigation
         let existing = false;
         try {
             const target = BrowserRouter.toTarget(to, opts.params, opts.query);
@@ -112,10 +39,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
             const key = Prefetcher.key(url.toString(), window.location.origin);
             if (!key)
                 throw new Error('Invalid navigation url');
-            // switch to the normalised target once the url is valid
             path = key;
-            // internal client navigation should update the route immediately, even
-            // if the subsequent fetch resolves to a 404 or other error state
             if (path !== currentPath) {
                 if (replace) {
                     window.history.replaceState(null, '', path);
@@ -124,9 +48,6 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                     window.history.pushState(null, '', path);
                 }
             }
-            // if the target was already prefetched, use the cached response promise
-            // and set existing to true so we don't remove it from cache
-            // after navigation
             let promise = prefetcher.get(path);
             existing = promise !== undefined;
             if (!promise) {
@@ -138,27 +59,18 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                 });
                 prefetcher.set(path, promise);
             }
-            // if another navigation has started since this one, ignore the result
-            // and return early
             if (navigationId !== id.current)
                 return path;
-            // we need both the parsed payload and the final response url because
-            // redirects can change the canonical path we should store in history
             const [res, payload] = await Promise.all([
                 promise,
                 createFromFetch(promise),
             ]);
-            // use the final response url so client history matches server redirects
             const resolvedPath = Prefetcher.key(res.url, window.location.origin) ?? path;
-            // check again if another navigation has started while we were awaiting
-            // the response
             if (navigationId !== id.current)
                 return resolvedPath;
             if (resolvedPath !== path) {
                 window.history.replaceState(null, '', resolvedPath);
             }
-            // this state update is already wrapped in a
-            // transition before being passed as props
             setPayload?.(payload);
             window.dispatchEvent(new CustomEvent(Solas.Events.names.NAVIGATION, {
                 detail: { path: resolvedPath },
@@ -180,20 +92,12 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
         finally {
             if (navigationId === id.current)
                 controller.current = null;
-            // keep entries that were already in the prefetch cache before go() ran. Only remove
-            // the temporary cache entry go() created for its own in-flight dedupe
             if (!existing) {
-                // this fetch was not an intentional prefetch, so do not leave it behind
-                // as a reusable cache entry after navigation finishes
                 prefetcher.remove(path);
             }
         }
         return path;
     }, [setPayload]);
-    /**
-     * Prefetch a route's RSC payload
-     * @param path the route path to prefetch (absolute or relative to origin)
-     */
     const prefetch = useCallback((path) => {
         const key = Prefetcher.key(path, window.location.origin);
         if (!key)