@veap/plugins 0.0.0-stage → 0.1.0

package/dist/router/matcher.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unified route matcher for Veap.
+ * Supports standard parameters (:id) and catch-all patterns (:path(.*)).
+ */
+export declare function matchRoute(pattern: string, path: string): Record<string, string> | null;

package/dist/router/matcher.js

@@ -0,0 +1,32 @@
+/**
+ * Unified route matcher for Veap.
+ * Supports standard parameters (:id) and catch-all patterns (:path(.*)).
+ */
+export function matchRoute(pattern, path) {
+    const paramNames = [];
+    let regexStr = pattern;
+    // Replace :name(.*) (catch-all) and :name (dynamic) in a single pass so that
+    // capture-group order always matches the order of placeholders in the
+    // pattern. Doing it in two passes would collect catch-all names first even
+    // when they appear after dynamic params in the pattern.
+    regexStr = regexStr.replace(/:([a-zA-Z0-9_]+)\(\.\*\)|:([a-zA-Z0-9_]+)/g, (_, catchAllName, dynamicName) => {
+        if (catchAllName) {
+            paramNames.push(catchAllName);
+            return "(.*)";
+        }
+        paramNames.push(dynamicName);
+        return "([^\\/]+)";
+    });
+    // Escape slashes
+    regexStr = regexStr.replace(/\//g, "\\/");
+    const regex = new RegExp(`^${regexStr}$`);
+    const match = path.match(regex);
+    if (!match)
+        return null;
+    const params = {};
+    paramNames.forEach((name, index) => {
+        // biome-ignore lint/style/noNonNullAssertion: We know the match exists and the index is valid
+        params[name] = match[index + 1];
+    });
+    return params;
+}

package/dist/router/middlewares.d.ts

@@ -0,0 +1,25 @@
+import type { ApiMiddleware, VeapMiddleware, VeapMiddlewareContext } from "../common/types";
+export declare const EnsuredGuest: VeapMiddleware;
+export declare const EnsuredUser: VeapMiddleware;
+/**
+ * Page-level opt-out from modular security requirements (2FA challenges,
+ * onboarding gates, ...). Append it AFTER EnsuredAuth in a page's
+ * `middlewares` export. Its marker propagates to the renderer, which skips
+ * EnsuredAuth entirely for this route, while explicit auth/roles/permissions
+ * (from the page itself) are still enforced by the pipeline below.
+ */
+export declare const SkipSecurity: VeapMiddleware;
+export declare const EnsuredAuth: VeapMiddleware;
+export declare const ApiEnsuredAuth: ApiMiddleware;
+/**
+ * Route middleware enforcing same-origin requests for state-changing operations.
+ * Throws AppError.Forbidden if request originates from an untrusted origin.
+ */
+export declare const SameOrigin: VeapMiddleware;
+/**
+ * API route middleware enforcing same-origin requests for state-changing operations.
+ * Returns a 403 JSON Response if request originates from an untrusted origin.
+ */
+export declare const ApiSameOrigin: ApiMiddleware;
+export declare function runPipeline(middlewares: VeapMiddleware[], context: VeapMiddlewareContext, final: (context: VeapMiddlewareContext) => Promise<React.ReactNode>): Promise<React.ReactNode>;
+export declare function runApiPipeline(middlewares: ApiMiddleware[], request: Request, context: any, final: (request: Request, context: any) => Promise<Response>): Promise<Response>;

package/dist/router/middlewares.js

@@ -0,0 +1,119 @@
+import { checkSecurity, getAuthRoutes, getCurrentSession } from "@veap/auth";
+import { AppError, verifySameOrigin } from "@veap/kernel";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+export const EnsuredGuest = async (ctx, next) => {
+    const { user, session } = await getCurrentSession();
+    if (user && session) {
+        const headersList = await headers();
+        const referer = headersList.get("referer");
+        if (referer && !referer.includes(ctx.path)) {
+            return redirect(referer);
+        }
+        return redirect("/");
+    }
+    return await next();
+};
+export const EnsuredUser = async (_ctx, next) => {
+    const { user, session } = await getCurrentSession();
+    if (!user || !session) {
+        const authRoutes = getAuthRoutes();
+        return redirect(authRoutes.signIn);
+    }
+    return await next();
+};
+/**
+ * Page-level opt-out from modular security requirements (2FA challenges,
+ * onboarding gates, ...). Append it AFTER EnsuredAuth in a page's
+ * `middlewares` export. Its marker propagates to the renderer, which skips
+ * EnsuredAuth entirely for this route, while explicit auth/roles/permissions
+ * (from the page itself) are still enforced by the pipeline below.
+ */
+export const SkipSecurity = async (ctx, next) => {
+    ctx.__skipSecurity =
+        true;
+    return await next();
+};
+export const EnsuredAuth = async (ctx, next) => {
+    const { user, session } = await getCurrentSession();
+    const authRoutes = getAuthRoutes();
+    if (!user || !session) {
+        return redirect(authRoutes.signIn);
+    }
+    const security = await checkSecurity(session, user, ctx.roles, ctx.permissions, undefined, ctx.path);
+    if (!security.satisfied) {
+        return redirect(security.redirect || authRoutes.signIn);
+    }
+    return await next();
+};
+export const ApiEnsuredAuth = async (_request, context, next) => {
+    const { user, session } = await getCurrentSession();
+    if (!user || !session) {
+        return new Response(JSON.stringify({ error: "Unauthorized" }), {
+            status: 401,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    const security = await checkSecurity(session, user, context.roles, context.permissions, undefined, context.path);
+    if (!security.satisfied) {
+        return new Response(JSON.stringify({
+            error: "Security requirement not met",
+            redirect: security.redirect,
+        }), {
+            status: 401,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    return await next();
+};
+/**
+ * Route middleware enforcing same-origin requests for state-changing operations.
+ * Throws AppError.Forbidden if request originates from an untrusted origin.
+ */
+export const SameOrigin = async (_ctx, next) => {
+    const headersList = await headers();
+    const origin = headersList.get("origin");
+    const secFetchSite = headersList.get("sec-fetch-site");
+    const secFetchMode = headersList.get("sec-fetch-mode");
+    if (origin || (secFetchSite && secFetchMode !== "navigate")) {
+        if (!verifySameOrigin({ headers: headersList, method: "POST" })) {
+            throw AppError.Forbidden("Cross-origin request rejected");
+        }
+    }
+    return await next();
+};
+/**
+ * API route middleware enforcing same-origin requests for state-changing operations.
+ * Returns a 403 JSON Response if request originates from an untrusted origin.
+ */
+export const ApiSameOrigin = async (request, _context, next) => {
+    if (!verifySameOrigin(request)) {
+        return new Response(JSON.stringify({ error: "Forbidden: Cross-origin request rejected" }), {
+            status: 403,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    return await next();
+};
+export async function runPipeline(middlewares, context, final) {
+    let index = 0;
+    async function next() {
+        if (index < middlewares.length) {
+            const middleware = middlewares[index++];
+            return await middleware(context, next);
+        }
+        return await final(context);
+    }
+    return await next();
+}
+export async function runApiPipeline(middlewares, request, context, final) {
+    let index = 0;
+    async function next() {
+        if (index < middlewares.length) {
+            const middleware = middlewares[index++];
+            return await middleware(request, context, next);
+        }
+        return await final(request, context);
+    }
+    return await next();
+}

package/dist/router/react/error-boundary.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+interface ErrorBoundaryProps {
+    children: React.ReactNode;
+    fallback?: React.ComponentType<{
+        error: Error;
+        reset: () => void;
+    }>;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+    resetKey: number;
+}
+/**
+ * Client-side error boundary for the Veap unstable router.
+ *
+ * Wraps route segments to catch rendering errors and display
+ * a recoverable fallback UI. Supports custom fallback components
+ * or renders a default error panel.
+ *
+ * Reset is implemented via internal key increment, which forces
+ * React to remount the children subtree.
+ */
+export declare class RouterErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    private reset;
+    render(): React.ReactNode;
+}
+export {};

package/dist/router/react/error-boundary.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+/**
+ * Client-side error boundary for the Veap unstable router.
+ *
+ * Wraps route segments to catch rendering errors and display
+ * a recoverable fallback UI. Supports custom fallback components
+ * or renders a default error panel.
+ *
+ * Reset is implemented via internal key increment, which forces
+ * React to remount the children subtree.
+ */
+export class RouterErrorBoundary extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = { error: null, resetKey: 0 };
+    }
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, errorInfo) {
+        if (process.env.NODE_ENV === "development") {
+            console.warn("[veap:Router] Caught error during rendering:", error, errorInfo);
+        }
+    }
+    reset = () => {
+        this.setState((prev) => ({
+            error: null,
+            resetKey: prev.resetKey + 1,
+        }));
+    };
+    render() {
+        const { error, resetKey } = this.state;
+        const { children, fallback: Fallback } = this.props;
+        if (error !== null) {
+            if (Fallback) {
+                return _jsx(Fallback, { error: error, reset: this.reset });
+            }
+            return (_jsxs("div", { role: "alert", style: {
+                    padding: "2rem",
+                    borderRadius: "0.5rem",
+                    border: "1px solid #fca5a5",
+                    backgroundColor: "#fef2f2",
+                    color: "#991b1b",
+                    fontFamily: "system-ui, -apple-system, sans-serif",
+                }, children: [_jsx("h2", { style: {
+                            margin: "0 0 0.5rem",
+                            fontSize: "1.125rem",
+                            fontWeight: 600,
+                        }, children: "Something went wrong" }), _jsx("p", { style: {
+                            margin: "0 0 1rem",
+                            fontSize: "0.875rem",
+                            color: "#b91c1c",
+                        }, children: error.message }), _jsx("button", { type: "button", onClick: this.reset, style: {
+                            padding: "0.5rem 1rem",
+                            fontSize: "0.875rem",
+                            fontWeight: 500,
+                            color: "#ffffff",
+                            backgroundColor: "#dc2626",
+                            border: "none",
+                            borderRadius: "0.375rem",
+                            cursor: "pointer",
+                        }, children: "Try again" })] }));
+        }
+        return _jsx(React.Fragment, { children: children }, resetKey);
+    }
+}

package/dist/router/react/index.d.ts

@@ -0,0 +1,4 @@
+export { RouterErrorBoundary } from "./error-boundary";
+export { VeapRouter } from "./renderer";
+export { SoftNavigationInterceptor } from "./soft-navigation";
+export { type WithRouterConfig, withRouter } from "./with-router";

package/dist/router/react/index.js

@@ -0,0 +1,4 @@
+export { RouterErrorBoundary } from "./error-boundary";
+export { VeapRouter } from "./renderer";
+export { SoftNavigationInterceptor } from "./soft-navigation";
+export { withRouter } from "./with-router";

package/dist/router/react/renderer.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+import type { RouteTree } from "../route-tree";
+export declare function VeapRouter({ tree, path, searchParams, CustomPageComponent, customConfig, }: {
+    tree: RouteTree;
+    path: string;
+    searchParams: Record<string, any>;
+    CustomPageComponent?: React.ComponentType<any>;
+    customConfig?: {
+        roles?: string[];
+        permissions?: string[];
+        middlewares?: any[];
+    };
+}): Promise<React.ReactNode>;

package/dist/router/react/renderer.js

@@ -0,0 +1,159 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { eventBus } from "@veap/kernel/events";
+import * as React from "react";
+import { EnsuredAuth, runPipeline, SkipSecurity } from "../middlewares";
+import { collectAuthRequirements, collectMiddlewares } from "../utils";
+import { RouterErrorBoundary } from "./error-boundary";
+import { SoftNavigationInterceptor } from "./soft-navigation";
+// ---------------------------------------------------------------------------
+// Parallel slot resolution
+// ---------------------------------------------------------------------------
+async function resolveParallelSlot(slotTree, path, searchParams, params, _slotName, context) {
+    const { RouteTree: RouteTreeClass } = await import("../route-tree");
+    const tempTree = new RouteTreeClass(slotTree);
+    const slotMatch = tempTree.match(path);
+    if (slotMatch?.node.page) {
+        const SlotPage = slotMatch.node.page;
+        const mergedParams = { ...params, ...slotMatch.params };
+        return (_jsx(SlotPage, { params: mergedParams, searchParams: searchParams, context: context }));
+    }
+    if (slotTree.default) {
+        const DefaultComponent = slotTree.default;
+        return (_jsx(DefaultComponent, { params: params, searchParams: searchParams, context: context }));
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Parallel slots resolver (all slots for a layout entry)
+// ---------------------------------------------------------------------------
+async function resolveAllParallelSlots(parallelSlots, path, searchParams, params, context) {
+    if (!parallelSlots || Object.keys(parallelSlots).length === 0) {
+        return {};
+    }
+    const entries = await Promise.all(Object.entries(parallelSlots).map(async ([slotName, slotNode]) => {
+        const rendered = await resolveParallelSlot(slotNode, path, searchParams, params, slotName, context);
+        return [slotName, rendered];
+    }));
+    const result = {};
+    for (const [name, node] of entries) {
+        result[name] = node;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Main renderer
+// ---------------------------------------------------------------------------
+export async function VeapRouter({ tree, path, searchParams, CustomPageComponent, customConfig, }) {
+    const match = tree.match(path);
+    if (process.env.NODE_ENV !== "production") {
+        eventBus
+            .publish("router:request", {
+            path,
+            searchParams,
+            params: match?.params || {},
+            matchedNode: match?.node?.segment || "/",
+            timestamp: Date.now(),
+        })
+            .catch(() => { });
+    }
+    if (!match) {
+        console.warn("[veap:Router] [renderer] match should never be null");
+        throw new Error(`[VeapRouter] Invariant failed: match should never be null`);
+    }
+    const allMiddlewares = collectMiddlewares(match.layoutChain, match.node);
+    const auth = collectAuthRequirements(match.layoutChain, match.node);
+    if (customConfig) {
+        if (customConfig.roles?.length) {
+            auth.roles.push(...customConfig.roles);
+            auth.needsAuth = true;
+        }
+        if (customConfig.permissions?.length) {
+            auth.permissions.push(...customConfig.permissions);
+            auth.needsAuth = true;
+        }
+        if (customConfig.middlewares?.length) {
+            allMiddlewares.push(...customConfig.middlewares);
+        }
+    }
+    if (auth.needsAuth && !allMiddlewares.includes(SkipSecurity)) {
+        allMiddlewares.unshift(EnsuredAuth);
+    }
+    const context = {
+        params: match.params,
+        searchParams,
+        path,
+        roles: auth.roles.length > 0 ? auth.roles : undefined,
+        permissions: auth.permissions.length > 0 ? auth.permissions : undefined,
+    };
+    return runPipeline(allMiddlewares, context, async (ctx) => {
+        return buildLayoutTree(match, searchParams, path, ctx, CustomPageComponent);
+    });
+}
+// ---------------------------------------------------------------------------
+// Layout tree builder
+// ---------------------------------------------------------------------------
+async function buildLayoutTree(match, searchParams, path, context, CustomPageComponent) {
+    const { node, params, layoutChain } = match;
+    const { getPluginBreadcrumbs: getBreadcrumbs } = await import("../../navigation/breadcrumbs");
+    const breadcrumbs = await getBreadcrumbs(path, searchParams);
+    let content;
+    if (CustomPageComponent) {
+        content = (_jsx(CustomPageComponent, { params: params, searchParams: searchParams, breadcrumbs: breadcrumbs, context: context }));
+    }
+    else if (match.isExact && node.page) {
+        const Page = node.page;
+        content = (_jsx(Page, { params: params, searchParams: searchParams, breadcrumbs: breadcrumbs, context: context }));
+    }
+    else {
+        let NotFound = node.notFound;
+        if (!NotFound) {
+            for (let i = layoutChain.length - 1; i >= 0; i--) {
+                if (layoutChain[i].notFound) {
+                    NotFound = layoutChain[i].notFound;
+                    break;
+                }
+            }
+        }
+        if (NotFound) {
+            content = _jsx(NotFound, {});
+        }
+        else {
+            content = (_jsx("div", { role: "alert", style: {
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    minHeight: "50vh",
+                    fontFamily: "system-ui, -apple-system, sans-serif",
+                }, children: _jsxs("div", { style: { textAlign: "center" }, children: [_jsx("h1", { style: { fontSize: "3rem", fontWeight: 700, margin: "0 0 1rem" }, children: "404" }), _jsxs("p", { style: { fontSize: "1.125rem", color: "#6b7280" }, children: ["Page not found:", " ", _jsx("code", { style: {
+                                        padding: "0.125rem 0.375rem",
+                                        borderRadius: "0.25rem",
+                                        backgroundColor: "#f3f4f6",
+                                        fontSize: "0.875rem",
+                                    }, children: path })] })] }) }));
+        }
+    }
+    if (node.error) {
+        content = _jsx(RouterErrorBoundary, { children: content });
+    }
+    const reversedChain = [...layoutChain].reverse();
+    for (const entry of reversedChain) {
+        if (entry.error) {
+            content = (_jsx(RouterErrorBoundary, { children: content }, `error-${entry.consumedPath || entry.id || "root"}`));
+        }
+        if (entry.loading) {
+            const Loading = entry.loading;
+            content = (_jsx(React.Suspense, { fallback: _jsx(Loading, {}), children: content }, `suspense-${entry.consumedPath || entry.id || "root"}`));
+        }
+        if (entry.layout) {
+            const Layout = entry.layout;
+            const consumedCount = entry.consumedPath
+                ? entry.consumedPath.split("/").filter(Boolean).length
+                : 0;
+            const remainingSegments = match.matchedSegments.slice(consumedCount);
+            const remainingPath = remainingSegments.join("/") || "/";
+            const resolvedSlots = await resolveAllParallelSlots(entry.parallelSlots, remainingPath, searchParams, params, context);
+            content = (_jsx(Layout, { params: params, context: context, ...resolvedSlots, children: content }));
+        }
+    }
+    return _jsx(SoftNavigationInterceptor, { children: content });
+}

package/dist/router/react/soft-navigation.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+export declare function SoftNavigationInterceptor({ children, }: {
+    children: React.ReactNode;
+}): React.JSX.Element;

package/dist/router/react/soft-navigation.js

@@ -0,0 +1,34 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useRouter } from "next/navigation";
+import * as React from "react";
+export function SoftNavigationInterceptor({ children, }) {
+    const router = useRouter();
+    React.useEffect(() => {
+        const handleClick = (e) => {
+            // Ignore clicks with modifiers
+            if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey || e.button !== 0) {
+                return;
+            }
+            // Find the closest anchor tag
+            let target = e.target;
+            while (target && target.tagName !== "A") {
+                target = target.parentElement;
+            }
+            if (!target)
+                return;
+            const anchor = target;
+            const href = anchor.getAttribute("href");
+            // Only intercept internal links
+            if (href?.startsWith("/") &&
+                !href.startsWith("//") &&
+                anchor.target !== "_blank") {
+                e.preventDefault();
+                router.push(href);
+            }
+        };
+        document.addEventListener("click", handleClick);
+        return () => document.removeEventListener("click", handleClick);
+    }, [router]);
+    return _jsx(_Fragment, { children: children });
+}

package/dist/router/react/with-router.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+/**
+ * A Higher-Order Component (HOC) that wraps a physical Next.js page component
+ * with the Veap Virtual Router. This allows physical pages to inherit virtual layouts,
+ * parallel slots (like @sidebar), and middleware protection from plugins.
+ *
+ * @example
+ * ```tsx
+ * import { withRouter } from "@veap/plugins/router";
+ *
+ * export default withRouter(async function CustomPage() {
+ *    return <div>My Custom Physical Page</div>;
+ * }, "/app/custom");
+ * ```
+ */
+export interface WithRouterConfig {
+    path?: string;
+    roles?: string[];
+    permissions?: string[];
+    middlewares?: any[];
+}
+export declare function withRouter(Component: React.ComponentType<any>, configOrPath?: WithRouterConfig | string): (props: any) => Promise<React.JSX.Element>;

package/dist/router/react/with-router.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { headers } from "next/headers";
+import { buildRouteTree } from "../discovery";
+import { VeapRouter } from "./renderer";
+export function withRouter(Component, configOrPath) {
+    return async function WrappedPage(props) {
+        const searchParams = (await props.searchParams) || {};
+        const config = typeof configOrPath === "string"
+            ? { path: configOrPath }
+            : configOrPath || {};
+        let routePath = config.path;
+        if (!routePath) {
+            const headersList = await headers();
+            routePath = headersList.get("x-invoke-path") || "/";
+        }
+        const tree = await buildRouteTree(true);
+        return (_jsx(VeapRouter, { tree: tree, path: routePath || "/", searchParams: searchParams, CustomPageComponent: Component, customConfig: config }));
+    };
+}