@o3co/create-auth-provider 0.11.0 → 0.12.1

package/templates/standalone/src/__tests__/replica-safety.test.mts

@@ -0,0 +1,456 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * #455 / #456 — the standalone's own store modules under
+ * `deployment.mode = "multi"`, booted the way an operator reaches them: from
+ * the shipped HOCON with one environment variable flipped.
+ *
+ * #455: the replica-safety guard keyed on core's module names, and this
+ * template wires its *own* in-memory modules for three of the stores —
+ * session stores, the code repository, the federation token store — under
+ * names the guard had never heard of. `DEPLOYMENT_MODE=multi` with
+ * `USER_SESSION_STORES_ADAPTER=memory` booted, and the refusal the README
+ * promises did not fire for exactly the stores that fork per replica the
+ * worst. Every memory branch is booted here under `"multi"` and must be
+ * refused by name; the all-Redis environment must boot.
+ *
+ * #456: `federationTokenStore.type = "redis"` was documented and could not
+ * boot — the module went through the adapter factory without ever handing
+ * the builder a client. The Redis branch now mounts
+ * `redisFederationTokenStoreModule` off the shared ioredis socket; the boot
+ * below is the test the README sentence never had.
+ *
+ * #474: express-session's own store was the one memory store the guard could
+ * not see — `SESSION_STORAGE_TYPE=memory` is config, and `sessionStoreModule`'s
+ * static manifest carried no declaration. `buildModules` now builds it from
+ * the config (`sessionStoreModuleFor`), so it is refused by name like the rest.
+ *
+ * #473: the Redis federation store's `allow-plaintext` guard keyed off
+ * `NODE_ENV` alone. It now reads the environment the config was selected by
+ * (`CONFIG_ENV || NODE_ENV`, passed through `buildModules`) and refuses under
+ * `deployment.mode = "multi"` in every environment.
+ *
+ * ioredis is mocked, as in `device-code-store-client-module.test.mts`: the
+ * point is composition and the boot planner's stage-1 verdict, not Redis.
+ * Nothing here issues a command. node-redis and connect-redis — the session
+ * store's own connection — are mocked for the same reason, since #474 puts
+ * `SESSION_STORAGE_TYPE=redis` in the baseline.
+ */
+
+import { fileURLToPath } from "node:url";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	InMemoryClientRepository,
+	InMemoryUserRepository,
+	registerBuiltinKeyStores,
+	replicaUnsafeReason,
+} from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+
+// The redis session-store builder dynamically imports these (#474 puts the
+// Redis session store in the baseline); mock them so no socket opens.
+vi.mock("redis", () => ({
+	createClient: vi.fn(() => ({
+		connect: vi.fn().mockResolvedValue(undefined),
+		quit: vi.fn().mockResolvedValue(undefined),
+		ping: vi.fn().mockResolvedValue("PONG"),
+		on: vi.fn(),
+	})),
+}));
+
+vi.mock("connect-redis", async () => {
+	const { EventEmitter } = await import("node:events");
+	// express-session subscribes to store events, so the fake must be an
+	// EventEmitter rather than a plain object.
+	return {
+		RedisStore: class MockRedisStore extends EventEmitter {
+			constructor(_opts: { client: unknown }) {
+				super();
+			}
+			get(): unknown {
+				return undefined;
+			}
+			set(): void {}
+			destroy(): void {}
+		},
+	};
+});
+
+vi.mock("ioredis", () => {
+	// Every command resolves to nothing. A boot that reached Redis would be a
+	// boot doing work at stage 2 that belongs in an integration test; the
+	// stand-in only has to be constructible, quit cleanly, and answer `ping`
+	// for the readiness probe the shared clients module registers.
+	const explicit: Record<string, unknown> = {
+		on: () => undefined,
+		quit: async () => "OK",
+		disconnect: () => undefined,
+		ping: async () => "PONG",
+	};
+	const makeMockRedis = (): object =>
+		new Proxy(
+			{},
+			{
+				get(_target, prop) {
+					// A `then` that is a function would make the instance a
+					// thenable and hang anything that awaits it.
+					if (typeof prop !== "string" || prop === "then") return undefined;
+					if (prop === "duplicate") return makeMockRedis;
+					if (prop in explicit) return explicit[prop];
+					return async () => null;
+				},
+			},
+		);
+	// The template does `new Redis(url, options)`. A plain function that
+	// returns an object yields that object under `new`, so no class — and no
+	// constructor returning a value — is needed for the stand-in.
+	function MockRedis(): object {
+		return makeMockRedis();
+	}
+	return { Redis: MockRedis, default: MockRedis };
+});
+
+// config/ is two levels above this test file: src/__tests__/ → src/ → standalone/
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+/** 32 bytes, base64 — what `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` carries. */
+const ENCRYPTION_KEY = Buffer.alloc(32, 7).toString("base64");
+
+/**
+ * The umbrella E2E's shape (`o3co/auth` `tests/docker-compose.yml`), with
+ * every shared store on Redis — express-session's own included, since #474
+ * put it under the guard. Each case below flips one variable off this.
+ */
+const ALL_REDIS_ENV: Readonly<Record<string, string>> = {
+	OAUTH_JWT_ALGORITHM: "HS256",
+	OAUTH_JWT_SECRET: "replica-safety-test-secret.at-least-32-bytes.ok",
+	OAUTH_JWT_ISSUER: "https://auth.test",
+	SESSION_SECRET: "replica-safety-session-secret.at-least-32-bytes.ok",
+	SESSION_SECURE: "false",
+	SESSION_NAME: "auth.session",
+	SESSION_STORAGE_TYPE: "redis",
+	SESSION_STORAGE_REDIS_URL: "redis://redis.test:6379",
+	CLIENT_USER_TYPE: "yaml",
+	DEPLOYMENT_MODE: "multi",
+	REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: "redis://redis.test:6379",
+	USER_SESSION_STORES_ADAPTER: "redis",
+	RATE_LIMITER_ADAPTER: "redis",
+	OAUTH_CODE_ADAPTER: "redis",
+	ACCESS_TOKEN_DENYLIST_ADAPTER: "redis",
+	FEDERATION_TOKEN_STORE_TYPE: "redis",
+	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: ENCRYPTION_KEY,
+};
+
+function resolveConfig(env: Record<string, string>): AppConfig {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	return validate(
+		parseFile(envConfPath, { env })
+			.withFallback(parseFile(applicationConfPath, { env }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env })),
+		AppConfigSchema,
+	);
+}
+
+/** Drops a variable, so the HOCON default takes over. */
+function without(env: Record<string, string>, ...names: string[]): Record<string, string> {
+	const copy = { ...env };
+	for (const name of names) delete copy[name];
+	return copy;
+}
+
+// The file-system-backed modules are replaced as in `smoke.test.mts`: the
+// boot under test is the store wiring, not the client registry on disk.
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () => new InMemoryClientRepository(new Map()),
+		userRepository: () => new InMemoryUserRepository(new Map()),
+	},
+});
+
+const testKeyStoreModule = defineModule({
+	name: "test:key-store",
+	requires: ["config"] as const,
+	provides: {
+		keyStore: async ({ config: c }) => {
+			const factory = createKeyStoreFactory();
+			registerBuiltinKeyStores(factory);
+			return factory.create({
+				type: "local",
+				...((c as AppConfig).oauth.jwt.signingKey.local ?? {}),
+			});
+		},
+	},
+});
+
+const modulesFor = (config: AppConfig, environment?: string) =>
+	buildModules(config, {
+		keyStoreModule: testKeyStoreModule,
+		repositoriesModule: testRepositoriesModule,
+		...(environment === undefined ? {} : { environment }),
+	});
+
+const boot = (config: AppConfig, environment?: string) =>
+	createApp({
+		modules: modulesFor(config, environment),
+		bootstrapComponents: { config, pathResolver: (s) => s },
+	});
+
+/** The message of a boot failure and of the module error it wraps, together. */
+const messageChain = (err: unknown): string => {
+	const e = err as { message?: string; cause?: { message?: string } };
+	return `${e.message ?? ""} ${e.cause?.message ?? ""}`;
+};
+
+describe('#455: the standalone\'s memory modules are refused under deployment.mode = "multi"', () => {
+	let handleRef: Awaited<ReturnType<typeof boot>> | undefined;
+
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	const cases: ReadonlyArray<readonly [variable: string, module: string]> = [
+		// The template's own modules — the three the guard could not see.
+		["USER_SESSION_STORES_ADAPTER", "standalone:in-memory-session-stores"],
+		["OAUTH_CODE_ADAPTER", "standalone:in-memory-code-repository"],
+		["FEDERATION_TOKEN_STORE_TYPE", "standalone:in-memory-federation-token-store"],
+		// #474: express-session's own store. Not a module of this template but
+		// built here from its config, which is what lets the manifest declare.
+		["SESSION_STORAGE_TYPE", "sessionStoreModule"],
+		// Core's, selected by the same kind of switch. The guard knew these by
+		// name; pinned so the name table's departure (#455) did not lose them.
+		["RATE_LIMITER_ADAPTER", "core-rate-limiter-memory"],
+		["ACCESS_TOKEN_DENYLIST_ADAPTER", "core-access-token-denylist-memory"],
+	];
+
+	for (const [variable, module] of cases) {
+		it(`${variable}=memory is refused, naming ${module}`, async () => {
+			const config = resolveConfig({ ...ALL_REDIS_ENV, [variable]: "memory" });
+			await expect(boot(config)).rejects.toMatchObject({
+				name: "BootError",
+				reason: "replica-unsafe-adapter",
+				details: { modules: [module] },
+			});
+		});
+	}
+
+	it("names every memory module together when every switch is memory", async () => {
+		const config = resolveConfig({
+			...ALL_REDIS_ENV,
+			USER_SESSION_STORES_ADAPTER: "memory",
+			OAUTH_CODE_ADAPTER: "memory",
+			FEDERATION_TOKEN_STORE_TYPE: "memory",
+			SESSION_STORAGE_TYPE: "memory",
+			RATE_LIMITER_ADAPTER: "memory",
+			ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+		});
+		await expect(boot(config)).rejects.toMatchObject({
+			reason: "replica-unsafe-adapter",
+			details: {
+				modules: expect.arrayContaining(cases.map(([, module]) => module)),
+			},
+		});
+	});
+
+	it("each standalone memory module declares its consequence on its own manifest", () => {
+		// The declaration is what the guard reads (#455), so it has to be on
+		// the module and it has to say what breaks — the guard quotes it.
+		const config = resolveConfig({
+			...ALL_REDIS_ENV,
+			USER_SESSION_STORES_ADAPTER: "memory",
+			OAUTH_CODE_ADAPTER: "memory",
+			FEDERATION_TOKEN_STORE_TYPE: "memory",
+		});
+		const standaloneMemoryModules = modulesFor(config).filter((m) =>
+			m.name.startsWith("standalone:in-memory-"),
+		);
+		expect(standaloneMemoryModules.map((m) => m.name).sort()).toEqual([
+			"standalone:in-memory-code-repository",
+			"standalone:in-memory-federation-token-store",
+			"standalone:in-memory-session-stores",
+		]);
+		for (const m of standaloneMemoryModules) {
+			expect(replicaUnsafeReason(m), m.name).toBeDefined();
+			expect((replicaUnsafeReason(m) ?? "").length, m.name).toBeGreaterThan(40);
+		}
+	});
+
+	it("boots the all-Redis environment, with nothing declaring replica-unsafe state", async () => {
+		const config = resolveConfig(ALL_REDIS_ENV);
+		for (const m of modulesFor(config)) {
+			expect(replicaUnsafeReason(m), m.name).toBeUndefined();
+		}
+		handleRef = await boot(config);
+		expect(handleRef).toBeDefined();
+	});
+});
+
+describe('#456: federationTokenStore.type = "redis" in the standalone', () => {
+	let handleRef: Awaited<ReturnType<typeof boot>> | undefined;
+
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	it("reaches the resolved config from FEDERATION_TOKEN_STORE_TYPE", () => {
+		// `AppConfigSchema` strips top-level keys it does not declare; the
+		// switch had to be declared before an env var could select anything.
+		expect(resolveConfig(ALL_REDIS_ENV).federationTokenStore?.type).toBe("redis");
+		expect(
+			resolveConfig(without(ALL_REDIS_ENV, "FEDERATION_TOKEN_STORE_TYPE")).federationTokenStore
+				?.type,
+		).toBe("memory");
+	});
+
+	it("selects the Redis module and the shared clients module, not the memory one", () => {
+		const modules = modulesFor(resolveConfig(ALL_REDIS_ENV));
+		const names = modules.map((m) => m.name);
+		expect(names).toContain("redis-federation-token-store");
+		expect(names).toContain("standalone:redis-clients");
+		expect(names).not.toContain("standalone:in-memory-federation-token-store");
+		// Exactly one provider for the slot: both modules provide it, so
+		// selecting both would be a boot-time slot collision.
+		const providers = modules.filter((m) =>
+			Object.keys(m.provides ?? {}).includes("federationTokenStore"),
+		);
+		expect(providers.map((m) => m.name)).toEqual(["redis-federation-token-store"]);
+	});
+
+	it("pulls the shared clients module in for the federation store alone", () => {
+		// Every other store on memory, single replica: the Redis federation
+		// store still needs `federationTokenStoreClient`, which only the shared
+		// clients module provides. Without this the branch fails stage 1 with
+		// `missing-required-component` — the #439 shape, once more.
+		const config = resolveConfig({
+			...ALL_REDIS_ENV,
+			DEPLOYMENT_MODE: "single",
+			USER_SESSION_STORES_ADAPTER: "memory",
+			OAUTH_CODE_ADAPTER: "memory",
+			RATE_LIMITER_ADAPTER: "memory",
+			ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+		});
+		const names = modulesFor(config).map((m) => m.name);
+		expect(names).toContain("redis-federation-token-store");
+		expect(names).toContain("standalone:redis-clients");
+	});
+
+	it("boots, and the resolved store is the Redis adapter", async () => {
+		handleRef = await boot(resolveConfig(ALL_REDIS_ENV));
+		const store = handleRef.components.federationTokenStore;
+		expect(store?.kind).toBe("redis");
+	});
+
+	it("fails at boot, naming the key, when the encryption key is missing", async () => {
+		// The store encrypts long-lived IdP refresh tokens at rest; a Redis
+		// branch with no key is a misconfiguration to refuse at boot, not a
+		// store that works until the first federation login.
+		const config = resolveConfig(
+			without(ALL_REDIS_ENV, "REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY"),
+		);
+		await expect(boot(config)).rejects.toSatisfy((err: unknown) => {
+			const e = err as { message?: string; cause?: { message?: string } };
+			return /encryption\.key/.test(`${e.message ?? ""} ${e.cause?.message ?? ""}`);
+		});
+	});
+
+	it("keeps the memory branch as it was: the default, in single mode, resolves the memory adapter", async () => {
+		const config = resolveConfig({
+			...without(ALL_REDIS_ENV, "FEDERATION_TOKEN_STORE_TYPE"),
+			DEPLOYMENT_MODE: "single",
+		});
+		const names = modulesFor(config).map((m) => m.name);
+		expect(names).toContain("standalone:in-memory-federation-token-store");
+		expect(names).not.toContain("redis-federation-token-store");
+		handleRef = await boot(config);
+		expect(handleRef.components.federationTokenStore?.kind).toBe("memory");
+	});
+});
+
+describe("#473: the Redis federation store's plaintext guard, booted from the shipped config", () => {
+	let handleRef: Awaited<ReturnType<typeof boot>> | undefined;
+	let warnSpy: ReturnType<typeof vi.spyOn>;
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+	let origInsecure: string | undefined;
+
+	beforeEach(() => {
+		// vitest runs with NODE_ENV=test: not a production name, so every
+		// refusal below comes from what the standalone passes, not from NODE_ENV.
+		expect(process.env.NODE_ENV).not.toMatch(/^(production|staging)$/);
+		origInsecure = process.env.FEDERATION_TOKENS_ALLOW_INSECURE;
+		delete process.env.FEDERATION_TOKENS_ALLOW_INSECURE;
+		warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+		if (origInsecure === undefined) delete process.env.FEDERATION_TOKENS_ALLOW_INSECURE;
+		else process.env.FEDERATION_TOKENS_ALLOW_INSECURE = origInsecure;
+		warnSpy.mockRestore();
+		errorSpy.mockRestore();
+	});
+
+	/** All-Redis, with the federation store told to skip encryption. */
+	const PLAINTEXT_ENV: Readonly<Record<string, string>> = {
+		...without(ALL_REDIS_ENV, "REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY"),
+		REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE: "allow-plaintext",
+	};
+
+	it('is refused under deployment.mode = "multi" in a development environment', async () => {
+		// The umbrella shape with plaintext: refused before #473 only if
+		// NODE_ENV happened to say production. A multi-replica deployment is
+		// never a development box.
+		await expect(boot(resolveConfig(PLAINTEXT_ENV), "development")).rejects.toSatisfy(
+			(err: unknown) => /deployment\.mode is "multi"/.test(messageChain(err)),
+		);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("is refused when the config was selected by CONFIG_ENV=production, whatever NODE_ENV says", async () => {
+		// `app.mts` selects `production.conf` by `CONFIG_ENV || NODE_ENV` and
+		// passes that name through `buildModules`; the guard used to read
+		// NODE_ENV alone and would have let this boot.
+		const config = resolveConfig({ ...PLAINTEXT_ENV, DEPLOYMENT_MODE: "single" });
+		await expect(boot(config, "production")).rejects.toSatisfy((err: unknown) =>
+			/the environment is "production"/.test(messageChain(err)),
+		);
+	});
+
+	it("boots with the plaintext warning in a development environment on a single replica", async () => {
+		const config = resolveConfig({ ...PLAINTEXT_ENV, DEPLOYMENT_MODE: "single" });
+		handleRef = await boot(config, "development");
+		expect(handleRef.components.federationTokenStore?.kind).toBe("redis");
+		expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("allow-plaintext"));
+	});
+
+	it("keeps the FEDERATION_TOKENS_ALLOW_INSECURE=1 escape hatch under multi, at CRITICAL", async () => {
+		process.env.FEDERATION_TOKENS_ALLOW_INSECURE = "1";
+		handleRef = await boot(resolveConfig(PLAINTEXT_ENV), "development");
+		expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("CRITICAL"));
+	});
+});

package/templates/standalone/src/__tests__/scaffold-assets.test.mts

@@ -26,11 +26,84 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { type AppConfig, AppConfigSchema } from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
 import { describe, expect, it } from "vitest";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
 
 const standaloneDir = fileURLToPath(new URL("../..", import.meta.url));
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 const read = (rel: string): string => readFileSync(`${standaloneDir}${rel}`, "utf8");
 
+/**
+ * The `environment:` entries of a compose file's `app` service, as the
+ * environment the container would actually see.
+ *
+ * A hand-rolled reader rather than a YAML dependency: these two files are
+ * fixed-shape artifacts in this repository, the block is flat `KEY: value`
+ * scalars, and adding a parser to the template's dependency tree to read its
+ * own scaffold would be a strange thing to ship to operators.
+ *
+ * Compose's `${VAR:?err}` required-variable form resolves from the operator's
+ * shell or `.env`, so there is no literal value to record — the key is mapped
+ * to `null`, which is the point of that form and what the assertions below
+ * check for.
+ */
+function composeAppEnvironment(rel: string): Map<string, string | null> {
+	const lines = read(rel).split("\n");
+	const start = lines.findIndex((line) => /^\s{4}environment:\s*$/.test(line));
+	const env = new Map<string, string | null>();
+	if (start === -1) return env;
+	for (const line of lines.slice(start + 1)) {
+		if (line.trim() === "" || /^\s*#/.test(line)) continue;
+		// The block ends at the first line indented no further than its own key.
+		if (!/^\s{6}\S/.test(line)) break;
+		const match = /^\s{6}([A-Z][A-Z0-9_]*):\s*(.*)$/.exec(line);
+		if (!match) continue;
+		const raw = (match[2] as string).trim().replace(/^["']|["']$/g, "");
+		env.set(match[1] as string, /^\$\{[A-Z][A-Z0-9_]*:\?/.test(raw) ? null : raw);
+	}
+	return env;
+}
+
+/** Resolve the shipped config layers under a given environment, as `src/app.mts` does. */
+function resolveWith(env: Record<string, string>, configEnv = "production"): AppConfig {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, configEnv);
+	return validate(
+		parseFile(envConfPath, { env })
+			.withFallback(parseFile(applicationConfPath, { env }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env })),
+		AppConfigSchema,
+	);
+}
+
+/**
+ * A compose file's `environment:` block, plus the secrets no compose file
+ * carries (they come from `.env` or a compose secret) — the environment the
+ * process would boot under.
+ *
+ * The key material follows what the file itself says: the production compose
+ * points the EdDSA key paths at its mounted secrets, so leave the default
+ * algorithm alone; the dev compose supplies no key at all, so give it the
+ * HS256 shape, whose `.strict()` union member is exactly why the two cannot
+ * share one map.
+ */
+function bootableEnv(rel: string): Record<string, string> {
+	const env: Record<string, string> = {
+		OAUTH_JWT_ISSUER: "https://auth.test",
+		SESSION_SECRET: "scaffold-assets-compose-session.at-least-32-bytes.ok",
+	};
+	for (const [key, value] of composeAppEnvironment(rel)) {
+		if (value !== null) env[key] = value;
+	}
+	if (env.OAUTH_JWT_PRIVATE_KEY_PATH === undefined) {
+		env.OAUTH_JWT_ALGORITHM = "HS256";
+		env.OAUTH_JWT_SECRET = "scaffold-assets-compose.at-least-32-bytes.ok";
+	}
+	return env;
+}
+
 describe("#407 — the Dockerfile installs with everything pnpm needs", () => {
 	it("copies pnpm-workspace.yaml into the deps stage", () => {
 		// `create-auth-provider` generates it to carry the bcrypt
@@ -106,6 +179,62 @@ describe("#407 — the production compose matches the topology it documents", ()
 	});
 });
 
+describe("the compose files put a store and its lifetime-sibling on the same backend", () => {
+	// The production compose set `SESSION_STORAGE_TYPE: redis` and left
+	// `USER_SESSION_STORES_ADAPTER` at its `memory` default. express-session
+	// then survives a restart and the `UserSession` it points at does not, so
+	// every browser comes back `isAuthenticated` with nothing behind it and
+	// /authorize loops until the cookie is deleted by hand.
+	//
+	// `DEPLOYMENT_MODE: single` is silent about this on purpose — the replica
+	// guard answers "can these stores be shared", not "do these two stores have
+	// the same lifetime" — so nothing but this assertion stands behind it.
+	for (const file of ["/docker-compose.production.yml", "/docker-compose.yml"]) {
+		it(`${file} keeps the user-session stores with the express-session store`, () => {
+			const config = resolveWith(bootableEnv(file));
+			// Resolved through the real config layers, not read off the file:
+			// what matters is the value the process ends up with, whether the
+			// compose stated it or `config/application.conf` did.
+			expect(config.session.storage?.type).toBe("redis");
+			expect(config.userSessionStores?.adapter).toBe("redis");
+		});
+	}
+
+	it("the production compose leaves no store on memory while a sibling is on Redis", () => {
+		const config = resolveWith(bootableEnv("/docker-compose.production.yml"));
+		// Every store whose records must outlive one process. The federation
+		// token store is deliberately absent: this template ships every
+		// federation disabled, so nothing writes to it, and turning it on needs
+		// an AES key the compose file must not invent.
+		expect(config.session.storage?.type).toBe("redis");
+		expect(config.userSessionStores?.adapter).toBe("redis");
+		expect(config.oauth.code?.adapter).toBe("redis");
+		expect(config.accessTokenDenylist?.adapter).toBe("redis");
+		expect(config.rateLimiter?.adapter).toBe("redis");
+	});
+});
+
+describe("the production compose refuses to guess HTTP_TRUST_PROXY", () => {
+	it("names the variable and supplies no default", () => {
+		// Without it the Secure cookie is never set, the CSRF origin check 403s
+		// every browser POST, and every IP-keyed rate limit shares one bucket.
+		// With a baked-in default it would silently trust a hop the operator
+		// never chose. The `${VAR:?err}` form is the only reading that is
+		// neither: compose refuses to start until the operator names their edge.
+		const compose = composeAppEnvironment("/docker-compose.production.yml");
+		expect(compose.has("HTTP_TRUST_PROXY")).toBe(true);
+		expect(compose.get("HTTP_TRUST_PROXY")).toBeNull();
+		expect(read("/docker-compose.production.yml")).not.toMatch(
+			/HTTP_TRUST_PROXY:\s*(true|false)\b/,
+		);
+	});
+
+	it("is offered in .env.example with no value", () => {
+		// The compose reads it from `.env`, which the operator copies from here.
+		expect(read("/.env.example")).toMatch(/^HTTP_TRUST_PROXY=$/m);
+	});
+});
+
 describe("#407 — the two READMEs agree on security advice", () => {
 	it("does not recommend HTTP_TRUST_PROXY=true in the Japanese README", () => {
 		// #292 made `trust proxy` a CIDR/hop policy precisely because `true`