@o3co/create-auth-provider 0.14.0 → 0.16.0

package/templates/standalone/config/application.conf

@@ -159,6 +159,44 @@ replaySeenSet {
   adapter = ${?REPLAY_SEEN_SET_ADAPTER}
 }
 
+# #593: federation grants — a user's standing consent that a backend or an
+# agent may obtain upstream IdP tokens with no session behind the call. Off by
+# default; FEDERATION_GRANTS_ENABLED=true installs the routes, the two stores
+# below and the subject-revocation service. Enabling it is a statement that
+# the deployment has a consent page (FEDERATION_GRANTS_CONSENT_URL, no default),
+# a `callbackURL` on every connection, and a user repository that covers each
+# connection's registration (or FEDERATION_GRANTS_IDENTITY_LOOKUP=unsupported,
+# the recorded decision not to make that check) — each refused at boot when
+# missing. Connections and the encryption key ring have no environment form;
+# write them in a deployment-owned HOCON layer (README: Federation Grants).
+federationGrants {
+  enabled = false
+  enabled = ${?FEDERATION_GRANTS_ENABLED}
+  identityLookup = "required"
+  identityLookup = ${?FEDERATION_GRANTS_IDENTITY_LOOKUP}
+  consent {
+    url = ${?FEDERATION_GRANTS_CONSENT_URL}
+  }
+  encryptionMode = "required"
+  encryptionMode = ${?FEDERATION_GRANTS_ENCRYPTION_MODE}
+}
+
+# "redis" for both, as for the denylist above: a grant is an offline credential
+# that must outlive a restart, and every store this file already selects shares
+# the same socket. Redis grants need the subject boundary in Redis too
+# (USER_SESSION_STORES_ADAPTER=redis, which both compose files set) — boot
+# refuses the pairing with a memory boundary, because the grants would outlive
+# what ends them. Single-instance local work can set both to "memory".
+federationGrantStore {
+  adapter = "redis"
+  adapter = ${?FEDERATION_GRANT_STORE_ADAPTER}
+}
+
+federationGrantIntentStore {
+  adapter = "redis"
+  adapter = ${?FEDERATION_GRANT_INTENT_STORE_ADAPTER}
+}
+
 # #527: where consent to a client that is not first-party is recorded.
 # "none" (the default) wires no store and such clients are refused at
 # /authorize; "memory" is single-replica only (refused under
@@ -269,6 +307,20 @@ federations {
 
     # Where the browser goes after a callback carrying no `redirect_to`.
     # clientUrl = ${?FEDERATIONS_GOOGLE_CLIENT_URL}
+
+    # RFC 9207: Google always returns `iss` on the callback, so a callback
+    # without one is refused. `false` is the way out if Google ever stops
+    # sending it. It permits a missing `iss` only — one that is sent and is not
+    # Google's is refused either way.
+    # requireAuthorizationResponseIss = ${?FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS}
+
+    # Whether sign-in asks Google for a refresh token. Unset is "offline":
+    # every sign-in shows Google's consent screen, because Google issues a
+    # refresh token only there, and every session gets one that
+    # POST /oauth/federation/google/token can refresh with. "online" shows the
+    # consent screen on the first sign-in only and gets no refresh token at
+    # all — for a deployment that uses Google to sign in and nothing more.
+    accessType = ${?FEDERATIONS_GOOGLE_ACCESS_TYPE}
   }
 
   # Any OpenID Connect provider (Okta, Entra ID, Auth0, Keycloak, your own
@@ -327,17 +379,40 @@ repositories {
       # Both URLs carry plaintext user credentials, so both must be absolute
       # https URLs. http:// is accepted only for a loopback host (localhost,
       # 127.0.0.0/8, [::1]); a private-range address or a container-network
-      # service name still needs https. Boot fails if either is not.
+      # service name still needs https. Boot fails if either is not. Each must
+      # also be the endpoint that answers: no request follows a 3xx, so a URL
+      # that redirects fails every call.
       authenticateUrl = ${?CLIENT_USER_AUTHENTICATE_URL}
       authenticateByTokenUrl = ${?CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL}
       # #482: optional. When set, a signed-in user can link a second federated
       # identity (GET /session/oauth/federation/<name>?link=1): the Store
       # receives { userId, provider, sub, token, claims } and decides — never on
-      # an unverified or relay e-mail. Same https rule as the two URLs above.
+      # an unverified or relay e-mail. Same https and no-redirect rule as the two URLs above.
       # Also declared in core's reference.conf, so a composition that does not
       # layer this file gets the same override.
       # Without it, link=1 is refused with link_unsupported.
       linkFederatedIdentityUrl = ${?CLIENT_USER_LINK_FEDERATED_IDENTITY_URL}
+      # #613: optional. The Store's identity lookup for federation grants —
+      # what lets this deployment keep FEDERATION_GRANTS_IDENTITY_LOOKUP=required
+      # with a connection configured. Same https and no-redirect rule. Declare what the Store
+      # covers, per registration, in a HOCON layer (README: Federation Grants):
+      #   federatedIdentityLookupCoverage = [
+      #     { provider = "entra-files", issuer = "...", clientId = "...", requiredClaims = ["tid", "oid"] }
+      #   ]
+      findSubjectByFederatedIdentityUrl = ${?CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL}
+      # Optional. Sent on every Store request as `Authorization: Bearer <token>`
+      # so the Store can refuse any caller but this deployment; unset, none is
+      # sent. A bare token (no "Bearer " prefix), at least 32 bytes of key
+      # material -- `openssl rand -hex 32`. Boot fails on a weak, malformed or
+      # blank value. One token goes to every URL above: one trust domain. A
+      # Store that refuses it with 401 (or 403) + `WWW-Authenticate: Bearer`
+      # makes every Store call an outage rather than a wrong password: 503 and
+      # a logged error at login, federation callbacks and the jwt-bearer
+      # grant; a temporarily_unavailable redirect and
+      # federation_grant_callback_unavailable (err.name
+      # StoreCredentialRefusedError) at the federation-grants callback. Also
+      # declared in core's reference.conf.
+      bearerToken = ${?CLIENT_USER_BEARER_TOKEN}
       # Positive integer, milliseconds, <= 2147483647. Boot fails otherwise —
       # including on a blank env override, which HOCON substitutes as "".
       timeout = 5000

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

@@ -49,6 +49,13 @@ 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
+    # 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`,
+    # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
+    stop_grace_period: 60s
     depends_on:
       redis:
         condition: service_healthy

package/templates/standalone/docker-compose.yml

@@ -8,6 +8,13 @@ services:
     volumes:
       - ./src:/home/node/src
       - ./config:/home/node/config
+    # #593 slice 7: 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`,
+    # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
+    stop_grace_period: 60s
     depends_on:
       redis:
         condition: service_healthy

package/templates/standalone/gitignore

@@ -1,6 +1,7 @@
 # #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
 .env

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -12,7 +12,7 @@
 		"build": "tsc",
 		"start": "node dist/app.mjs",
 		"debug": "NODE_OPTIONS='--conditions=development' tsx watch src/app.mts",
-		"test": "vitest run --passWithNoTests"
+		"test": "tsc --noEmit && vitest run --passWithNoTests"
 	},
 	"imports": {
 		"#/*": {
@@ -23,6 +23,7 @@
 	"dependencies": {
 		"@o3co/auth-provider-core": "workspace:*",
 		"@o3co/auth-provider-federation-google": "workspace:*",
+		"@o3co/auth-provider-federation-grants": "workspace:*",
 		"@o3co/auth-provider-federation-oidc": "workspace:*",
 		"@o3co/auth-provider-foundation": "workspace:*",
 		"@o3co/auth-provider-oauth": "workspace:*",

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

@@ -27,7 +27,7 @@
  */
 
 import { fileURLToPath } from "node:url";
-import { type AppConfig, AppConfigSchema } from "@o3co/auth-provider-core";
+import { type AppConfig, AppConfigSchema, 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";
@@ -54,15 +54,47 @@ function loadShipped(env: Record<string, string> = {}): AppConfig {
 	);
 }
 
-/** 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: AppConfig): 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: AppConfig) =>
+	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 +113,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 +124,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]);
 	});
 });