@o3co/create-auth-provider 0.8.0 → 0.10.0

package/templates/standalone/config/clients.yaml.example

@@ -9,22 +9,63 @@
 # Secret format (only for confidential clients — basic / post):
 #   - Plain text: "my-secret"
 #   - Bcrypt hash: "$2b$10$..." (generate with: node -e "require('bcrypt').hash('secret',10).then(console.log)")
+#
+# `firstParty` (#267): REQUIRED to be `true` for a client to use `/authorize`.
+#   `/authorize` mints a code as soon as the session is authenticated, with no
+#   consent step, so a forced top-level navigation from an attacker's page
+#   makes a logged-in user's browser mint one for whatever client is named.
+#   That is defensible for clients you operate and only for those. Mark a
+#   client `firstParty: true` only if you would be comfortable with it
+#   receiving the user's identity without the user being asked.
+#
+#   A client without it is refused at `/authorize`, as is one carrying an
+#   explicit `firstParty: false`. There is no opt-out: mark every client you
+#   operate before pointing it at `/authorize`.
+#
+# `allowPlainPkce` (#273): PKCE is mandatory for EVERY client — confidential
+#   ones included — and `S256` is the only method accepted. There is no
+#   server-wide setting that changes either half. This per-client flag is the
+#   one exception hatch, and only for the method: `allowPlainPkce: true` lets
+#   that one client use the RFC 7636 `plain` challenge, which stores the
+#   verifier itself as the challenge and so proves nothing against anyone who
+#   can read the authorization request. Set it only for a legacy client that
+#   genuinely cannot compute SHA-256, and treat it as a migration deadline.
 
 my-app:
   tokenEndpointAuthMethod: "client_secret_basic"
+  firstParty: true
   clientSecret: "$2b$10$REPLACE_WITH_BCRYPT_HASH"
   allowedRedirectUris:
     - "http://localhost:3000/callback"
   allowedScopes:
     - "read"
     - "write"
+  # What an omitted `scope` parameter grants (#396). Must be a subset of
+  # allowedScopes (checked at boot). Without this, a request that omits
+  # `scope` is refused with invalid_scope — the old behavior granted the
+  # ENTIRE allowlist, which made "forgot to send scope" the maximum grant.
+  # Declare what an unscoped request should mean, not the ceiling.
+  defaultScopes:
+    - "read"
 
 # Public client example (e.g., a single-page app or mobile app):
 # my-spa:
 #   tokenEndpointAuthMethod: "none"
+#   firstParty: true
 #   # clientSecret MUST be absent for "none" clients.
 #   allowedRedirectUris:
 #     - "https://app.example/callback"
 #   allowedScopes:
 #     - "openid"
 #     - "profile"
+
+# Legacy client that cannot compute SHA-256 (#273). Prefer fixing the client.
+# my-legacy-device:
+#   tokenEndpointAuthMethod: "client_secret_basic"
+#   firstParty: true
+#   clientSecret: "$2b$10$REPLACE_WITH_BCRYPT_HASH"
+#   allowPlainPkce: true
+#   allowedRedirectUris:
+#     - "https://legacy.example/callback"
+#   allowedScopes:
+#     - "openid"

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

@@ -0,0 +1,116 @@
+# Production compose example (#293 item 16).
+#
+# `docker-compose.yml` is a DEVELOPMENT file: it builds the `develop` target
+# and bind-mounts ./src and ./config into the container, so copy-paste
+# deploying it ships a hot-reload server running your working tree. This file
+# is the deployable shape: the `runtime` target (compiled JS only, tini,
+# healthcheck), no source mounts, restart policies, and a Redis that is
+# reachable from the app network only and persists to a volume.
+#
+#   openssl genpkey -algorithm ed25519 -out jwt-private.pem
+#   openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
+#   chmod 600 jwt-private.pem
+#   docker compose -f docker-compose.production.yml up -d --build
+#
+# The pem pair is required: EdDSA is the default and there is no key-material
+# default, so a deployment that generates none fails at boot naming the keys to
+# set. It reaches the container as a compose secret rather than through
+# `config/`, which the image COPYs — see the `secrets:` block below.
+#
+# What this file deliberately does NOT do:
+#
+# - **TLS.** Terminate it in front (reverse proxy / load balancer), and set
+#   HTTP_TRUST_PROXY to that hop's address so `req.ip` — and every IP-keyed
+#   rate limit — means the client, not the proxy. See README
+#   "Multi-replica deployments".
+# - **Scale out.** This is one replica (DEPLOYMENT_MODE=single). Before
+#   `--scale app=N`, set DEPLOYMENT_MODE=multi and read that same README
+#   section — boot will then refuse any in-memory store that must be shared.
+# - **Invent secrets.** SESSION_SECRET (and any client secrets referenced by
+#   config/clients.yaml) come from `.env`, which is required here — chmod 600
+#   it, keep it out of git (`git local-files` or your secret manager of
+#   choice), and never bake it into the image.
+
+services:
+  app:
+    build:
+      context: .
+      target: runtime
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    depends_on:
+      redis:
+        condition: service_healthy
+    env_file:
+      # Required, unlike the dev file: a production boot without
+      # SESSION_SECRET (or with the sample one) must fail loudly here, not
+      # serve quietly with a guessable secret.
+      - path: .env
+        required: true
+    secrets:
+      # The signing keys. EdDSA is the default algorithm and there is no key
+      # material default, so the process needs the pem pair at boot — and the
+      # `runtime` image deliberately does not contain it: `Dockerfile` COPYs
+      # `config/`, so a key parked there is baked into a layer that travels
+      # with every image push. Compose secrets mount read-only under
+      # /run/secrets and are the reason the env below overrides the
+      # `./jwt-*.pem` paths in `.env.example`.
+      #
+      # Generate them next to this file before the first `up`:
+      #   openssl genpkey -algorithm ed25519 -out jwt-private.pem
+      #   openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
+      #   chmod 600 jwt-private.pem
+      - jwt_private_key
+      - jwt_public_key
+    environment:
+      NODE_ENV: production
+      DEPLOYMENT_MODE: single
+      # Point the process at the mounted secrets rather than the working-copy
+      # paths `.env` carries for local runs.
+      OAUTH_JWT_PRIVATE_KEY_PATH: /run/secrets/jwt_private_key
+      OAUTH_JWT_PUBLIC_KEY_PATH: /run/secrets/jwt_public_key
+      # `environment` wins over `env_file`, which is the point here:
+      # `.env.example` ships SESSION_SECURE=false / SESSION_NAME=auth.sid so a
+      # plain-HTTP local run works, and this file requires that same `.env`.
+      # Behind the TLS this compose assumes, a non-Secure session cookie is the
+      # session handed to anyone who can read one plaintext hop. The default
+      # `__Host-` cookie name is restored with it — the prefix browsers only
+      # honour on a Secure cookie.
+      SESSION_SECURE: "true"
+      SESSION_NAME: __Host-auth.session
+      # Every Redis-backed store shares the compose-network Redis below.
+      REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: redis://redis:6379
+      SESSION_STORAGE_TYPE: redis
+      SESSION_STORAGE_REDIS_URL: redis://redis:6379
+      # The memory rate limiter is per-process and evadable under bucket
+      # exhaustion (see README) — production points it at Redis.
+      RATE_LIMITER_ADAPTER: redis
+
+  redis:
+    image: redis:7.2-alpine
+    restart: unless-stopped
+    # No `ports:`, deliberately — the app reaches Redis over the compose
+    # network, and nothing else should. The dev file publishes 6379 to
+    # loopback for redis-cli convenience; a published production Redis with
+    # no AUTH is an incident.
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  redis-data:
+
+secrets:
+  # File-backed, so the pem pair stays on the host and reaches the container
+  # read-only at /run/secrets. Keep both out of git alongside `.env`; a key
+  # committed or COPYed into the image is a key you have to rotate.
+  jwt_private_key:
+    file: ./jwt-private.pem
+  jwt_public_key:
+    file: ./jwt-public.pem

package/templates/standalone/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
-		"node": ">=18.19.0"
+		"node": ">=22.0.0"
 	},
 	"packageManager": "pnpm@10.29.3",
 	"type": "module",
@@ -23,33 +23,29 @@
 	"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-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
+		"@o3co/auth-provider-session": "workspace:*",
 		"@o3co/auth.utils": "^0.0.4",
-		"@o3co/ts.hocon": "^1.1.0",
-		"connect-redis": "^9.0.0",
+		"@o3co/ts.hocon": "^1.12.0",
+		"connect-redis": "^10.0.0",
 		"express": "^5.2.1",
 		"express-session": "^1.19.0",
-		"helmet": "^8.1.0",
-		"ioredis": "^5.4.1",
+		"helmet": "^8.3.0",
+		"ioredis": "^6.0.0",
 		"pino": "^10.3.1",
-		"redis": "^5.12.1"
+		"prom-client": "^15.1.3",
+		"redis": "^6.2.0"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
-		"@types/node": "^25.7.0",
-		"@types/supertest": "^7.2.0",
+		"@types/node": "^26.2.0",
+		"@types/supertest": "^7.2.1",
 		"supertest": "^7.1.0",
-		"tsx": "^4.21.0",
+		"tsx": "^4.23.10",
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.6"
-	},
-	"pnpm": {
-		"onlyBuiltDependencies": [
-			"bcrypt"
-		]
+		"vitest": "^4.1.10"
 	}
 }

package/templates/standalone/src/__tests__/audit-sink.test.mts

@@ -0,0 +1,343 @@
+/*
+ * 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.
+ */
+
+/**
+ * #287 — the audit-event pipeline existed and the scaffold wired no sink, so
+ * every security-relevant event the routes emit (`token.issued.failure`,
+ * `authorize.rejected`, `rate_limit.unavailable`, …) was dropped by the
+ * artifact operators actually deploy. `emitAuditEvent` is a no-op when the
+ * slot is empty, so nothing failed and nothing warned: the deployment simply
+ * had no audit trail.
+ *
+ * These tests pin the closure from three sides — the sink implementation, the
+ * module that resolves it from config, and the manifest that must contain
+ * exactly one provider for the slot.
+ */
+
+import { generateKeyPairSync } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+	type AppConfig,
+	type AuditEvent,
+	type AuditSink,
+	createApp,
+	createKeyStoreFactory,
+	defineModule,
+	InMemoryClientRepository,
+	InMemoryUserRepository,
+	type Logger,
+	memoryRefreshTokenFamilyStoreModule,
+	registerBuiltinKeyStores,
+} from "@o3co/auth-provider-core";
+import express from "express";
+import request from "supertest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildModules } from "../buildModules.mjs";
+import { createAppLogger, createAuditLogger, createLoggerAuditSink } from "../logger.mjs";
+import { auditSinkModule } from "../modules.mjs";
+
+const keyPair = generateKeyPairSync("ed25519", {
+	publicKeyEncoding: { type: "spki", format: "pem" },
+	privateKeyEncoding: { type: "pkcs8", format: "pem" },
+});
+
+const baseConfig: AppConfig = {
+	http: { port: 0, trustProxy: false, readinessTimeoutMs: 1000 },
+	logging: { level: "silent" },
+	oauth: {
+		jwt: {
+			issuer: "https://auth.test",
+			signingKey: {
+				provider: "local",
+				local: {
+					algorithm: "EdDSA",
+					kid: "v0",
+					privateKey: keyPair.privateKey,
+					publicKey: keyPair.publicKey,
+					previousKeys: [],
+				},
+			},
+		},
+		accessToken: { expiresIn: 3600 },
+		refreshToken: {
+			expiresIn: 86400,
+			unknownFamilyPolicy: "reject" as const,
+			legacyRtPolicy: "reject" as const,
+		},
+		grants: {},
+		oidcMode: "oidc-required",
+		code: { adapter: "memory" as const },
+	},
+	session: {
+		secret: "test-session-secret.at-least-32-bytes.ok",
+		name: "auth.sid",
+		maxAge: 3600000,
+		secure: false,
+		sameSite: "lax",
+		domain: null,
+		storage: { type: "memory", redis: { url: "redis://localhost:6379" } },
+	},
+	rateLimit: {
+		login: { windowMs: 60000, limit: 10 },
+		failMode: "open",
+	},
+	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: "/login" } },
+	cors: { allowedOrigins: [] },
+	audit: { sink: { type: "logger" } },
+};
+
+const CLIENT_ID = "audit-client";
+const CLIENT_SECRET = "audit-secret";
+const BASIC_AUTH = `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`;
+
+const testRepositoriesModule = defineModule({
+	name: "test:repositories",
+	provides: {
+		clientRepository: () =>
+			new InMemoryClientRepository(
+				new Map([
+					[
+						CLIENT_ID,
+						{
+							tokenEndpointAuthMethod: "client_secret_basic",
+							clientSecret: CLIENT_SECRET,
+							allowedRedirectUris: [],
+							allowedScopes: [],
+							allowedAudiences: [],
+							backchannelLogoutSessionRequired: true,
+							frontchannelLogoutSessionRequired: true,
+							allowedAzpForFederationToken: false,
+						},
+					],
+				]),
+			),
+		userRepository: () => new InMemoryUserRepository(new Map()),
+	},
+});
+
+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 ?? {}),
+			});
+		},
+	},
+});
+
+/** Minimal `Logger` double — the interface is pino's, so only what we assert on. */
+function fakeLogger(): Logger & { info: ReturnType<typeof vi.fn> } {
+	const self = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		child: () => self,
+	};
+	return self as unknown as Logger & { info: ReturnType<typeof vi.fn> };
+}
+
+/** Resolve `auditSink` the way the boot planner does: call the module's provider. */
+async function resolveSink(config: AppConfig): Promise<AuditSink> {
+	const provider = auditSinkModule.provides?.auditSink;
+	if (!provider) throw new Error("auditSinkModule must provide the auditSink slot");
+	return (await provider({ config } as never)) as AuditSink;
+}
+
+describe("#287: the template's audit sink", () => {
+	describe("createLoggerAuditSink — one event, one line, through the app's own JSON stream", () => {
+		it("records the event through the injected logger", async () => {
+			const logger = fakeLogger();
+			const sink = createLoggerAuditSink(logger);
+			const event: AuditEvent = {
+				timestamp: new Date("2026-08-27T00:00:00Z"),
+				type: "authorize.rejected",
+				clientId: "c1",
+				subject: "u1",
+				details: { reason: "client_not_first_party" },
+			};
+
+			await sink.record(event);
+
+			expect(logger.info).toHaveBeenCalledTimes(1);
+			const [payload, message] = logger.info.mock.calls[0] as [Record<string, unknown>, string];
+			// The event type doubles as the message so an operator can alert on
+			// the name without a JSON path, matching how this template's other
+			// structured events are named.
+			expect(message).toBe("authorize.rejected");
+			expect(payload.audit).toMatchObject({
+				type: "authorize.rejected",
+				clientId: "c1",
+				subject: "u1",
+			});
+		});
+
+		it("nests the event under `audit` so it cannot collide with pino's own keys", async () => {
+			// `level`, `time`, `name` and `msg` belong to the log envelope. An
+			// event spread at the top level would let a future audit field
+			// overwrite one of them and corrupt the line for every consumer.
+			const logger = fakeLogger();
+			await createLoggerAuditSink(logger).record({
+				timestamp: new Date("2026-08-27T00:00:00Z"),
+				type: "rate_limit.unavailable",
+			});
+			const [payload] = logger.info.mock.calls[0] as [Record<string, unknown>];
+			expect(Object.keys(payload)).toEqual(["audit"]);
+		});
+
+		it("reports the sink kind it was registered under", () => {
+			expect(createLoggerAuditSink(fakeLogger()).kind).toBe("logger");
+		});
+	});
+
+	describe("the audit trail is not gated by logging.level", () => {
+		it("keeps the audit logger at info while the app logger is silenced", () => {
+			// An audit trail is evidence, not diagnostics. `LOG_LEVEL=warn` is an
+			// ordinary production setting and `silent` is a legitimate one; if
+			// either silenced audit events, #287 would be back — the same silent
+			// drop, reached from the operator's side instead of the scaffold's.
+			const appLogger = createAppLogger({ ...baseConfig, logging: { level: "silent" } });
+			const auditLogger = createAuditLogger();
+			expect((appLogger as unknown as { level: string }).level).toBe("silent");
+			expect((auditLogger as unknown as { level: string }).level).toBe("info");
+		});
+
+		it("names the audit stream so it is separable from application logs", () => {
+			const bindings = (
+				createAuditLogger() as unknown as { bindings(): Record<string, unknown> }
+			).bindings();
+			expect(bindings.name).toBe("audit");
+		});
+	});
+
+	describe("auditSinkModule — resolves the sink from config", () => {
+		it("resolves the logger sink for the shipped default", async () => {
+			expect((await resolveSink(baseConfig)).kind).toBe("logger");
+		});
+
+		it("resolves core's built-in console sink when selected", async () => {
+			const sink = await resolveSink({ ...baseConfig, audit: { sink: { type: "console" } } });
+			expect(sink.kind).toBe("console");
+		});
+
+		it("still produces a sink when the audit section is absent entirely", async () => {
+			// The failure #287 describes is silent absence. A config that says
+			// nothing about auditing must land on a sink, not on `undefined`.
+			const { audit: _audit, ...withoutAudit } = baseConfig;
+			const sink = await resolveSink(withoutAudit as AppConfig);
+			expect(sink.kind).toBe("logger");
+		});
+
+		it("refuses an unknown sink type at boot, naming what is registered", async () => {
+			// There is no "none" — #304's sink policy. An operator who writes one
+			// gets a boot failure naming the sinks that exist, not a silent
+			// deployment with no audit trail.
+			await expect(
+				resolveSink({ ...baseConfig, audit: { sink: { type: "none" } } }),
+			).rejects.toThrow(/none/);
+		});
+	});
+
+	describe("buildModules — the slot is filled in the manifest operators deploy", () => {
+		it("wires exactly one auditSink provider", () => {
+			const modules = buildModules(baseConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+			});
+			const providers = modules.filter((m) => Object.keys(m.provides ?? {}).includes("auditSink"));
+			expect(providers).toHaveLength(1);
+			expect(providers[0]?.name).toBe("standalone:audit-sink");
+		});
+
+		it("the shipped application.conf selects a sink, and never 'none'", () => {
+			const conf = readFileSync(new URL("../../config/application.conf", import.meta.url), "utf8");
+			expect(conf).toMatch(/audit\s*\{[\s\S]*?sink\s*\{[\s\S]*?type\s*=\s*"logger"/);
+			expect(conf).not.toMatch(/type\s*=\s*"none"/);
+		});
+	});
+
+	describe("end to end: an OAuth failure reaches the sink", () => {
+		let handleRef: { dispose(): Promise<void> } | undefined;
+
+		afterEach(async () => {
+			await handleRef?.dispose();
+			handleRef = undefined;
+		});
+
+		it("records token.issued.failure for an unsupported grant_type", async () => {
+			// Before #287 this assertion could not fail: nothing filled the slot,
+			// so `emitAuditEvent` returned without recording anything.
+			const logger = fakeLogger();
+			const spyAuditModule = defineModule({
+				name: "standalone:audit-sink",
+				provides: { auditSink: () => createLoggerAuditSink(logger) },
+			});
+			const handle = await createApp({
+				modules: buildModules(baseConfig, {
+					keyStoreModule: testKeyStoreModule,
+					repositoriesModule: testRepositoriesModule,
+					refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+					auditSinkModule: spyAuditModule,
+				}),
+				bootstrapComponents: { config: baseConfig, pathResolver: (s) => s },
+			});
+			handleRef = handle;
+
+			const app = express();
+			app.use(handle.router);
+			const res = await request(app)
+				.post("/oauth/token")
+				.set("Authorization", BASIC_AUTH)
+				.type("form")
+				.send({ grant_type: "definitely-not-a-grant" });
+
+			expect(res.status).toBe(400);
+			// `emitAuditEvent` is fire-and-forget; let the detached promise settle.
+			await new Promise((r) => setImmediate(r));
+			const types = logger.info.mock.calls.map(
+				(call) => (call[0] as { audit: AuditEvent }).audit.type,
+			);
+			expect(types).toContain("token.issued.failure");
+		});
+
+		it("boots the shipped manifest with its own audit sink wired", async () => {
+			const handle = await createApp({
+				modules: buildModules(baseConfig, {
+					keyStoreModule: testKeyStoreModule,
+					repositoriesModule: testRepositoriesModule,
+					refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+				}),
+				bootstrapComponents: { config: baseConfig, pathResolver: (s) => s },
+			});
+			handleRef = handle;
+			expect(handle).toBeDefined();
+		});
+	});
+});