@o3co/create-auth-provider 0.17.0-rc.1 → 0.17.0-rc.3

package/templates/standalone/config/reference.conf

@@ -1,6 +1,7 @@
 # Defaults of the standalone template's own modules (src/modules.mts), each in
 # the section named after its module, and of its own `adapters` and
-# `mfaMode`, each key with its variable, named after its path. Layered
+# `mfaMode`, each key with its variable, named after its path, and the MFA
+# routes' budget in each rate limiter's section (below `mfaMode`). Layered
 # beneath application.conf and {env}.conf: set a deployment's own values
 # there, not here. A value either file sets wins over
 # the variable bound here, except for HTTP_PORT, HTTP_TRUST_PROXY,
@@ -129,11 +130,17 @@ key-store {
 
 # `redis-clients`: the one ioredis socket per replica every Redis-backed store
 # shares. More than one replica needs a shared Redis 7.2+ here; localhost
-# inside a container is the container itself.
+# inside a container is the container itself. The Redis stores that keep
+# durable keys refuse to boot unless the server reports maxmemory-policy
+# `noeviction`. `assumeNoEviction = true` asserts it for a server that will not
+# report it (INFO and CONFIG refused to the connection's user); a policy the
+# server does report always decides.
 redis-clients {
   url = "redis://localhost:6379"
   url = ${?REDIS_CLIENTS_URL}
   password = ${?REDIS_CLIENTS_PASSWORD}
+  assumeNoEviction = false
+  assumeNoEviction = ${?REDIS_CLIENTS_ASSUME_NO_EVICTION}
 }
 
 # `repositories`: the client registry, and the user repository's settings for
@@ -217,9 +224,16 @@ audit-sink {}
 # replica, and `core.deployment.mode = "multi"` refuses each memory store by
 # name. Each Redis store shares the one socket `redis-clients` opens.
 adapters {
-  # The OAuth endpoints' and /session/login's rate-limit counters.
+  # The rate-limit counters: the OAuth endpoints' and the MFA routes'.
   rateLimiter = "memory"
   rateLimiter = ${?ADAPTERS_RATE_LIMITER}
+  # The counter behind /session/login's own attempt limit
+  # (session.rateLimit.login), and device verification's
+  # (device-grant.rateLimit) when the device grant is added. `memory` wires
+  # none: each counts per process, which `core.deployment.mode = "multi"`
+  # refuses. `redis` needs a server whose maxmemory-policy is `noeviction`.
+  attemptCounter = "memory"
+  attemptCounter = ${?ADAPTERS_ATTEMPT_COUNTER}
   # The four user-session stores and the subject-level revocation pair. They
   # must be on Redis whenever express-session's store is, or a restart leaves
   # every browser a session whose user session is gone.
@@ -294,14 +308,25 @@ adapters {
 mfaMode = "required"
 mfaMode = ${?MFA_MODE}
 
+# The MFA routes' budget: the one setting this file writes in sections of
+# modules other than the template's own. Every /session/mfa POST is limited
+# per client address under the prefix `mfa` (`mfa:ip:<ip>`) by the wired
+# limiter alone: the MFA package ships no budget of its own. Both limiters
+# carry it, so switching `adapters.rateLimiter` keeps it; written here, beside
+# each package's own defaults, the limiter not wired has it as a default
+# rather than as a setting nothing reads. Without an entry the limiter's
+# `defaultLimit` (60 per 60 s) applies. The MFA lock is separate and unchanged.
+core-rate-limiter-memory.limits.mfa { limit = 60, windowSeconds = 300 }
+redis-rate-limiter.limits.mfa { limit = 60, windowSeconds = 300 }
+
 # The old paths of these sections refuse boot naming the new ones: `cors`,
 # `oauth.jwt.signingKey`, `refreshTokenFamilyStore.redis`,
 # `repositories.code` and `audit.sink`; the old adapter switches
 # (`rateLimiter.adapter`, `oauth.code.adapter`, ...) are refused before the
 # modules are chosen, and so are the variables renamed with them. What the
 # resolution saw of each variable they renamed: each name null, then its value
-# when set. Boot refuses an old name set unless its new name is set to the
-# same value, and removes this section before it parses the configuration.
+# when set. Boot refuses an old name set, whether or not its new name is set,
+# and removes this section before it parses the configuration.
 # Never write it in another layer.
 renamed-variables {
   LOG_LEVEL = null

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

@@ -4,6 +4,9 @@
 #
 #   docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 #
+# Write MFA_ENCRYPTION_KEY into .env first (openssl rand -base64 32): this run
+# reads its MFA key from it, not the development sample key.
+#
 # Mailpit keeps every mail the provider sends and delivers none; read them at
 # http://localhost:8025. Never use it in production, where
 # STANDARD_SMTP_MAIL_SENDER_* name a real relay. Leave every

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

@@ -142,8 +142,8 @@ services:
       SESSION_STORE_STORAGE_TYPE: redis
       SESSION_STORE_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
+      # the subject index and revocation boundaries beside it, and the session
+      # lifecycle records. 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.
       #
@@ -161,6 +161,9 @@ services:
       # The memory rate limiter is per-process and evadable under bucket
       # exhaustion (see README) — production points it at Redis.
       ADAPTERS_RATE_LIMITER: redis
+      # The counter behind the login's own attempt limit: on Redis, a restart
+      # does not reset it. Redis must keep `maxmemory-policy noeviction`.
+      ADAPTERS_ATTEMPT_COUNTER: 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

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.17.0-rc.1",
+	"version": "0.17.0-rc.3",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {

package/templates/standalone/src/__tests__/adapters.test.mts

@@ -28,7 +28,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { defineModule } from "@o3co/auth-provider-core";
+import { BootError, defineModule } from "@o3co/auth-provider-core";
 import { afterAll, describe, expect, it } from "vitest";
 import { z } from "zod";
 import { buildModules } from "#/buildModules.mjs";
@@ -60,12 +60,13 @@ const MFA_OFF: Readonly<Record<string, string>> = { MFA_MODE: "off" };
 const adaptersFrom = (env: Record<string, string> = {}, hocon?: string) =>
 	readSwitches(readOwnLayers(ownFiles(hocon), { env })).adapters;
 
-/** What phase one refuses under `env` and an operator's `hocon`. */
-function refusal(env: Record<string, string> = {}, hocon?: string): Error {
+/** What phase one refuses under `env` and an operator's `hocon`: a `BootError`. */
+function refusal(env: Record<string, string> = {}, hocon?: string): BootError {
 	try {
 		adaptersFrom(env, hocon);
 	} catch (err) {
-		return err as Error;
+		expect(err).toBeInstanceOf(BootError);
+		return err as BootError;
 	}
 	throw new Error("phase one read the adapters");
 }
@@ -141,6 +142,7 @@ describe("the shipped selections", () => {
 	it("reads every selection from the template's reference.conf, at the values the template ships", () => {
 		expect(adaptersFrom()).toEqual({
 			rateLimiter: "memory",
+			attemptCounter: "memory",
 			userSessionStores: "memory",
 			accessTokenDenylist: "redis",
 			replaySeenSet: "redis",
@@ -164,14 +166,25 @@ describe("the shipped selections", () => {
 		},
 	);
 
+	it("reads adapters.attemptCounter from ADAPTERS_ATTEMPT_COUNTER", () => {
+		expect(adaptersFrom({ ADAPTERS_ATTEMPT_COUNTER: "redis" }).attemptCounter).toBe("redis");
+		expect(refusal({ ADAPTERS_ATTEMPT_COUNTER: "memcached" }).message).toMatch(
+			/adapters\.attemptCounter/,
+		);
+	});
+
 	it("reads a selection an operator writes in HOCON", () => {
 		expect(adaptersFrom({}, 'adapters.rateLimiter = "redis"\n').rateLimiter).toBe("redis");
 	});
 
 	it("refuses a value its schema does not know, naming the key", () => {
-		expect(refusal({ ADAPTERS_RATE_LIMITER: "memcached" }).message).toMatch(
-			/adapters\.rateLimiter/,
-		);
+		const err = refusal({ ADAPTERS_RATE_LIMITER: "memcached" });
+		expect(err.message).toMatch(/adapters\.rateLimiter/);
+		expect(err.reason).toBe("config-validation-failed");
+		expect(err.details).toMatchObject({
+			issues: [{ path: ["adapters", "rateLimiter"] }],
+			modules: [{ module: "adapters", schemaPath: "adapters" }],
+		});
 	});
 
 	it("refuses the Store for the MFA transaction store, which holds verification state, and accepts it for the factor store", () => {
@@ -198,9 +211,22 @@ describe("a path a selection moved from, written in the operator's own layer", (
 		"adapters.%s: refused where it was, %s's old path, naming the new path and ADAPTERS_%s",
 		(key, name, oldPath, _oldName, value) => {
 			const err = refusal({}, `${oldPath} = "${value}"\n`);
-			expect(err).toBeInstanceOf(RangeError);
-			expect(err.message).toContain(`${oldPath} has moved to adapters.${key}`);
+			expect(err.message).toContain(
+				`${oldPath} has moved to adapters.${key}; see the upgrade guide (docs/upgrading-from-v0.16.0.md).`,
+			);
 			expect(err.message).toContain(`ADAPTERS_${name}`);
+			expect(err.reason).toBe("config-path-relocated");
+			expect(err.details).toEqual({
+				reason: "config-path-relocated",
+				relocated: [
+					{
+						module: "adapters",
+						from: oldPath,
+						to: `adapters.${key}`,
+						environmentVariable: `ADAPTERS_${name}`,
+					},
+				],
+			});
 		},
 	);
 
@@ -212,6 +238,13 @@ describe("a path a selection moved from, written in the operator's own layer", (
 		for (const path of ["rateLimiter.adapter", "consentStore.adapter", "audit.sink.type"]) {
 			expect(err.message).toContain(path);
 		}
+		expect(err.details).toMatchObject({
+			relocated: [
+				{ from: "rateLimiter.adapter" },
+				{ from: "consentStore.adapter" },
+				{ from: "audit.sink.type" },
+			],
+		});
 	});
 });
 
@@ -220,9 +253,22 @@ describe("a variable renamed with a selection", () => {
 		"adapters.%s: %s's old variable set alone is refused, naming ADAPTERS_%s",
 		(key, name, _oldPath, oldName, value) => {
 			const err = refusal({ [oldName]: value });
-			expect(err).toBeInstanceOf(RangeError);
-			expect(err.message).toContain(`${oldName} was renamed ADAPTERS_${name}`);
-			expect(err.message).toContain(`adapters.${key}`);
+			expect(err.message).toContain(
+				`${oldName} was renamed ADAPTERS_${name}, the variable adapters.${key} is bound to; see the upgrade guide (docs/upgrading-from-v0.16.0.md).`,
+			);
+			expect(err.reason).toBe("environment-variable-renamed");
+			expect(err.details).toEqual({
+				reason: "environment-variable-renamed",
+				renamed: [
+					{
+						module: "adapters",
+						from: oldName,
+						to: `ADAPTERS_${name}`,
+						path: `adapters.${key}`,
+						state: "unset",
+					},
+				],
+			});
 		},
 	);
 
@@ -233,13 +279,18 @@ describe("a variable renamed with a selection", () => {
 			expect(err.message).toContain(oldName);
 			expect(err.message).not.toContain("old-value-5e2d");
 			expect(err.message).not.toContain("new-value-c81a");
+			expect(err.details).toMatchObject({ renamed: [{ from: oldName, state: "different" }] });
+			expect(JSON.stringify(err.details)).not.toMatch(/old-value-5e2d|new-value-c81a/);
 		},
 	);
 
 	it.each(SELECTIONS)(
-		"adapters.%s: the old variable beside ADAPTERS_%s at the same value is read",
-		(key, name, _oldPath, oldName, value) => {
-			expect(adaptersFrom({ [oldName]: value, [`ADAPTERS_${name}`]: value })[key]).toBe(value);
+		"adapters.%s: the old variable beside ADAPTERS_%s at the same value is refused all the same",
+		(_key, name, _oldPath, oldName, value) => {
+			const err = refusal({ [oldName]: value, [`ADAPTERS_${name}`]: value });
+			expect(err.reason).toBe("environment-variable-renamed");
+			expect(err.message).toContain(`unset ${oldName}`);
+			expect(err.details).toMatchObject({ renamed: [{ from: oldName, state: "different" }] });
 		},
 	);
 });
@@ -277,6 +328,13 @@ describe("the modules phase one chooses by the selections", () => {
 		expect(modules).toContain(installed);
 		expect(modules).not.toContain(absent);
 	});
+
+	it("ADAPTERS_ATTEMPT_COUNTER=redis installs redis-attempt-counter over the shared Redis socket; memory installs no counter", () => {
+		const onRedis = names({ ADAPTERS_ATTEMPT_COUNTER: "redis" });
+		expect(onRedis).toContain("redis-attempt-counter");
+		expect(onRedis).toContain("redis-clients");
+		expect(names({ ADAPTERS_ATTEMPT_COUNTER: "memory" })).not.toContain("redis-attempt-counter");
+	});
 });
 
 describe("the federation-grant stores", () => {
@@ -335,24 +393,33 @@ describe("boot and the section", () => {
 	});
 
 	it.each([
-		["named adapters", "adapters", undefined],
-		["with its section at adapters.custom", "custom-thing", "adapters.custom"],
-	] as const)("refuses a module %s: its section would never reach boot", (_label, name, at) => {
+		["named adapters", "adapters"],
+		["named mfaMode", "mfaMode"],
+	] as const)("refuses a module %s: its section would never reach boot", (_label, name) => {
 		const own = readOwnLayers(ownFiles(), { env: MFA_OFF });
 		const switches = readSwitches(own);
 		const mine = defineModule({
 			name,
-			section: {
-				schema: z.object({}).passthrough().optional(),
-				...(at === undefined ? {} : { at }),
-			},
+			section: { schema: z.object({}).passthrough().optional() },
 		});
-		expect(() =>
+		const run = () =>
 			resolveForBoot(
 				own,
 				[...buildModules(switches, { environment: "production" }), mine],
 				switches,
-			),
-		).toThrow(new RegExp(`"${name}".*adapters`));
+			);
+		expect(run).toThrow(new RegExp(`"${name}".*composition root's own section`));
+		const err = (() => {
+			try {
+				run();
+			} catch (thrown) {
+				return thrown;
+			}
+		})();
+		expect(err).toBeInstanceOf(BootError);
+		expect(err).toMatchObject({
+			reason: "module-section-path-invalid",
+			details: { module: name, at: name },
+		});
 	});
 });

package/templates/standalone/src/__tests__/admission-lifecycle.test.mts

@@ -0,0 +1,87 @@
+/*
+ * 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.
+ */
+
+/**
+ * The oauth package's consumers of session admission read the session
+ * lifecycle's record the template's session stores provide: a session whose
+ * record is closing is refused at `/authorize`, the code exchange and the
+ * refresh grant, while its user session is still there.
+ */
+
+import type { SessionLifecycleStore, UserSessionStore } from "@o3co/auth-provider-core";
+import request from "supertest";
+import { describe, expect, it } from "vitest";
+import {
+	authorize,
+	basic,
+	codeFrom,
+	compose,
+	login,
+	redeem,
+	WEB,
+} from "./all-modules-composition.fixture.mjs";
+
+/** A JWT's claims, unverified. */
+const claimsOf = (token: string): Record<string, unknown> =>
+	JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+
+describe("a session whose lifecycle record is closing", () => {
+	it("is refused at /authorize, the code exchange and the refresh grant", async () => {
+		const { app, handle } = await compose();
+		try {
+			const components = handle.components as Record<string, unknown>;
+			const store = components.sessionLifecycleStore as SessionLifecycleStore;
+			const sessions = components.userSessionStore as UserSessionStore;
+			const { cookies } = await login(app);
+			const tokens = (await redeem(app, codeFrom(await authorize(app, cookies)))).body as Record<
+				string,
+				string
+			>;
+			const sid = String(claimsOf(tokens.id_token ?? "").sid);
+			const pendingCode = codeFrom(await authorize(app, cookies));
+
+			// The session's close commits, its work pending: the user session stays.
+			const session = await sessions.get(sid);
+			if (session === null) throw new Error("the login wrote no session");
+			expect((await store.open(sid, session.sub, session.expiresAt)).outcome).toBe("opened");
+			const closing = await store.beginClose(sid, {
+				cause: "rp_logout",
+				steps: ["held_open"],
+				perParticipant: [],
+				retainMs: 0,
+			});
+			expect(closing.outcome).toBe("closing");
+			expect(await sessions.get(sid)).not.toBeNull();
+
+			const again = await authorize(app, cookies);
+			// Sent to log in again, with no code.
+			expect(again.status).toBe(302);
+			expect(String(again.headers.location)).not.toMatch(/[?&]code=/);
+
+			expect((await redeem(app, pendingCode)).body).toMatchObject({ error: "invalid_grant" });
+
+			const refreshed = await request(app)
+				.post("/oauth/token")
+				.set("Authorization", basic(WEB))
+				.type("form")
+				.send({ grant_type: "refresh_token", refresh_token: tokens.refresh_token });
+			expect(refreshed.status).toBe(400);
+			expect(refreshed.body).toMatchObject({ error: "invalid_grant" });
+		} finally {
+			await handle.dispose();
+		}
+	});
+});