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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.17.0-rc.3",
+  "version": "0.17.0",
   "description": "Scaffold a new o3co/auth.provider project from one of its templates",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,9 +29,9 @@
   },
   "devDependencies": {
     "@o3co/ts.hocon": "^1.13.0",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.4",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.3"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/README.ja.md

@@ -1,6 +1,6 @@
 # @o3co/auth-provider-standalone
 
-最終更新: 2026-10-06
+最終更新: 2026-10-07
 
 auth.provider のデプロイ可能なサーバーテンプレート。これは composition root であり、設定を読み込み、モジュールをロードし、Express サーバーを起動する。`@o3co/create-auth-provider` で生成される。
 
@@ -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`）。ローテーションした鍵がキャッシュする検証者に間に合って届くよう、鍵の重複期間より十分短く保つこと。 |
 
@@ -465,6 +464,8 @@ core.federations {
 | `REPOSITORIES_USER_HTTP_TIMEOUT` | `5000` | HTTP リクエストタイムアウト（ミリ秒）。`2147483647` 以下の正の整数 |
 | `REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES` | `1048576` | 上流レスポンスボディの受け入れ上限（バイト） |
 
+**`yaml` のユーザーファイル**はユーザー名をキーとし、各エントリは `password` と、任意で `id`（無ければユーザー名）とクレームを持つ。パスワードは平文か bcrypt ハッシュ: `$2` で始まるものはハッシュとして読み、コスト 04 から 15 の整った `$2a$`・`$2b$`・`$2y$` ハッシュ（`$2y$` は `$2b$` として比較する）でなければならない（比較 1 回は、コスト 15 で約 2 秒、10 で約 60 ms、Node の libuv スレッドプールの 1 スレッドを使う）。`$2b$` と `$2y$` はパスワードの先頭 72 バイト（UTF-8 の日本語で約 24 文字）しか比較しない。`$2a$` は 254 バイトまでのパスワードでは同じ 72 バイトを読むが、それより長いものは長さを 256 で割った余りとして数えるため、255 バイト以上のパスワードは別のパスワードとして比較されることがある。新しいエントリには `$2b$` を使う。平文のエントリは全長で比較する。bcrypt エントリはすべて一つのコストを使う。これらの規則に反するパスワード、複数のコストにまたがる bcrypt エントリ（コストを名指しする）、空の `id` やユーザー名、同じ id を持つ二人のユーザー、エントリ内の `username` キーは、フィールドと、ユーザーかコストを名指しし、値は出さずに起動時に拒否される。`yaml` バックエンドで起動するたびに、環境を問わず `user_repository_in_memory` をテンプレートのロガーに warn で記録する（`LOGGING_LEVEL` が効く）: ユーザーファイルは開発とテスト用である。[core パッケージの README](../../packages/core/README.ja.md#yaml-からクライアントとユーザーを読み込む) を参照。
+
 ユーザー認証 URL は 2 つとも上流ストアへ**平文のユーザー資格情報**を運ぶため、いずれも絶対 `https://` URL でなければならない。`http://` は loopback ホスト（`localhost`、`127.0.0.0/8` 内のアドレス、`[::1]`）に限って許可され、ローカル開発で証明書を用意せずに済むようにしている。プライベートレンジのアドレス（`http://10.0.0.5/…`）やコンテナネットワークのサービス名（`http://user-service/…`）には依然として `https://` が必要 — これらはデプロイが端から端まで制御していないネットワークを越えるため。URL のどちらか、タイムアウト、レスポンス上限のいずれかが使えない値なら、最初のログイン時ではなく起動時に失敗する。
 
 各 URL には、リダイレクトするエンドポイントではなく応答するエンドポイントを設定する: どのリクエストも `3xx` を追わないので、リダイレクトする URL ではすべての呼び出しが失敗する — [Store が自分で守るべきこと](../../packages/foundation/README.ja.md#store-が自分で守るべきこと) を参照。

package/templates/standalone/README.md

@@ -1,6 +1,6 @@
 # @o3co/auth-provider-standalone
 
-Last updated: 2026-10-06
+Last updated: 2026-10-07
 
 Deployable server template for auth.provider. This is the composition root — it reads config, loads modules, and starts the Express server. Generated by `@o3co/create-auth-provider`.
 
@@ -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. |
 
@@ -751,6 +750,26 @@ and the production compose file mounts it (see [Docker](#docker)).
 | `REPOSITORIES_USER_HTTP_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
 | `REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
 
+**The `yaml` users file** is keyed by username; each entry holds `password`,
+and optionally `id` (the username when absent) and claims. A password is plain
+text, or a bcrypt hash: anything starting with `$2` is read as one, and must be
+a well-formed `$2a$`, `$2b$` or `$2y$` hash (the last compared as `$2b$`) at a
+cost from 04 to 15 (a compare at 15 takes about 2 s, at 10 about 60 ms, on a
+thread of Node's libuv pool). `$2b$` and `$2y$` compare only the first 72
+bytes of a password (about 24 Japanese characters in UTF-8). `$2a$` reads the
+same 72 bytes of a password up to 254 bytes long, but counts a longer one's
+length modulo 256, so a password of 255 bytes or more can compare as a
+different one; use `$2b$` for new entries. A plain-text entry is compared over
+its full length.
+Every bcrypt entry uses one cost. Boot refuses a password that breaks these
+rules, bcrypt entries at more than one cost (naming the costs), an empty `id`
+or username, two users with the same id, and a `username` key inside an entry,
+naming the field and the user or the costs, never a value. Each start with the `yaml` backend logs
+`user_repository_in_memory` at warn on the template's logger (`LOGGING_LEVEL`
+applies), whatever the environment: the users file is meant for development
+and tests. See
+[the core package's README](../../packages/core/README.md#loading-clients-and-users-from-yaml).
+
 Both user-authentication URLs carry **plaintext user credentials** to the
 upstream store, so both must be absolute `https://` URLs. `http://` is accepted
 only for a loopback host — `localhost`, an address in `127.0.0.0/8`, or `[::1]`

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.3",
+	"version": "0.17.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
@@ -37,19 +37,20 @@
 		"express-session": "^1.19.0",
 		"helmet": "^8.3.0",
 		"ioredis": "^6.0.0",
-		"pino": "^10.3.1",
+		"pino": "^10.4.0",
 		"prom-client": "^15.1.3",
-		"redis": "^6.2.1",
+		"redis": "^6.3.0",
 		"zod": "^4.6.5"
 	},
 	"devDependencies": {
+		"@o3co/auth-provider-test-kit": "workspace:*",
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
-		"@types/node": "^26.6.3",
+		"@types/node": "^26.6.4",
 		"@types/supertest": "^7.2.1",
-		"supertest": "^7.3.0",
+		"supertest": "^7.3.1",
 		"tsx": "^4.23.15",
 		"typescript": "^6.0.3",
-		"vitest": "^5.0.2"
+		"vitest": "^5.0.3"
 	}
 }

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",
@@ -139,7 +138,6 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	OAUTH_SESSION_ENABLED: "false",
 	OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED: "true",
 	OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED: "true",
-	OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY: "reject",
 	OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED: "true",
 	OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED: "false",
 
@@ -316,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:
@@ -341,7 +341,9 @@ const DELIBERATELY_UNSET: Readonly<Record<string, string>> = {
 	OAUTH_GRANTS_REFRESH_TOKEN_ENABLED:
 		"renamed OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED, and only captured — set at any value, beside its new name or not, it fails boot",
 	OAUTH_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY:
-		"renamed OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY, and only captured — set at any value, beside its new name or not, it fails boot",
+		"the variable of a removed key, and only captured — any value fails boot",
+	OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_UNKNOWN_FAMILY_POLICY:
+		"the variable of a removed key, and only captured — any value fails boot",
 	OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED:
 		"renamed OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED, and only captured — set at any value, beside its new name or not, it fails boot",
 	OAUTH_GRANTS_JWT_BEARER_ENABLED:
@@ -766,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);
@@ -1105,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 () => {
@@ -1184,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 ?? {}),
 			});
 		},
 	},