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

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

@@ -15,7 +15,11 @@
 # 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.
+# `config/`, which the image COPYs — see the `secrets:` block below. So does
+# the client registry, `config/clients.yaml` (#705): it is per-deployment, so
+# `.gitignore` keeps it out of git and `.dockerignore` out of the image, and
+# the image carries no registry of its own. Create it from
+# `config/clients.yaml.example` before the first `up`.
 #
 # What this file deliberately does NOT do:
 #
@@ -24,13 +28,13 @@
 #   and every IP-keyed rate limit — means the client, not the proxy; compose
 #   refuses to start until you supply it. 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
+# - **Scale out.** This is one replica (CORE_DEPLOYMENT_MODE=single). Before
+#   `--scale app=N`, set CORE_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.
+# - **Invent secrets.** SESSION_STORE_SECRET comes 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. The client
+#   registry's secrets are yours to write too; give them as bcrypt hashes.
 
 services:
   app:
@@ -49,11 +53,11 @@ services:
       # security group, a firewall rule, or the proxy's own network. Do not
       # widen this line and call it done.
       - "127.0.0.1:3000:3000"
-    # #593 slice 7: compose's default grace is ten seconds — the HTTP drain
+    # Compose's default grace is ten seconds — the HTTP drain
     # budget alone. With federation grants on, `src/app.mts` gives cleanup 45
     # more for the drain of a rotated upstream credential's write, and SIGKILL
     # has to arrive after that: drain (10) + cleanup (45) + an exit margin.
-    # The cleanup allowance grows by itself with `federationGrants.upstreamHardTimeoutMs`,
+    # The cleanup allowance grows by itself with `federation-grants.upstreamHardTimeoutMs`,
     # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
     stop_grace_period: 60s
     depends_on:
@@ -61,7 +65,7 @@ services:
         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
+      # SESSION_STORE_SECRET (or with the sample one) must fail loudly here, not
       # serve quietly with a guessable secret.
       - path: .env
         required: true
@@ -80,6 +84,10 @@ services:
       #   chmod 600 jwt-private.pem
       - jwt_private_key
       - jwt_public_key
+      # The client registry (#705), for the same reason: `config/clients.yaml`
+      # is per-deployment and may hold client secrets, so it is kept out of the
+      # image and mounted here. REPOSITORIES_CLIENT_YAML_PATH below points the process at it.
+      - client_registry
     environment:
       NODE_ENV: production
       # One replica. Under `single` the replica-safety guard is SILENT by
@@ -88,7 +96,7 @@ services:
       # why the adapter block further down states every one of them explicitly
       # instead of leaving them to inherit. Before `--scale app=N`, set `multi`
       # and read the README's "Multi-replica deployments".
-      DEPLOYMENT_MODE: single
+      CORE_DEPLOYMENT_MODE: single
       # Behind the TLS terminator this file assumes, `req.ip` is the proxy's
       # address and `req.protocol` reads `http` until this names the hop. The
       # README calls it required for exactly that reason, and the cost of
@@ -109,29 +117,30 @@ services:
       HTTP_TRUST_PROXY: ${HTTP_TRUST_PROXY:?set to your TLS terminator's address or CIDR range (e.g. 10.0.0.0/8, or `loopback` for a same-host sidecar) — never `true` behind an open network}
       # 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
+      KEY_STORE_LOCAL_PRIVATE_KEY_PATH: /run/secrets/jwt_private_key
+      KEY_STORE_LOCAL_PUBLIC_KEY_PATH: /run/secrets/jwt_public_key
+      REPOSITORIES_CLIENT_YAML_PATH: /run/secrets/client_registry
       # `environment` wins over `env_file`, which is the point here:
-      # `.env.example` ships SESSION_SECURE=false / SESSION_NAME=auth.sid so a
+      # `.env.example` ships SESSION_STORE_SECURE=false / SESSION_STORE_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
+      SESSION_STORE_SECURE: "true"
+      SESSION_STORE_NAME: __Host-auth.session
       # Every Redis-backed store shares the compose-network Redis below.
       #
       # These are stated in full rather than inherited from
-      # `config/application.conf`, so that the deployable file names its own
+      # `config/reference.conf`, so that the deployable file names its own
       # topology: an operator reading only this one can see which stores
-      # survive a restart. `OAUTH_CODE_ADAPTER` and
-      # `ACCESS_TOKEN_DENYLIST_ADAPTER` already ship as `redis` in that config
-      # layer and are left there on purpose — restating a value that agrees is
+      # survive a restart. `ADAPTERS_CODE_REPOSITORY` and
+      # `ADAPTERS_ACCESS_TOKEN_DENYLIST` already ship as `redis` in that file
+      # and are left there on purpose — restating a value that agrees is
       # a second place to forget to change.
-      REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: redis://redis:6379
-      SESSION_STORAGE_TYPE: redis
-      SESSION_STORAGE_REDIS_URL: redis://redis:6379
+      REDIS_CLIENTS_URL: redis://redis:6379
+      SESSION_STORE_STORAGE_TYPE: redis
+      SESSION_STORE_STORAGE_REDIS_URL: redis://redis:6379
       # The UserSession stores: the provider's own record of who is signed in,
       # which RPs a session has touched, and the family / federation indexes
       # hanging off it. They MUST be on Redis whenever the express-session
@@ -145,13 +154,13 @@ services:
       # authenticated session, finds no user session behind it, and sends the
       # browser to log in again, where the still-valid cookie puts it straight
       # back. A login loop that clears only when the user deletes the cookie.
-      # `DEPLOYMENT_MODE: single` says nothing about it: the replica guard
+      # `CORE_DEPLOYMENT_MODE: single` says nothing about it: the replica guard
       # answers "can these stores be shared", not "do these two stores have the
       # same lifetime".
-      USER_SESSION_STORES_ADAPTER: redis
+      ADAPTERS_USER_SESSION_STORES: redis
       # The memory rate limiter is per-process and evadable under bucket
       # exhaustion (see README) — production points it at Redis.
-      RATE_LIMITER_ADAPTER: redis
+      ADAPTERS_RATE_LIMITER: redis
       # The federation token store is deliberately left at its `memory`
       # default, and that is coherent here rather than an oversight: this
       # template ships every federation disabled, so nothing writes to the
@@ -159,8 +168,24 @@ services:
       # (REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY) that this file must not
       # invent — the records are long-lived upstream refresh tokens. Enabling
       # a federation means setting BOTH, together:
-      #   FEDERATION_TOKEN_STORE_TYPE: redis
+      #   ADAPTERS_FEDERATION_TOKEN_STORE: redis
       #   REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: <openssl rand -base64 32, from .env>
+      #
+      # MFA is on by default (MFA_MODE, `required`): every password login
+      # needs a second factor. Its two stores are left at their `memory`
+      # default, which the template refuses in production before boot; that
+      # refusal names everything MFA needs and the opt-out, so it is the first
+      # thing a deployment that has decided nothing about MFA meets. Decide in
+      # `.env`: either turn it on with all of
+      #   ADAPTERS_MFA_FACTOR_STORE=redis       (or `store`, the factors in your Store)
+      #   ADAPTERS_MFA_TRANSACTION_STORE=redis
+      #   MFA_ENCRYPTION_KEY=<openssl rand -base64 32>
+      #   STANDARD_SMTP_MAIL_SENDER_HOST=... and STANDARD_SMTP_MAIL_SENDER_FROM=...
+      #   MFA_PAGE_URL=<your MFA page, /mfa by default>
+      # or keep the provider without MFA:
+      #   MFA_MODE=off
+      # The Redis below persists (appendonly), as the MFA stores need: a lost
+      # factor lets whoever holds the password bind one of their own.
 
   redis:
     # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
@@ -189,10 +214,13 @@ 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.
+  # File-backed, so the pem pair and the client registry stay on the host and
+  # reach the container read-only at /run/secrets. Keep them 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
+  client_registry:
+    file: ./config/clients.yaml

package/templates/standalone/docker-compose.yml

@@ -8,11 +8,11 @@ services:
     volumes:
       - ./src:/home/node/src
       - ./config:/home/node/config
-    # #593 slice 7: compose's default grace is ten seconds — the HTTP drain
+    # Compose's default grace is ten seconds — the HTTP drain
     # budget alone. With federation grants on, `src/app.mts` gives cleanup 45
     # more for the drain of a rotated upstream credential's write, and SIGKILL
     # has to arrive after that: drain (10) + cleanup (45) + an exit margin.
-    # The cleanup allowance grows by itself with `federationGrants.upstreamHardTimeoutMs`,
+    # The cleanup allowance grows by itself with `federation-grants.upstreamHardTimeoutMs`,
     # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
     stop_grace_period: 60s
     depends_on:
@@ -37,7 +37,17 @@ services:
       # debug it. Redis is already running and already required by three other
       # stores, so this costs nothing: the shared ioredis socket is open
       # either way.
-      USER_SESSION_STORES_ADAPTER: redis
+      ADAPTERS_USER_SESSION_STORES: redis
+      # MFA is on by default (MFA_MODE). Its two stores ship in memory, which
+      # this run would empty on every save: every enrolled factor gone while
+      # the sessions above survive, so each password login after a save binds
+      # a factor anew. On the Redis above they last as the sessions do. These
+      # lines, like ADAPTERS_USER_SESSION_STORES above, override `.env`:
+      # compose's `environment:` wins over `env_file`. The key ring is
+      # config/development.conf's sample key and the mail sender logs each
+      # code; MFA_MODE=off in .env runs without MFA.
+      ADAPTERS_MFA_FACTOR_STORE: redis
+      ADAPTERS_MFA_TRANSACTION_STORE: redis
 
   redis:
     # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)

package/templates/standalone/gitignore

@@ -1,8 +1,10 @@
 # #407: without this file, the first `git add .` in a scaffolded project
-# commits the two things the README's own setup steps tell you to create right
-# here — the `.env` holding SESSION_SECRET, and the signing key pair.
+# commits the two things a local setup creates right here — the signing key
+# pair the README's Usage generates, and the `.env` (holding SESSION_SECRET)
+# the compose files read.
 
 # Secrets and per-machine configuration
+# `.dockerignore` keeps the same out of the image (#705); change both together.
 .env
 .env.*
 !.env.example

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.15.0",
+	"version": "0.17.0-rc.1",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -26,9 +26,11 @@
 		"@o3co/auth-provider-federation-grants": "workspace:*",
 		"@o3co/auth-provider-federation-oidc": "workspace:*",
 		"@o3co/auth-provider-foundation": "workspace:*",
+		"@o3co/auth-provider-mfa": "workspace:*",
 		"@o3co/auth-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
 		"@o3co/auth-provider-session": "workspace:*",
+		"@o3co/auth-provider-standard": "workspace:*",
 		"@o3co/ts.hocon": "^1.13.0",
 		"connect-redis": "^10.0.0",
 		"express": "^5.2.1",
@@ -37,16 +39,17 @@
 		"ioredis": "^6.0.0",
 		"pino": "^10.3.1",
 		"prom-client": "^15.1.3",
-		"redis": "^6.2.1"
+		"redis": "^6.2.1",
+		"zod": "^4.6.5"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
-		"@types/node": "^26.5.1",
+		"@types/node": "^26.6.3",
 		"@types/supertest": "^7.2.1",
-		"supertest": "^7.1.0",
-		"tsx": "^4.23.13",
+		"supertest": "^7.3.0",
+		"tsx": "^4.23.15",
 		"typescript": "^6.0.3",
-		"vitest": "^5.0.0"
+		"vitest": "^5.0.2"
 	}
 }

package/templates/standalone/src/__tests__/access-token-lifetime-alias.test.mts

@@ -16,53 +16,84 @@
 
 /**
  * `oauth.accessToken.expiresIn` / OAUTH_ACCESS_TOKEN_EXPIRES_IN is a deprecated
- * alias of `defaultExpiresIn`, and the composition says so once — the OR-9
- * shape `repositories.code.type` already has.
+ * alias of `defaultExpiresIn`, and the composition says so once.
  *
- * The line has to be exact in both directions. Core's `reference.conf` keeps
- * the shipped lifetime on the deprecated key, so "the alias supplied the
- * default" describes every deployment that set nothing; warning on that would
- * train operators to ignore the line. Only an override of the old key is
- * something to move.
+ * Core's `reference.conf` keeps the shipped lifetime on the deprecated key, so
+ * the alias supplies the default for every deployment that set nothing; a
+ * warning there would train operators to ignore it. Only an override of the old
+ * key is something to move.
  */
 
 import { fileURLToPath } from "node:url";
-import { type AppConfig, AppConfigSchema } from "@o3co/auth-provider-core";
+import { AppConfigSchema, coreReference, type Logger } from "@o3co/auth-provider-core";
 import { parseFile } from "@o3co/ts.hocon";
 import { validate } from "@o3co/ts.hocon/zod";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildModules } from "../buildModules.mjs";
-import { resolveConfigPaths, resolveLibraryReferenceConfPath } from "../configPath.mjs";
+import { resolveConfigPaths, type Switches } from "../configPath.mjs";
+import { templateReference } from "../modules.mjs";
+import { rootSectionsOf } from "./library-references.fixture.mjs";
 
 const configDir = fileURLToPath(new URL("../../config", import.meta.url));
 
 const REQUIRED_ENV = {
-	OAUTH_JWT_SECRET: "access-token-alias.at-least-32-bytes.ok",
+	KEY_STORE_LOCAL_SECRET: "access-token-alias.at-least-32-bytes.ok",
 	OAUTH_JWT_ISSUER: "https://auth.test",
-	SESSION_SECRET: "access-token-alias-session.at-least-32-bytes.ok",
+	SESSION_STORE_SECRET: "access-token-alias-session.at-least-32-bytes.ok",
 };
 
 /** The shipped layers, resolved the way `app.mts` resolves them. */
-function loadShipped(env: Record<string, string> = {}): AppConfig {
+function loadShipped(env: Record<string, string> = {}): Switches {
 	const { applicationConfPath, envConfPath } = resolveConfigPaths(configDir, "development");
 	const resolvedEnv = { ...REQUIRED_ENV, ...env };
-	return validate(
-		parseFile(envConfPath, { env: resolvedEnv })
-			.withFallback(parseFile(applicationConfPath, { env: resolvedEnv }))
-			.withFallback(parseFile(resolveLibraryReferenceConfPath(), { env: resolvedEnv })),
-		AppConfigSchema,
-	);
+	const layers = parseFile(envConfPath, { env: resolvedEnv })
+		.withFallback(parseFile(applicationConfPath, { env: resolvedEnv }))
+		.withFallback(parseFile(fileURLToPath(templateReference()), { env: resolvedEnv }))
+		.withFallback(parseFile(fileURLToPath(coreReference()), { env: resolvedEnv }));
+	return { ...validate(layers, AppConfigSchema), ...rootSectionsOf(layers, resolvedEnv) };
 }
 
-/** Every console warning `buildModules` emits about the deprecated key. */
-function aliasWarnings(config: AppConfig): string[] {
-	const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-	buildModules(config);
-	return warn.mock.calls
-		.map((call) => String(call[0]))
-		.filter((message) => message.includes("oauth.accessToken.expiresIn"));
+/** What `buildModules` hands the logger it is given, per level. */
+function logged(config: Switches): Array<{ level: string; args: unknown[] }> {
+	const calls: Array<{ level: string; args: unknown[] }> = [];
+	const record =
+		(level: string) =>
+		(...args: unknown[]): void => {
+			calls.push({ level, args });
+		};
+	const logger: Logger = {
+		trace: record("trace"),
+		debug: record("debug"),
+		info: record("info"),
+		warn: record("warn"),
+		error: record("error"),
+		fatal: record("fatal"),
+		child: () => logger,
+	};
+	buildModules(config, { logger });
+	return calls;
 }
 
+/** The one line the alias is reported by: object-first, an event name, at warn. */
+const ALIAS_WARNING = {
+	level: "warn",
+	args: [
+		{
+			key: "oauth.accessToken.expiresIn",
+			env: "OAUTH_ACCESS_TOKEN_EXPIRES_IN",
+			replacement: "oauth.accessToken.defaultExpiresIn",
+			replacementEnv: "OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN",
+		},
+		"config_key_deprecated",
+	],
+};
+
+/** Every line `buildModules` writes about the deprecated key. */
+const aliasWarnings = (config: Switches) =>
+	logged(config).filter(
+		({ args }) => (args[0] as { key?: unknown } | undefined)?.key === "oauth.accessToken.expiresIn",
+	);
+
 describe("the deprecated access-token lifetime alias", () => {
 	afterEach(() => {
 		vi.restoreAllMocks();
@@ -81,12 +112,8 @@ describe("the deprecated access-token lifetime alias", () => {
 		);
 	});
 
-	it("warns once when OAUTH_ACCESS_TOKEN_EXPIRES_IN still decides the default", () => {
-		const warnings = aliasWarnings(loadShipped({ OAUTH_ACCESS_TOKEN_EXPIRES_IN: "900" }));
-		expect(warnings).toHaveLength(1);
-		expect(warnings[0]).toMatch(/deprecated/);
-		expect(warnings[0]).toMatch(/oauth\.accessToken\.defaultExpiresIn/);
-		expect(warnings[0]).toMatch(/OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN/);
+	it("warns once, object-first, when OAUTH_ACCESS_TOKEN_EXPIRES_IN still decides the default", () => {
+		expect(logged(loadShipped({ OAUTH_ACCESS_TOKEN_EXPIRES_IN: "900" }))).toEqual([ALIAS_WARNING]);
 	});
 
 	it("warns for a hand-built configuration that overrides only the old key", () => {
@@ -96,6 +123,12 @@ describe("the deprecated access-token lifetime alias", () => {
 				...config,
 				oauth: { ...config.oauth, accessToken: { expiresIn: 900 } },
 			}),
-		).toHaveLength(1);
+		).toEqual([ALIAS_WARNING]);
+	});
+
+	it("writes the same line through consoleLogger when no logger is handed over", () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		buildModules(loadShipped({ OAUTH_ACCESS_TOKEN_EXPIRES_IN: "900" }));
+		expect(warn.mock.calls).toEqual([ALIAS_WARNING.args]);
 	});
 });