@o3co/create-auth-provider 0.4.1 → 0.5.1

package/templates/standalone/config/application.conf

@@ -35,12 +35,12 @@ oauth {
   }
   grants {
     session { enabled = true, enabled = ${?OAUTH_GRANTS_SESSION_ENABLED} }
-    authorization {
+    authorization_code {
       enabled = true
-      enabled = ${?OAUTH_GRANTS_AUTHORIZATION_ENABLED}
+      enabled = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED}
       pkce {
         requireS256 = false
-        requireS256 = ${?OAUTH_GRANTS_AUTHORIZATION_PKCE_REQUIRE_S256}
+        requireS256 = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_PKCE_REQUIRE_S256}
       }
     }
     refresh_token { enabled = true, enabled = ${?OAUTH_GRANTS_REFRESH_TOKEN_ENABLED} }
@@ -122,7 +122,10 @@ repositories {
 }
 
 endpoints {
-  login { url = ${?ENDPOINTS_LOGIN_URL} }
+  login {
+    url = "/login"
+    url = ${?ENDPOINTS_LOGIN_URL}
+  }
   client { url = ${?ENDPOINTS_CLIENT_URL} }
   authCallback { url = ${?ENDPOINTS_AUTH_CALLBACK_URL} }
 }

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.0.0",
+	"version": "0.5.1",
 	"private": true,
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.29.3",
@@ -23,6 +23,7 @@
 		"@o3co/auth-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-session": "workspace:*",
 		"@o3co/auth-provider-foundation": "workspace:*",
+		"@o3co/auth-provider-redis": "workspace:*",
 		"@o3co/auth.utils": "^0.0.3",
 		"@o3co/ts.hocon": "^1.1.0",
 		"connect-redis": "^9.0.0",

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

@@ -17,26 +17,18 @@
 import {
 	type AppConfig,
 	createApp,
-	createFederationTokenStoreFactory,
 	createKeyStoreFactory,
-	createUserSessionStoreFactory,
+	defineModule,
 	generateToken,
 	InMemoryClientRepository,
 	InMemoryCodeRepository,
 	InMemoryUserRepository,
-	registerBuiltinFederationTokenStores,
 	registerBuiltinKeyStores,
-	registerBuiltinUserSessionStores,
 } from "@o3co/auth-provider-core";
-import {
-	oauthAuthorizationModule,
-	oauthModule,
-	oauthSessionModule,
-} from "@o3co/auth-provider-oauth";
-import { sessionModule } from "@o3co/auth-provider-session";
 import express from "express";
 import request from "supertest";
-import { afterAll, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildModules } from "../buildModules.mjs";
 
 const config: AppConfig = {
 	http: { port: 0, trustProxy: false },
@@ -76,109 +68,127 @@ const config: AppConfig = {
 		code: { type: "memory", defaultExpiresIn: 600 },
 	},
 	endpoints: {
-		login: { url: undefined },
+		login: { url: "/login" },
 		client: { url: undefined },
 		authCallback: { url: undefined },
 	},
 	cors: { allowedOrigins: [] },
 };
 
-describe("standalone smoke test", () => {
-	let grantRegistryRef: Awaited<ReturnType<typeof buildApp>>["grantRegistry"];
-	let _appRef: ReturnType<typeof express>;
+/**
+ * Test-only repository module — bypasses the file-system-backed repositories
+ * that `repositoriesModule` provides in production. Smoke tests use in-memory
+ * empty repositories to verify the boot pipeline shape, not the data layer.
+ */
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () => new InMemoryClientRepository(new Map()),
+		userRepository: () => new InMemoryUserRepository(new Map()),
+		codeRepository: () => new InMemoryCodeRepository(),
+	},
+});
 
-	async function buildApp() {
-		const clientRepository = new InMemoryClientRepository(new Map());
-		const userRepository = new InMemoryUserRepository(new Map());
-		const codeRepository = new InMemoryCodeRepository();
+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 keyStoreFactory = createKeyStoreFactory();
-		registerBuiltinKeyStores(keyStoreFactory);
-		const keyStore = await keyStoreFactory.create({
-			type: "local",
-			...(config.oauth.jwt.signingKey.local ?? {}),
-		});
+describe("standalone smoke test", () => {
+	let handleRef: Awaited<ReturnType<typeof buildApp>>["handle"] | undefined;
 
-		const userSessionStoreFactory = createUserSessionStoreFactory();
-		registerBuiltinUserSessionStores(userSessionStoreFactory);
-		const userSessionStore = await userSessionStoreFactory.create({ type: "memory" });
-
-		const federationTokenStoreFactory = createFederationTokenStoreFactory();
-		registerBuiltinFederationTokenStores(federationTokenStoreFactory);
-		const federationTokenStore = await federationTokenStoreFactory.create({ type: "memory" });
-
-		const { init, router, grantRegistry } = createApp({
-			express,
-			config,
-			keyStore,
-			userSessionStore,
-			federationTokenStore,
-			modules: [
-				oauthModule({ clientRepository, codeRepository, express }),
-				sessionModule({ userRepository, express }),
-				oauthSessionModule({ clientRepository }),
-				oauthAuthorizationModule({ codeRepository, clientRepository }),
-			],
+	async function buildApp() {
+		const handle = await createApp({
+			modules: buildModules(config, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+			}),
+			bootstrapComponents: { config, pathResolver: (s) => s },
 		});
 
-		await init();
-
 		const app = express();
-		app.use(router);
-
-		return { app, grantRegistry };
+		app.get("/_healthcheck", (_req, res) => {
+			res.status(200).json({ status: "ok" });
+		});
+		app.use(handle.router);
+		return { app, handle };
 	}
 
-	afterAll(async () => {
-		await grantRegistryRef?.cleanup();
+	afterEach(async () => {
+		await handleRef?.dispose();
+		handleRef = undefined;
 	});
 
 	it("GET /_healthcheck returns 200", async () => {
-		const { app, grantRegistry } = await buildApp();
-		grantRegistryRef = grantRegistry;
-		_appRef = app;
-
+		const { app, handle } = await buildApp();
+		handleRef = handle;
 		const res = await request(app).get("/_healthcheck");
 		expect(res.status).toBe(200);
 	});
 
 	it("POST /oauth/token with unsupported grant_type returns 400", async () => {
-		const { app, grantRegistry } = await buildApp();
-		grantRegistryRef = grantRegistry;
-		_appRef = app;
-
+		const { app, handle } = await buildApp();
+		handleRef = handle;
 		const res = await request(app)
 			.post("/oauth/token")
 			.type("form")
 			.send({ grant_type: "unsupported" });
-
 		expect(res.status).toBe(400);
 	});
 
-	it("POST /oauth/token successful response has Cache-Control: no-store", async () => {
-		// We cannot easily trigger a full token issuance without a session,
-		// so we verify the header via a session grant with an authenticated session.
-		// Instead, test that 400 responses do NOT have Cache-Control (only successes do).
-		// The Cache-Control header is set only when "tokens" in result — covered by
-		// the introspect test below which exercises the full response path.
-		const { app, grantRegistry } = await buildApp();
-		grantRegistryRef = grantRegistry;
-		_appRef = app;
-
-		// 400 responses must NOT have Cache-Control: no-store
+	it("POST /oauth/token 400 responses do NOT have Cache-Control: no-store", async () => {
+		const { app, handle } = await buildApp();
+		handleRef = handle;
 		const res = await request(app)
 			.post("/oauth/token")
 			.type("form")
 			.send({ grant_type: "unsupported" });
-
 		expect(res.status).toBe(400);
 		expect(res.headers["cache-control"]).not.toBe("no-store");
 	});
 
+	// Regression guard: a freshly scaffolded standalone app must boot under
+	// the default `federations.google.enabled = false`. The earlier shape of
+	// app.mts unconditionally listed `googleFederationModule` and the config
+	// bridge `googleFederationConfigModule`, so the bridge's
+	// `extractFederationSection` returned undefined and threw at boot. The
+	// fix moved the manifest assembly into `buildModules`, which conditionally
+	// includes the federation pair. The first sub-assertion asserts directly
+	// on the manifest list — a regression that bypasses the gate fails the
+	// `not.toContain` even if `googleFederationConfigModule` is later made
+	// tolerant of `undefined` (which would otherwise mask the gating bug).
+	// The second sub-assertion verifies the resulting handle still boots
+	// (Codex Round 1 P1 reproducibility).
+	it("boots when google federation is disabled (default scaffold config)", async () => {
+		const modules = buildModules(config, {
+			keyStoreModule: testKeyStoreModule,
+			repositoriesModule: testRepositoriesModule,
+		});
+		const moduleNames = modules.map((m) => m.name);
+		expect(moduleNames).not.toContain("federation:google");
+		expect(moduleNames).not.toContain("standalone:google-federation-config");
+
+		const handle = await createApp({
+			modules,
+			bootstrapComponents: { config, pathResolver: (s) => s },
+		});
+		handleRef = handle;
+		expect(handle).toBeDefined();
+	});
+
 	it("POST /oauth/introspect returns iat in active token response", async () => {
-		const { app, grantRegistry } = await buildApp();
-		grantRegistryRef = grantRegistry;
-		_appRef = app;
+		const { app, handle } = await buildApp();
+		handleRef = handle;
 
 		const ksf = createKeyStoreFactory();
 		registerBuiltinKeyStores(ksf);

package/templates/standalone/src/app.mts

@@ -13,34 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { gracefulShutdown } from "@o3co/auth.utils";
+import { type AppConfig, AppConfigSchema, createApp } from "@o3co/auth-provider-core";
 import {
-	type AppConfig,
-	AppConfigSchema,
-	createApp,
-	createDefaultFactories,
-	createFederationTokenStoreFactory,
-	createKeyStoreFactory,
-	createUserSessionStoreFactory,
-	registerBuiltinFederationTokenStores,
-	registerBuiltinKeyStores,
-	registerBuiltinUserSessionStores,
-} from "@o3co/auth-provider-core";
-import { registerGoogleFederation } from "@o3co/auth-provider-federation-google";
-// import { registerGithubFederation } from "@o3co/auth-provider-federation-github";
-import { registerBuiltinAdapters } from "@o3co/auth-provider-foundation";
-import {
-	oauthAuthorizationModule,
-	oauthModule,
-	oauthSessionModule,
-} from "@o3co/auth-provider-oauth";
-import {
-	createFederationProviderFactory,
 	createSessionStoreFactory,
 	registerBuiltinSessionStores,
-	sessionModule,
 } from "@o3co/auth-provider-session";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
@@ -49,12 +27,11 @@ import session from "express-session";
 import helmet from "helmet";
 
 import logger from "#/logger.mjs";
+import { buildModules } from "./buildModules.mjs";
 import { resolveConfigPaths } from "./configPath.mjs";
 
 // Step 1: Load and validate application config (HOCON → Zod schema).
-// Layering: {ENV}.conf overrides application.conf.
-// ENV = CONFIG_ENV || NODE_ENV || "development". A missing {ENV}.conf is a
-// boot-time error (fail-fast on typos or unconfigured environments).
+// ENV = CONFIG_ENV || NODE_ENV || "development"; missing {ENV}.conf is fatal.
 const env = process.env.CONFIG_ENV || process.env.NODE_ENV || "development";
 const configDir = new URL("../config/", import.meta.url);
 const configDirPath = fileURLToPath(configDir);
@@ -64,47 +41,9 @@ const config: AppConfig = validate(
 	AppConfigSchema,
 );
 
-const flattenAdapterConfig = (
-	section: ({ type: string } | { provider: string }) & Record<string, unknown>,
-): { type: string } & Record<string, unknown> => {
-	const selector =
-		(section as { type?: string; provider?: string }).type ??
-		(section as { provider?: string }).provider;
-	if (typeof selector !== "string") {
-		throw new TypeError("flattenAdapterConfig: section requires 'type' or 'provider' string");
-	}
-	const sub = section[selector];
-	const flattenedSub =
-		typeof sub === "object" && sub !== null && !Array.isArray(sub)
-			? (sub as Record<string, unknown>)
-			: {};
-	return { type: selector, ...flattenedSub };
-};
-
 await (async (): Promise<void> => {
-	// Step 2: Build repository factories and register built-in adapters (memory / file / etc.).
-	const appDir = path.dirname(fileURLToPath(import.meta.url));
-	const { clientFactory, userFactory, codeFactory } = createDefaultFactories();
-	registerBuiltinAdapters({ userFactory, codeFactory, pathResolver: import.meta.resolve });
-
-	// Step 3: Instantiate client / user / code repositories from config.
-	const clientConfig = flattenAdapterConfig(
-		config.repositories.client as { type: string } & Record<string, unknown>,
-	);
-	if (typeof clientConfig.path === "string") {
-		clientConfig.path = path.resolve(appDir, "..", clientConfig.path);
-	}
-	const clientRepository = await clientFactory.create(clientConfig);
-	const userRepository = await userFactory.create(
-		flattenAdapterConfig(config.repositories.user as { type: string } & Record<string, unknown>),
-	);
-	const codeRepository = await codeFactory.create(
-		flattenAdapterConfig(config.repositories.code as { type: string } & Record<string, unknown>),
-	);
-
-	// Step 4: Create the Express app and apply base security middleware (trust proxy + helmet).
+	// Step 2: Create the Express app and apply base security middleware.
 	const app = express();
-
 	app.set("trust proxy", config.http.trustProxy);
 	app.use(
 		helmet({
@@ -117,19 +56,24 @@ await (async (): Promise<void> => {
 		}),
 	);
 
-	// Step 5: Build the session store from config and mount express-session middleware.
+	// Step 3: Build the Express session store and mount express-session.
+	// (express-session is host-environment middleware, not part of the auth
+	// boot pipeline — wired before createApp so it sits ahead of the router.)
 	const sessionStoreFactory = createSessionStoreFactory();
 	registerBuiltinSessionStores(sessionStoreFactory);
-	const store = await sessionStoreFactory.create(
-		flattenAdapterConfig(config.session.storage as { type: string } & Record<string, unknown>),
-	);
-
+	const sessionStorageSlice = config.session.storage as {
+		type: string;
+	} & Record<string, unknown>;
+	const sessionStore = await sessionStoreFactory.create({
+		type: sessionStorageSlice.type,
+		...((sessionStorageSlice[sessionStorageSlice.type] ?? {}) as Record<string, unknown>),
+	});
 	app.use(
 		session({
 			secret: config.session.secret,
 			resave: false,
 			saveUninitialized: false,
-			store,
+			store: sessionStore,
 			cookie: {
 				path: "/",
 				httpOnly: true,
@@ -141,61 +85,34 @@ await (async (): Promise<void> => {
 		}),
 	);
 
-	// Step 6: Build the JWT signing KeyStore used to issue access / ID tokens.
-	const keyStoreFactory = createKeyStoreFactory();
-	registerBuiltinKeyStores(keyStoreFactory);
-	const keyStore = await keyStoreFactory.create(flattenAdapterConfig(config.oauth.jwt.signingKey));
-
-	// Step 7: Build UserSessionStore and FederationTokenStore (required by sessionModule).
-	const userSessionStoreFactory = createUserSessionStoreFactory();
-	registerBuiltinUserSessionStores(userSessionStoreFactory);
-	const userSessionStore = await userSessionStoreFactory.create(
-		flattenAdapterConfig(
-			(config as { userSessionStore?: { type: string } & Record<string, unknown> })
-				.userSessionStore ?? { type: "memory" },
-		),
-	);
-
-	const federationTokenStoreFactory = createFederationTokenStoreFactory();
-	registerBuiltinFederationTokenStores(federationTokenStoreFactory);
-	const federationTokenStore = await federationTokenStoreFactory.create(
-		flattenAdapterConfig(
-			(config as { federationTokenStore?: { type: string } & Record<string, unknown> })
-				.federationTokenStore ?? { type: "memory" },
-		),
-	);
-
-	const federationProviderFactory = createFederationProviderFactory();
-	registerGoogleFederation(federationProviderFactory);
-	// registerGithubFederation(federationProviderFactory);
-
-	// Step 8: Compose the OAuth / session modules and build the app router.
-	const { init, router, grantRegistry } = createApp({
-		express,
-		pathResolver: import.meta.resolve,
-		config,
-		keyStore,
-		userSessionStore,
-		federationTokenStore,
-		modules: [
-			oauthModule({ clientRepository, codeRepository, express }),
-			sessionModule({ userRepository, express, federationProviderFactory }),
-			oauthSessionModule({ clientRepository }),
-			oauthAuthorizationModule({ codeRepository, clientRepository }),
-		],
+	// Step 4: Boot the auth pipeline. bootstrapComponents carries only host-
+	// environment values (config + pathResolver per A2-γ §4 worked example);
+	// every other component flows through composition-root-local modules.
+	// `buildModules` is the single source of truth for the module list — it
+	// gates federation modules on `config.federations.<name>.enabled`, which
+	// the standalone scaffold defaults to false.
+	const handle = await createApp({
+		modules: buildModules(config),
+		bootstrapComponents: {
+			config,
+			pathResolver: import.meta.resolve,
+		},
 	});
 
-	// Step 9: Run async module init (resolves external deps via pathResolver).
-	await init();
-
-	// Step 10: Mount the composed router onto the Express app.
-	app.use(router);
+	// Step 5: Wire host-level routes (healthcheck) before the auth router so
+	// they remain reachable even when the auth pipeline is degraded.
+	app.get("/_healthcheck", (_req, res) => {
+		res.status(200).json({ status: "ok" });
+	});
 
-	// Step 11: Start the HTTP server.
+	// Step 6: Mount the composed auth router and start the HTTP server.
+	app.use(handle.router);
 	const server = app.listen(config.http.port, (): void => {
 		logger.info(`Server is running on http://localhost:${config.http.port}`);
 	});
 
-	// Step 12: Register graceful shutdown so in-flight grants are cleaned up on SIGTERM / SIGINT.
-	gracefulShutdown(server, () => grantRegistry.cleanup());
+	// Step 7: Graceful shutdown — handle.dispose() runs reverse-topological
+	// per-component cleanup (per A2-β §8.1). Replaces the v0.4.x
+	// grantRegistry.cleanup() bridge.
+	gracefulShutdown(server, () => handle.dispose());
 })();

package/templates/standalone/src/buildModules.mts

@@ -0,0 +1,78 @@
+/*
+ * 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.
+ */
+import {
+	type AppConfig,
+	defaultRefreshTokenFamilyRevocationModule,
+	defaultRefreshTokenFamilyRotationModule,
+	type Module,
+	memoryRefreshTokenFamilyStoreModule,
+} from "@o3co/auth-provider-core";
+import { googleFederationModule } from "@o3co/auth-provider-federation-google";
+import {
+	oauthAuthorizationModule,
+	oauthModule,
+	oauthSessionModule,
+} from "@o3co/auth-provider-oauth";
+import { sessionModule } from "@o3co/auth-provider-session";
+import {
+	googleFederationConfigModule,
+	keyStoreModule,
+	repositoriesModule,
+	storesModule,
+} from "./modules.mjs";
+
+/**
+ * Test-only overrides allowing the smoke test to substitute in-memory
+ * implementations of the file-system-backed modules. Production callers
+ * should not pass overrides; the defaults match the standalone scaffold.
+ */
+export interface BuildModulesOverrides {
+	readonly keyStoreModule?: Module;
+	readonly repositoriesModule?: Module;
+	readonly storesModule?: Module;
+}
+
+/**
+ * Compose the standalone v0.5.0 module list from `config`. Splitting this
+ * out of `app.mts` keeps the composition root testable: a smoke test can
+ * verify that disabling a federation removes its module pair from the
+ * manifest without spinning up a full HTTP server.
+ *
+ * Federation gating: `googleFederationModule` requires `googleFederationConfig`,
+ * which `googleFederationConfigModule` produces by reading
+ * `config.federations.google`. When google is disabled (or the section is
+ * absent), the config-bridge module's provider throws — so the entire pair
+ * MUST be conditionally included at composition time, not gated inside the
+ * provider.
+ */
+export function buildModules(config: AppConfig, overrides: BuildModulesOverrides = {}): Module[] {
+	const googleEnabled =
+		(config.federations?.google as { enabled?: boolean } | undefined)?.enabled === true;
+
+	return [
+		oauthModule({ config }),
+		oauthSessionModule({ config }),
+		oauthAuthorizationModule({ config }),
+		sessionModule,
+		...(googleEnabled ? [googleFederationModule, googleFederationConfigModule] : []),
+		overrides.keyStoreModule ?? keyStoreModule,
+		overrides.repositoriesModule ?? repositoriesModule,
+		overrides.storesModule ?? storesModule,
+		memoryRefreshTokenFamilyStoreModule,
+		defaultRefreshTokenFamilyRotationModule,
+		defaultRefreshTokenFamilyRevocationModule,
+	];
+}