@o3co/create-auth-provider 0.15.0 → 0.16.0

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

@@ -52,6 +52,7 @@ import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPa
 const standaloneDir = fileURLToPath(new URL("../..", import.meta.url));
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 const readmePath = fileURLToPath(new URL("../../README.md", import.meta.url));
+const readmeJaPath = fileURLToPath(new URL("../../README.ja.md", import.meta.url));
 
 /**
  * Every environment variable the shipped artifact documents, with a value in
@@ -194,6 +195,7 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	FEDERATIONS_GOOGLE_CLIENT_ID: "google-client-id",
 	FEDERATIONS_GOOGLE_CLIENT_SECRET: "google-client-secret",
 	FEDERATIONS_GOOGLE_CALLBACK_URL: "https://auth.test/session/oauth/federation/google/callback",
+	FEDERATIONS_GOOGLE_ACCESS_TYPE: "online",
 	// #524: the generic OIDC federation the template ships disabled.
 	FEDERATIONS_OIDC_ENABLED: "true",
 	FEDERATIONS_OIDC_ISSUER: "https://idp.test",
@@ -214,6 +216,8 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 		"https://users.example.com/find-subject-by-federated-identity",
 	CLIENT_USER_TIMEOUT: "5000",
 	CLIENT_USER_MAX_RESPONSE_BYTES: "1048576",
+	// The credential the http user adapter presents to the Store; >= 32 bytes.
+	CLIENT_USER_BEARER_TOKEN: "0328d706529061d93abd6d826e09ef0f0a1e71a12af813b29e5cd2977b7dc63a",
 	CLIENT_CODE_TYPE: "redis",
 	CLIENT_CODE_DEFAULT_EXPIRES_IN: "600",
 	CLIENT_CODE_ENDPOINT_URI: "redis://redis:6379",
@@ -306,11 +310,9 @@ function substitutionsIn(path: string): Set<string> {
  * The underscore is what separates an environment variable from the HTTP
  * methods in the endpoint table, which share the shouting-case shape.
  */
-function documentedInReadme(): Set<string> {
+function documentedInReadme(path: string = readmePath): Set<string> {
 	const found = new Set<string>();
-	for (const match of readFileSync(readmePath, "utf8").matchAll(
-		/^\|\s*`([A-Z][A-Z0-9_]*)`\s*\|/gm,
-	)) {
+	for (const match of readFileSync(path, "utf8").matchAll(/^\|\s*`([A-Z][A-Z0-9_]*)`\s*\|/gm)) {
 		const name = match[1] as string;
 		if (name.includes("_")) found.add(name);
 	}
@@ -351,6 +353,7 @@ describe("#288: the shipped config boots with every documented override supplied
 		expect(config.http.port).toBe(3000);
 		expect(config.http.readinessTimeoutMs).toBe(1500);
 		expect(config.http.trustProxy).toEqual(["10.0.0.0/8", "loopback"]);
+		expect(config.federations.google?.accessType).toBe("online");
 		// The new default wins over the deprecated variable, and the parsed
 		// config mirrors it onto the old key for readers that predate the split.
 		expect(resolveAccessTokenLifetime(config)).toEqual({
@@ -522,12 +525,23 @@ describe("#288: the shipped config boots with every documented override supplied
 		});
 
 		it("covers every environment variable the README documents", () => {
-			const uncovered = [...documentedInReadme()].filter(
+			const uncovered = [...documentedInReadme(), ...documentedInReadme(readmeJaPath)].filter(
 				(name) => !(name in DOCUMENTED_ENV) && !(name in DELIBERATELY_UNSET),
 			);
 			expect(uncovered).toEqual([]);
 		});
 
+		it("documents the same variables in README.md and README.ja.md", () => {
+			// The Japanese README carries the same facts (AGENTS.md): a row added
+			// to one and not the other is a variable one audience never hears of.
+			const en = documentedInReadme();
+			const ja = documentedInReadme(readmeJaPath);
+			expect({
+				onlyInEnglish: [...en].filter((name) => !ja.has(name)).sort(),
+				onlyInJapanese: [...ja].filter((name) => !en.has(name)).sort(),
+			}).toEqual({ onlyInEnglish: [], onlyInJapanese: [] });
+		});
+
 		it("exercises no variable the config layers no longer substitute", () => {
 			// Catches the reverse drift: a README row (and a test entry) left
 			// behind by a key that was removed from the HOCON.

package/templates/standalone/src/__tests__/federation-grants-composition.test.mts

@@ -257,9 +257,10 @@ describe("#593 slice 7: the standalone composes federation grants from its confi
 		);
 		expect(installed).not.toContain("redis-federation-grant-store");
 		expect(installed).not.toContain("redis-federation-grant-intent-store");
-		// The routes precede oauthModule's body parsers (the package README's
-		// mounting-order rule), and the browser half sits after the session
-		// middleware by its own `after`.
+		// Listed ahead of oauthModule, as the template writes them — the
+		// template's choice, since each module parses its own bodies and the
+		// order no longer changes that; the browser half sits after the
+		// session middleware by its own `after`.
 		expect(installed.indexOf("federation-grants")).toBeLessThan(installed.indexOf("oauth"));
 
 		handleRef = await boot(config, true);
@@ -382,3 +383,63 @@ describe("#593 slice 7: the standalone composes federation grants from its confi
 		expect(names(config)).toContain("core-federation-grant-intent-store-memory");
 	});
 });
+
+describe("the browser consent route parses its own body, with sessionModule listed ahead of it", () => {
+	// `sessionModule`'s routers are mounted at `/session`, the prefix the
+	// federation grants browser half mounts under too. Their parsers ran for
+	// every request beneath `/session`, so with `sessionModule` listed first
+	// the consent route's body arrived parsed — past its 16 KiB bound, its
+	// throttle-then-parse order and its JSON refusals.
+	let handleRef: Awaited<ReturnType<typeof boot>> | undefined;
+
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
+	});
+
+	/** The standalone's modules, with `sessionModule` moved ahead of the grant modules. */
+	const sessionFirst = (config: AppConfig) => {
+		const modules = modulesFor(config, true);
+		const session = modules.find((m) => m.name === "session");
+		if (session === undefined) throw new Error("sessionModule is not in the standalone's list");
+		const rest = modules.filter((m) => m !== session);
+		const at = rest.findIndex((m) => m.name.startsWith("federation-grant"));
+		return [...rest.slice(0, at), session, ...rest.slice(at)];
+	};
+
+	const bootSessionFirst = async () => {
+		const config = resolveConfig({ ...BASE_ENV, ...GRANTS_ON });
+		handleRef = await createApp({
+			modules: sessionFirst(config),
+			bootstrapComponents: { config, pathResolver: (s) => s },
+		});
+		return express().use(handleRef.router);
+	};
+
+	const CONSENT = "/session/federation-grants/consent";
+
+	it("refuses a body over 16 KiB with the route's own 413", async () => {
+		const app = await bootSessionFirst();
+
+		const res = await request(app)
+			.post(CONSENT)
+			.set("Content-Type", "application/json")
+			.send(JSON.stringify({ challenge: "c", decision: "accept", pad: "a".repeat(40 * 1024) }));
+
+		expect(res.status).toBe(413);
+		expect(res.body).toEqual({ error: "invalid_request", error_description: "body_too_large" });
+	});
+
+	it("refuses malformed JSON with the route's own 400", async () => {
+		const app = await bootSessionFirst();
+
+		const res = await request(app)
+			.post(CONSENT)
+			.set("Content-Type", "application/json")
+			.send("{not json");
+
+		expect(res.status).toBe(400);
+		expect(res.body).toEqual({ error: "invalid_request", error_description: "malformed_body" });
+		expect(res.headers["cache-control"]).toContain("no-store");
+	});
+});

package/templates/standalone/src/__tests__/federation-grants-survive-logout.test.mts

@@ -236,6 +236,7 @@ async function seedGrant(store: MemoryFederationGrantStore): Promise<void> {
 			consent: { at, sid: "sid-consent", scopes: [...SCOPES] },
 			authorizedAt: at,
 			expiresAt: new Date(at.getTime() + 30 * DAY),
+			resource: undefined,
 		},
 		credentials: {
 			refreshToken: REFRESH_TOKEN,
@@ -389,6 +390,13 @@ describe("#593 AC8: a grant outlives the browser session at both logout endpoint
 		await federationTokenStore.attach(sid, "upstream", {
 			accessToken: "session-bound-upstream-token",
 			expiresAt: null,
+			// Every field is a required key since the #645 follow-up; this
+			// record carries only the access token.
+			refreshToken: undefined,
+			idToken: undefined,
+			tokenType: undefined,
+			scope: undefined,
+			grantedScope: undefined,
 		});
 		expect(await userSessionStore.get(sid)).not.toBeNull();
 		await expectGrantUntouched(app, federationGrantStore);
@@ -414,6 +422,13 @@ describe("#593 AC8: a grant outlives the browser session at both logout endpoint
 		await federationTokenStore.attach(sid, "upstream", {
 			accessToken: "session-bound-upstream-token",
 			expiresAt: null,
+			// Every field is a required key since the #645 follow-up; this
+			// record carries only the access token.
+			refreshToken: undefined,
+			idToken: undefined,
+			tokenType: undefined,
+			scope: undefined,
+			grantedScope: undefined,
 		});
 		expect(await userSessionStore.get(sid)).not.toBeNull();
 		await expectGrantUntouched(app, federationGrantStore);

package/templates/standalone/src/__tests__/federation-token-refresh-outage.test.mts

@@ -0,0 +1,133 @@
+/*
+ * 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.
+ */
+
+/**
+ * `POST /oauth/federation/:name/token` ends a session's upstream tokens only
+ * on the upstream's own verdict that the refresh token is bad — a structured
+ * `invalid_grant` under a 4xx — and never while the upstream is down, whatever
+ * the body of its 5xx says. An outage is `503`, and the tokens are kept for
+ * the retry.
+ *
+ * Driven through the real Google adapter and its library (openid-client)
+ * against a fake Google (`createFakeIdp`), so the errors the route classifies
+ * are the ones the library raises: a 4xx whose body names a code is a
+ * `ResponseBodyError` carrying `error` and `status`; a 5xx is an
+ * `OperationProcessingError` raised over the `Response`, whose body the
+ * library does not read — and which the route used to answer `500
+ * refresh_failed`, as if the upstream had said something it could not place.
+ */
+
+import { createFakeIdp, type FakeIdp } from "@o3co/auth-provider-core/testing";
+import request from "supertest";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	accessTokenWithFamily,
+	GOOGLE_CLIENT_ID,
+	type GoogleSession,
+	signInLinkedToGoogle,
+} from "./google-session.fixture.mjs";
+
+const GOOGLE = {
+	issuer: "https://accounts.google.com",
+	authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+	tokenEndpoint: "https://oauth2.googleapis.com/token",
+	jwksUri: "https://www.googleapis.com/oauth2/v3/certs",
+	userinfoEndpoint: "https://www.googleapis.com/oauth2/v3/userinfo",
+};
+const STORED_REFRESH_TOKEN = "stored-refresh-token";
+
+describe("POST /oauth/federation/google/token: an upstream outage never ends the session's Google tokens", () => {
+	let session: GoogleSession | undefined;
+
+	afterEach(async () => {
+		await session?.dispose();
+		session = undefined;
+	});
+
+	/**
+	 * Alice's session with Google linked, its access token expired so the
+	 * route refreshes, and the fake Google answering the refresh with `status`
+	 * and `body`.
+	 */
+	async function refreshAnswered(status: number, body: Record<string, unknown>) {
+		const idp: FakeIdp = await createFakeIdp({ ...GOOGLE, clientId: GOOGLE_CLIENT_ID });
+		idp.tokenStatus = status;
+		idp.refusal = body;
+		session = await signInLinkedToGoogle({
+			google: { fetch: idp.fetch },
+			tokens: {
+				accessToken: "expired-upstream-access-token",
+				expiresAt: new Date(Date.now() - 60_000),
+				refreshToken: STORED_REFRESH_TOKEN,
+				idToken: undefined,
+				tokenType: "Bearer",
+				scope: "openid profile email",
+				grantedScope: "openid profile email",
+			},
+		});
+		const res = await request(session.app)
+			.post("/oauth/federation/google/token")
+			.set("Authorization", `Bearer ${accessTokenWithFamily(session.sid)}`)
+			.send();
+		// The library did ask Google: what follows is its reading of the answer.
+		expect(
+			idp.requests.filter(
+				(r) =>
+					`${r.url.origin}${r.url.pathname}` === GOOGLE.tokenEndpoint &&
+					r.body?.get("grant_type") === "refresh_token",
+			),
+		).toHaveLength(1);
+		return { res, ...session };
+	}
+
+	it("keeps them and answers 503 when Google answers 503 with a body naming invalid_grant", async () => {
+		const { res, sid, federationTokenStore, sessionFederationIndex } = await refreshAnswered(503, {
+			error: "invalid_grant",
+			error_description: "Backend unavailable",
+		});
+
+		expect(res.status).toBe(503);
+		expect(res.body).toEqual({
+			error: "temporarily_unavailable",
+			error_description: "upstream federation provider temporarily unavailable",
+		});
+		expect((await federationTokenStore.get(sid, "google"))?.refreshToken).toBe(
+			STORED_REFRESH_TOKEN,
+		);
+		expect(await sessionFederationIndex.listFederations(sid)).toContain("google");
+	});
+
+	it("keeps them and answers 503 when Google answers 502 with no OAuth body at all", async () => {
+		const { res, sid, federationTokenStore } = await refreshAnswered(502, {});
+
+		expect(res.status).toBe(503);
+		expect((await federationTokenStore.get(sid, "google"))?.refreshToken).toBe(
+			STORED_REFRESH_TOKEN,
+		);
+	});
+
+	it("ends them on Google's structured 400 invalid_grant", async () => {
+		const { res, sid, federationTokenStore, sessionFederationIndex } = await refreshAnswered(400, {
+			error: "invalid_grant",
+			error_description: "Token has been expired or revoked.",
+		});
+
+		expect(res.status).toBe(410);
+		expect(res.body.error).toBe("re_authentication_required");
+		expect(await federationTokenStore.get(sid, "google")).toBeNull();
+		expect(await sessionFederationIndex.listFederations(sid)).not.toContain("google");
+	});
+});

package/templates/standalone/src/__tests__/google-federation-config-module.test.mts

@@ -169,3 +169,31 @@ describe("googleFederationConfigModule — requireAuthorizationResponseIss (#597
 		}
 	});
 });
+
+describe("googleFederationConfigModule — accessType", () => {
+	// federation-google asks every sign-in for consent with offline access, so
+	// every session gets a refresh token; "online" is the operator's way to
+	// keep Google's consent screen to the first sign-in, at the price of no
+	// refresh token at all. A bridge that drops the field leaves the operator
+	// without that choice.
+	it("is absent by default, so the provider's own default (offline) applies", () => {
+		expect("accessType" in buildConfig(credentials)).toBe(false);
+	});
+
+	it("leaves a null accessType absent, never forwarded as null, which the provider refuses", () => {
+		expect("accessType" in buildConfig({ ...credentials, accessType: null })).toBe(false);
+	});
+
+	it("forwards offline and online", () => {
+		expect(buildConfig({ ...credentials, accessType: "online" }).accessType).toBe("online");
+		expect(buildConfig({ ...credentials, accessType: "offline" }).accessType).toBe("offline");
+	});
+
+	it("refuses anything else at boot, naming the key", () => {
+		for (const bad of ["", "offine", "Online", "true", false, 1]) {
+			expect(() => buildConfig({ ...credentials, accessType: bad })).toThrow(
+				/federations\.google\.accessType/,
+			);
+		}
+	});
+});

package/templates/standalone/src/__tests__/google-session.fixture.mts

@@ -0,0 +1,304 @@
+/*
+ * 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.
+ */
+
+/**
+ * A browser session with Google linked, on the standalone as a deployment
+ * composes it: `oauthModule`, the session module and the real Google adapter,
+ * booted through `createApp` under the shipped configuration.
+ *
+ * The routes that act on a session's federation — the two logout routes and
+ * `POST /oauth/federation/:name/token` — live in `@o3co/auth-provider-oauth`,
+ * which depends on no adapter, so its own tests stand one in. What they hand
+ * the adapter, and what they make of what its library raises, can only be
+ * seen here.
+ *
+ * Not `all-modules-composition.fixture.mts`: that one switches every module
+ * on and signs with a key it keeps to itself. The tests here present an
+ * `id_token_hint` and an access token of their own — a caller's, with the
+ * claims the case needs — so the deployment signs with an HS256 secret this
+ * file holds, and nothing but Google is federated.
+ */
+
+import { createHmac } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+	type AppConfig,
+	AppConfigSchema,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	type FederationTokenStore,
+	type FederationTokens,
+	InMemoryClientRepository,
+	InMemoryUserRepository,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+	type SessionFederationIndex,
+	type UserSessionStore,
+} from "@o3co/auth-provider-core";
+import {
+	type GoogleProviderConfig,
+	googleFederationModule,
+} from "@o3co/auth-provider-federation-google";
+import { parseFile } from "@o3co/ts.hocon";
+import { validate } from "@o3co/ts.hocon/zod";
+import express from "express";
+import request from "supertest";
+import { expect } from "vitest";
+import { buildModules } from "#/buildModules.mjs";
+import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "#/configPath.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+export const ISSUER = "https://auth.test";
+const JWT_SECRET = "google-session.fixture.at-least-32-bytes.ok";
+
+/** The one client: first-party, allowed federation tokens, one post-logout URI registered. */
+export const CLIENT_ID = "rp";
+const CLIENT_SECRET = "rp-secret-value";
+const BASIC = `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`;
+export const REGISTERED_POST_LOGOUT_REDIRECT_URI = "https://rp.example/signed-out";
+
+const USERNAME = "alice";
+const PASSWORD = "correct-horse-battery-staple";
+const SUB = "u-alice";
+
+/** The Google client the adapter is configured with. */
+export const GOOGLE_CLIENT_ID = "google-client";
+const GOOGLE_CLIENT_SECRET = "google-secret";
+const GOOGLE_CALLBACK = `${ISSUER}/session/oauth/federation/google/callback`;
+
+const ENV: Readonly<Record<string, string>> = {
+	OAUTH_JWT_ALGORITHM: "HS256",
+	OAUTH_JWT_SECRET: JWT_SECRET,
+	OAUTH_JWT_ISSUER: ISSUER,
+	SESSION_SECRET: "google-session.fixture-session.at-least-32-bytes.ok",
+	SESSION_SECURE: "false",
+	SESSION_NAME: "auth.session",
+	SESSION_STORAGE_TYPE: "memory",
+	CLIENT_USER_TYPE: "yaml",
+	REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: "redis://redis.test:6379",
+	USER_SESSION_STORES_ADAPTER: "memory",
+	RATE_LIMITER_ADAPTER: "memory",
+	OAUTH_CODE_ADAPTER: "memory",
+	ACCESS_TOKEN_DENYLIST_ADAPTER: "memory",
+	REPLAY_SEEN_SET_ADAPTER: "memory",
+	FEDERATION_TOKEN_STORE_TYPE: "memory",
+	CONSENT_STORE_ADAPTER: "none",
+};
+
+/**
+ * `"shipped"`: Google switched on the way an operator does, through its
+ * environment variables and the template's own configuration bridge — which
+ * has no setting for an end-session endpoint or a `fetch`. Otherwise the
+ * adapter's configuration beyond its credentials, composed with
+ * `googleFederationModule` directly.
+ */
+export type GoogleWiring =
+	| "shipped"
+	| Omit<GoogleProviderConfig, "clientId" | "clientSecret" | "callbackURL">;
+
+function resolveConfig(google: GoogleWiring): AppConfig {
+	const env: Record<string, string> =
+		google === "shipped"
+			? {
+					...ENV,
+					FEDERATIONS_GOOGLE_ENABLED: "true",
+					FEDERATIONS_GOOGLE_CLIENT_ID: GOOGLE_CLIENT_ID,
+					FEDERATIONS_GOOGLE_CLIENT_SECRET: GOOGLE_CLIENT_SECRET,
+					FEDERATIONS_GOOGLE_CALLBACK_URL: GOOGLE_CALLBACK,
+				}
+			: { ...ENV };
+	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "production");
+	return validate(
+		parseFile(envConfPath, { env })
+			.withFallback(parseFile(applicationConfPath, { env }))
+			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env })),
+		AppConfigSchema,
+	) as AppConfig;
+}
+
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () =>
+			new InMemoryClientRepository(
+				new Map([
+					[
+						CLIENT_ID,
+						{
+							tokenEndpointAuthMethod: "client_secret_basic",
+							clientSecret: CLIENT_SECRET,
+							allowedRedirectUris: [],
+							allowedScopes: ["openid", "profile"],
+							allowedAudiences: [],
+							allowedGrantTypes: ["session"],
+							postLogoutRedirectUris: [REGISTERED_POST_LOGOUT_REDIRECT_URI],
+							backchannelLogoutSessionRequired: true,
+							frontchannelLogoutSessionRequired: true,
+							allowedAzpForFederationToken: true,
+						},
+					],
+				]),
+			),
+		userRepository: () =>
+			new InMemoryUserRepository(
+				new Map([[USERNAME, { id: SUB, password: PASSWORD, email: "alice@example.com" }]]),
+			),
+	} 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 AppConfig).oauth.jwt.signingKey.local ?? {}),
+			});
+		},
+	},
+});
+
+const base64url = (value: unknown): string =>
+	Buffer.from(JSON.stringify(value)).toString("base64url");
+
+/** A JWT signed with the deployment's own HS256 key: what its keystore verifies. */
+function signed(typ: string, claims: Record<string, unknown>): string {
+	const header = base64url({ alg: "HS256", kid: "v0", typ });
+	const now = Math.floor(Date.now() / 1000);
+	const payload = base64url({ iss: ISSUER, sub: SUB, iat: now, exp: now + 3600, ...claims });
+	const signature = createHmac("sha256", JWT_SECRET)
+		.update(`${header}.${payload}`)
+		.digest("base64url");
+	return `${header}.${payload}.${signature}`;
+}
+
+/**
+ * A fresh id_token for the session, issued to the client: what an RP — or
+ * anyone holding an id_token of their own — presents as `id_token_hint`.
+ */
+export const idTokenHint = (sid: string): string => signed("JWT", { aud: CLIENT_ID, sid });
+
+/**
+ * An access token for the session as the authorization-code grant issues it
+ * to the client: `azp`, `sid` and a refresh-token `family_id`. The `session`
+ * grant's token names no family, and the federation token route asks for one.
+ */
+export const accessTokenWithFamily = (sid: string): string =>
+	signed("at+jwt", { azp: CLIENT_ID, sid, family_id: "family-1", scope: "openid" });
+
+const claimsOf = (jwt: string): Record<string, unknown> =>
+	JSON.parse(Buffer.from(jwt.split(".")[1] ?? "", "base64url").toString("utf8")) as Record<
+		string,
+		unknown
+	>;
+
+export interface GoogleSession {
+	readonly app: express.Express;
+	readonly sid: string;
+	/** The access token the `session` grant minted for the session; it carries `azp`. */
+	readonly accessToken: string;
+	readonly userSessionStore: UserSessionStore;
+	readonly sessionFederationIndex: SessionFederationIndex;
+	readonly federationTokenStore: FederationTokenStore;
+	readonly dispose: () => Promise<void>;
+}
+
+/**
+ * Boots the deployment, signs alice in with her password, and links Google to
+ * her session as a federated sign-in would: the session's federation index
+ * names it and the token store holds `tokens`.
+ */
+export async function signInLinkedToGoogle(options: {
+	readonly google: GoogleWiring;
+	readonly tokens: FederationTokens;
+}): Promise<GoogleSession> {
+	const { google, tokens } = options;
+	const config = resolveConfig(google);
+	const googleModules =
+		google === "shipped"
+			? []
+			: [
+					googleFederationModule,
+					defineModule({
+						name: "test:google-federation-config",
+						provides: {
+							googleFederationConfig: (): GoogleProviderConfig => ({
+								clientId: GOOGLE_CLIENT_ID,
+								clientSecret: GOOGLE_CLIENT_SECRET,
+								callbackURL: GOOGLE_CALLBACK,
+								...google,
+							}),
+						},
+					}),
+				];
+	const handle = await createApp({
+		modules: [
+			...buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			}),
+			...googleModules,
+		],
+		bootstrapComponents: { config, pathResolver: (s) => s },
+	});
+	try {
+		const components = handle.components as {
+			userSessionStore: UserSessionStore;
+			sessionFederationIndex: SessionFederationIndex;
+			federationTokenStore: FederationTokenStore;
+		};
+		const app = express();
+		app.use(handle.router);
+
+		const csrfRes = await request(app).get("/session/csrf");
+		expect(csrfRes.status).toBe(200);
+		const loginRes = await request(app)
+			.post("/session/login")
+			.set("Cookie", csrfRes.headers["set-cookie"] as unknown as string[])
+			.set(csrfRes.body.header_name as string, csrfRes.body.csrf_token as string)
+			.type("form")
+			.send({ username: USERNAME, password: PASSWORD });
+		expect(loginRes.status).toBe(200);
+
+		const tokenRes = await request(app)
+			.post("/oauth/token")
+			.set("Authorization", BASIC)
+			.set("Cookie", loginRes.headers["set-cookie"] as unknown as string[])
+			.type("form")
+			.send({ grant_type: "session" });
+		expect(tokenRes.status).toBe(200);
+		const accessToken = tokenRes.body.access_token as string;
+		const claims = claimsOf(accessToken);
+		expect(claims.azp).toBe(CLIENT_ID);
+		const sid = claims.sid as string;
+		expect(typeof sid).toBe("string");
+
+		const session = await components.userSessionStore.get(sid);
+		if (session === null) throw new Error("fixture: the sign-in left no session");
+		await components.sessionFederationIndex.addFederation(sid, "google", session.expiresAt);
+		await components.federationTokenStore.attach(sid, "google", tokens);
+		return { app, sid, accessToken, ...components, dispose: () => handle.dispose() };
+	} catch (error) {
+		await handle.dispose();
+		throw error;
+	}
+}