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

package/src/dist/serve.js

@@ -4,16 +4,42 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdminSpaServeApp = exports.injectBaseGlobal = exports.rewriteIndexHtml = void 0;
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const api_1 = require("@terreno/api");
-const express_1 = __importDefault(require("express"));
+const express_1 = require("expo-server/adapter/express");
+const express_2 = __importDefault(require("express"));
 const appConfig_1 = require("./appConfig");
-// Compiled (CommonJS) file lives at src/dist/serve.js; the pre-built bundle lives at
-// admin-spa/dist. `__dirname` is the CommonJS module-directory global.
+const gate_1 = require("./gate");
+const routesManifest_1 = require("./routesManifest");
+const serverContext_1 = require("./serverContext");
+// Compiled (CommonJS) file lives at src/dist/serve.js; the export root (`client/` +
+// `server/`) lives at admin-spa/dist. `__dirname` is the CommonJS module-directory global.
 const DIST_DIR = node_path_1.default.resolve(__dirname, "../../dist");
 const NO_STORE = "no-store";
+/** Server-rendered pages and loader data can hold PHI: never cached, never shared. */
+const NO_STORE_PRIVATE = "no-store, private";
+/** API prefixes a server render may fetch, besides the admin API base path. */
+const DEFAULT_SSR_API_PREFIXES = [
+    "/auth/me",
+    "/orgs",
+    "/jobs",
+    "/comms",
+    "/configuration",
+    "/rbac",
+];
 /**
+ * The default SSR allowlist: the admin API base, the fixed API roots, and the RBAC root, which
+ * mounts at the API root (`/internal/admin` puts it at `/internal/rbac`, as `useAdminRoles` does).
+ */
+const defaultSsrApiPrefixes = (adminApiBasePath = "/admin") => {
+    const rbacPrefix = `${adminApiBasePath.replace(/\/admin\/?$/, "")}/rbac`;
+    const prefixes = [adminApiBasePath, ...DEFAULT_SSR_API_PREFIXES];
+    return prefixes.includes(rbacPrefix) ? prefixes : [...prefixes, rbacPrefix];
+};
+/**
+ * @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`.
  */
@@ -26,6 +52,9 @@ const rewriteIndexHtml = (rawIndex, basePath) => {
 };
 exports.rewriteIndexHtml = rewriteIndexHtml;
 /**
+ * @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.
@@ -39,8 +68,9 @@ const injectBaseGlobal = (html, basePath) => {
 };
 exports.injectBaseGlobal = injectBaseGlobal;
 /**
- * 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
@@ -78,31 +108,96 @@ class AdminSpaServeApp {
             api_1.logger.info(`Admin SPA dev-proxied to ${this.opts.devProxyTarget} at ${basePath}/`);
             return;
         }
-        // Read index.html once and rewrite absolute asset refs to the mounted basePath.
-        const indexHtmlPath = node_path_1.default.join(distDir, "index.html");
-        let indexHtml = "";
-        try {
-            indexHtml = (0, exports.injectBaseGlobal)((0, exports.rewriteIndexHtml)(node_fs_1.default.readFileSync(indexHtmlPath, "utf-8"), basePath), basePath);
-        }
-        catch {
-            api_1.logger.warn(`Admin SPA: no pre-built bundle found at ${indexHtmlPath}. ` +
-                "Run `bun run --filter '@terreno/admin-spa' build:web` or set devProxyTarget.");
-        }
-        // 1. Hashed asset directories — long cache, immutable.
+        const context = {
+            appConfig,
+            basePath,
+            internalOrigin: this.opts.internalOrigin ?? `http://127.0.0.1:${process.env.PORT ?? 4000}`,
+            ssrApiPrefixes: this.opts.ssrApiPrefixes ?? defaultSsrApiPrefixes(appConfig.adminApiBasePath),
+            warn: (message, meta) => {
+                api_1.logger.warn(message, meta);
+            },
+        };
+        (0, serverContext_1.publishAdminSpaServerContext)(context);
+        // 1. Hashed client asset directories: long cache, immutable.
+        const clientDir = node_path_1.default.join(distDir, "client");
         const staticOpts = { immutable: true, maxAge: "365d" };
-        app.use(`${basePath}/_expo`, express_1.default.static(node_path_1.default.join(distDir, "_expo"), staticOpts));
-        app.use(`${basePath}/assets`, express_1.default.static(node_path_1.default.join(distDir, "assets"), staticOpts));
-        // 2. Runtime config — never cached.
+        app.use(`${basePath}/_expo`, express_2.default.static(node_path_1.default.join(clientDir, "_expo"), staticOpts));
+        app.use(`${basePath}/assets`, express_2.default.static(node_path_1.default.join(clientDir, "assets"), staticOpts));
+        // 2. Runtime config, never cached.
         app.get(`${basePath}/app-config.json`, (_req, res) => {
             res.set("Cache-Control", NO_STORE).json(appConfig);
         });
-        // 3. SPA fallback. Two registrations: bare basePath (no trailing slash) AND splat,
-        // matching the `/*name` Express 5 convention used elsewhere in the repo.
-        const serveSpa = (_req, res) => {
-            res.set("Cache-Control", NO_STORE).type("html").send(indexHtml);
+        // 3. Server render. Without a server build, answer 503 instead of crashing the backend.
+        const serverDir = node_path_1.default.join(distDir, "server");
+        const rawManifest = (0, routesManifest_1.readRoutesManifest)(serverDir);
+        if (!rawManifest) {
+            api_1.logger.warn(`Admin SPA: no server build found at ${serverDir}. ` +
+                "Run `bun run --filter '@terreno/admin-spa' build:web` or set devProxyTarget.");
+            const unavailable = (_req, res) => {
+                res.status(503).set("Cache-Control", NO_STORE).type("text").send("Admin SPA unavailable");
+            };
+            app.get(basePath, unavailable);
+            app.get(`${basePath}/*splat`, unavailable);
+            return;
+        }
+        const bakedBaseUrl = (0, routesManifest_1.bakedBaseUrlOf)(rawManifest);
+        if (bakedBaseUrl !== basePath) {
+            throw new Error(`Admin SPA basePath "${basePath}" does not match the bundle's baseUrl "${bakedBaseUrl}"`);
+        }
+        const manifest = (0, routesManifest_1.prepareRoutesManifest)(rawManifest, {
+            pageCacheControl: NO_STORE_PRIVATE,
+        });
+        const handler = (0, express_1.createRequestHandler)({ build: serverDir }, { getRoutesManifest: async () => manifest });
+        // Every server render runs in a request scope, so a render reads only its own request's
+        // data. Middleware that set a richer scope earlier (the auth gate) keeps it.
+        // A failed render or loader logs the route path and the error only: never the query string
+        // or response data, which can hold PHI.
+        const renderError = (error, req, res) => {
+            api_1.logger.error(`Admin SPA render failed for ${req.path}`, {
+                error: error instanceof Error ? error.message : String(error),
+                path: req.path,
+            });
+            if (res.headersSent) {
+                res.end();
+                return;
+            }
+            res.status(500).set("Cache-Control", NO_STORE_PRIVATE).type("text").send("Admin SPA error");
+        };
+        const mountPrefix = basePath === "/" ? "" : basePath;
+        // Runs Expo's handler in a request scope (the gate's, or a base one) and catches its errors
+        // here rather than in a root error middleware, which would also see the API's errors.
+        const renderPage = (req, res, next) => {
+            res.set("Cache-Control", NO_STORE_PRIVATE);
+            // Expo matches routes without the mount path; root loader requests have none to strip.
+            if (mountPrefix && (req.path === mountPrefix || req.path.startsWith(`${mountPrefix}/`))) {
+                const rest = req.url.slice(mountPrefix.length);
+                req.url = rest.startsWith("/") ? rest : `/${rest}`;
+            }
+            const run = () => {
+                handler(req, res, (error) => {
+                    if (error) {
+                        renderError(error, req, res);
+                        return;
+                    }
+                    next();
+                });
+            };
+            if ((0, serverContext_1.getAdminSpaRequest)()) {
+                run();
+                return;
+            }
+            (0, serverContext_1.runInAdminSpaRequest)({ appConfig, basePath }, run);
         };
-        app.get(basePath, serveSpa);
-        app.get(`${basePath}/*splat`, serveSpa);
+        // The gate decides access before anything renders, for pages under basePath and for loader
+        // data, which Expo 58's client fetches from the site root regardless of the baked baseUrl
+        // (D11 in the SSR plan).
+        app.use((0, gate_1.createAdminSpaGate)({
+            adminApiBasePath: appConfig.adminApiBasePath ?? "/admin",
+            appConfig,
+            basePath,
+            handler: renderPage,
+            internalOrigin: context.internalOrigin,
+        }));
         api_1.logger.info(`Admin SPA mounted at ${basePath}/`);
     }
 }

package/src/dist/serverContext.d.ts

@@ -0,0 +1,61 @@
+import type { AdminSpaAppConfig } from "./appConfig";
+/** What the serve plugin publishes for `render.js`, `+html.tsx`, and route loaders. */
+export interface AdminSpaServerContext {
+    appConfig: AdminSpaAppConfig;
+    basePath: string;
+    /** Origin loopback SSR fetches go to. Never built from `Host` or `X-Forwarded-*`. */
+    internalOrigin: string;
+    /** API path prefixes a server render may fetch; anything else is rejected. */
+    ssrApiPrefixes: string[];
+    /**
+     * The host's warning logger (`logger.warn` from `@terreno/api`). The render bundle stubs
+     * `@terreno/api`, so server code reaches the host's log pipeline through this.
+     */
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * What one request's server render may read: set by Express before the Expo handler runs,
+ * visible to that request's render and loaders only.
+ */
+export interface AdminSpaRequestScope {
+    appConfig: AdminSpaAppConfig;
+    basePath: string;
+    /** The Better Auth session snapshot, or null for an anonymous visitor. Set by the gate. */
+    session?: AdminSpaSessionSnapshot | null;
+    /** The visitor's `GET /auth/me` body, or null when anonymous. Set by the gate. */
+    profile?: unknown;
+    /** The `GET {adminApiBasePath}/config` body for an admin, else null. Set by the gate. */
+    adminConfig?: unknown;
+    /** Status of the admin config read (200 admin, 403 forbidden), or null when not read. */
+    adminConfigStatus?: number | null;
+}
+/** The Better Auth session as the client's session source reads it. */
+export interface AdminSpaSessionSnapshot {
+    userId: string;
+    user: unknown;
+}
+/** Publish the server context. One admin SPA per process: a later call replaces it. */
+export declare const publishAdminSpaServerContext: (context: AdminSpaServerContext) => void;
+/** Read the published server context, or undefined before the plugin registers. */
+export declare const getAdminSpaServerContext: () => AdminSpaServerContext | undefined;
+/**
+ * Warn from server render code through the host's logger, or `console.warn` before the plugin
+ * has published one. Callers pass paths and reasons only: never a query string, a cookie or a
+ * response body.
+ */
+export declare const warnAdminSpaServer: (message: string, meta?: Record<string, unknown>) => void;
+/**
+ * True while rendering on the server: there is no browser `window`, and the serve plugin has
+ * published its context in this process. A server render reads what it was given and never
+ * starts watchers, sockets or requests of its own.
+ */
+export declare const isAdminSpaServerRender: () => boolean;
+/** Run `fn` with `scope` as the current request scope (server only). */
+export declare const runInAdminSpaRequest: <T>(scope: AdminSpaRequestScope, fn: () => T) => T;
+/** The current request's scope, or undefined outside a request (and always in the browser). */
+export declare const getAdminSpaRequest: () => AdminSpaRequestScope | undefined;
+/**
+ * Serialize a value for embedding in HTML (an inline `<script>` or a JSON script blob): JSON
+ * with every character that could close the script or break a JS string literal escaped.
+ */
+export declare const serializeForHtml: (value: unknown) => string;

package/src/dist/serverContext.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeForHtml = exports.getAdminSpaRequest = exports.runInAdminSpaRequest = exports.isAdminSpaServerRender = exports.warnAdminSpaServer = exports.getAdminSpaServerContext = exports.publishAdminSpaServerContext = void 0;
+/**
+ * Key of the process global the serve plugin publishes for the server render. The Expo
+ * `render.js` bundle and its loaders run in the same process as Express but are bundled
+ * separately, so a process global is the one place both can read. `Symbol.for` keeps the
+ * key identical across the two bundles.
+ */
+const ADMIN_SPA_SERVER_CONTEXT_KEY = Symbol.for("terreno.adminSpa.server");
+/** Key of the one per-request `AsyncLocalStorage`, shared by every bundle in the process. */
+const ADMIN_SPA_REQUEST_STORE_KEY = Symbol.for("terreno.adminSpa.requestStore");
+/** Publish the server context. One admin SPA per process: a later call replaces it. */
+const publishAdminSpaServerContext = (context) => {
+    globalThis[ADMIN_SPA_SERVER_CONTEXT_KEY] = context;
+};
+exports.publishAdminSpaServerContext = publishAdminSpaServerContext;
+/** Read the published server context, or undefined before the plugin registers. */
+const getAdminSpaServerContext = () => {
+    return globalThis[ADMIN_SPA_SERVER_CONTEXT_KEY];
+};
+exports.getAdminSpaServerContext = getAdminSpaServerContext;
+/**
+ * Warn from server render code through the host's logger, or `console.warn` before the plugin
+ * has published one. Callers pass paths and reasons only: never a query string, a cookie or a
+ * response body.
+ */
+const warnAdminSpaServer = (message, meta) => {
+    const warn = (0, exports.getAdminSpaServerContext)()?.warn;
+    if (warn) {
+        warn(message, meta);
+        return;
+    }
+    if (meta) {
+        console.warn(message, meta);
+        return;
+    }
+    console.warn(message);
+};
+exports.warnAdminSpaServer = warnAdminSpaServer;
+/**
+ * True while rendering on the server: there is no browser `window`, and the serve plugin has
+ * published its context in this process. A server render reads what it was given and never
+ * starts watchers, sockets or requests of its own.
+ */
+const isAdminSpaServerRender = () => {
+    return !("window" in globalThis) && (0, exports.getAdminSpaServerContext)() !== undefined;
+};
+exports.isAdminSpaServerRender = isAdminSpaServerRender;
+/**
+ * The process-wide request store, created on first use. `process.getBuiltinModule` keeps
+ * `node:async_hooks` out of the static import graph, because this module is also bundled for
+ * the browser, where there is no request store.
+ */
+const requestStore = () => {
+    const global = globalThis;
+    const existing = global[ADMIN_SPA_REQUEST_STORE_KEY];
+    if (existing) {
+        return existing;
+    }
+    const asyncHooks = process.getBuiltinModule("node:async_hooks");
+    const store = new asyncHooks.AsyncLocalStorage();
+    global[ADMIN_SPA_REQUEST_STORE_KEY] = store;
+    return store;
+};
+/** Run `fn` with `scope` as the current request scope (server only). */
+const runInAdminSpaRequest = (scope, fn) => {
+    return requestStore().run(scope, fn);
+};
+exports.runInAdminSpaRequest = runInAdminSpaRequest;
+/** The current request's scope, or undefined outside a request (and always in the browser). */
+const getAdminSpaRequest = () => {
+    return globalThis[ADMIN_SPA_REQUEST_STORE_KEY]?.getStore();
+};
+exports.getAdminSpaRequest = getAdminSpaRequest;
+/**
+ * Serialize a value for embedding in HTML (an inline `<script>` or a JSON script blob): JSON
+ * with every character that could close the script or break a JS string literal escaped.
+ */
+const serializeForHtml = (value) => {
+    return JSON.stringify(value)
+        .replaceAll("<", "\\u003c")
+        .replaceAll(">", "\\u003e")
+        .replaceAll("&", "\\u0026")
+        .replaceAll("\u2028", "\\u2028")
+        .replaceAll("\u2029", "\\u2029");
+};
+exports.serializeForHtml = serializeForHtml;

package/src/dist/signedInOnlyRoutes.d.ts

@@ -0,0 +1,2 @@
+/** Whether a route path (`/oauth/consent`, trailing slashes ignored) is signed-in-only. */
+export declare const isSignedInOnlyRoute: (pathname: string) => boolean;

package/src/dist/signedInOnlyRoutes.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSignedInOnlyRoute = void 0;
+/** Routes any signed-in user may open; they skip the admin check and admin bootstrapping. */
+const SIGNED_IN_ONLY_ROUTES = ["/oauth/consent"];
+/** Whether a route path (`/oauth/consent`, trailing slashes ignored) is signed-in-only. */
+const isSignedInOnlyRoute = (pathname) => {
+    return SIGNED_IN_ONLY_ROUTES.includes(pathname.replace(/\/+$/, "") || "/");
+};
+exports.isSignedInOnlyRoute = isSignedInOnlyRoute;