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

package/templates/standalone/src/__tests__/upstream-amr.acceptance.test.mts

@@ -0,0 +1,390 @@
+/*
+ * 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.
+ */
+
+/**
+ * What an upstream IdP asserted about its own login counts only for a
+ * federation configured with `core.federations.<name>.trustUpstreamAmr = true`
+ * (ADR 2026-09-25-multi-factor-authentication), end to end: a federated login
+ * through the session routes, `/oauth/authorize` with `acr_values`, and
+ * `/oauth/token`, on the standalone as a deployment composes it
+ * (`buildModules`), with a federation whose IdP asserts `mfa` and `hwk`.
+ * By default they are kept in `authentication.upstreamAmr` and an `acr` entry
+ * only they could meet is withheld; trusted, they are recorded beside `fed`.
+ * The session routes and `oauth` read the switch separately (neither package
+ * depends on the other); this is where the two meet.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	type FederationProvider,
+	federationsOf,
+	InMemoryClientRepository,
+	InMemoryUserRepository,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+	type UserSessionStore,
+} from "@o3co/auth-provider-core";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "#/buildModules.mjs";
+import { resolveConfigPaths, type Switches } from "#/configPath.mjs";
+import { templateReference } from "../modules.mjs";
+import {
+	capturedRenames,
+	libraryLayers,
+	rootSectionsOf,
+	sectionsCoreDoesNotDeclare,
+} from "./library-references.fixture.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+const ISSUER = "https://auth.test";
+const CLIENT_ID = "rp";
+const CLIENT_SECRET = "rp-secret-value";
+const BASIC = `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`;
+const REDIRECT_URI = "https://rp.example/callback";
+const FEDERATION = "partner";
+const CALLBACK_URL = `${ISSUER}/session/oauth/federation/${FEDERATION}/callback`;
+/** What the partner IdP asserts about its own login. */
+const UPSTREAM_AMR = ["mfa", "hwk"];
+const MFA_ACR = "urn:example:mfa";
+const FED_ACR = "urn:example:fed";
+
+const ENV: Readonly<Record<string, string>> = {
+	// This provider verifies no second factor of its own here: only upstream's.
+	MFA_MODE: "off",
+	KEY_STORE_LOCAL_ALGORITHM: "HS256",
+	KEY_STORE_LOCAL_SECRET: "upstream-amr.acceptance.at-least-32-bytes",
+	OAUTH_JWT_ISSUER: ISSUER,
+	SESSION_STORE_SECRET: "upstream-amr.acceptance-session.at-least-32-bytes",
+	SESSION_STORE_SECURE: "false",
+	SESSION_STORE_NAME: "auth.session",
+	SESSION_STORE_STORAGE_TYPE: "memory",
+	ADAPTERS_USER_REPOSITORY: "yaml",
+	REDIS_CLIENTS_URL: "redis://redis.test:6379",
+	ADAPTERS_USER_SESSION_STORES: "memory",
+	ADAPTERS_RATE_LIMITER: "memory",
+	ADAPTERS_CODE_REPOSITORY: "memory",
+	ADAPTERS_ACCESS_TOKEN_DENYLIST: "memory",
+	ADAPTERS_REPLAY_SEEN_SET: "memory",
+	ADAPTERS_FEDERATION_TOKEN_STORE: "memory",
+	ADAPTERS_CONSENT_STORE: "none",
+};
+
+/** The shipped configuration, with the partner federation and an acr table beside it. */
+function resolveConfig(trustUpstreamAmr: boolean | undefined): Switches {
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	const layers = parseFile(envConfPath, { env: ENV })
+		.withFallback(parseFile(applicationConfPath, { env: ENV }))
+		.withFallback(parseFile(fileURLToPath(templateReference()), { env: ENV }))
+		.withFallback(libraryLayers(ENV));
+	const shipped = validate(layers, AppConfigSchema) as AppConfig;
+	const parsed = AppConfigSchema.parse({
+		...shipped,
+		core: {
+			...shipped.core,
+			federations: {
+				...federationsOf(shipped),
+				[FEDERATION]: {
+					enabled: true,
+					type: FEDERATION,
+					callbackURL: CALLBACK_URL,
+					...(trustUpstreamAmr === undefined ? {} : { trustUpstreamAmr }),
+				},
+			},
+		},
+		oauth: {
+			...shipped.oauth,
+			authorize: {
+				...shipped.oauth.authorize,
+				acrValues: { [MFA_ACR]: ["mfa"], [FED_ACR]: ["fed"] },
+			},
+		},
+	});
+	return {
+		...sectionsCoreDoesNotDeclare(layers),
+		...rootSectionsOf(layers, ENV),
+		...parsed,
+		// What the resolution captured of core's renamed variables, which the
+		// schema's parse drops.
+		"renamed-variables": capturedRenames(ENV),
+	} as Switches;
+}
+
+/** An IdP that authenticates `ext-1` and says it did so with `mfa` and `hwk`. */
+const partner: FederationProvider = {
+	name: FEDERATION,
+	scope: ["openid"],
+	buildAuthorizationUrl: ({ state }) => {
+		const url = new URL("https://idp.partner.example/authorize");
+		url.searchParams.set("state", state);
+		return url;
+	},
+	exchangeCode: async () => ({
+		issuer: "https://idp.partner.example",
+		sub: "ext-1",
+		accessToken: "upstream-at",
+		expiresAt: null,
+		amr: UPSTREAM_AMR,
+	}),
+};
+
+const partnerFederationModule = defineModule({
+	name: "test:partner-federation",
+	contributes: {
+		federations: { [FEDERATION]: () => partner },
+		federationRedirectPolicies: {
+			[FEDERATION]: () => ({
+				validateRedirect: () => ({ ok: true as const, value: undefined }),
+				resolveCallbackRedirect: () => ({ ok: true as const, value: "/" }),
+			}),
+		},
+	} as never,
+});
+
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () =>
+			new InMemoryClientRepository(
+				new Map([
+					[
+						CLIENT_ID,
+						{
+							tokenEndpointAuthMethod: "client_secret_basic",
+							clientSecret: CLIENT_SECRET,
+							allowedRedirectUris: [REDIRECT_URI],
+							allowedScopes: ["openid"],
+							allowedAudiences: [],
+							allowedGrantTypes: ["authorization_code"],
+							firstParty: true,
+							backchannelLogoutSessionRequired: false,
+							frontchannelLogoutSessionRequired: false,
+							allowedAzpForFederationToken: false,
+						},
+					],
+				]),
+			),
+		// The partner's `ext-1` is alice's linked identity.
+		userRepository: () =>
+			new InMemoryUserRepository(
+				new Map([["alice", { id: "u-alice", password: "unused", token: `${FEDERATION}:ext-1` }]]),
+			),
+	} as never,
+});
+
+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 { "key-store"?: { local?: object } })["key-store"]?.local ?? {}),
+			});
+		},
+	},
+});
+
+/** A JWT's claims, unverified: the deployment signed it, and the test reads what it said. */
+const decodeJwt = (jwt: string): Record<string, unknown> =>
+	JSON.parse(Buffer.from(jwt.split(".")[1] ?? "", "base64url").toString("utf8")) as Record<
+		string,
+		unknown
+	>;
+
+const cookiesOf = (res: request.Response): string[] =>
+	(res.headers["set-cookie"] as unknown as string[] | undefined) ?? [];
+
+interface Deployment {
+	readonly app: express.Express;
+	readonly userSessionStore: UserSessionStore;
+	readonly dispose: () => Promise<void>;
+}
+
+async function boot(trustUpstreamAmr: boolean | undefined): Promise<Deployment> {
+	const config = resolveConfig(trustUpstreamAmr);
+	const handle = await createApp({
+		modules: [
+			...buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			}),
+			partnerFederationModule,
+		],
+		bootstrapComponents: { config, pathResolver: (s) => s },
+	});
+	const app = express();
+	app.use(handle.router);
+	return {
+		app,
+		userSessionStore: (handle.components as { userSessionStore: UserSessionStore })
+			.userSessionStore,
+		dispose: () => handle.dispose(),
+	};
+}
+
+/** Signs alice in through the partner federation; the browser's cookies after the callback. */
+async function signInThroughPartner(app: express.Express): Promise<string[]> {
+	const start = await request(app).get(`/session/oauth/federation/${FEDERATION}`);
+	expect(start.status).toBe(302);
+	const state = new URL(start.headers.location as string).searchParams.get("state");
+	expect(state).toBeTruthy();
+	const callback = await request(app)
+		.get(`/session/oauth/federation/${FEDERATION}/callback`)
+		.query({ state, code: "upstream-code" })
+		.set("Cookie", cookiesOf(start));
+	expect(callback.status).toBe(302);
+	return cookiesOf(callback);
+}
+
+/** `/oauth/authorize` for the signed-in browser: the redirect back to the client, as parameters. */
+async function authorize(
+	app: express.Express,
+	cookies: readonly string[],
+	acrValues: string,
+): Promise<{ readonly params: URLSearchParams; readonly verifier: string }> {
+	const verifier = randomBytes(32).toString("base64url");
+	const res = await request(app)
+		.get("/oauth/authorize")
+		.query({
+			response_type: "code",
+			client_id: CLIENT_ID,
+			redirect_uri: REDIRECT_URI,
+			scope: "openid",
+			state: "rp-state",
+			code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+			code_challenge_method: "S256",
+			acr_values: acrValues,
+		})
+		.set("Cookie", [...cookies]);
+	expect(res.status).toBe(302);
+	const location = new URL(res.headers.location as string);
+	expect(`${location.origin}${location.pathname}`).toBe(REDIRECT_URI);
+	return { params: location.searchParams, verifier };
+}
+
+/** The tokens `/oauth/token` mints for `code`, decoded. */
+async function tokensFor(
+	app: express.Express,
+	code: string,
+	verifier: string,
+): Promise<{
+	readonly idToken: Record<string, unknown>;
+	readonly accessToken: Record<string, unknown>;
+}> {
+	const res = await request(app)
+		.post("/oauth/token")
+		.set("Authorization", BASIC)
+		.type("form")
+		.send({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: REDIRECT_URI,
+			code_verifier: verifier,
+		});
+	expect(res.status).toBe(200);
+	return {
+		idToken: decodeJwt(res.body.id_token as string),
+		accessToken: decodeJwt(res.body.access_token as string),
+	};
+}
+
+describe("an upstream IdP's amr counts only for a federation that trusts it", () => {
+	let deployment: Deployment | undefined;
+
+	afterEach(async () => {
+		await deployment?.dispose();
+		deployment = undefined;
+	});
+
+	it("by default: kept apart in the session, withheld from discovery, unmet at /authorize, on no token", async () => {
+		deployment = await boot(undefined);
+		const { app, userSessionStore } = deployment;
+
+		const discovery = await request(app).get("/.well-known/openid-configuration");
+		// The entry only the IdP's `mfa` could meet is dropped, since that `mfa`
+		// is not recorded: no deployment advertises what it cannot meet.
+		expect(discovery.body.acr_values_supported).toEqual([FED_ACR]);
+
+		const cookies = await signInThroughPartner(app);
+
+		const unmet = await authorize(app, cookies, MFA_ACR);
+		expect(unmet.params.get("error")).toBe("unmet_authentication_requirements");
+		expect(unmet.params.get("code")).toBeNull();
+
+		const { params, verifier } = await authorize(app, cookies, FED_ACR);
+		const code = params.get("code");
+		expect(code).toBeTruthy();
+		const { idToken, accessToken } = await tokensFor(app, code as string, verifier);
+		expect(idToken.acr).toBe(FED_ACR);
+		expect(idToken.amr).toEqual(["fed"]);
+		expect(accessToken.amr).toEqual(["fed"]);
+
+		// The session keeps what the IdP said, for the record.
+		const session = await userSessionStore.get(idToken.sid as string);
+		expect(session?.amr).toEqual(["fed"]);
+		expect(session?.authentication).toStrictEqual({
+			primary: "fed",
+			federation: FEDERATION,
+			upstreamAmr: UPSTREAM_AMR,
+			mfaAt: undefined,
+		});
+	});
+
+	it("trusted: recorded beside fed, advertised, met at /authorize and stamped", async () => {
+		deployment = await boot(true);
+		const { app, userSessionStore } = deployment;
+
+		const discovery = await request(app).get("/.well-known/openid-configuration");
+		expect(discovery.body.acr_values_supported).toEqual([MFA_ACR, FED_ACR]);
+
+		const cookies = await signInThroughPartner(app);
+		const { params, verifier } = await authorize(app, cookies, MFA_ACR);
+		const code = params.get("code");
+		expect(code).toBeTruthy();
+		const { idToken, accessToken } = await tokensFor(app, code as string, verifier);
+		expect(idToken.acr).toBe(MFA_ACR);
+		expect(idToken.amr).toEqual([...UPSTREAM_AMR, "fed"]);
+		expect(accessToken.amr).toEqual([...UPSTREAM_AMR, "fed"]);
+
+		const session = await userSessionStore.get(idToken.sid as string);
+		expect(session?.authentication).toStrictEqual({
+			primary: "fed",
+			federation: FEDERATION,
+			upstreamAmr: undefined,
+			mfaAt: undefined,
+		});
+	});
+
+	it("says false explicitly as it says nothing: kept apart", async () => {
+		deployment = await boot(false);
+		const discovery = await request(deployment.app).get("/.well-known/openid-configuration");
+		expect(discovery.body.acr_values_supported).toEqual([FED_ACR]);
+	});
+});

package/templates/standalone/src/adapters.mts

@@ -0,0 +1,149 @@
+/*
+ * 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 composition root's own section, `adapters`: which adapter fills each
+ * slot. Phase one reads it alone, before the modules are chosen, with the
+ * template's own schema; boot is never handed it. The paths the selections
+ * moved from, and the variables renamed with them, are refused here, before
+ * any module is chosen, in the words boot refuses a module's in: a renamed
+ * variable set alone, or beside its new name at a different value, is
+ * refused, naming the variables and never a value.
+ */
+
+import { refuseRenamedVariables } from "./rootRenames.mjs";
+import { type Adapters, adaptersSchema } from "./sections.mjs";
+
+/** The composition root's own section. No module may be named after it. */
+export const ADAPTERS_SECTION = "adapters";
+
+/** Each selection's key under `adapters`, and the variable its path is bound to. */
+const VARIABLES: Readonly<Record<keyof Adapters, string>> = {
+	rateLimiter: "ADAPTERS_RATE_LIMITER",
+	userSessionStores: "ADAPTERS_USER_SESSION_STORES",
+	accessTokenDenylist: "ADAPTERS_ACCESS_TOKEN_DENYLIST",
+	replaySeenSet: "ADAPTERS_REPLAY_SEEN_SET",
+	consentStore: "ADAPTERS_CONSENT_STORE",
+	federationTokenStore: "ADAPTERS_FEDERATION_TOKEN_STORE",
+	federationGrantStore: "ADAPTERS_FEDERATION_GRANT_STORE",
+	federationGrantIntentStore: "ADAPTERS_FEDERATION_GRANT_INTENT_STORE",
+	mfaFactorStore: "ADAPTERS_MFA_FACTOR_STORE",
+	mfaTransactionStore: "ADAPTERS_MFA_TRANSACTION_STORE",
+	codeRepository: "ADAPTERS_CODE_REPOSITORY",
+	clientRepository: "ADAPTERS_CLIENT_REPOSITORY",
+	userRepository: "ADAPTERS_USER_REPOSITORY",
+	auditSink: "ADAPTERS_AUDIT_SINK",
+};
+
+/** Each selection's old path, and its key under `adapters`. */
+const MOVED: readonly (readonly [string, keyof Adapters])[] = [
+	["rateLimiter.adapter", "rateLimiter"],
+	["userSessionStores.adapter", "userSessionStores"],
+	["accessTokenDenylist.adapter", "accessTokenDenylist"],
+	["replaySeenSet.adapter", "replaySeenSet"],
+	["consentStore.adapter", "consentStore"],
+	["federationTokenStore.type", "federationTokenStore"],
+	["federationGrantStore.adapter", "federationGrantStore"],
+	["federationGrantIntentStore.adapter", "federationGrantIntentStore"],
+	["mfaFactorStore.adapter", "mfaFactorStore"],
+	["mfaTransactionStore.adapter", "mfaTransactionStore"],
+	["oauth.code.adapter", "codeRepository"],
+	["repositories.code.type", "codeRepository"],
+	["repositories.client.type", "clientRepository"],
+	["repositories.user.type", "userRepository"],
+	["audit.sink.type", "auditSink"],
+];
+
+/** Each variable renamed with a selection, and the selection's key under `adapters`. */
+const RENAMED: readonly (readonly [string, keyof Adapters])[] = [
+	["RATE_LIMITER_ADAPTER", "rateLimiter"],
+	["USER_SESSION_STORES_ADAPTER", "userSessionStores"],
+	["ACCESS_TOKEN_DENYLIST_ADAPTER", "accessTokenDenylist"],
+	["REPLAY_SEEN_SET_ADAPTER", "replaySeenSet"],
+	["CONSENT_STORE_ADAPTER", "consentStore"],
+	["FEDERATION_TOKEN_STORE_TYPE", "federationTokenStore"],
+	["FEDERATION_GRANT_STORE_ADAPTER", "federationGrantStore"],
+	["FEDERATION_GRANT_INTENT_STORE_ADAPTER", "federationGrantIntentStore"],
+	["MFA_FACTOR_STORE_ADAPTER", "mfaFactorStore"],
+	["MFA_TRANSACTION_STORE_ADAPTER", "mfaTransactionStore"],
+	["OAUTH_CODE_ADAPTER", "codeRepository"],
+	["CLIENT_CODE_TYPE", "codeRepository"],
+	["CLIENT_TYPE", "clientRepository"],
+	["CLIENT_USER_TYPE", "userRepository"],
+	["AUDIT_SINK_TYPE", "auditSink"],
+];
+
+/** The value at a dotted `path` of `config`, read as own properties; `undefined` when absent. */
+function valueAt(config: unknown, path: string): unknown {
+	let cursor: unknown = config;
+	for (const key of path.split(".")) {
+		if (typeof cursor !== "object" || cursor === null || !Object.hasOwn(cursor, key)) {
+			return undefined;
+		}
+		cursor = (cursor as Record<string, unknown>)[key];
+	}
+	return cursor;
+}
+
+/**
+ * `adapters` from `resolved` — the template's own layers over its
+ * `config/reference.conf` — under `env`, the environment they were
+ * substituted with, parsed with the template's schema. Refuses, with a
+ * `RangeError`, a selection still written at the path it moved from, naming
+ * its new path and variable; then a variable renamed with one
+ * (`refuseRenamedVariables`); then a value or a key the schema refuses,
+ * naming its path under `adapters`.
+ */
+export function readAdapters(
+	resolved: Readonly<Record<string, unknown>>,
+	env: Readonly<Record<string, string>>,
+): Adapters {
+	const moved = MOVED.filter(([from]) => valueAt(resolved, from) !== undefined).map(
+		([from, key]) => {
+			const to = `${ADAPTERS_SECTION}.${key}`;
+			return `${from} has moved to ${to}; see CHANGELOG. Write it there (environment variable ${VARIABLES[key]}) and remove this field from your config (or unset the environment variable that sets it).`;
+		},
+	);
+	if (moved.length > 0) {
+		throw new RangeError(
+			`Configuration sets ${moved.length} path(s) that moved: ${moved.join(" ")}`,
+		);
+	}
+	refuseRenamedVariables(
+		env,
+		RENAMED.map(([from, key]) => ({
+			from,
+			to: VARIABLES[key],
+			path: `${ADAPTERS_SECTION}.${key}`,
+		})),
+	);
+	const result = adaptersSchema.safeParse(resolved[ADAPTERS_SECTION]);
+	if (!result.success) {
+		const issues = result.error.issues;
+		throw new RangeError(
+			`Config validation failed — ${issues.length} issue(s) found: ${issues
+				.map((issue) => {
+					const unknown =
+						issue.code === "unrecognized_keys" ? ` ${JSON.stringify(issue.keys)}` : "";
+					const path = [ADAPTERS_SECTION, ...issue.path.map(String)].join(".");
+					return `${path}: ${issue.message}${unknown}`;
+				})
+				.join("; ")}`,
+			{ cause: result.error },
+		);
+	}
+	return result.data;
+}