feat: env leak detection

.changeset/forty-crabs-judge.md

@@ -0,0 +1,41 @@
+---
+'astro': patch
+---
+
+Adds an optional middleware for usage with `astro:env`
+
+If you're using `astro:env`, you can now use a middleware to detect server envrionment variables leaks on the client:
+
+```ts
+// src/middleware.js
+
+import { leakDetectionMiddleware } from 'astro/env/middleware'
+import { sequence, defineMiddleware } from 'astro:middleware'
+
+const userMiddleware = defineMiddleware((_, next) => {
+	return next()
+})
+
+export const onRequest = sequence(
+	// It's important to use use it first to be able to catch the returned response last
+	leakDetectionMiddleware(),
+	userMiddleware
+);
+```
+
+An error will be thrown instead of rendering the page if a leak is detected.
+
+You can pass 2 options:
+
+1. `filterContentType`: filters what response content type should trigger the check. Defaults to the content type starting with `text/` or `application/json` 
+2. `excludeKeys`: by default, all server environment variables are checked. However, you may have variables whose value is really likely to end up on the client but not because it leaked (eg. `test`). In this case, you can exclude those keys.
+
+```ts
+import { leakDetectionMiddleware } from 'astro/env/middleware'
+
+export const onRequest = leakDetectionMiddleware({
+    // Do not filter json response
+    filterContentType: (contentType) => contentType.startsWith('text/'),
+    excludeKeys: ['PORT']
+})
+```

packages/astro/package.json

@@ -32,7 +32,8 @@
       "default": "./dist/core/index.js"
     },
     "./env": "./env.d.ts",
-    "./env/runtime": "./dist/env/runtime.js",
+    "./env/runtime": "./dist/env/runtime/index.js",
+    "./env/middleware": "./dist/env/runtime/middleware.js",
     "./env/setup": "./dist/env/setup.js",
     "./types": "./types.d.ts",
     "./client": "./client.d.ts",

packages/astro/src/@types/astro.ts

@@ -2138,7 +2138,6 @@ export interface AstroUserConfig {
 			 * @name experimental.env.schema
 			 * @kind h4
 			 * @type {EnvSchema}
-			 * @default `undefined`
 			 * @version 4.10.0
 			 * @description
 			 *
@@ -2160,7 +2159,7 @@ export interface AstroUserConfig {
 			 * })
 			 * ```
 			 */
-			schema?: EnvSchema;
+			schema: EnvSchema;
 		};
 	};
 }

packages/astro/src/core/base-pipeline.ts

@@ -8,7 +8,7 @@ import type {
 	SSRManifest,
 	SSRResult,
 } from '../@types/astro.js';
-import { setGetEnv } from '../env/runtime.js';
+import { setGetEnv } from '../env/runtime/index.js';
 import { createI18nMiddleware } from '../i18n/middleware.js';
 import { AstroError } from './errors/errors.js';
 import { AstroErrorData } from './errors/index.js';

packages/astro/src/core/config/schema.ts

@@ -89,6 +89,10 @@ export const ASTRO_CONFIG_DEFAULTS = {
 		clientPrerender: false,
 		globalRoutePriority: false,
 		rewriting: false,
+		env: {
+			// Make TS happy
+			schema: {},
+		},
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -525,7 +529,7 @@ export const AstroConfigSchema = z.object({
 			rewriting: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.rewriting),
 			env: z
 				.object({
-					schema: EnvSchema.optional(),
+					schema: EnvSchema,
 				})
 				.strict()
 				.optional(),

packages/astro/src/env/runtime.ts → packages/astro/src/env/runtime/index.ts

@@ -1,5 +1,5 @@
-import { AstroError, AstroErrorData } from '../core/errors/index.js';
-export { validateEnvVariable } from './validators.js';
+import { AstroError, AstroErrorData } from '../../core/errors/index.js';
+export { validateEnvVariable } from '../validators.js';
 
 export type GetEnv = (key: string) => string | undefined;
 

packages/astro/src/env/runtime/middleware.ts

@@ -0,0 +1,48 @@
+import type { MiddlewareHandler } from '../../@types/astro.js';
+
+interface MiddewareOptions {
+	/**
+	 * Filters what response content type should trigger the check. Defaults to the content type
+	 * starting with `/text` or `application/json` 
+	 */
+	filterContentType?: (contentType: string) => boolean;
+	/**
+	 * By default, all server environment variables are checked. However, you may have variables
+	 * whose value is really likely to end up on the client but not because it leaked (eg. `test`).
+	 * In this case, you can exclude those keys.
+	 */
+	// @ts-ignore
+	excludeKeys?: Array<keyof Omit<typeof import('astro:env/server'), 'getSecret'>>;
+}
+
+/**
+ * This middleware will throw if a response with the specified content type contains a server
+ * environment variable.
+ */
+export function leakDetectionMiddleware({
+	filterContentType = (v) => v.startsWith('text/') || v.startsWith('application/json'),
+	excludeKeys = [],
+}: MiddewareOptions = {}): MiddlewareHandler {
+	return async (_, next) => {
+		const response = await next();
+
+		const contentType = response.headers.get('Content-Type');
+		if (contentType && filterContentType(contentType)) {
+			const content = await response.clone().text();
+			const { getSecret, ...secrets }: Record<string, string | undefined> = await import(
+				// @ts-ignore
+				'astro:env/server'
+			);
+			for (const [key, value] of Object.entries(secrets)) {
+				if (excludeKeys.includes(key) || value === undefined) {
+					continue;
+				}
+				if (content.includes(value)) {
+					throw new Error(`[astro:env] \`${key}\` leaked client-side.`);
+				}
+			}
+		}
+
+		return response;
+	};
+}

packages/astro/src/env/setup.ts

@@ -1 +1 @@
-export { setGetEnv, type GetEnv } from './runtime.js';
+export { setGetEnv, type GetEnv } from './runtime/index.js';

packages/astro/src/env/vite-plugin-env.ts

@@ -33,7 +33,7 @@ export function astroEnv({
 	if (!settings.config.experimental.env) {
 		return;
 	}
-	const schema = settings.config.experimental.env.schema ?? {};
+	const schema = settings.config.experimental.env?.schema ?? {};
 
 	let templates: { client: string; server: string; internal: string } | null = null;
 

packages/astro/test/env-leak-detection.test.js

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { loadFixture } from './test-utils.js';
+
+describe('astro:env leak detection', () => {
+	it('should fail if a secret is sent to the client', async () => {
+		const fixture = await loadFixture({
+			root: './fixtures/astro-env-leak-detection/',
+		});
+
+		let error;
+		try {
+			await fixture.build();
+		} catch (err) {
+			error = err;
+		}
+
+		assert.equal(error instanceof Error, true);
+		assert.equal(error.message.includes('leaked client-side'), true);
+	});
+});

packages/astro/test/fixtures/astro-env-leak-detection/astro.config.mjs

@@ -0,0 +1,16 @@
+import { defineConfig, envField } from 'astro/config';
+
+// https://astro.build/config
+export default defineConfig({
+    experimental: {
+        env: {
+            schema: {
+                FOO: envField.string({
+                    context: 'server',
+                    access: 'secret',
+                    default: 'this is a secret'
+                }),
+            },
+        }
+    }
+});

packages/astro/test/fixtures/astro-env-leak-detection/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@test/astro-env-leak-detection",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "astro": "workspace:*"
+  }
+}

packages/astro/test/fixtures/astro-env-leak-detection/src/middleware.ts

@@ -0,0 +1,3 @@
+import { leakDetectionMiddleware } from 'astro/env/middleware'
+
+export const onRequest = leakDetectionMiddleware()

packages/astro/test/fixtures/astro-env-leak-detection/src/pages/index.astro

@@ -0,0 +1,4 @@
+---
+import { FOO } from "astro:env/server"
+---
+<p>{FOO}</p>

packages/astro/test/fixtures/astro-env-leak-detection/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "astro/tsconfigs/base"
+}