@northlight-systems/cloud-render 0.0.0-stage → 0.6.0

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.
package/dist/render.js ADDED
@@ -0,0 +1,106 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { join } from "node:path";
3
+ import { fileURLToPath, pathToFileURL } from "node:url";
4
+ /**
5
+ * A Content-Security-Policy for pages that carry no inline script or style
6
+ * except Start's hydration scripts and the one `<style>` React Aria adds
7
+ * (`touch-action` for pressable elements), which hold the request's nonce
8
+ * (React Aria reads it from Start's `csp-nonce` meta tag). A nonce admits
9
+ * `<script>` and `<style>` elements only; inline `style` attributes stay
10
+ * blocked. Scripts, styles and fonts come from this origin only; images from this origin and any
11
+ * https host; `fetch` only to this origin, which admits the same-origin
12
+ * browser errors tunnel (`/_nl/errors`). An app that needs another `connect-src`
13
+ * source extends this one directive, never adds a second `connect-src`, which
14
+ * browsers ignore.
15
+ */
16
+ export const strictContentSecurityPolicy = (nonce) => [
17
+ "default-src 'none'",
18
+ `script-src 'self' 'nonce-${nonce}'`,
19
+ `style-src 'self' 'nonce-${nonce}'`,
20
+ "font-src 'self'",
21
+ "img-src 'self' https:",
22
+ "connect-src 'self'",
23
+ "form-action 'self'",
24
+ "frame-ancestors 'none'",
25
+ "base-uri 'none'",
26
+ ].join("; ");
27
+ /**
28
+ * {@link strictContentSecurityPolicy} for a page that sits in another site's
29
+ * iframe: any origin may frame it (`frame-ancestors *`) and its form may submit
30
+ * or redirect to any https URL (`form-action 'self' https:`).
31
+ */
32
+ export const embeddableContentSecurityPolicy = (nonce) => [
33
+ "default-src 'none'",
34
+ `script-src 'self' 'nonce-${nonce}'`,
35
+ `style-src 'self' 'nonce-${nonce}'`,
36
+ "font-src 'self'",
37
+ "img-src 'self' https:",
38
+ "connect-src 'self'",
39
+ "form-action 'self' https:",
40
+ "frame-ancestors *",
41
+ "base-uri 'none'",
42
+ ].join("; ");
43
+ const directoryOf = (root) => typeof root === "string" ? root : fileURLToPath(root);
44
+ /**
45
+ * Binds a renderer to a built TanStack Start app. The controller keeps the
46
+ * routing, auth and redirects and computes the page's data; the renderer runs
47
+ * Start on it and writes the HTML to the Express response. `Page` is the data
48
+ * the web app reads from the request context, defined by the app.
49
+ */
50
+ export function createStartRenderer(config) {
51
+ const mode = config.mode ?? "frame-deny";
52
+ const policy = config.contentSecurityPolicy ??
53
+ (mode === "embeddable"
54
+ ? embeddableContentSecurityPolicy
55
+ : strictContentSecurityPolicy);
56
+ const nonceHeader = config.nonceHeader ?? "x-csp-nonce";
57
+ const serverUrl = pathToFileURL(join(directoryOf(config.webRoot), "server", "server.js")).href;
58
+ let startServer;
59
+ const load = () => {
60
+ startServer ??= import(/* @vite-ignore */ serverUrl).then((module) => module.default);
61
+ const loading = startServer;
62
+ // A failed import is not cached: the next render tries again.
63
+ loading.catch(() => {
64
+ if (startServer === loading)
65
+ startServer = undefined;
66
+ });
67
+ return loading;
68
+ };
69
+ return async (req, res, page, options) => {
70
+ const server = await load();
71
+ const origin = typeof config.origin === "function" ? config.origin() : config.origin;
72
+ const nonce = mode !== "frame-deny" ? randomBytes(16).toString("base64") : undefined;
73
+ const response = await server.fetch(new Request(new URL(options?.path ?? config.path ?? req.originalUrl, origin), {
74
+ headers: {
75
+ accept: "text/html",
76
+ ...(nonce === undefined ? {} : { [nonceHeader]: nonce }),
77
+ },
78
+ }), { context: { page } });
79
+ res.status(options?.status ?? response.status);
80
+ // An embeddable page drops X-Frame-Options from Start and from the per-render headers: any
81
+ // value of it would stop the framing that `frame-ancestors *` allows.
82
+ const keep = (name) => mode !== "embeddable" || name.toLowerCase() !== "x-frame-options";
83
+ const setCookies = response.headers.getSetCookie();
84
+ response.headers.forEach((value, key) => {
85
+ if (key !== "set-cookie" && keep(key))
86
+ res.setHeader(key, value);
87
+ });
88
+ if (setCookies.length > 0)
89
+ res.setHeader("set-cookie", setCookies);
90
+ if (nonce !== undefined) {
91
+ res.setHeader("content-type", "text/html; charset=utf-8");
92
+ res.setHeader("cache-control", "no-store");
93
+ res.setHeader("referrer-policy", "no-referrer");
94
+ }
95
+ for (const [name, value] of Object.entries(options?.headers ?? {})) {
96
+ if (keep(name))
97
+ res.setHeader(name, value);
98
+ }
99
+ res.setHeader("content-security-policy", nonce === undefined ? "frame-ancestors 'none'" : policy(nonce));
100
+ if (mode !== "embeddable")
101
+ res.setHeader("x-frame-options", "DENY");
102
+ // The body is the page Start rendered from `page`, which React escapes.
103
+ // nosemgrep: javascript.express.security.audit.xss.direct-response-write.direct-response-write
104
+ res.send(Buffer.from(await response.arrayBuffer()));
105
+ };
106
+ }
@@ -0,0 +1,38 @@
1
+ /** The options of Express's static middleware that the routes use. */
2
+ export interface StaticServeOptions {
3
+ prefix?: string;
4
+ index?: boolean;
5
+ maxAge?: number | string;
6
+ immutable?: boolean;
7
+ }
8
+ /** A Nest Express application (`NestExpressApplication`) satisfies this. */
9
+ export interface StaticApp {
10
+ useStaticAssets(path: string, options?: StaticServeOptions): unknown;
11
+ }
12
+ export interface StaticRoutesOptions {
13
+ /** The built web app: see `StartRendererOptions.webRoot`. */
14
+ webRoot: string | URL;
15
+ /**
16
+ * Cache headers for `/assets/`. Defaults to one year, immutable: Vite hashes
17
+ * the file names. `{ maxAge: 0, immutable: false }` sends Express's default.
18
+ */
19
+ assets?: {
20
+ maxAge?: number | string;
21
+ immutable?: boolean;
22
+ };
23
+ /** Cache headers for `/brand/`. Defaults to one day. */
24
+ brand?: {
25
+ maxAge?: number | string;
26
+ };
27
+ }
28
+ /** The built client assets (scripts, styles, fonts) that `/assets/` serves. */
29
+ export declare const assetsRoot: (webRoot: string | URL) => string;
30
+ /**
31
+ * The brand files (favicon, touch icon, mark) from the app's own
32
+ * `@northlight-systems/cloud-ui`, which `/brand/` serves. This package keeps
33
+ * cloud-ui as a peer dependency, so the path resolves in the consumer's
34
+ * install and the app keeps no copy that could drift.
35
+ */
36
+ export declare const brandRoot: () => string;
37
+ /** Registers `/assets/` (the web app's build) and `/brand/` (the UI kit's brand files). */
38
+ export declare function serveStaticRoutes(app: StaticApp, options: StaticRoutesOptions): void;
package/dist/static.js ADDED
@@ -0,0 +1,24 @@
1
+ import { dirname, join } from "node:path";
2
+ import { fileURLToPath } from "node:url";
3
+ /** The built client assets (scripts, styles, fonts) that `/assets/` serves. */
4
+ export const assetsRoot = (webRoot) => join(typeof webRoot === "string" ? webRoot : fileURLToPath(webRoot), "client", "assets");
5
+ /**
6
+ * The brand files (favicon, touch icon, mark) from the app's own
7
+ * `@northlight-systems/cloud-ui`, which `/brand/` serves. This package keeps
8
+ * cloud-ui as a peer dependency, so the path resolves in the consumer's
9
+ * install and the app keeps no copy that could drift.
10
+ */
11
+ export const brandRoot = () => dirname(fileURLToPath(import.meta.resolve("@northlight-systems/cloud-ui/brand/mark.svg")));
12
+ /** Registers `/assets/` (the web app's build) and `/brand/` (the UI kit's brand files). */
13
+ export function serveStaticRoutes(app, options) {
14
+ app.useStaticAssets(assetsRoot(options.webRoot), {
15
+ prefix: "/assets/",
16
+ maxAge: options.assets?.maxAge ?? "1y",
17
+ immutable: options.assets?.immutable ?? true,
18
+ });
19
+ app.useStaticAssets(brandRoot(), {
20
+ prefix: "/brand/",
21
+ index: false,
22
+ maxAge: options.brand?.maxAge ?? "1d",
23
+ });
24
+ }
package/package.json CHANGED
@@ -1,6 +1,58 @@
1
1
  {
2
2
  "name": "@northlight-systems/cloud-render",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "description": "Renders a TanStack Start page from an Express or Nest controller, answers browsers with a kit-styled error page, and builds per-page link-preview tags and cards.",
5
+ "license": "MPL-2.0",
6
+ "repository": "https://github.com/Northlight-Systems/shared.git",
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "type": "module",
11
+ "exports": {
12
+ ".": {
13
+ "types": "./dist/index.d.ts",
14
+ "default": "./dist/index.js"
15
+ },
16
+ "./card": {
17
+ "types": "./dist/card.d.ts",
18
+ "default": "./dist/card.js"
19
+ }
20
+ },
21
+ "publishConfig": {
22
+ "access": "restricted",
23
+ "registry": "https://npm.pkg.github.com"
24
+ },
25
+ "scripts": {
26
+ "generate": "pnpm --filter @northlight-systems/cloud-ui build && node scripts/build-error-page.ts",
27
+ "build": "pnpm generate && tsc -p tsconfig.build.json",
28
+ "typecheck": "pnpm generate && tsc -p tsconfig.json",
29
+ "test": "pnpm generate && vitest run"
30
+ },
31
+ "devDependencies": {
32
+ "@northlight-systems/cloud-ui": "workspace:*",
33
+ "@resvg/resvg-js": "2.6.2",
34
+ "@tailwindcss/node": "4.3.3",
35
+ "@types/express": "5.0.6",
36
+ "@types/node": "26.6.2",
37
+ "@types/react": "19.3.0",
38
+ "@types/react-dom": "19.3.0",
39
+ "react": "19.3.0",
40
+ "react-dom": "19.3.0",
41
+ "satori": "0.63.2",
42
+ "tailwindcss": "4.3.3",
43
+ "vitest": "4.1.11"
44
+ },
45
+ "peerDependencies": {
46
+ "@northlight-systems/cloud-ui": ">=0.5.0 <1",
47
+ "@resvg/resvg-js": "2.6.2",
48
+ "satori": "0.63.2"
49
+ },
50
+ "peerDependenciesMeta": {
51
+ "satori": {
52
+ "optional": true
53
+ },
54
+ "@resvg/resvg-js": {
55
+ "optional": true
56
+ }
57
+ }
58
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.