@terreno/admin-spa 58.0.0-beta.2 → 58.0.0-beta.4

package/src/dist/gate.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdminSpaGate = void 0;
+const api_1 = require("@terreno/api");
+const returnTo_1 = require("./returnTo");
+const serverContext_1 = require("./serverContext");
+const signedInOnlyRoutes_1 = require("./signedInOnlyRoutes");
+/** Longest the gate waits on any of its loopback reads before failing closed. */
+const UPSTREAM_TIMEOUT_MS = 5000;
+/** Where Expo's client fetches route loader data, at the site root and under `basePath`. */
+const LOADERS_PATH = "/_expo/loaders";
+/** Paths under `basePath` that are never gated: hashed assets and the runtime config. */
+const UNGATED_PREFIXES = ["/_expo/static", "/assets", "/app-config.json"];
+/** Routes an anonymous or forbidden visitor may render (and load data for). */
+const PUBLIC_ROUTES = new Set(["/login", "/forbidden"]);
+/** Statuses the gate understands; anything else fails closed. */
+const KNOWN_STATUSES = new Set([200, 401, 403]);
+const ANONYMOUS = {
+    access: "anonymous",
+    adminConfig: null,
+    adminConfigStatus: null,
+    profile: null,
+    session: null,
+};
+/** Thrown when an upstream read fails in a way the gate cannot decide on. */
+class GateUnavailableError extends Error {
+}
+/** Base for resolving a request URL on its own. */
+const URL_BASE = "http://gate.invalid";
+/** Characters RFC 3986 calls unreserved: an escape of one of them means the character itself. */
+const UNRESERVED = /^[A-Za-z0-9\-._~]$/;
+/**
+ * RFC 3986 percent-encoding normalization: decode escapes of unreserved characters and
+ * uppercase the hex of the rest. `/console/User/%36ae…` and `/console/User/6ae…` name the same
+ * record, and Expo keys loader data by the raw path while the router looks it up by the decoded
+ * params, so only the canonical form renders with its data. The URL parser already treats `%2E`
+ * as a dot, so this changes no dot-segment decision.
+ */
+const canonicalizeEscapes = (url) => {
+    return url.replace(/%([0-9A-Fa-f]{2})/g, (match, hex) => {
+        const character = String.fromCharCode(Number.parseInt(hex, 16));
+        return UNRESERVED.test(character) ? character : match.toUpperCase();
+    });
+};
+/**
+ * Classify a request by its normalized path: dot segments, including encoded ones, resolved
+ * the way Expo will resolve them. Deciding on the raw path would let `/console/assets/../Todo`
+ * pass as an asset and then render as `/Todo`.
+ */
+const classify = (method, requestPath, basePath) => {
+    const isRead = method === "GET" || method === "HEAD";
+    if (requestPath.startsWith(`${LOADERS_PATH}/`)) {
+        return isRead
+            ? { kind: "loader", route: requestPath.slice(LOADERS_PATH.length) }
+            : { kind: "write" };
+    }
+    if (requestPath !== basePath && !requestPath.startsWith(`${basePath}/`)) {
+        return { kind: "outside" };
+    }
+    if (!isRead) {
+        return { kind: "write" };
+    }
+    const inner = requestPath.slice(basePath.length) || "/";
+    if (inner.startsWith(`${LOADERS_PATH}/`)) {
+        return { kind: "loader", route: inner.slice(LOADERS_PATH.length) };
+    }
+    if (UNGATED_PREFIXES.some((prefix) => inner === prefix || inner.startsWith(`${prefix}/`))) {
+        return { kind: "static" };
+    }
+    return { kind: "page", route: inner };
+};
+/** One loopback read with the visitor's cookie. Only a 200 body is read. */
+const readUpstream = async (url, cookie) => {
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: cookie ? { Accept: "application/json", Cookie: cookie } : { Accept: "application/json" },
+            redirect: "manual",
+            signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.name : "unknown error";
+        throw new GateUnavailableError(`${new URL(url).pathname} failed: ${reason}`);
+    }
+    if (!KNOWN_STATUSES.has(response.status)) {
+        throw new GateUnavailableError(`${new URL(url).pathname} answered ${response.status}`);
+    }
+    if (response.status !== 200) {
+        return { body: null, status: response.status };
+    }
+    try {
+        return { body: await response.json(), status: 200 };
+    }
+    catch {
+        throw new GateUnavailableError(`${new URL(url).pathname} answered a body that is not JSON`);
+    }
+};
+/** The session snapshot from a Better Auth `get-session` body, or null when signed out. */
+const sessionSnapshotOf = (body) => {
+    const value = body;
+    const userId = value?.session?.userId;
+    if (typeof userId !== "string" || !value?.user) {
+        return null;
+    }
+    return { user: value.user, userId };
+};
+/** Read the session, profile and admin config in parallel and decide the visitor's access. */
+const loadShellPayload = async (req, { adminApiBasePath, appConfig, internalOrigin }) => {
+    const cookie = req.headers.cookie;
+    const authBasePath = appConfig.authBasePath ?? "/api/auth";
+    const [session, profile, config] = await Promise.all([
+        readUpstream(`${internalOrigin}${authBasePath}/get-session`, cookie),
+        readUpstream(`${internalOrigin}/auth/me`, cookie),
+        readUpstream(`${internalOrigin}${adminApiBasePath}/config`, cookie),
+    ]);
+    const snapshot = session.status === 200 ? sessionSnapshotOf(session.body) : null;
+    if (!snapshot || profile.status === 401 || config.status === 401) {
+        return ANONYMOUS;
+    }
+    const profileBody = profile.status === 200 ? profile.body : null;
+    if (config.status === 403) {
+        return {
+            access: "forbidden",
+            adminConfig: null,
+            adminConfigStatus: 403,
+            profile: profileBody,
+            session: snapshot,
+        };
+    }
+    return {
+        access: "admin",
+        adminConfig: config.body,
+        adminConfigStatus: 200,
+        profile: profileBody,
+        session: snapshot,
+    };
+};
+/**
+ * Express middleware that decides access before the admin SPA renders anything. Mounted at
+ * the site root, it gates `GET` page and loader requests under `basePath` and loader requests
+ * at the root `/_expo/loaders`, and passes every other path through.
+ *
+ * - Anonymous: pages other than `/login` redirect to `{basePath}/login?returnTo=<path>`;
+ *   loaders answer 401 JSON (the `login` and `forbidden` loaders run).
+ * - Signed in but not an admin (`/admin/config` 403): signed-in-only routes (`/oauth/consent`)
+ *   render, `/login` with a safe `returnTo` redirects there; other pages redirect to
+ *   `{basePath}/forbidden`;
+ *   loaders answer 403 JSON.
+ * - Admin: `/login` redirects to a safe `returnTo` (or `{basePath}/`); everything else renders
+ *   inside a request scope holding the session, profile and admin config, so the page renders
+ *   with its shell instead of a spinner.
+ * - An upstream answer other than 200 / 401 / 403, a network error or a 5 s timeout answers
+ *   503 without rendering. A 401 counts as anonymous.
+ */
+const createAdminSpaGate = (options) => {
+    const { appConfig, handler } = options;
+    const basePath = options.basePath === "/" ? "" : options.basePath;
+    const render = (req, res, next, payload) => {
+        const scope = {
+            adminConfig: payload.adminConfig,
+            adminConfigStatus: payload.adminConfigStatus,
+            appConfig,
+            basePath: options.basePath,
+            profile: payload.profile,
+            session: payload.session,
+        };
+        (0, serverContext_1.runInAdminSpaRequest)(scope, () => handler(req, res, next));
+    };
+    // Every decision depends on the visitor's session, so no redirect may be cached or shared.
+    const redirect = (res, location) => {
+        res.set("Cache-Control", "no-store, private").redirect(302, location);
+    };
+    const deny = (res, status) => {
+        res
+            .status(status)
+            .set("Cache-Control", "no-store, private")
+            .json({ title: status === 401 ? "Unauthorized" : "Forbidden" });
+    };
+    return (req, res, next) => {
+        const normalized = new URL(canonicalizeEscapes(req.url), URL_BASE);
+        const classified = classify(req.method, normalized.pathname, basePath);
+        // Static paths are served by the static middleware mounted before the gate. A miss must
+        // never reach the page renderer, which would render it as a route (`/assets/Todo` matches
+        // `[model]/[id]`) without an access decision.
+        if (classified.kind === "outside" || classified.kind === "static") {
+            next();
+            return;
+        }
+        // Hand the renderer exactly the path the gate decided on.
+        req.url = `${normalized.pathname}${normalized.search}`;
+        // The admin SPA serves only reads: a write never reaches the renderer or a loader.
+        if (classified.kind === "write") {
+            next();
+            return;
+        }
+        const decide = async () => {
+            const payload = req.user ? await loadShellPayload(req, options) : ANONYMOUS;
+            const { route } = classified;
+            const isPublic = PUBLIC_ROUTES.has(route);
+            // Signed-in-only routes (MCP OAuth consent) render for any signed-in user.
+            const isOpenToVisitor = isPublic || (payload.access !== "anonymous" && (0, signedInOnlyRoutes_1.isSignedInOnlyRoute)(route));
+            if (classified.kind === "loader") {
+                if (payload.access === "admin" || isOpenToVisitor) {
+                    render(req, res, next, payload);
+                    return;
+                }
+                deny(res, payload.access === "anonymous" ? 401 : 403);
+                return;
+            }
+            if (payload.access === "anonymous") {
+                if (route === "/login") {
+                    render(req, res, next, payload);
+                    return;
+                }
+                const search = req.url.includes("?") ? req.url.slice(req.url.indexOf("?")) : "";
+                const returnTo = encodeURIComponent(`${route}${search}`);
+                redirect(res, `${basePath}/login?returnTo=${returnTo}`);
+                return;
+            }
+            if (payload.access === "forbidden") {
+                // Like the client gate: a signed-in user on /login goes to a safe returnTo, which
+                // renders when signed-in-only (the MCP consent flow) and otherwise redirects again.
+                const forbiddenTarget = route === "/login"
+                    ? (0, returnTo_1.sanitizeReturnTo)(req.query.returnTo)
+                    : null;
+                if (forbiddenTarget) {
+                    redirect(res, `${basePath}${forbiddenTarget}`);
+                    return;
+                }
+                if (isOpenToVisitor) {
+                    render(req, res, next, payload);
+                    return;
+                }
+                redirect(res, `${basePath}/forbidden`);
+                return;
+            }
+            if (route === "/login") {
+                const target = (0, returnTo_1.sanitizeReturnTo)(req.query.returnTo);
+                redirect(res, `${basePath}${target ?? "/"}`);
+                return;
+            }
+            if (route === "/forbidden") {
+                redirect(res, `${basePath}/`);
+                return;
+            }
+            render(req, res, next, payload);
+        };
+        decide().catch((error) => {
+            if (!(error instanceof GateUnavailableError)) {
+                next(error);
+                return;
+            }
+            api_1.logger.warn(`Admin SPA gate failed closed for ${req.path}`, { reason: error.message });
+            res
+                .status(503)
+                .set("Cache-Control", "no-store, private")
+                .type("text")
+                .send("Admin SPA unavailable");
+        });
+    };
+};
+exports.createAdminSpaGate = createAdminSpaGate;

package/src/dist/returnTo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Accept a post-login destination only when it is an in-app path ("/oauth/consent?request=abc"):
+ * one leading `/`, no second `/` right after it, no backslash, whitespace or control character,
+ * and not the login page itself. Anything else (an absolute URL, a protocol-relative `//host`,
+ * `/\\host`, a relative path) is an open redirect and yields undefined. A repeated query
+ * parameter uses its first value. The server gate and the client share this one rule.
+ */
+export declare const sanitizeReturnTo: (value: unknown) => string | undefined;

package/src/dist/returnTo.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeReturnTo = void 0;
+// Any ASCII control character or whitespace; a valid in-app path never contains one.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point
+const UNSAFE_RETURN_TO_CHARS = /[\u0000-\u001f\u007f\s\\]/;
+/**
+ * Accept a post-login destination only when it is an in-app path ("/oauth/consent?request=abc"):
+ * one leading `/`, no second `/` right after it, no backslash, whitespace or control character,
+ * and not the login page itself. Anything else (an absolute URL, a protocol-relative `//host`,
+ * `/\\host`, a relative path) is an open redirect and yields undefined. A repeated query
+ * parameter uses its first value. The server gate and the client share this one rule.
+ */
+const sanitizeReturnTo = (value) => {
+    const candidate = Array.isArray(value) ? value[0] : value;
+    if (typeof candidate !== "string" || !candidate.startsWith("/") || candidate.startsWith("//")) {
+        return undefined;
+    }
+    if (UNSAFE_RETURN_TO_CHARS.test(candidate) || candidate.startsWith("/login")) {
+        return undefined;
+    }
+    return candidate;
+};
+exports.sanitizeReturnTo = sanitizeReturnTo;

package/src/dist/routesManifest.d.ts

@@ -0,0 +1,35 @@
+interface RawRoute {
+    page: string;
+    namedRegex: string;
+    [key: string]: unknown;
+}
+/** The parts of an Expo server build's `_expo/routes.json` the serve plugin reads. */
+export interface RawRoutesManifest {
+    assets?: {
+        js?: string[];
+    };
+    htmlRoutes?: RawRoute[];
+    apiRoutes?: RawRoute[];
+    notFoundRoutes?: RawRoute[];
+    redirects?: RawRoute[];
+    rewrites?: RawRoute[];
+    pageHeaders?: RawRoute[];
+    [key: string]: unknown;
+}
+/** Read `_expo/routes.json` from a server build, or undefined when there is no build. */
+export declare const readRoutesManifest: (serverDir: string) => RawRoutesManifest | undefined;
+/**
+ * The baseUrl baked into the build, read from its asset URLs (`/console/_expo/static/...`).
+ * "" for a bundle built for the site root.
+ */
+export declare const bakedBaseUrlOf: (manifest: RawRoutesManifest) => string;
+/**
+ * Prepare the manifest the way expo-server's environment does (regex strings become
+ * `RegExp`s), with HTML routes ordered by specificity. Expo 58 exports `routes.json`
+ * unsorted, and expo-server takes the first regex match, so `/[model]` would shadow `/login`
+ * and render it without its loader data. The router itself already prefers static routes.
+ */
+export declare const prepareRoutesManifest: (raw: RawRoutesManifest, { pageCacheControl }?: {
+    pageCacheControl?: string;
+}) => Record<string, unknown>;
+export {};

package/src/dist/routesManifest.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareRoutesManifest = exports.bakedBaseUrlOf = exports.readRoutesManifest = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const REGEX_LISTS = [
+    "htmlRoutes",
+    "apiRoutes",
+    "notFoundRoutes",
+    "redirects",
+    "rewrites",
+    "pageHeaders",
+];
+/** Read `_expo/routes.json` from a server build, or undefined when there is no build. */
+const readRoutesManifest = (serverDir) => {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(serverDir, "_expo", "routes.json"), "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.readRoutesManifest = readRoutesManifest;
+/**
+ * The baseUrl baked into the build, read from its asset URLs (`/console/_expo/static/...`).
+ * "" for a bundle built for the site root.
+ */
+const bakedBaseUrlOf = (manifest) => {
+    const firstAsset = manifest.assets?.js?.[0] ?? "";
+    const index = firstAsset.indexOf("/_expo/");
+    return index > 0 ? firstAsset.slice(0, index) : "";
+};
+exports.bakedBaseUrlOf = bakedBaseUrlOf;
+/** Expo Router's match priority for one path segment: static, then dynamic, then catch-all. */
+const segmentRank = (segment) => {
+    if (segment.startsWith("[...")) {
+        return 2;
+    }
+    if (segment.startsWith("[")) {
+        return 1;
+    }
+    return 0;
+};
+const routeRanks = (page) => {
+    return page
+        .split("/")
+        .filter((segment) => segment !== "" && !(segment.startsWith("(") && segment.endsWith(")")))
+        .map(segmentRank);
+};
+/** Compare two routes segment by segment: the more specific route sorts first. */
+const compareSpecificity = (a, b) => {
+    const aRanks = routeRanks(a.page);
+    const bRanks = routeRanks(b.page);
+    const length = Math.min(aRanks.length, bRanks.length);
+    for (let index = 0; index < length; index++) {
+        const difference = (aRanks[index] ?? 0) - (bRanks[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+};
+/**
+ * Replace every `Cache-Control` in the manifest's `pageHeaders` rules. Expo exports a
+ * `no-store` rule for every loader response, and expo-server applies it after Express
+ * middleware, so the plugin's own header would be overwritten.
+ */
+const withCacheControl = (routes, cacheControl) => {
+    return routes.map((route) => {
+        const headers = route.headers;
+        if (!headers) {
+            return route;
+        }
+        const kept = Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== "cache-control"));
+        const hadCacheControl = Object.keys(kept).length !== Object.keys(headers).length;
+        return hadCacheControl ? { ...route, headers: { ...kept, "Cache-Control": cacheControl } } : route;
+    });
+};
+/**
+ * Prepare the manifest the way expo-server's environment does (regex strings become
+ * `RegExp`s), with HTML routes ordered by specificity. Expo 58 exports `routes.json`
+ * unsorted, and expo-server takes the first regex match, so `/[model]` would shadow `/login`
+ * and render it without its loader data. The router itself already prefers static routes.
+ */
+const prepareRoutesManifest = (raw, { pageCacheControl } = {}) => {
+    const prepared = { ...raw };
+    for (const list of REGEX_LISTS) {
+        const exported = raw[list];
+        const routes = list === "pageHeaders" && exported && pageCacheControl
+            ? withCacheControl(exported, pageCacheControl)
+            : exported;
+        if (!routes) {
+            // expo-server defaults every list except `pageHeaders` to empty.
+            if (list !== "pageHeaders") {
+                prepared[list] = [];
+            }
+            continue;
+        }
+        const ordered = list === "htmlRoutes" ? [...routes].sort(compareSpecificity) : routes;
+        prepared[list] = ordered.map((route) => ({ ...route, namedRegex: new RegExp(route.namedRegex) }));
+    }
+    return prepared;
+};
+exports.prepareRoutesManifest = prepareRoutesManifest;

package/src/dist/serve.d.ts

@@ -6,28 +6,49 @@ export interface AdminSpaServeOptions {
     basePath?: string;
     /** Runtime config served at `${basePath}/app-config.json`. Merged with defaults. */
     appConfig?: Partial<AdminSpaAppConfig>;
-    /** Override the directory the pre-built bundle is served from (used by tests/custom builds). */
+    /**
+     * Override the export root the bundle is served from: it holds `client/` (static files)
+     * and `server/` (the Expo server build). Used by tests, custom builds, and compiled binaries.
+     */
     distDir?: string;
     /**
      * In dev, proxy all SPA paths to a running `expo start --web` server, e.g.
      * "http://localhost:8083". Avoids re-running `expo export` per change.
      */
     devProxyTarget?: string;
+    /**
+     * Origin the server render fetches API data from, with the visitor's cookie. Default:
+     * `http://127.0.0.1:${PORT ?? 4000}`, this process. Never derived from `Host` or
+     * `X-Forwarded-*`, so a request cannot point the render at another host.
+     */
+    internalOrigin?: string;
+    /**
+     * API path prefixes a server render may fetch. Default: the admin API base path plus
+     * `/auth/me`, `/orgs`, `/jobs`, `/comms`, `/configuration`, and `/rbac`.
+     */
+    ssrApiPrefixes?: string[];
 }
 /**
+ * @deprecated The server-rendered build no longer serves a static index.html. Kept for
+ * consumers of the static-export API; it will be removed in the next major release.
+ *
  * Rewrite the absolute `/_expo/` and `/assets/` references emitted by Expo's static
  * web export so a single pre-built bundle works when mounted at any `basePath`.
  */
 export declare const rewriteIndexHtml: (rawIndex: string, basePath: string) => string;
 /**
+ * @deprecated `+html.tsx` now writes `window.__ADMIN_SPA_BASE__` into the server-rendered
+ * page. Kept for consumers of the static-export API; it will be removed in the next major.
+ *
  * Inject `window.__ADMIN_SPA_BASE__` so the SPA can build absolute URLs (e.g.
  * `${base}/app-config.json`) regardless of the current deep route. Inserted before
  * `</head>` so it runs before the bundle.
  */
 export declare const injectBaseGlobal: (html: string, basePath: string) => string;
 /**
- * Opt-in Express plugin that serves a pre-built admin SPA (Expo Router static export)
- * from the same Node process as a Terreno backend. Mounts at `/console` by default.
+ * Opt-in Express plugin that server-renders the pre-built admin SPA (Expo Router
+ * `web.output: "server"` export) from the same Node process as a Terreno backend. Mounts at
+ * `/console` by default; `basePath` must equal the baseUrl the bundle was built with.
  *
  * @example
  * ```typescript