@o3co/create-auth-provider 0.17.0-rc.4 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.17.0-rc.4",
+  "version": "0.17.0",
   "description": "Scaffold a new o3co/auth.provider project from one of its templates",
   "license": "Apache-2.0",
   "type": "module",

package/templates/standalone/README.ja.md

@@ -58,7 +58,7 @@ my-app:
 
 ロードバランサ配下で standalone サーバーを複数インスタンス動かすときは、`REDIS_CLIENTS_URL` を**共有**の Redis 7.2+ インスタンスに向けること。共有の Redis URL が無いと、各レプリカは refresh token family を自分の接続（と、ローカル専用の Redis）に保持するため、トークンを発行していないレプリカに届いた refresh リクエストは `invalid_grant` を返し、ラウンドロビンの LB では 1 回おきにそうなる。
 
-**その Redis は `maxmemory-policy noeviction`（Redis のデフォルト）で動かすこと。** 期限まで残らなければならないキーを持つ Redis のストア — attempt counter、ユーザーセッションストアのライフサイクルストア、フェデレーショントークンストア、MFA のストア — は起動時にポリシーを読む（`INFO memory`、次に `CONFIG GET maxmemory-policy`）。ほかのポリシーでは起動を拒否し、サーバーがポリシーを答えないときも拒否する。接続のユーザーが `INFO` や `CONFIG` を実行できない（ACL で制限されたユーザー、それらを改名するマネージドサービス）が、サーバーが `noeviction` で動いていると分かっているなら、`REDIS_CLIENTS_ASSUME_NO_EVICTION=true`（`redis-clients.assumeNoEviction`、デフォルト `false`）を設定すること。これはポリシーを読めないときにだけ読まれる: サーバーが答えたポリシーが常に優先するので、`allkeys-*` や `volatile-*` のサーバーを通すことはない。
+**その Redis は `maxmemory-policy noeviction`（Redis のデフォルト）で動かすこと。** 期限まで残らなければならないキーを持つ Redis のストア — attempt counter、ユーザーセッションストアのライフサイクルストア、フェデレーショントークンストア、MFA のストア、失効の状態を持つストア（アクセストークン denylist、subject revocation ストア、refresh token family ストア）、そして replay seen-set — は起動時にポリシーを読む（`INFO memory`、次に `CONFIG GET maxmemory-policy`）。ほかのポリシーでは起動を拒否し、サーバーがポリシーを答えないときも拒否する。接続のユーザーが `INFO` や `CONFIG` を実行できない（ACL で制限されたユーザー、それらを改名するマネージドサービス）が、サーバーが `noeviction` で動いていると分かっているなら、`REDIS_CLIENTS_ASSUME_NO_EVICTION=true`（`redis-clients.assumeNoEviction`、デフォルト `false`）を設定すること。これはポリシーを読めないときにだけ読まれる: サーバーが答えたポリシーが常に優先するので、`allkeys-*` や `volatile-*` のサーバーを通すことはない。これらのストアは構築時にサーバーに問い合わせ、refresh token family ストアは常に、アクセストークン denylist と replay seen-set はデフォルトで Redis 上にあるため、Redis がまだ起動していない、または到達できないと起動は失敗する — ほかの `adapters` の選択がすべて memory でも同じである: provider より先に Redis を起動すること。
 
 **ロードバランサ配下では `HTTP_TRUST_PROXY` をプロキシのアドレスに設定すること。** デフォルトは `false` で、この場合 `req.ip` はクライアントではなく*ロードバランサの*アドレスになる。すると IP をキーとするすべての rate limit — OAuth エンドポイントの limiter と `POST /session/login` の総当たり対策ガード — が**全ユーザーで 1 つのバケットを共有する**: 誰からであれ最初の 20 回のログイン試行でウィンドウを使い切り、以降のユーザーは全員 `429` を受け取る。この障害は設定ミスではなく攻撃のように見えるため、深夜 3 時の診断が高くつく。このサービスの前段で何かが TLS を終端したりプロキシしたりしているなら必ず設定し、`X-Forwarded-For` を設定しているのがそのホップであることを確認すること。`ip` のない監査イベントは、リクエストのアドレスがアドレスでなかった — `req.ip` がアドレス以外を入れた `X-Forwarded-For` から来た — ことを意味するので、`HTTP_TRUST_PROXY` がそのヘッダーを設定するホップだけを信頼しているか確認すること。
 
@@ -268,7 +268,7 @@ overlay の値は `application.conf` より優先される。scaffold には `de
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_TIMEOUT_MS` | `5000` | 取得のタイムアウト。 |
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_CACHE_MAX_AGE_MS` | `600000` | 有効なドキュメントをキャッシュから返す期間の上限。`Cache-Control: max-age` によって短くなることがある。 |
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_CACHE_ENTRIES` | `256` | 同時に記憶しておくドキュメントの数。キーは未認証の呼び出し元が選ぶため、マップには上限を設けている。 |
-| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_STALE_IF_ERROR_MS` | `300000` | 検証済みの登録情報を、ドキュメント側に原因の無い理由（DNS の一時的な不調、5xx、タイムアウト）で再検証が失敗した後も返し続ける期間 — 障害で、動いているクライアントを壊すべきではないため。*拒否*されたドキュメントは即座に破棄される。`0` で無効化する。 |
+| `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_STALE_IF_ERROR_MS` | `0` | 検証済みの登録情報を、ドキュメント側に原因の無い理由（DNS の一時的な不調、5xx、429、タイムアウト）で再検証が失敗した後も、期限を過ぎてから返し続ける期間。既定の `0` では返さない — 期限切れのドキュメントの再検証が失敗すると、取得が再び成功するまで、かつ失敗から少なくとも `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_NEGATIVE_CACHE_MS` の間そのクライアントは解決されない（`invalid_client`）。猶予を設定すると、ホストの障害の間も動いているクライアントを止めず、その間は最後に検証したリダイレクト許可リストを有効として扱う。*拒否*されたドキュメントは即座に破棄される。 |
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_NEGATIVE_CACHE_MS` | `60000` | 拒否を記憶しておく期間。同じ `client_id` をリクエストのたびに解決・取得し直さないためである。ドキュメントを修正したクライアントが締め出されないよう、短くしてある。 |
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_MAX_CONCURRENT_FETCHES` | `8` | すべての `client_id` を通じて、同時に取得中にできるドキュメントの数。未認証の呼び出し元がこのサーバーに接続させられる量を制限する。 |
 | `KEY_STORE_LOCAL_KID` | `v0` | JWT ヘッダーに含まれる key ID。制御文字を含まない 1〜256 文字。それ以外は起動時に拒否される — export されているが空の変数も含む（以前は kid `""` で署名されていた。そうして発行されたトークンは修正後に拒否されるため、そのユーザーは再ログインになる） |
@@ -276,7 +276,6 @@ overlay の値は `application.conf` より優先される。scaffold には `de
 | `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` | — | PEM 秘密鍵ファイルのパス |
 | `KEY_STORE_LOCAL_PUBLIC_KEY` | — | PEM エンコードされた公開鍵 |
 | `KEY_STORE_LOCAL_PUBLIC_KEY_PATH` | — | PEM 公開鍵ファイルのパス |
-| `OAUTH_JWT_LEGACY_TYP_ACCEPT` | `false` | `typ` ヘッダーの無いトークンを受け付ける。`false` ではそれらを拒否し、typ の無いトークンを、たいていそうであるように設定ミスかダウングレードの試みとして扱う。`true` にするのは、v0.4.x のトークンがまだ流通している間の、期限を区切った移行期間に限ること。 |
 | `JWKS_PATH` | `/.well-known/jwks.json` | issuer の下で検証鍵を公開するパスで、discovery が `jwks_uri` として広告するもの（`jwks.path`）。`//`、ドットセグメント、クエリ、フラグメント、バックスラッシュ、パーセントエンコーディング、制御文字を含まない絶対パス。 |
 | `JWKS_CACHE_MAX_AGE` | `300` | JWKS レスポンスの `Cache-Control: public, max-age`（秒、`jwks.cacheMaxAge`）。ローテーションした鍵がキャッシュする検証者に間に合って届くよう、鍵の重複期間より十分短く保つこと。 |
 

package/templates/standalone/README.md

@@ -112,7 +112,7 @@ The [operator runbook](../../docs/operator-runbook.md) covers the operational si
 
 When running multiple instances of the standalone server behind a load balancer, point `REDIS_CLIENTS_URL` at a **shared** Redis 7.2+ instance. Without a shared Redis URL, every replica holds refresh-token families in its own connection (and any local-only Redis), so a refresh request that lands on a replica that did not issue the token returns `invalid_grant` on every other request in a round-robin LB.
 
-**That Redis must run `maxmemory-policy noeviction`** (Redis's default). The Redis stores whose keys must stay until they expire — the attempt counter, the user-session stores' lifecycle store, the federation token store and the MFA stores — read the policy at boot (`INFO memory`, then `CONFIG GET maxmemory-policy`), and refuse to boot on any other policy or on one the server will not report. If the connection's user may not run `INFO` or `CONFIG` (an ACL-restricted user, or a managed service that renames them) and you know the server runs `noeviction`, set `REDIS_CLIENTS_ASSUME_NO_EVICTION=true` (`redis-clients.assumeNoEviction`, default `false`). It is read only while the policy cannot be read: a policy the server reports always takes precedence, so it never lets an `allkeys-*` or `volatile-*` server through.
+**That Redis must run `maxmemory-policy noeviction`** (Redis's default). The Redis stores whose keys must stay until they expire — the attempt counter, the user-session stores' lifecycle store, the federation token store, the MFA stores, the stores that hold revocation state (the access-token denylist, the subject revocation store and the refresh-token family store) and the replay seen-set — read the policy at boot (`INFO memory`, then `CONFIG GET maxmemory-policy`), and refuse to boot on any other policy or on one the server will not report. If the connection's user may not run `INFO` or `CONFIG` (an ACL-restricted user, or a managed service that renames them) and you know the server runs `noeviction`, set `REDIS_CLIENTS_ASSUME_NO_EVICTION=true` (`redis-clients.assumeNoEviction`, default `false`). It is read only while the policy cannot be read: a policy the server reports always takes precedence, so it never lets an `allkeys-*` or `volatile-*` server through. Since those stores ask the server when they are built, and the refresh-token family store is always on Redis and the access-token denylist and the replay seen-set are by default, a boot with Redis not yet started or unreachable fails — even with every other `adapters` selection on memory: start Redis before the provider.
 
 **Set `HTTP_TRUST_PROXY` to your proxy's address behind a load balancer.** It defaults to `false`, which makes `req.ip` the *load balancer's* address rather than the client's. Every rate limit keyed by IP — the OAuth endpoint limiters and the `POST /session/login` brute-force guard — then shares **one bucket across all users**: the first 20 login attempts from anyone exhaust the window and every subsequent user gets `429`. The failure reads like an attack rather than a misconfiguration, which is what makes it expensive to diagnose at 3am. Set it whenever anything terminates TLS or proxies in front of this service, and make sure that hop is the one setting `X-Forwarded-For`. An audit event with no `ip` means the request's address was not an address — `req.ip` came from an `X-Forwarded-For` that held something else — so check that `HTTP_TRUST_PROXY` trusts only the hop that sets the header.
 
@@ -445,7 +445,7 @@ The signing key is the `key-store` module's section: `key-store.provider`
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_TIMEOUT_MS` | `5000` | Fetch timeout. |
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_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_CLIENT_ID_METADATA_DOCUMENTS_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_CLIENT_ID_METADATA_DOCUMENTS_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_CLIENT_ID_METADATA_DOCUMENTS_STALE_IF_ERROR_MS` | `0` | How long past its expiry 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 429, a timeout). `0`, the default, serves none: an expired document whose revalidation fails leaves the client unresolved (`invalid_client`) until a fetch succeeds again and for at least `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_NEGATIVE_CACHE_MS` after the failure. A window keeps a working client through an outage at its host, and honours the redirect allowlist last validated for that long. A document that was *rejected* is dropped immediately. |
 | `OAUTH_CLIENT_ID_METADATA_DOCUMENTS_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_CLIENT_ID_METADATA_DOCUMENTS_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. |
 | `KEY_STORE_LOCAL_KID` | `v0` | Key ID included in the JWT header. 1 to 256 characters with no control character; anything else fails boot, including a variable exported but empty (which used to sign under the kid `""`; tokens issued that way are refused once it is corrected, so their users sign in again) |
@@ -453,7 +453,6 @@ The signing key is the `key-store` module's section: `key-store.provider`
 | `KEY_STORE_LOCAL_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
 | `KEY_STORE_LOCAL_PUBLIC_KEY` | — | PEM-encoded public key |
 | `KEY_STORE_LOCAL_PUBLIC_KEY_PATH` | — | Path to PEM public key file |
-| `OAUTH_JWT_LEGACY_TYP_ACCEPT` | `false` | Accept tokens whose `typ` header is absent. `false` rejects them, treating a typ-less token as the misconfiguration or downgrade attempt it usually is. Set `true` only for a bounded migration window while v0.4.x tokens are still in circulation. |
 | `JWKS_PATH` | `/.well-known/jwks.json` | Where the verification keys are published under the issuer, and what discovery advertises as `jwks_uri` (`jwks.path`). An absolute path with no `//`, dot-segment, query, fragment, backslash, percent-encoding or control character. |
 | `JWKS_CACHE_MAX_AGE` | `300` | The JWKS response's `Cache-Control: public, max-age`, in seconds (`jwks.cacheMaxAge`). Keep it well below the key-overlap window, so a rotated key reaches caching verifiers in time. |
 

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

@@ -54,17 +54,23 @@
 # `allowExchangeOfTokensIssuedToOthers`: read only where the token-exchange
 #   module (@o3co/auth-provider-oauth-token-exchange) is installed, which this
 #   template does not do by default. Token exchange requires the caller to be
-#   an audience of the subject token by default: the token's `azp` is the
-#   client, or its `aud` contains it. `true` lets this one client exchange
-#   tokens issued to other clients (a gateway, an on-behalf-of service). Only
-#   a strict `true` counts.
+#   an audience of the subject token, and of an actor token, by default: the
+#   token's `azp` is the client, or its `aud` contains it. `true` lets this one
+#   client present subject and actor tokens issued to other clients (a
+#   gateway, an on-behalf-of service). Only a strict `true` counts. The token
+#   it is issued is for one of the subject token's audiences, so such a
+#   client's `allowedAudiences` must list the audiences of the tokens it
+#   exchanges.
 
 # 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).
+# (REPLAY_SEEN_SET_ADAPTER, on by default). A `jwksUri` (or a
+# `backchannelLogoutUri`) served from a loopback, private, link-local or other
+# special-use address (for example 100.64.0.0/10) needs its host in `core.outbound.internalHosts`
+# (CORE_OUTBOUND_INTERNAL_HOSTS); plain http only for a listed loopback host.
 #
 # orders-service:
 #   tokenEndpointAuthMethod: "private_key_jwt"

package/templates/standalone/config/reference.conf

@@ -236,15 +236,18 @@ adapters {
   attemptCounter = ${?ADAPTERS_ATTEMPT_COUNTER}
   # The four user-session stores and the subject-level revocation pair. They
   # must be on Redis whenever express-session's store is, or a restart leaves
-  # every browser a session whose user session is gone.
+  # every browser a session whose user session is gone. `redis` needs a server
+  # whose maxmemory-policy is `noeviction` once the revocation store is read.
   userSessionStores = "memory"
   userSessionStores = ${?ADAPTERS_USER_SESSION_STORES}
   # The RFC 7009 access-token denylist, which POST /oauth/revoke writes and
   # verification reads. On Redis, so a token revoked on one replica is revoked
-  # on every one.
+  # on every one; `redis` needs a server whose maxmemory-policy is
+  # `noeviction`.
   accessTokenDenylist = "redis"
   accessTokenDenylist = ${?ADAPTERS_ACCESS_TOKEN_DENYLIST}
   # The `jti` single-use record behind private_key_jwt client authentication.
+  # `redis` needs a server whose maxmemory-policy is `noeviction`.
   replaySeenSet = "redis"
   replaySeenSet = ${?ADAPTERS_REPLAY_SEEN_SET}
   # Consent to a client that is not first-party: "none" wires no store and

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.17.0-rc.4",
+	"version": "0.17.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -43,6 +43,7 @@
 		"zod": "^4.6.5"
 	},
 	"devDependencies": {
+		"@o3co/auth-provider-test-kit": "workspace:*",
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
 		"@types/node": "^26.6.4",

package/templates/standalone/src/__tests__/all-modules-composition.fixture.mts

@@ -23,8 +23,8 @@
  * `reference.conf`, core's last, under the environment a deployment would
  * export) read in `app.mts`'s two phases (`readSwitches`, then
  * `resolveForBoot` for `createApp`), `buildModules`, core's `createApp`, every
- * module and store it selects, the key store, the audit sink, `helmet` and the
- * terminal error handler.
+ * module and store it selects, the key store, the audit sink, the security
+ * headers (`securityHeaders`) and the terminal error handler.
  *
  * Substituted (the first two are overrides `buildModules` offers):
  * - client and user repositories: in memory, not YAML off disk;
@@ -65,7 +65,6 @@ import { createFakeIdp, type FakeIdp } from "@o3co/auth-provider-core/testing";
 import { googleFederationTypeModule } from "@o3co/auth-provider-federation-google";
 import { oidcFederationTypeModule } from "@o3co/auth-provider-federation-oidc";
 import express from "express";
-import helmet from "helmet";
 import request from "supertest";
 import { beforeAll, describe, expect, it } from "vitest";
 import { buildModules } from "#/buildModules.mjs";
@@ -78,6 +77,7 @@ import {
 	resolveForBoot,
 	type Switches,
 } from "#/configPath.mjs";
+import { securityHeaders } from "#/securityHeaders.mjs";
 
 export const ISSUER = "https://auth.test";
 const OIDC_ISSUER = "https://idp.test";
@@ -657,8 +657,8 @@ export interface Composition {
 }
 
 /**
- * Boots the composition and mounts it as `app.mts` does: `helmet`, the
- * composed router, and the terminal error handler last (unless
+ * Boots the composition and mounts it as `app.mts` does: its security headers
+ * (`securityHeaders`), the composed router, and the terminal error handler last (unless
  * `terminalErrorHandler` is `false`), all on one logger that is also the
  * boot's `logger` component.
  */
@@ -697,11 +697,7 @@ export async function compose(options: ComposeOptions = {}): Promise<Composition
 	if (httpSettings === undefined) throw new Error("createApp booted without httpSettings");
 	const app = express();
 	app.set("trust proxy", httpSettings.trustProxy);
-	app.use(
-		helmet({
-			contentSecurityPolicy: { directives: { defaultSrc: ["'none'"], frameAncestors: ["'none'"] } },
-		}),
-	);
+	app.use(securityHeaders());
 	app.use(handle.router);
 	if (options.terminalErrorHandler !== false) app.use(terminalErrorHandler(logger));
 	return { app, handle, config: parsed, resolved, modules, logger, upstreams: fakes };

package/templates/standalone/src/__tests__/all-modules-composition.test.mts

@@ -122,8 +122,8 @@ const TEMPLATE_PACKAGES: Readonly<Record<string, string>> = {
 };
 
 /**
- * Workspace packages the template does not depend on, so nothing here can
- * boot them. Each but the test kit, which has no module, is a module a
+ * Workspace packages the template does not compose (the test kit is a
+ * devDependency only), so nothing here can boot them. Each but the test kit, which has no module, is a module a
  * deployment adds to this manifest by hand —
  * `modules.mts` provides the Redis clients their stores need for that reason
  * — and `tools/composition` in the monorepo boots each beside every module

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

@@ -48,6 +48,7 @@ import { buildModules } from "../buildModules.mjs";
 import type { Switches } from "../configPath.mjs";
 import { createAppLogger, createAuditLogger, createLoggerAuditSink } from "../logger.mjs";
 import { auditSinkModuleFor } from "../modules.mjs";
+import { keyStoreSectionSchema } from "../sections.mjs";
 import { capturedRenames, shippedAdapters } from "./library-references.fixture.mjs";
 
 const keyPair = generateKeyPairSync("ed25519", {
@@ -115,6 +116,12 @@ const baseConfig: Switches & AppConfig & Record<string, unknown> = {
 	},
 	rateLimit: { failMode: "open" },
 	"standalone-in-memory-code-repository": { defaultExpiresIn: 600 },
+	// The in-process limiter's section as core's `reference.conf` ships it.
+	"core-rate-limiter-memory": {
+		maxBuckets: 10000,
+		defaultLimit: { limit: 60, windowSeconds: 60 },
+		limits: {},
+	},
 };
 
 const CLIENT_ID = "audit-client";
@@ -146,16 +153,18 @@ const testRepositoriesModule = defineModule({
 	},
 });
 
+// The template's `key-store` section, read by its own schema, without the
+// section's relocation bridge.
 const testKeyStoreModule = defineModule({
-	name: "test:key-store",
-	requires: ["config"] as const,
+	name: "key-store",
+	section: { schema: keyStoreSectionSchema },
 	provides: {
-		keyStore: async ({ config: c }) => {
+		keyStore: async ({ section }) => {
 			const factory = createKeyStoreFactory();
 			registerBuiltinKeyStores(factory);
 			return factory.create({
 				type: "local",
-				...((c as { "key-store"?: { local?: object } })["key-store"]?.local ?? {}),
+				...(section.local ?? {}),
 			});
 		},
 	},

package/templates/standalone/src/__tests__/backchannel-peer.fixture.mts

@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+
+/**
+ * A relying party's back-channel logout endpoint on loopback, for the
+ * template's tests: it answers every POST with one status and keeps each
+ * `logout_token` it was sent. The composition reaches it only with its host
+ * in `core.outbound.internalHosts` (`withLoopbackRelyingParties`).
+ */
+
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { AppConfig } from "@o3co/auth-provider-core";
+import { withOutbound } from "@o3co/auth-provider-core/testing";
+
+export interface BackchannelPeer {
+	/** The endpoint, `http://127.0.0.1:<port>/logout`. */
+	readonly uri: string;
+	/** Each `logout_token` posted to it, in order. */
+	readonly tokens: readonly string[];
+	close(): Promise<void>;
+}
+
+/** A loopback back-channel endpoint answering `status` to every POST. */
+export async function backchannelPeer(status = 200): Promise<BackchannelPeer> {
+	const tokens: string[] = [];
+	const server = createServer((req, res) => {
+		let body = "";
+		req.setEncoding("utf8");
+		req.on("data", (chunk: string) => {
+			body += chunk;
+		});
+		req.on("end", () => {
+			const token = new URLSearchParams(body).get("logout_token");
+			if (token !== null) tokens.push(token);
+			res.writeHead(status);
+			res.end();
+		});
+	});
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const { port } = server.address() as AddressInfo;
+	return {
+		uri: `http://127.0.0.1:${port}/logout`,
+		tokens,
+		close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+	};
+}
+
+/** `config` with loopback listed in `core.outbound.internalHosts`, so a `BackchannelPeer` is reachable. */
+export const withLoopbackRelyingParties = (config: AppConfig): AppConfig =>
+	withOutbound(config, { internalHosts: ["127.0.0.1"] }) as AppConfig;

package/templates/standalone/src/__tests__/documented-env-overrides.test.mts

@@ -101,7 +101,6 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	KEY_STORE_LOCAL_PRIVATE_KEY_PATH: "./config/jwt-private.pem",
 	KEY_STORE_LOCAL_PUBLIC_KEY: "-----BEGIN PUBLIC KEY-----\nMCo=\n-----END PUBLIC KEY-----",
 	KEY_STORE_LOCAL_PUBLIC_KEY_PATH: "./config/jwt-public.pem",
-	OAUTH_JWT_LEGACY_TYP_ACCEPT: "true",
 
 	// --- oauth tokens / policy ----------------------------------------
 	OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN: "900",
@@ -315,6 +314,8 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 const DELIBERATELY_UNSET: Readonly<Record<string, string>> = {
 	OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS:
 		"the variable of a removed key, and only captured — any value fails boot",
+	OAUTH_JWT_LEGACY_TYP_ACCEPT:
+		"the variable of a removed key, and only captured — any value fails boot",
 	OAUTH_ACCESS_TOKEN_EXPIRES_IN:
 		"renamed OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN, and only captured — set at any value, beside its new name or not, it fails boot",
 	DEPLOYMENT_MODE:
@@ -767,7 +768,6 @@ describe("the shipped config boots with every documented override supplied as a
 		// Each of these arrives from HOCON as a string. A leftover string is
 		// not a cosmetic defect: `=== true` is how the runtime reads them.
 		expect(sessionStoreSection(config).secure).toBe(false);
-		expect(oauthSection(config).jwt.legacyTypAccept).toBe(true);
 		expect(oauthSection(config).requireEmailVerified).toBe(true);
 		expect(oauthSection(config).resourceIndicator?.enabled).toBe(true);
 		expect(config.core?.federations?.google?.enabled).toBe(true);
@@ -1106,14 +1106,6 @@ describe("the shipped config boots with every documented override supplied as a
 				});
 				expect(sessionStoreSection(config).secure).toBe(expected);
 			});
-
-			it(`OAUTH_JWT_LEGACY_TYP_ACCEPT=${JSON.stringify(supplied)} resolves to ${expected}`, async () => {
-				const config = await bootParsed({
-					...DOCUMENTED_ENV,
-					OAUTH_JWT_LEGACY_TYP_ACCEPT: supplied,
-				});
-				expect(oauthSection(config).jwt.legacyTypAccept).toBe(expected);
-			});
 		}
 
 		it("refuses a spelling it does not recognise rather than guessing", async () => {
@@ -1185,6 +1177,15 @@ describe("the shipped config boots with every documented override supplied as a
 			await expect(booting).rejects.toThrow(/oauth\.authorize\.allowUnmarkedClients/);
 		});
 
+		it("refuses OAUTH_JWT_LEGACY_TYP_ACCEPT as the variable of a removed key, naming oauth.jwt.legacyTypAccept and the upgrade guide", async () => {
+			for (const value of ["true", "false"]) {
+				const booting = bootParsed({ ...DOCUMENTED_ENV, OAUTH_JWT_LEGACY_TYP_ACCEPT: value });
+				await expect(booting).rejects.toMatchObject({ reason: "environment-variable-renamed" });
+				await expect(booting).rejects.toThrow(/oauth\.jwt\.legacyTypAccept/);
+				await expect(booting).rejects.toThrow(/docs\/upgrading-from-v0\.16\.0\.md/);
+			}
+		});
+
 		it("refuses an access-token default above the max, naming both keys", async () => {
 			await expect(
 				bootParsed({

package/templates/standalone/src/__tests__/federation-grants-composition.test.mts

@@ -44,6 +44,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildModules } from "../buildModules.mjs";
 import { resolveConfigPaths } from "../configPath.mjs";
 import { templateReference } from "../modules.mjs";
+import { keyStoreSectionSchema } from "../sections.mjs";
 import { installGracefulShutdown } from "../shutdown.mjs";
 import {
 	type BothPhases,
@@ -187,16 +188,18 @@ const testRepositoriesModule = defineModule({
 	},
 });
 
+// The template's `key-store` section, read by its own schema, without the
+// section's relocation bridge.
 const testKeyStoreModule = defineModule({
-	name: "test:key-store",
-	requires: ["config"] as const,
+	name: "key-store",
+	section: { schema: keyStoreSectionSchema },
 	provides: {
-		keyStore: async ({ config: c }) => {
+		keyStore: async ({ section }) => {
 			const factory = createKeyStoreFactory();
 			registerBuiltinKeyStores(factory);
 			return factory.create({
 				type: "local",
-				...((c as { "key-store"?: { local?: object } })["key-store"]?.local ?? {}),
+				...(section.local ?? {}),
 			});
 		},
 	},

package/templates/standalone/src/__tests__/federation-grants-survive-logout.test.mts

@@ -55,6 +55,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { buildModules } from "../buildModules.mjs";
 import { resolveConfigPaths } from "../configPath.mjs";
 import { templateReference } from "../modules.mjs";
+import { keyStoreSectionSchema } from "../sections.mjs";
 import {
 	type BothPhases,
 	bothPhasesOf,
@@ -201,16 +202,18 @@ const testRepositoriesModule = defineModule({
 	} as never,
 });
 
+// The template's `key-store` section, read by its own schema, without the
+// section's relocation bridge.
 const testKeyStoreModule = defineModule({
-	name: "test:key-store",
-	requires: ["config"] as const,
+	name: "key-store",
+	section: { schema: keyStoreSectionSchema },
 	provides: {
-		keyStore: async ({ config: c }) => {
+		keyStore: async ({ section }) => {
 			const factory = createKeyStoreFactory();
 			registerBuiltinKeyStores(factory);
 			return factory.create({
 				type: "local",
-				...((c as { "key-store"?: { local?: object } })["key-store"]?.local ?? {}),
+				...(section.local ?? {}),
 			});
 		},
 	},

package/templates/standalone/src/__tests__/frontchannel-logout-csp.test.mts

@@ -0,0 +1,168 @@
+/*
+ * 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.
+ */
+
+/**
+ * The front-channel logout page, served through the template behind its
+ * security headers, works under the one policy the response carries: its
+ * relying party's frame and its redirect are allowed, and nothing else is.
+ * Every other answer keeps the template's policy.
+ */
+
+import { createHash } from "node:crypto";
+import request from "supertest";
+import { describe, expect, it } from "vitest";
+import {
+	authorize,
+	basic,
+	codeFrom,
+	compose,
+	login,
+	PKCE,
+} from "./all-modules-composition.fixture.mjs";
+
+const RP = {
+	id: "rp-fc",
+	secret: "rp-fc-secret-long-enough",
+	redirectUri: "https://rp-fc.test/cb",
+	frontchannelLogoutUri: "https://rp-fc.test:8443/frontchannel-logout",
+	postLogoutRedirectUri: "https://rp-fc.test/signed-out",
+} as const;
+
+/** A serialized policy as directive name → sources; a directive named twice fails. */
+const parsePolicy = (policy: string): Map<string, string[]> => {
+	const directives = new Map<string, string[]>();
+	for (const part of policy.split(";")) {
+		const [name, ...sources] = part.trim().split(/\s+/);
+		if (name === undefined || name === "") continue;
+		if (directives.has(name)) throw new Error(`directive ${name} appears twice`);
+		directives.set(name, sources);
+	}
+	return directives;
+};
+
+/** The sources a fetch directive resolves to: its own, else `default-src`'s. */
+const effective = (policy: Map<string, string[]>, directive: string): string[] =>
+	policy.get(directive) ?? policy.get("default-src") ?? [];
+
+const decode = (value: string): string =>
+	value
+		.replace(/&quot;/g, '"')
+		.replace(/&#39;/g, "'")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&amp;/g, "&");
+
+/** How many `Content-Security-Policy` header lines the response carried, as sent. */
+const policyHeaderCount = (response: object): number => {
+	const raw = (response as { res?: { rawHeaders?: unknown } }).res?.rawHeaders;
+	if (!Array.isArray(raw)) throw new Error("the response carries no raw headers");
+	return raw.filter(
+		(name, i) => i % 2 === 0 && String(name).toLowerCase() === "content-security-policy",
+	).length;
+};
+
+describe("the front-channel logout page under the template's security headers", () => {
+	it("is allowed its relying party's frame and its redirect by the one policy it is served with", async () => {
+		const { app, handle } = await compose({
+			extraClients: {
+				[RP.id]: {
+					tokenEndpointAuthMethod: "client_secret_basic",
+					clientSecret: RP.secret,
+					allowedRedirectUris: [RP.redirectUri],
+					allowedScopes: ["openid"],
+					allowedGrantTypes: ["authorization_code"],
+					frontchannelLogoutUri: RP.frontchannelLogoutUri,
+					postLogoutRedirectUris: [RP.postLogoutRedirectUri],
+					firstParty: true,
+				},
+			},
+		});
+		try {
+			// A session the relying party joined by exchanging a code.
+			const { cookies } = await login(app);
+			const exchanged = await request(app)
+				.post("/oauth/token")
+				.set("Authorization", basic(RP))
+				.type("form")
+				.send({
+					grant_type: "authorization_code",
+					code: codeFrom(await authorize(app, cookies, RP)),
+					redirect_uri: RP.redirectUri,
+					code_verifier: PKCE.verifier,
+				});
+			expect(exchanged.status).toBe(200);
+
+			const res = await request(app)
+				.get("/oauth/logout")
+				.set("Accept", "text/html")
+				.set("Cookie", cookies)
+				.query({
+					id_token_hint: exchanged.body.id_token as string,
+					post_logout_redirect_uri: RP.postLogoutRedirectUri,
+					state: "s-1",
+				});
+
+			expect(res.status).toBe(200);
+			expect(res.headers["content-type"]).toBe("text/html; charset=utf-8");
+			expect(policyHeaderCount(res)).toBe(1);
+			const policy = parsePolicy(res.headers["content-security-policy"] as string);
+
+			// The frame: the relying party's, from the one origin the policy allows.
+			const srcs = [...res.text.matchAll(/<iframe src="([^"]*)"/g)].map((m) => decode(m[1] ?? ""));
+			expect(srcs).toHaveLength(1);
+			expect(new URL(srcs[0] ?? "").origin).toBe("https://rp-fc.test:8443");
+			expect(effective(policy, "frame-src")).toEqual(["https://rp-fc.test:8443"]);
+
+			// The redirect: one inline script, allowed by its hash, sending the
+			// browser to the registered URI with the state.
+			const scripts = [
+				...res.text.matchAll(/<script data-target="([^"]*)" data-delay="(\d+)">([^<]*)<\/script>/g),
+			];
+			expect(scripts).toHaveLength(1);
+			expect(res.text.match(/<script/g)).toHaveLength(1);
+			const [, target, , text] = scripts[0] ?? [];
+			expect(decode(target ?? "")).toBe(`${RP.postLogoutRedirectUri}?state=s-1`);
+			const hash = createHash("sha256")
+				.update(text ?? "", "utf8")
+				.digest("base64");
+			expect(effective(policy, "script-src")).toEqual([`'sha256-${hash}'`]);
+
+			// Nothing else.
+			expect(policy.get("default-src")).toEqual(["'none'"]);
+			expect(effective(policy, "style-src")).toEqual(["'none'"]);
+			expect(effective(policy, "connect-src")).toEqual(["'none'"]);
+			expect(policy.get("frame-ancestors")).toEqual(["'none'"]);
+			expect(res.headers["cache-control"]).toBe("no-store");
+		} finally {
+			await handle.dispose();
+		}
+	});
+
+	it("leaves the template's policy on every other answer", async () => {
+		const { app, handle } = await compose();
+		try {
+			const res = await request(app).get("/.well-known/openid-configuration");
+
+			expect(policyHeaderCount(res)).toBe(1);
+			const policy = parsePolicy(res.headers["content-security-policy"] as string);
+			expect(policy.get("default-src")).toEqual(["'none'"]);
+			expect(policy.get("frame-ancestors")).toEqual(["'none'"]);
+			expect(effective(policy, "frame-src")).toEqual(["'none'"]);
+		} finally {
+			await handle.dispose();
+		}
+	});
+});