@o3co/create-auth-provider 0.10.0 → 0.12.0

package/templates/standalone/docker-compose.production.yml

@@ -19,10 +19,11 @@
 #
 # What this file deliberately does NOT do:
 #
-# - **TLS.** Terminate it in front (reverse proxy / load balancer), and set
-#   HTTP_TRUST_PROXY to that hop's address so `req.ip` — and every IP-keyed
-#   rate limit — means the client, not the proxy. See README
-#   "Multi-replica deployments".
+# - **TLS.** Terminate it in front (reverse proxy / load balancer). The
+#   HTTP_TRUST_PROXY entry below then needs that hop's address so `req.ip` —
+#   and every IP-keyed rate limit — means the client, not the proxy; compose
+#   refuses to start until you supply it. See README "Multi-replica
+#   deployments".
 # - **Scale out.** This is one replica (DEPLOYMENT_MODE=single). Before
 #   `--scale app=N`, set DEPLOYMENT_MODE=multi and read that same README
 #   section — boot will then refuse any in-memory store that must be shared.
@@ -38,7 +39,16 @@ services:
       target: runtime
     restart: unless-stopped
     ports:
-      - "3000:3000"
+      # Loopback-bound on purpose (#407). This file assumes TLS is terminated
+      # in front, and the README says to keep `/metrics` off the public
+      # listener — a bare "3000:3000" publishes on every interface and
+      # contradicts both. A reverse proxy on the same host reaches it here.
+      #
+      # If your load balancer is on another host, publish it instead
+      # (`- "3000:3000"`) and put the access control somewhere real: a
+      # security group, a firewall rule, or the proxy's own network. Do not
+      # widen this line and call it done.
+      - "127.0.0.1:3000:3000"
     depends_on:
       redis:
         condition: service_healthy
@@ -65,7 +75,31 @@ services:
       - jwt_public_key
     environment:
       NODE_ENV: production
+      # One replica. Under `single` the replica-safety guard is SILENT by
+      # design — you have told it there are no peers — so it will not tell you
+      # that a store below is on memory while its sibling is on Redis. That is
+      # why the adapter block further down states every one of them explicitly
+      # instead of leaving them to inherit. Before `--scale app=N`, set `multi`
+      # and read the README's "Multi-replica deployments".
       DEPLOYMENT_MODE: single
+      # Behind the TLS terminator this file assumes, `req.ip` is the proxy's
+      # address and `req.protocol` reads `http` until this names the hop. The
+      # README calls it required for exactly that reason, and the cost of
+      # leaving it unset is three failures at once: the Secure cookie pinned
+      # below is never set, the CSRF origin check 403s every browser POST
+      # (the browser sends `Origin: https://…`, the process believes it is
+      # serving http), and every IP-keyed rate limit — the OAuth endpoint
+      # limiters and the /session/login brute-force guard — shares ONE bucket
+      # across all users.
+      #
+      # It cannot be guessed and it is not defaulted: only you know what sits
+      # in front, and a default here would silently trust a hop you never
+      # chose. Put your edge's address or CIDR range in `.env` — `10.0.0.0/8`,
+      # or `loopback` for a sidecar on this host. Prefer that over `true`,
+      # which believes a forwarded client address from anyone able to reach
+      # this process. The `:?` form makes compose refuse to start until it is
+      # set, rather than starting wrong.
+      HTTP_TRUST_PROXY: ${HTTP_TRUST_PROXY:?set to your TLS terminator's address or CIDR range (e.g. 10.0.0.0/8, or `loopback` for a same-host sidecar) — never `true` behind an open network}
       # Point the process at the mounted secrets rather than the working-copy
       # paths `.env` carries for local runs.
       OAUTH_JWT_PRIVATE_KEY_PATH: /run/secrets/jwt_private_key
@@ -80,14 +114,55 @@ services:
       SESSION_SECURE: "true"
       SESSION_NAME: __Host-auth.session
       # Every Redis-backed store shares the compose-network Redis below.
+      #
+      # These are stated in full rather than inherited from
+      # `config/application.conf`, so that the deployable file names its own
+      # topology: an operator reading only this one can see which stores
+      # survive a restart. `OAUTH_CODE_ADAPTER` and
+      # `ACCESS_TOKEN_DENYLIST_ADAPTER` already ship as `redis` in that config
+      # layer and are left there on purpose — restating a value that agrees is
+      # a second place to forget to change.
       REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: redis://redis:6379
       SESSION_STORAGE_TYPE: redis
       SESSION_STORAGE_REDIS_URL: redis://redis:6379
+      # The UserSession stores: the provider's own record of who is signed in,
+      # which RPs a session has touched, and the family / federation indexes
+      # hanging off it. They MUST be on Redis whenever the express-session
+      # store above is, and this line is the fix for what happens when they
+      # are not.
+      #
+      # express-session on Redis survives a restart; a memory UserSession store
+      # does not. So every browser comes back holding a session cookie whose
+      # express-session record still says `isAuthenticated: true`, while the
+      # `UserSession` that record points at is gone — /authorize sees an
+      # authenticated session, finds no user session behind it, and sends the
+      # browser to log in again, where the still-valid cookie puts it straight
+      # back. A login loop that clears only when the user deletes the cookie.
+      # `DEPLOYMENT_MODE: single` says nothing about it: the replica guard
+      # answers "can these stores be shared", not "do these two stores have the
+      # same lifetime".
+      USER_SESSION_STORES_ADAPTER: redis
       # The memory rate limiter is per-process and evadable under bucket
       # exhaustion (see README) — production points it at Redis.
       RATE_LIMITER_ADAPTER: redis
+      # The federation token store is deliberately left at its `memory`
+      # default, and that is coherent here rather than an oversight: this
+      # template ships every federation disabled, so nothing writes to the
+      # store, and switching it on would need a 32-byte AES key
+      # (REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY) that this file must not
+      # invent — the records are long-lived upstream refresh tokens. Enabling
+      # a federation means setting BOTH, together:
+      #   FEDERATION_TOKEN_STORE_TYPE: redis
+      #   REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: <openssl rand -base64 32, from .env>
 
   redis:
+    # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
+    # and that argument holds here too — a tag is mutable, so two `up`s a month
+    # apart can run different Redis builds. Pin the digest for a production
+    # deployment you need to reproduce:
+    #   image: redis:7.2-alpine@sha256:<digest>
+    # Left as a tag in the template because a digest goes stale the week it is
+    # written and a scaffold that ships a stale one teaches nothing (#407).
     image: redis:7.2-alpine
     restart: unless-stopped
     # No `ports:`, deliberately — the app reaches Redis over the compose

package/templates/standalone/docker-compose.yml

@@ -14,8 +14,32 @@ services:
     env_file:
       - path: .env
         required: false
+    environment:
+      # The same coherence the production file states, for the same reason,
+      # and it matters MORE here. `config/application.conf` already puts
+      # express-session, the authorization codes and the access-token denylist
+      # on the Redis this compose runs; only the UserSession stores were left
+      # on their `memory` default. That combination survives a restart on one
+      # side and not the other, so every browser comes back holding an
+      # express-session that still says `isAuthenticated` with no `UserSession`
+      # behind it and /authorize loops.
+      #
+      # A dev container restarts on every save (`target: develop` is hot
+      # reload), so the developer meets that loop constantly — and meets it
+      # while changing something else, which is the worst possible time to
+      # debug it. Redis is already running and already required by three other
+      # stores, so this costs nothing: the shared ioredis socket is open
+      # either way.
+      USER_SESSION_STORES_ADAPTER: redis
 
   redis:
+    # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
+    # and that argument holds here too — a tag is mutable, so two `up`s a month
+    # apart can run different Redis builds. Pin the digest for a production
+    # deployment you need to reproduce:
+    #   image: redis:7.2-alpine@sha256:<digest>
+    # Left as a tag in the template because a digest goes stale the week it is
+    # written and a scaffold that ships a stale one teaches nothing (#407).
     image: redis:7.2-alpine
     ports:
       - "127.0.0.1:6379:6379"

package/templates/standalone/gitignore

@@ -0,0 +1,21 @@
+# #407: without this file, the first `git add .` in a scaffolded project
+# commits the two things the README's own setup steps tell you to create right
+# here — the `.env` holding SESSION_SECRET, and the signing key pair.
+
+# Secrets and per-machine configuration
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+config/clients.yaml
+config/*.local.conf
+
+# Build output and dependencies
+node_modules/
+dist/
+coverage/
+
+# Editor / OS noise
+.DS_Store
+*.log

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -27,8 +27,7 @@
 		"@o3co/auth-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
 		"@o3co/auth-provider-session": "workspace:*",
-		"@o3co/auth.utils": "^0.0.4",
-		"@o3co/ts.hocon": "^1.12.0",
+		"@o3co/ts.hocon": "^1.13.0",
 		"connect-redis": "^10.0.0",
 		"express": "^5.2.1",
 		"express-session": "^1.19.0",
@@ -36,7 +35,7 @@
 		"ioredis": "^6.0.0",
 		"pino": "^10.3.1",
 		"prom-client": "^15.1.3",
-		"redis": "^6.2.0"
+		"redis": "^6.2.1"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
@@ -45,7 +44,7 @@
 		"@types/supertest": "^7.2.1",
 		"supertest": "^7.1.0",
 		"tsx": "^4.23.10",
-		"typescript": "^5.9.3",
-		"vitest": "^4.1.10"
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.11"
 	}
 }

package/templates/standalone/src/__tests__/device-code-store-client-module.test.mts

@@ -0,0 +1,100 @@
+/*
+ * 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.
+ */
+
+/**
+ * `standaloneRedisClientsModule` provides `deviceCodeStoreClient` (#433).
+ *
+ * The template does not mount the device grant, so nothing in `buildModules`
+ * selects `redisDeviceCodeStoreModule` today and the smoke test's client-slot
+ * invariant cannot see it. This pins the slot directly: a deployment that adds
+ * `deviceGrantModule` to this manifest and picks the Redis store must not hit
+ * the `missing-required-component` boot failure that #439 already paid for
+ * once with the subject-level slots — a Redis-branch module whose required
+ * client slot the shared clients module did not provide, caught only by the
+ * umbrella e2e.
+ */
+
+import type { LifecycleRegistrar } from "@o3co/auth-provider-core";
+import { redisDeviceCodeStoreModule } from "@o3co/auth-provider-redis";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const redisCtorCalls: Array<{ url: string }> = [];
+
+vi.mock("ioredis", () => {
+	class MockRedis {
+		on = vi.fn();
+		quit = vi.fn(async () => "OK" as const);
+		ping = vi.fn(async () => "PONG" as const);
+		eval = vi.fn();
+		evalsha = vi.fn();
+		duplicate(): MockRedis {
+			return new MockRedis("redis://duplicate.local");
+		}
+		constructor(url: string) {
+			redisCtorCalls.push({ url });
+		}
+	}
+	return { Redis: MockRedis, default: MockRedis };
+});
+
+const importModule = async () => await import("../modules.mjs");
+
+const baseConfig = {
+	refreshTokenFamilyStore: {
+		redis: { url: "redis://example.com:6379" },
+	},
+};
+
+describe("#433 / standaloneRedisClientsModule.deviceCodeStoreClient", () => {
+	beforeEach(() => {
+		redisCtorCalls.length = 0;
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("provides every *Client slot redisDeviceCodeStoreModule requires", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provided = new Set(Object.keys(standaloneRedisClientsModule.provides ?? {}));
+		const required = [...(redisDeviceCodeStoreModule.requires ?? [])].filter((key) =>
+			key.endsWith("Client"),
+		);
+		expect(required).toEqual(["deviceCodeStoreClient"]);
+		expect(required.filter((key) => !provided.has(key))).toEqual([]);
+	});
+
+	it("resolves the client off the one shared socket, not a second connection", async () => {
+		const { standaloneRedisClientsModule } = await importModule();
+		const provides = (
+			standaloneRedisClientsModule as unknown as {
+				provides: Record<string, (deps: Record<string, unknown>) => Promise<unknown>>;
+			}
+		).provides;
+		const lifecycleRegistrar: LifecycleRegistrar = { register: () => {} };
+
+		const client = (await provides.deviceCodeStoreClient?.({
+			config: { ...baseConfig },
+			lifecycleRegistrar,
+		})) as Record<string, unknown>;
+		await provides.rateLimiterClient?.({ config: { ...baseConfig }, lifecycleRegistrar });
+
+		expect(redisCtorCalls).toHaveLength(1);
+		for (const method of ["create", "findPending", "decide", "poll", "remove"]) {
+			expect(typeof client[method], `deviceCodeStoreClient.${method}`).toBe("function");
+		}
+	});
+});

package/templates/standalone/src/__tests__/documented-env-overrides.test.mts

@@ -88,11 +88,15 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	OAUTH_OIDC_MODE: "dual",
 	OAUTH_CODE_ADAPTER: "redis",
 	OAUTH_REVOCATION_ACCESS_TOKEN: "denylist",
+	OAUTH_REVOCATION_SUBJECT: "unsupported",
 	OAUTH_REQUIRE_EMAIL_VERIFIED: "true",
+	OAUTH_REQUIRE_GRANT_TYPE_ALLOWLIST: "true",
+	OAUTH_GRANTS_JWT_BEARER_ENABLED: "false",
 	OAUTH_NONCE_MAX_LENGTH: "256",
 	OAUTH_TOKEN_EXCHANGE_MAX_ACTOR_CHAIN_DEPTH: "3",
 	OAUTH_RESOURCE_INDICATOR_ENABLED: "true",
 	OAUTH_TOKEN_BINDING_DISPATCH_POLICY: "intent-explicit",
+	OAUTH_TOKEN_BINDING_BIND_CONFIDENTIAL_CLIENT_REFRESH_TOKENS: "true",
 
 	// --- oauth.grants -------------------------------------------------
 	OAUTH_GRANTS_SESSION_ENABLED: "false",
@@ -138,6 +142,12 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	REFRESH_TOKEN_FAMILY_STORE_CAS_RETRY_LIMIT: "3",
 	REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: "redis://redis:6379",
 	REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD: "rt-family-password",
+	// #456: the federation token store's Redis branch, which the README
+	// documented and which could not boot.
+	FEDERATION_TOKEN_STORE_TYPE: "redis",
+	REDIS_FEDERATION_TOKEN_STORE_KEY_PREFIX: "ft:",
+	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE: "required",
+	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=",
 
 	// --- federation ---------------------------------------------------
 	FEDERATIONS_GOOGLE_ENABLED: "true",
@@ -162,6 +172,12 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 
 	// --- endpoints ----------------------------------------------------
 	ENDPOINTS_LOGIN_URL: "/login",
+
+	// --- cors ---------------------------------------------------------
+	// #500: a list, in the only shape an environment variable can carry one.
+	// The schema splits and validates it; the `turns every non-boolean
+	// override into its declared type` case below pins the result.
+	CORS_ALLOWED_ORIGINS: "https://app.example.com,http://localhost:5173",
 };
 
 /**
@@ -180,6 +196,14 @@ const DELIBERATELY_UNSET: Readonly<Record<string, string>> = {
  * so a parse failure here is a red umbrella build that this repository can see
  * first. `SESSION_SECURE=false` is the one it cannot run without: the suite
  * speaks plain HTTP.
+ *
+ * The two `FEDERATION_TOKEN_STORE` lines are what #455 / #456 **require the
+ * umbrella compose to add**: the federation token store defaults to memory,
+ * and the standalone's memory module now declares itself replica-unsafe, so
+ * the umbrella's `DEPLOYMENT_MODE=multi` refuses it by name until the compose
+ * selects the Redis store and supplies its encryption key. Until that lands
+ * in `o3co/auth`, this transcription is ahead of the file it transcribes on
+ * exactly those two lines.
  */
 const UMBRELLA_E2E_ENV: Readonly<Record<string, string>> = {
 	OAUTH_JWT_ALGORITHM: "HS256",
@@ -194,6 +218,8 @@ const UMBRELLA_E2E_ENV: Readonly<Record<string, string>> = {
 	USER_SESSION_STORES_ADAPTER: "redis",
 	RATE_LIMITER_ADAPTER: "redis",
 	OAUTH_CODE_ADAPTER: "redis",
+	FEDERATION_TOKEN_STORE_TYPE: "redis",
+	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=",
 	CLIENT_USER_TYPE: "yaml",
 	OAUTH_RESOURCE_INDICATOR_ENABLED: "true",
 	OAUTH_REQUIRE_EMAIL_VERIFIED: "true",
@@ -274,6 +300,45 @@ describe("#288: the shipped config boots with every documented override supplied
 		expect(config.session.maxAge).toBe(3600000);
 		expect(config.session.csrf?.ttlSeconds).toBe(7200);
 		expect(config.oauth.nonce?.maxLength).toBe(256);
+		// #500: a comma-separated string becomes a list of origins, trimmed.
+		expect(config.cors?.allowedOrigins).toEqual([
+			"https://app.example.com",
+			"http://localhost:5173",
+		]);
+	});
+
+	describe("CORS_ALLOWED_ORIGINS (#500)", () => {
+		it("reads an exported-but-empty variable as no origins, not as an error", () => {
+			// The .env / compose / ConfigMap shape. "CORS off" is what both the
+			// unset key and the empty string mean, so they must agree.
+			const config = buildResolvedConfig({ ...DOCUMENTED_ENV, CORS_ALLOWED_ORIGINS: "" });
+			expect(config.cors?.allowedOrigins).toEqual([]);
+		});
+
+		it("fails boot on an origin that could never match, naming the key", () => {
+			// Every one of these parses as a URL and is a real typo: matching is
+			// exact string equality against the Origin header, so each would be
+			// an allowlist that admits nobody with nothing to say so.
+			for (const bad of [
+				"https://app.example.com/", // trailing slash
+				"https://app.example.com:443", // explicit default port
+				"https://*.example.com", // wildcard
+				"http://app.example.com", // plaintext off loopback
+				"https://app.example.com/callback", // a URL, not an origin
+			]) {
+				expect(() => buildResolvedConfig({ ...DOCUMENTED_ENV, CORS_ALLOWED_ORIGINS: bad })).toThrow(
+					/cors\.allowedOrigins/,
+				);
+			}
+		});
+
+		it("accepts the loopback http carve-out a dev front-end needs", () => {
+			const config = buildResolvedConfig({
+				...DOCUMENTED_ENV,
+				CORS_ALLOWED_ORIGINS: "http://localhost:5173,http://127.0.0.1:5173,https://app.example.com",
+			});
+			expect(config.cors?.allowedOrigins).toHaveLength(3);
+		});
 	});
 
 	it("parses the HS256 shape, whose strict union refuses asymmetric key fields", () => {
@@ -302,10 +367,12 @@ describe("#288: the shipped config boots with every documented override supplied
 	it("wires nothing replica-unsafe for the umbrella E2E environment", async () => {
 		// `DEPLOYMENT_MODE=multi` makes the provider audit its own store wiring
 		// at boot, so a config that parses but wires a memory store still fails
-		// there. Assert against the guard's own list rather than module names.
-		const { REPLICA_UNSAFE_MODULES } = await import("@o3co/auth-provider-core");
-		for (const name of buildModules(buildResolvedConfig(UMBRELLA_E2E_ENV)).map((m) => m.name)) {
-			expect(REPLICA_UNSAFE_MODULES).not.toContain(name);
+		// there. Ask each manifest, the way the guard does (#455): the exported
+		// name list covers core's modules only, and the template's own memory
+		// modules are precisely the ones it could not see.
+		const { replicaUnsafeReason } = await import("@o3co/auth-provider-core");
+		for (const module of buildModules(buildResolvedConfig(UMBRELLA_E2E_ENV))) {
+			expect(replicaUnsafeReason(module), module.name).toBeUndefined();
 		}
 	});
 

package/templates/standalone/src/__tests__/redis-rate-limiter-config-survives.test.mts

@@ -0,0 +1,179 @@
+/*
+ * 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.
+ */
+
+/**
+ * #495 / #496 — end to end, through this template's real resolution chain.
+ *
+ * `app.mts` resolves `{env}.conf → application.conf → reference.conf` and
+ * validates the result with `AppConfigSchema` before `buildModules` runs.
+ * The schema strips what it does not declare, so a section declared by a
+ * module rather than by core used to vanish at exactly that step — and,
+ * because `redisRateLimiterModule.configSchema` carries a
+ * `.default({ limit: 60, windowSeconds: 60 })`, the deployment that
+ * `docker-compose.production.yml` ships (`RATE_LIMITER_ADAPTER: redis`) then
+ * ran on 60 requests / 60 s no matter what the operator wrote.
+ *
+ * This starts from the shipped configuration, adds the two overrides an
+ * operator writes in their own `application.conf` layer, and follows them all
+ * the way to the limiter the module builds.
+ */
+
+import { fileURLToPath } from "node:url";
+import { type AppConfig, AppConfigSchema, type RateLimiter } from "@o3co/auth-provider-core";
+import { redisRateLimiterModule } from "@o3co/auth-provider-redis";
+import { parseFile, parseString } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import { describe, expect, it } from "vitest";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+/**
+ * The secrets `application.conf` substitutes, plus the one
+ * `docker-compose.production.yml` sets to put the OAuth endpoints behind a
+ * shared limiter. Test-only values; #282's entropy floor applies to the two
+ * secrets, and the `.` characters keep them out of the base64 alphabet so the
+ * UTF-8 length is what counts.
+ */
+const ENV = {
+	OAUTH_JWT_SECRET: "test-secret-rate-limiter-e2e.at-least-32-bytes.ok",
+	OAUTH_JWT_ISSUER: "https://auth.test",
+	SESSION_SECRET: "test-session-secret-rate-limiter-e2e.at-least-32-bytes.ok",
+	RATE_LIMITER_ADAPTER: "redis",
+};
+
+/**
+ * What an operator adds to their own `application.conf` layer: per-endpoint
+ * budgets for the Redis limiter, and the mTLS posture from
+ * `@o3co/auth-provider-mtls`. Neither section appears in anything this
+ * template ships, which is why neither was ever covered by a `.conf` diff.
+ */
+const OPERATOR_OVERRIDES = `
+redisRateLimiter {
+  limits {
+    token { limit = 120, windowSeconds = 60 }
+    authorize { limit = 30, windowSeconds = 60 }
+  }
+}
+
+oauth.mtls {
+  enabled = true
+  mode = "full-pki"
+  trusted-cas = ["-----BEGIN CERTIFICATE-----"]
+  full-pki {
+    revocation {
+      mode = "crl"
+      on-unavailable = "reject"
+      allowed-hosts = ["crl.example.com"]
+    }
+  }
+}
+`;
+
+function resolveShippedConfig(): AppConfig {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	return validate(
+		parseString(OPERATOR_OVERRIDES, { env: ENV })
+			.withFallback(parseFile(envConfPath, { env: ENV }))
+			.withFallback(parseFile(applicationConfPath, { env: ENV }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env: ENV })),
+		AppConfigSchema,
+	);
+}
+
+/** Counts one request per key, the way an untouched Redis counter would. */
+function makeCountingClient(): { incrementWithTtl: (key: string, ttl: number) => Promise<number> } {
+	return { incrementWithTtl: async () => 1 };
+}
+
+function buildLimiter(config: AppConfig): RateLimiter {
+	const provides = (
+		redisRateLimiterModule as unknown as {
+			provides: Record<string, (deps: Record<string, unknown>) => RateLimiter>;
+		}
+	).provides;
+	const provider = provides.rateLimiter;
+	if (!provider) throw new Error("redisRateLimiterModule no longer provides rateLimiter");
+	return provider({ config, rateLimiterClient: makeCountingClient() });
+}
+
+describe("the shipped configuration reaches the Redis rate limiter (#495)", () => {
+	const config = resolveShippedConfig();
+
+	it("selects the Redis adapter the production compose file pins", () => {
+		expect(config.rateLimiter?.adapter).toBe("redis");
+	});
+
+	it("carries the operator's per-endpoint budgets through the pre-parse", () => {
+		expect(config.redisRateLimiter?.limits).toEqual({
+			token: { limit: 120, windowSeconds: 60 },
+			authorize: { limit: 30, windowSeconds: 60 },
+		});
+	});
+
+	it("applies the declared budget at /token", async () => {
+		const decision = await buildLimiter(config).check("token:ip:203.0.113.5", {
+			ip: "203.0.113.5",
+		});
+		expect(decision.limit).toBe(120);
+	});
+
+	it("applies the declared budget at /authorize", async () => {
+		const decision = await buildLimiter(config).check("authorize:ip:203.0.113.5", {
+			ip: "203.0.113.5",
+		});
+		expect(decision.limit).toBe(30);
+	});
+
+	it("still falls back to the module's default where nothing is declared", async () => {
+		// The point of the assertion above: 60 is what EVERY endpoint got while
+		// the section was stripped, so a test that only saw 60 could not tell a
+		// working configuration from a lost one.
+		const decision = await buildLimiter(config).check("introspect:ip:203.0.113.5", {
+			ip: "203.0.113.5",
+		});
+		expect(decision.limit).toBe(60);
+	});
+
+	it("keeps seeding /session/login from rateLimit.login", async () => {
+		// `resolveSeededLimitSpecs` reads a declared section, so this worked
+		// even while `redisRateLimiter` was being stripped — which is why the
+		// defect showed up only at the endpoints below it.
+		const decision = await buildLimiter(config).check("login:ip:203.0.113.5", {
+			ip: "203.0.113.5",
+		});
+		expect(decision.limit).toBe(config.rateLimit?.login.limit);
+	});
+});
+
+describe("the shipped configuration carries an mTLS posture through (#496)", () => {
+	const config = resolveShippedConfig();
+
+	it("keeps the operator's mTLS block instead of reporting mTLS off", () => {
+		expect(config.oauth.mtls).toEqual({
+			enabled: true,
+			mode: "full-pki",
+			"trusted-cas": ["-----BEGIN CERTIFICATE-----"],
+			"full-pki": {
+				revocation: {
+					mode: "crl",
+					"on-unavailable": "reject",
+					"allowed-hosts": ["crl.example.com"],
+				},
+			},
+		});
+	});
+});