@o3co/create-auth-provider 0.4.1

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

@@ -0,0 +1,16 @@
+services:
+  test:
+    build:
+      context: .
+      target: test
+    depends_on:
+      redis:
+        condition: service_healthy
+
+  redis:
+    image: redis:7-alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5

package/templates/standalone/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  app:
+    build:
+      context: .
+      target: develop
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./src:/home/node/src
+      - ./config:/home/node/config
+    depends_on:
+      redis:
+        condition: service_healthy
+    env_file:
+      - path: .env
+        required: false
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "127.0.0.1:6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5

package/templates/standalone/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@o3co/auth-provider-standalone",
+	"version": "0.0.0",
+	"private": true,
+	"license": "Apache-2.0",
+	"packageManager": "pnpm@10.29.3",
+	"type": "module",
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/app.mjs",
+		"debug": "NODE_OPTIONS='--conditions=development' tsx watch src/app.mts",
+		"test": "vitest run --passWithNoTests"
+	},
+	"imports": {
+		"#/*": {
+			"development": "./src/*",
+			"default": "./dist/*"
+		}
+	},
+	"dependencies": {
+		"@o3co/auth-provider-core": "workspace:*",
+		"@o3co/auth-provider-federation-google": "workspace:*",
+		"@o3co/auth-provider-oauth": "workspace:*",
+		"@o3co/auth-provider-session": "workspace:*",
+		"@o3co/auth-provider-foundation": "workspace:*",
+		"@o3co/auth.utils": "^0.0.3",
+		"@o3co/ts.hocon": "^1.1.0",
+		"connect-redis": "^9.0.0",
+		"express": "^5.2.1",
+		"express-session": "^1.19.0",
+		"helmet": "^8.1.0",
+		"pino": "^10.3.1",
+		"redis": "^5.10.0"
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.6",
+		"@types/express-session": "^1",
+		"@types/node": "^25.1.0",
+		"@types/supertest": "^7.2.0",
+		"supertest": "^7.1.0",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.1.2"
+	}
+}

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

@@ -0,0 +1,50 @@
+/*
+ * 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 { describe, expect, it } from "vitest";
+import { resolveConfigPaths } from "../configPath.mjs";
+
+describe("resolveConfigPaths", () => {
+	it("accepts a configDirPath with a trailing slash (regression: fileURLToPath preserves trailing /)", () => {
+		const { applicationConfPath, envConfPath } = resolveConfigPaths(
+			"/home/node/templates/standalone/config/",
+			"production",
+		);
+		expect(applicationConfPath).toBe("/home/node/templates/standalone/config/application.conf");
+		expect(envConfPath).toBe("/home/node/templates/standalone/config/production.conf");
+	});
+
+	it("accepts a configDirPath without a trailing slash", () => {
+		const { applicationConfPath, envConfPath } = resolveConfigPaths(
+			"/home/node/templates/standalone/config",
+			"development",
+		);
+		expect(applicationConfPath).toBe("/home/node/templates/standalone/config/application.conf");
+		expect(envConfPath).toBe("/home/node/templates/standalone/config/development.conf");
+	});
+
+	it("rejects env names that resolve outside configDirPath (path traversal)", () => {
+		expect(() =>
+			resolveConfigPaths("/home/node/templates/standalone/config/", "../secrets"),
+		).toThrow(/resolves outside/);
+	});
+
+	it("rejects env names containing a path separator", () => {
+		expect(() =>
+			resolveConfigPaths("/home/node/templates/standalone/config/", "nested/env"),
+		).toThrow(/resolves outside/);
+	});
+});

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

@@ -0,0 +1,204 @@
+/*
+ * 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,
+	createApp,
+	createFederationTokenStoreFactory,
+	createKeyStoreFactory,
+	createUserSessionStoreFactory,
+	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";
+
+const config: AppConfig = {
+	http: { port: 0, trustProxy: false },
+	oauth: {
+		jwt: {
+			signingKey: {
+				provider: "local",
+				local: {
+					algorithm: "HS256",
+					secret: "test-secret-for-smoke-test",
+					kid: "v0",
+					previousKeys: [],
+				},
+			},
+		},
+		accessToken: { expiresIn: 3600 },
+		refreshToken: { expiresIn: 86400 },
+		grants: {},
+	},
+	session: {
+		secret: "test-session-secret",
+		maxAge: 3600000,
+		secure: false,
+		sameSite: "lax",
+		domain: null,
+		storage: { type: "memory", redis: { url: "redis://localhost:6379" } },
+	},
+	rateLimit: {
+		login: { windowMs: 60000, limit: 10 },
+	},
+	federations: {
+		google: { enabled: false },
+	},
+	repositories: {
+		client: { type: "yaml", path: "./config/clients.yaml" },
+		user: { type: "yaml", path: "./config/users.yaml", timeout: 5000 },
+		code: { type: "memory", defaultExpiresIn: 600 },
+	},
+	endpoints: {
+		login: { url: undefined },
+		client: { url: undefined },
+		authCallback: { url: undefined },
+	},
+	cors: { allowedOrigins: [] },
+};
+
+describe("standalone smoke test", () => {
+	let grantRegistryRef: Awaited<ReturnType<typeof buildApp>>["grantRegistry"];
+	let _appRef: ReturnType<typeof express>;
+
+	async function buildApp() {
+		const clientRepository = new InMemoryClientRepository(new Map());
+		const userRepository = new InMemoryUserRepository(new Map());
+		const codeRepository = new InMemoryCodeRepository();
+
+		const keyStoreFactory = createKeyStoreFactory();
+		registerBuiltinKeyStores(keyStoreFactory);
+		const keyStore = await keyStoreFactory.create({
+			type: "local",
+			...(config.oauth.jwt.signingKey.local ?? {}),
+		});
+
+		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 }),
+			],
+		});
+
+		await init();
+
+		const app = express();
+		app.use(router);
+
+		return { app, grantRegistry };
+	}
+
+	afterAll(async () => {
+		await grantRegistryRef?.cleanup();
+	});
+
+	it("GET /_healthcheck returns 200", async () => {
+		const { app, grantRegistry } = await buildApp();
+		grantRegistryRef = grantRegistry;
+		_appRef = app;
+
+		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 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
+		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");
+	});
+
+	it("POST /oauth/introspect returns iat in active token response", async () => {
+		const { app, grantRegistry } = await buildApp();
+		grantRegistryRef = grantRegistry;
+		_appRef = app;
+
+		const ksf = createKeyStoreFactory();
+		registerBuiltinKeyStores(ksf);
+		const keyStore = await ksf.create({
+			type: "local",
+			...(config.oauth.jwt.signingKey.local ?? {}),
+		});
+		const { token } = await generateToken(
+			{},
+			{ keyStore, subject: "u1", expiresIn: 3600, tokenType: "at+jwt" },
+		);
+
+		const res = await request(app)
+			.post("/oauth/introspect")
+			.set("Authorization", `Bearer ${token}`)
+			.type("form")
+			.send({ token });
+
+		expect(res.status).toBe(200);
+		expect(res.body.active).toBe(true);
+		expect(typeof res.body.iat).toBe("number");
+	});
+});

package/templates/standalone/src/app.mts

@@ -0,0 +1,201 @@
+/*
+ * 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 path from "node:path";
+import { fileURLToPath } from "node:url";
+import { gracefulShutdown } from "@o3co/auth.utils";
+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";
+import express from "express";
+import session from "express-session";
+import helmet from "helmet";
+
+import logger from "#/logger.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).
+const env = process.env.CONFIG_ENV || process.env.NODE_ENV || "development";
+const configDir = new URL("../config/", import.meta.url);
+const configDirPath = fileURLToPath(configDir);
+const { applicationConfPath, envConfPath } = resolveConfigPaths(configDirPath, env);
+const config: AppConfig = validate(
+	parseFile(envConfPath).withFallback(parseFile(applicationConfPath)),
+	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).
+	const app = express();
+
+	app.set("trust proxy", config.http.trustProxy);
+	app.use(
+		helmet({
+			contentSecurityPolicy: {
+				directives: {
+					defaultSrc: ["'none'"],
+					frameAncestors: ["'none'"],
+				},
+			},
+		}),
+	);
+
+	// Step 5: Build the session store from config and mount express-session middleware.
+	const sessionStoreFactory = createSessionStoreFactory();
+	registerBuiltinSessionStores(sessionStoreFactory);
+	const store = await sessionStoreFactory.create(
+		flattenAdapterConfig(config.session.storage as { type: string } & Record<string, unknown>),
+	);
+
+	app.use(
+		session({
+			secret: config.session.secret,
+			resave: false,
+			saveUninitialized: false,
+			store,
+			cookie: {
+				path: "/",
+				httpOnly: true,
+				secure: config.session.secure,
+				maxAge: config.session.maxAge,
+				sameSite: config.session.sameSite,
+				domain: config.session.domain || undefined,
+			},
+		}),
+	);
+
+	// 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 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 11: Start the HTTP server.
+	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());
+})();

package/templates/standalone/src/configPath.mts

@@ -0,0 +1,37 @@
+/*
+ * 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 path from "node:path";
+
+export interface ResolvedConfigPaths {
+	readonly applicationConfPath: string;
+	readonly envConfPath: string;
+}
+
+export function resolveConfigPaths(configDirPath: string, env: string): ResolvedConfigPaths {
+	// path.resolve strips trailing slashes that fileURLToPath may preserve, so
+	// the containment check below compares equal shapes (path.dirname never
+	// returns a trailing separator).
+	const normalizedConfigDir = path.resolve(configDirPath);
+	const applicationConfPath = path.join(normalizedConfigDir, "application.conf");
+	const envConfPath = path.resolve(normalizedConfigDir, `${env}.conf`);
+	if (path.dirname(envConfPath) !== normalizedConfigDir) {
+		throw new Error(
+			`Invalid config environment name: "${env}" resolves outside ${normalizedConfigDir}`,
+		);
+	}
+	return { applicationConfPath, envConfPath };
+}

package/templates/standalone/src/logger.mts

@@ -0,0 +1,18 @@
+/*
+ * 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 { createLogger } from "@o3co/auth.utils";
+
+export default createLogger("provider");

package/templates/standalone/tests/Makefile

@@ -0,0 +1,5 @@
+install:
+	npm install
+
+test:
+	npm test