@o3co/create-auth-provider 0.12.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,8 +28,8 @@
     "node": ">=22.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "vitest": "^4.1.11"
+    "@types/node": "^26.5.1",
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/.dockerignore

@@ -1,9 +1,10 @@
 node_modules
 dist
 .git
-.gitignore
 .env*
 !.env.example
-*.md
-docker-compose*.yml
 Makefile
+# .gitignore, the READMEs and the compose files stay in the context: the
+# `test` image copies them because the shipped suite reads them (#512). The
+# runtime image never copies them, so they cost the context a few kilobytes
+# and the image nothing.

package/templates/standalone/.env.example

@@ -72,6 +72,11 @@ SESSION_NAME=auth.sid
 
 # Optional
 # HTTP_PORT=3000
+# OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN=3600
+# The most a token-exchange `expires_in` can obtain; unset = the default.
+# OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN=3600
+# DEPRECATED alias of OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN, read only while
+# that one is unset.
 # OAUTH_ACCESS_TOKEN_EXPIRES_IN=3600
 # OAUTH_REFRESH_TOKEN_EXPIRES_IN=86400
 # SESSION_MAX_AGE=3600000

package/templates/standalone/Dockerfile

@@ -1,9 +1,9 @@
-# The base image is pinned by digest, not just by tag: `node:24-alpine` is a
+# The base image is pinned by digest, not just by tag: `node:26-alpine` is a
 # moving pointer, so the same source produced a different image on every
 # rebuild (#289). The digest is the multi-arch index, so amd64 and arm64 both
 # resolve from it. Dependabot's `docker` ecosystem keeps the pair in step —
 # bump the tag and the digest together, never the tag alone.
-FROM node:24-alpine@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 AS node-base
+FROM node:26-alpine@sha256:ef24c5053d50fdc3e4e56eb4e7ddb7861874ab0fdc797046ba897581deb8e868 AS node-base
 
 ENV HOME=/home/node
 
@@ -103,8 +103,15 @@ CMD ["node", "dist/app.mjs"]
 #############################################
 FROM builder AS test
 
-COPY --chown=node:node vitest.config.mts ./
+COPY --chown=node:node vitest.config.mts vitest.supertest-loopback.mts ./
 COPY --chown=node:node tests/ ./tests/
+# #512: the suite reads these from the project root (scaffold-assets,
+# documented-env-overrides, smoke). The builder stage brings only what the
+# build needs, so inside this image they did not exist and `make test` failed
+# on files that were never a test's business. `.dockerignore` lets them into
+# the context for the same reason; nothing copies them into `runtime`.
+COPY --chown=node:node Dockerfile .dockerignore .env.example .gitignore README.md README.ja.md \
+  docker-compose.yml docker-compose.production.yml ./
 
 CMD ["pnpm", "run", "test", "--", "--passWithNoTests"]
 

package/templates/standalone/README.ja.md

@@ -79,13 +79,18 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 
 | 変数 | デフォルト | 説明 |
 |---|---|---|
-| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | `3600` | アクセストークンの有効期間（秒）。正の整数、上限は 1 年（`31536000`）。 |
+| `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` | `3600` | リクエストが有効期間を指定しないときに全グラントが発行するアクセストークンの有効期間（秒）。正の整数、上限は 1 年（`31536000`）。 |
+| `OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN` | デフォルトと同じ | token exchange リクエストの `expires_in` パラメータで得られる上限。超えるリクエストはこの値に切り詰められる。未設定ならデフォルトと同じで、設定しない限り延長されない。デフォルトがこれを超えると両キーを名指しして起動失敗。オフラインで検証するリソースサーバーに対し、交換で発行されたトークンが失効後も通用し得る期間の上限でもある。 |
+| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | — | `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` の**非推奨（deprecated）**エイリアス（config キーでは `oauth.accessToken.expiresIn` が `oauth.accessToken.defaultExpiresIn` のエイリアス）。新しい変数が未設定の間だけ読まれる。値は新しい変数へ移すこと。 |
 | `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | リフレッシュトークンの有効期間（秒）。正の整数、上限は 1 年（`31536000`）。 |
 
 これらを空文字で export すると fallback ではなく起動失敗になる: HOCON は `FOO=` を
 `""` に解決し、それが `0` に coerce され、有効期間 0 は「発行時点で期限切れ」の
 トークンを作るため。
 
+`expires_in` リクエストパラメータを読むのは token exchange（RFC 8693）だけで、
+他のグラントはそれを無視してデフォルトを発行する。
+
 ### グラントタイプ
 
 | 変数 | デフォルト | 説明 |

package/templates/standalone/README.md

@@ -25,6 +25,12 @@ my-app:
   allowedRedirectUris: ["https://app.example/callback"]
 ```
 
+A machine client can authenticate with a key instead of a shared secret (#484):
+`tokenEndpointAuthMethod: "private_key_jwt"` plus `jwks` (inline public keys) or
+`jwksUri`, and it presents a signed assertion at `/oauth/token` — see the
+[oauth package README](../../packages/oauth/README.md#client-authentication-private_key_jwt-rfc-7523-22).
+Nothing secret lives in `clients.yaml` for such a client.
+
 **What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident. The step that changes the former is a consent screen, tracked separately.
 
 **Migrating.** Registrations that predate the field are refused at `/authorize` until you mark them — a client with no `firstParty` field and one carrying an explicit `false` are treated alike. Mark every client you operate before pointing it at `/authorize`; there is no admit-with-warning window. The one-time `oauth.authorize.allowUnmarkedClients` migration flag was removed before it ever shipped in a release, and a config or environment still setting it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot with migration instructions rather than being silently ignored.
@@ -106,6 +112,8 @@ Other multi-replica considerations covered by the default modules:
 - The `express-session` store (`sessionStoreModule`) is its own connection: `SESSION_STORAGE_TYPE=redis` with `SESSION_STORAGE_REDIS_URL` (`session.storage.redis.url`) pointing at the shared instance.
 - The user-session stores switch on `userSessionStores.adapter = "redis"` (`USER_SESSION_STORES_ADAPTER`), which wires `redisSessionStoresModule` off the shared ioredis connection — the one `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` configures.
 - The authorization-code repository switches on `oauth.code.adapter` (`OAUTH_CODE_ADAPTER`); the template ships `"redis"`, on that same connection. The older `repositories.code.type = "redis"` (`CLIENT_CODE_TYPE`) switch is still honoured with a deprecation warning at boot. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is still bound by `config/application.conf` but nothing reads it: the Redis code repository has run on the shared connection since the `{ endpointUri }` builder shape was retired, so there is one Redis URL for every adapter and that variable is legacy.
+- The replay seen-set — the `jti` single-use record behind `private_key_jwt` client authentication (#484) — switches on `replaySeenSet.adapter` (`REPLAY_SEEN_SET_ADAPTER`); the template ships `"redis"` on the shared connection, and `memory` is refused under `DEPLOYMENT_MODE=multi` because a captured client assertion would replay once per replica.
+- The consent step for clients that are not first-party (#527) switches on `consentStore.adapter` (`CONSENT_STORE_ADAPTER`). It is off (`none`) by default; `memory` is refused under `DEPLOYMENT_MODE=multi`, because a consent granted on one replica would be asked for again on every other and a consent page's parked request would be unknown to the replica that receives the answer. `redis` (#561) keeps both on the shared connection. See [Consent Store](#consent-store).
 - The federation token store defaults to memory. Set `FEDERATION_TOKEN_STORE_TYPE=redis` (`federationTokenStore.type = "redis"`) and supply `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` — 32 bytes, base64-encoded (`openssl rand -base64 32`); the store encrypts the upstream refresh tokens it holds. It shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`. See [Federation Token Store](#federation-token-store).
 
 ## Usage
@@ -161,6 +169,18 @@ fail fast rather than silently falling back to defaults.
 | `OAUTH_JWT_SECRET` | — | Signing secret, **HMAC (`HS256`) only**. At least 32 bytes (256 bits) of random material — `openssl rand -hex 32`. Hex/base64 values are measured **decoded**, so a 32-character hex string counts as 16 bytes and is refused. |
 | `OAUTH_JWT_ISSUER` | **(required)** | Canonical issuer URL stamped as `iss` on every token. Must be absolute `https` (`http` only for a loopback host), with no query or fragment. Boot fails when unset — it is never derived from the `Host` header. |
 | `OAUTH_REQUIRE_EMAIL_VERIFIED` | `false` | Refuse to issue tokens for a user until the Store publishes `emailVerified: true`. Enforced at `/authorize` and on the `session` grant. Verification itself is the Store's job — this only reads the result. |
+| `OAUTH_CIMD_ENABLED` | `false` | Accept Client ID Metadata Documents (#529): a client whose `client_id` is the `https` URL of its own registration, the model MCP hosts use. Such a client is public, never first-party — it goes through the consent step, so wire `CONSENT_STORE_ADAPTER`. |
+| `OAUTH_CIMD_ALLOWED_SCOPES` | — | Comma-separated: what any such client may obtain (its document's `scope` is intersected with this). Empty admits none. |
+| `OAUTH_CIMD_ALLOWED_AUDIENCES` | — | Comma-separated: the resource servers it may mint for (RFC 8707 `resource`). Empty admits only its own `client_id`. |
+| `OAUTH_CIMD_ALLOWED_HOSTS` | — | Comma-separated hosts a document may live on: exact, or `.suffix` for a domain and its subdomains. Empty admits any public host. |
+| `OAUTH_CIMD_DENIED_HOSTS` | — | Comma-separated hosts refused even when allowed above. |
+| `OAUTH_CIMD_MAX_BYTES` | `5120` | Byte cap on a document (the draft recommends 5 KB). |
+| `OAUTH_CIMD_TIMEOUT_MS` | `5000` | Fetch timeout. |
+| `OAUTH_CIMD_CACHE_MAX_AGE_MS` | `600000` | Upper bound on how long a valid document is served from cache; `Cache-Control: max-age` may shorten it. |
+| `OAUTH_CIMD_MAX_CACHE_ENTRIES` | `256` | How many documents are remembered at once. The keys are chosen by an unauthenticated caller, so the map is bounded. |
+| `OAUTH_CIMD_STALE_IF_ERROR_MS` | `300000` | How long a registration already validated is still served after a revalidation that failed for a reason that is not the document's (a DNS blip, a 5xx, a timeout) — an outage should not break a working client. A document that was *rejected* is dropped immediately. `0` disables it. |
+| `OAUTH_CIMD_NEGATIVE_CACHE_MS` | `60000` | How long a refusal is remembered, so the same `client_id` is not resolved and fetched again on every request. Short, so a client that fixes its document is not locked out. |
+| `OAUTH_CIMD_MAX_CONCURRENT_FETCHES` | `8` | How many documents may be in flight at once, across every `client_id`. Bounds what an unauthenticated caller can make this server dial. |
 | `OAUTH_JWT_KID` | `v0` | Key ID included in the JWT header |
 | `OAUTH_JWT_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
 | `OAUTH_JWT_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
@@ -191,13 +211,18 @@ every relying party must be handed the shared secret — which also lets it
 
 | Variable | Default | Description |
 |---|---|---|
-| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | `3600` | Access token lifetime in seconds. Whole positive number, at most one year (`31536000`). |
+| `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` | `3600` | Access token lifetime in seconds that every grant mints when the request asks for none. Whole positive number, at most one year (`31536000`). |
+| `OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN` | the default | The most a token-exchange request's `expires_in` parameter can obtain; a larger request is clamped to it. Unset means the default, so no token is extended unless you set this. A default above it is a boot failure naming both keys. It also bounds how long an exchanged token outlives a revocation at a resource server that validates it offline. |
+| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | — | **Deprecated** alias of `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` (config key `oauth.accessToken.expiresIn`, of `oauth.accessToken.defaultExpiresIn`), read only while the new one is unset. Move the value to the new variable. |
 | `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | Refresh token lifetime in seconds. Whole positive number, at most one year (`31536000`). |
 
 Exporting one of these as an empty string is a boot failure, not a fallback:
 HOCON resolves `FOO=` to `""`, which coerces to `0`, and a zero lifetime mints
 tokens that have already expired.
 
+Only token exchange (RFC 8693) reads an `expires_in` request parameter; every
+other grant ignores it and mints the default.
+
 ### Grant Types
 
 | Variable | Default | Description |
@@ -311,6 +336,46 @@ all — no headers, no `Vary`, nothing changed.
 | `FEDERATIONS_GOOGLE_CLIENT_SECRET` | — | Google OAuth client secret |
 | `FEDERATIONS_GOOGLE_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/google/callback` | Google OAuth callback URL |
 
+### OIDC Federation (any OpenID Connect provider)
+
+One instance ships in `config/application.conf` under `federations.oidc`
+(`@o3co/auth-provider-federation-oidc`, #524): Okta, Entra ID, Auth0, Keycloak
+or your own tenant, selected by issuer. Discovery runs at boot and a failure
+refuses boot. The identity handed to the Store is `oidc:<sub>`; an identity
+the Store does not know is refused with 401 — nothing is provisioned.
+
+| Variable | Default | Description |
+|---|---|---|
+| `FEDERATIONS_OIDC_ENABLED` | `false` | Enable the OIDC federation |
+| `FEDERATIONS_OIDC_ISSUER` | — | Issuer identifier (https), exactly as the IdP writes `iss` |
+| `FEDERATIONS_OIDC_CLIENT_ID` | — | Client ID registered at the IdP |
+| `FEDERATIONS_OIDC_CLIENT_SECRET` | — | Client secret (`client_secret_basic`); set `privateKey` in the config file for `private_key_jwt` instead |
+| `FEDERATIONS_OIDC_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/oidc/callback` | Where the IdP sends the browser back |
+
+A second IdP is another section with `type = "oidc"` and its own callback:
+
+```hocon
+federations {
+  okta {
+    enabled = true
+    type = "oidc"
+    issuer = "https://dev-123.okta.com"
+    clientId = ${OKTA_CLIENT_ID}
+    clientSecret = ${OKTA_CLIENT_SECRET}
+    callbackURL = "https://auth.example.com/session/oauth/federation/okta/callback"
+    redirectAllowlist = ["https://app.example.com/welcome"]
+  }
+}
+```
+
+The section's `type` names the implementation. `federations.google` without a
+`type` is the built-in Google federation; with `type = "oidc"` it is a generic
+OIDC instance named `google`, and the built-in module is not composed.
+
+Every field the package accepts — `scopes`, `discovery` / `endpoints`,
+`privateKey`, `userInfo`, `idTokenSignedResponseAlg`, `clockToleranceSeconds` —
+is documented in [its README](../../packages/federation-oidc/README.md).
+
 ### Client Repository
 
 | Variable | Default | Description |
@@ -325,6 +390,7 @@ all — no headers, no `Vary`, nothing changed.
 | `CLIENT_USER_TYPE` | `http` | User repository backend: `http` |
 | `CLIENT_USER_AUTHENTICATE_URL` | — | URL for password-based user authentication. **https required** (see below) |
 | `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication. **https required** (see below) |
+| `CLIENT_USER_LINK_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store links a federated identity at (#482); enables `?link=1` on the federation start route. **https required** |
 | `CLIENT_USER_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
 | `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
 
@@ -364,6 +430,19 @@ needs a key.
 `scanFallback` migration flag live under `redisFederationTokenStore` in a
 config layer rather than behind an environment variable.
 
+### Consent Store
+
+Where an end-user's consent to a client that is not first-party is recorded,
+together with the `/authorize` request parked while the consent page asks
+(#527, #552). One switch wires both. `none` by default: such clients are
+refused and only first-party clients are served. `memory` forks per replica and
+is refused under `DEPLOYMENT_MODE=multi`; `redis` (#561) shares both over the
+socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`.
+
+| Variable | Default | Description |
+|---|---|---|
+| `CONSENT_STORE_ADAPTER` | `none` | Consent store for clients that are not first-party (#527): `none` (such clients are refused), `memory` (single replica) or `redis` (shared, #561) |
+
 ### Redis Namespacing
 
 For multi-tenant Redis clusters, set deployment-specific key prefixes so two
@@ -375,15 +454,17 @@ auth.provider instances cannot collide in the same database:
 | `REFRESH_TOKEN_FAMILY_STORE_KEY_PREFIX` | `rtfam:` | Prefix for refresh-token family records. |
 | `CLIENT_CODE_KEY_PREFIX` | `oauth:code:` | Prefix for OAuth authorization codes. |
 | `REDIS_FEDERATION_TOKEN_STORE_KEY_PREFIX` | `ft:` | Prefix for federation token records, their per-session index and their lock keys. |
+| `REDIS_CONSENT_STORE_KEY_PREFIX` | `consent:` | Prefix for consent records and for parked consent requests with their per-session index (`CONSENT_STORE_ADAPTER=redis`, #561). |
 
 Use values that include the deployment name, for example `tenant-a:ss:`,
-`tenant-a:rtfam:`, `tenant-a:code:`, and `tenant-a:ft:`.
+`tenant-a:rtfam:`, `tenant-a:code:`, `tenant-a:ft:`, and `tenant-a:consent:`.
 
 ### Endpoints
 
 | Variable | Default | Description |
 |---|---|---|
 | `ENDPOINTS_LOGIN_URL` | `/login` | URL of the login page (for redirects) |
+| `ENDPOINTS_CONSENT_URL` | `/consent` | URL of the consent page a client that is not first-party is routed through, with `?challenge=<id>` (#527) |
 
 `ENDPOINTS_CLIENT_URL` and `ENDPOINTS_AUTH_CALLBACK_URL` were removed (IH-10) —
 no production consumer read them, and the config lines leaked values into

package/templates/standalone/config/application.conf

@@ -94,6 +94,18 @@ oauth {
   # restart and across replicas — multi-replica production MUST use "redis".
   # Supersedes the legacy `repositories.code.type` switch (kept below as
   # deprecated for backward compat — see CHANGELOG for the removal version).
+  # #481: the Authentication Context Class References this deployment can
+  # vouch for, each mapped to the RFC 8176 `amr` values a session must carry
+  # (`pwd` for a password login, `hwk` for a passkey, `fed` for a federated
+  # login, `mfa` when a resumed MFA login records it). `/authorize` answers
+  # `acr_values` from this table alone — anything else is
+  # `unmet_authentication_requirements` — and discovery advertises the keys.
+  #
+  #   authorize.acrValues {
+  #     "urn:example:pwd" = ["pwd"]
+  #     "urn:example:mfa" = ["pwd", "mfa"]
+  #   }
+  #
   # #267: /authorize refuses any client not marked `firstParty: true` in
   # clients.yaml — the template's example clients are marked. There is no
   # opt-out: the one-time `allowUnmarkedClients` migration flag was removed
@@ -134,6 +146,31 @@ accessTokenDenylist {
   adapter = ${?ACCESS_TOKEN_DENYLIST_ADAPTER}
 }
 
+# #484: backend for the replay seen-set — the `jti` single-use record behind
+# `private_key_jwt` client authentication (a client registered with `jwks` or
+# `jwksUri` in config/clients.yaml). Same reasoning as the denylist above:
+# "memory" forks per replica, so a captured client assertion would replay
+# once per replica, and `deployment.mode = "multi"` refuses it by name. It
+# shares the ioredis socket, so it costs no extra connection.
+#
+# Single-instance local development can set REPLAY_SEEN_SET_ADAPTER=memory.
+replaySeenSet {
+  adapter = "redis"
+  adapter = ${?REPLAY_SEEN_SET_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
+# DEPLOYMENT_MODE=multi by name); "redis" (#561) keeps the consent records and
+# the requests parked while the consent page asks on the shared ioredis socket,
+# and is what a deployment of more than one replica selects. Its key namespace
+# is REDIS_CONSENT_STORE_KEY_PREFIX (default "consent:").
+consentStore {
+  adapter = "none"
+  adapter = ${?CONSENT_STORE_ADAPTER}
+}
+
 session {
   secret = ${?SESSION_SECRET}
   # MIN-2: __Host- prefix requires Secure, Path=/, and no Domain attribute.
@@ -233,6 +270,42 @@ federations {
     # Where the browser goes after a callback carrying no `redirect_to`.
     # clientUrl = ${?FEDERATIONS_GOOGLE_CLIENT_URL}
   }
+
+  # Any OpenID Connect provider (Okta, Entra ID, Auth0, Keycloak, your own
+  # tenant) — `@o3co/auth-provider-federation-oidc` (#524). Disabled by
+  # default; the env vars below switch this one instance on. The section
+  # name is the federation name: the browser starts at
+  # /session/oauth/federation/oidc and the identity handed to the Store is
+  # "oidc:<sub>". An identity the Store does not know is refused (401);
+  # nothing is provisioned. To broker to a second IdP, copy this block under
+  # another name (`okta { type = "oidc" ... }`) with its own callbackURL.
+  oidc {
+    enabled = false
+    enabled = ${?FEDERATIONS_OIDC_ENABLED}
+    type = "oidc"
+
+    # Issuer identifier, exactly as the IdP writes it into `iss`. Discovery
+    # runs at boot from <issuer>/.well-known/openid-configuration and a
+    # failure refuses boot. https only (plain http on localhost for dev).
+    issuer = ${?FEDERATIONS_OIDC_ISSUER}
+    clientId = ${?FEDERATIONS_OIDC_CLIENT_ID}
+    # client_secret_basic. For private_key_jwt drop clientSecret and set
+    # privateKey (a PEM PKCS#8 key, or { pem, kid, alg }) instead.
+    clientSecret = ${?FEDERATIONS_OIDC_CLIENT_SECRET}
+    callbackURL = "http://localhost:3000/session/oauth/federation/oidc/callback"
+    callbackURL = ${?FEDERATIONS_OIDC_CALLBACK_URL}
+    scopes = ["openid", "profile", "email"]
+
+    # Same rules as the Google block above: exact URLs, https except on a
+    # loopback host, and an empty list refuses every `redirect_to`.
+    redirectAllowlist = []
+    # sessionDomain, authCallbackUrl and clientUrl work as for Google.
+    #
+    # Hand-typed endpoints instead of discovery (the IdP's document is wrong
+    # or unreachable from this network):
+    #   discovery = false
+    #   endpoints { authorizationEndpoint = "...", tokenEndpoint = "...", jwksUri = "..." }
+  }
 }
 
 repositories {
@@ -257,6 +330,14 @@ repositories {
       # service name still needs https. Boot fails if either is not.
       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.
+      # 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}
       # Positive integer, milliseconds, <= 2147483647. Boot fails otherwise —
       # including on a blank env override, which HOCON substitutes as "".
       timeout = 5000
@@ -287,6 +368,13 @@ endpoints {
     url = "/login"
     url = ${?ENDPOINTS_LOGIN_URL}
   }
+  # #527: the consent page a client that is not first-party is routed
+  # through (`?challenge=<id>`). Deployment-owned, like the login page: it
+  # reads GET /oauth/consent and posts to POST /oauth/consent.
+  consent {
+    url = "/consent"
+    url = ${?ENDPOINTS_CONSENT_URL}
+  }
   # IH-10: `client { url }` and `authCallback { url }` removed — no
   # production consumer reads them.
 }

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

@@ -4,6 +4,9 @@
 # `tokenEndpointAuthMethod` is REQUIRED (RFC 6749 §2.3 / RFC 7591 §2):
 #   - "client_secret_basic": HTTP Basic Authorization header — recommended for confidential clients
 #   - "client_secret_post":  form-encoded body parameters
+#   - "private_key_jwt":     the client signs a JWT with its own private key
+#                            (RFC 7523 §2.2, #484) — register its public keys as
+#                            `jwks` (inline) or `jwksUri`, exactly one; no clientSecret
 #   - "none":                public client — no clientSecret; PKCE/S256 mandatory at /authorize
 #
 # Secret format (only for confidential clients — basic / post):
@@ -44,6 +47,25 @@
 #   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.
 
+# A machine client that authenticates with a key pair (#484). Nothing here is
+# secret: the private half stays with the client, which signs an assertion
+# (iss = sub = client id, aud = the issuer or the token endpoint, exp within
+# an hour, a fresh jti) per token request. Rotating the key is a JWKS
+# publish when `jwksUri` is used. Needs the replay seen-set wired
+# (REPLAY_SEEN_SET_ADAPTER, on by default).
+#
+# orders-service:
+#   tokenEndpointAuthMethod: "private_key_jwt"
+#   jwksUri: "https://orders.example.com/.well-known/jwks.json"
+#   # or inline:
+#   # jwks:
+#   #   keys:
+#   #     - { kty: "EC", crv: "P-256", kid: "2026-09", x: "...", y: "..." }
+#   allowedGrantTypes: ["client_credentials"]
+#   allowedScopes: ["orders:read"]
+#   defaultScopes: ["orders:read"]
+#   allowedAudiences: ["https://api.example.com/orders"]
+
 my-app:
   tokenEndpointAuthMethod: "client_secret_basic"
   firstParty: true

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.12.1",
+	"version": "0.14.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -23,6 +23,7 @@
 	"dependencies": {
 		"@o3co/auth-provider-core": "workspace:*",
 		"@o3co/auth-provider-federation-google": "workspace:*",
+		"@o3co/auth-provider-federation-oidc": "workspace:*",
 		"@o3co/auth-provider-foundation": "workspace:*",
 		"@o3co/auth-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
@@ -40,11 +41,11 @@
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
-		"@types/node": "^26.2.0",
+		"@types/node": "^26.5.1",
 		"@types/supertest": "^7.2.1",
 		"supertest": "^7.1.0",
-		"tsx": "^4.23.10",
+		"tsx": "^4.23.13",
 		"typescript": "^6.0.3",
-		"vitest": "^4.1.11"
+		"vitest": "^5.0.0"
 	}
 }

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

@@ -0,0 +1,101 @@
+/*
+ * 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.
+ */
+
+/**
+ * `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.
+ *
+ * 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.
+ */
+
+import { fileURLToPath } from "node:url";
+import { type AppConfig, AppConfigSchema } 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";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+const REQUIRED_ENV = {
+	OAUTH_JWT_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",
+};
+
+/** The shipped layers, resolved the way `app.mts` resolves them. */
+function loadShipped(env: Record<string, string> = {}): AppConfig {
+	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,
+	);
+}
+
+/** 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"));
+}
+
+describe("the deprecated access-token lifetime alias", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("says nothing for a deployment that sets no lifetime at all", () => {
+		// Also what keeps the template's idea of "the shipped value" honest: it
+		// is measured against core's real `reference.conf`, so a change to the
+		// shipped literal fails here rather than warning every deployment.
+		expect(aliasWarnings(loadShipped())).toEqual([]);
+	});
+
+	it("says nothing for a deployment on the new variable", () => {
+		expect(aliasWarnings(loadShipped({ OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN: "900" }))).toEqual(
+			[],
+		);
+	});
+
+	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 for a hand-built configuration that overrides only the old key", () => {
+		const config = loadShipped();
+		expect(
+			aliasWarnings({
+				...config,
+				oauth: { ...config.oauth, accessToken: { expiresIn: 900 } },
+			}),
+		).toHaveLength(1);
+	});
+});