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

package/README.ja.md

@@ -1,6 +1,6 @@
 # @o3co/create-auth-provider
 
-最終更新: 2026-10-03
+最終更新: 2026-10-06
 
 auth.provider 用の CLI スキャフォルダーです。内包するテンプレートの 1 つから新しいサーバープロジェクトを生成します。
 
@@ -86,6 +86,8 @@ SMTP リレー）を設定するか、`MFA_MODE=off` で MFA を無効にする
 `mfaMode = ${?MFA_MODE}` をこの順に追記するので、後のテンプレートがデフォルトを
 変えてもプロジェクトは off のままで、`MFA_MODE` を設定すれば作り直さずに MFA を
 有効にできます。MFA パッケージは依存に残り、ほかには何も削除・変更しません。
+プロジェクトに含まれるテスト（`pnpm run test`）はスイッチをプロジェクトの設定から
+読み、その値が意味する動作を確かめるので、`--no-mfa` の有無にかかわらず通ります。
 
 生成されるプロジェクトは pnpm のプロジェクトです。`Dockerfile` は
 `pnpm install --frozen-lockfile` でインストールし、ビルドの許可リストは

package/README.md

@@ -1,6 +1,6 @@
 # @o3co/create-auth-provider
 
-Last updated: 2026-10-03
+Last updated: 2026-10-06
 
 CLI scaffolder for auth.provider. Generates a new server project from one of the built-in templates.
 
@@ -85,7 +85,10 @@ switch installs and needs is in the template's README.
 it appends `mfaMode = "off"` and then `mfaMode = ${?MFA_MODE}` to
 `config/application.conf`, so the project stays off whatever default a later
 template ships, and `MFA_MODE` still turns MFA on without re-scaffolding. The
-MFA package stays a dependency; nothing else is removed or changed.
+MFA package stays a dependency; nothing else is removed or changed. The
+project's own suite (`pnpm run test`) reads the switch from the project's
+configuration and asserts what it implies, so it passes with or without
+`--no-mfa`.
 
 The generated project is a pnpm project: its `Dockerfile` installs with
 `pnpm install --frozen-lockfile`, and its build allowlist lives in

package/package.json

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

package/templates/standalone/.env.example

@@ -78,6 +78,10 @@ SESSION_STORE_STORAGE_REDIS_URL=redis://redis:6379
 # defaults to redis://localhost:6379, which inside the container is the
 # container, so leaving it unset makes the compose boot dial nothing.
 REDIS_CLIENTS_URL=redis://redis:6379
+# The Redis stores refuse to boot unless the server reports maxmemory-policy
+# noeviction (README: Multi-replica deployments). Only for a server that does
+# run noeviction but will not report it (INFO and CONFIG refused to this user):
+# REDIS_CLIENTS_ASSUME_NO_EVICTION=true
 
 # --- Federation grants (#593, optional) --------------------------------------
 # Offline delegation of an upstream IdP's tokens to a backend or an agent, on a
@@ -126,8 +130,9 @@ REDIS_CLIENTS_URL=redis://redis:6379
 # Or run without MFA:
 # MFA_MODE=off
 # To read the mail in development, leave every STANDARD_SMTP_MAIL_SENDER_*
-# unset (USER and PASSWORD included) and run the Mailpit
-# overlay, which sets them (README: Mailpit for the SMTP sender):
+# unset (USER and PASSWORD included), set MFA_ENCRYPTION_KEY to a key of your
+# own (the run does not use the development sample key), and run the Mailpit
+# overlay, which sets the sender's variables (README: Mailpit for the SMTP sender):
 #   docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 
 # Development (override for local HTTP).

package/templates/standalone/README.ja.md

@@ -58,6 +58,8 @@ 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-*` のサーバーを通すことはない。
+
 **ロードバランサ配下では `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` がそのヘッダーを設定するホップだけを信頼しているか確認すること。
 
 取りうる形は 4 つで、いずれも Express 自身のものである:
@@ -77,7 +79,7 @@ allowlist はネットワーク上の制御であって、暗号学的な制御
 
 **MFA ルートの予算はリミッターのものである。** MFA パッケージは自身のルートの予算を持たない: `/session/mfa` への POST はすべて、配線されたリミッターだけによって、クライアントアドレスごとにプレフィックス `mfa` の下で制限される。`config/reference.conf` は両方のリミッターに `limits.mfa { limit = 60, windowSeconds = 300 }`（`core-rate-limiter-memory.limits.mfa`、`redis-rate-limiter.limits.mfa`）を与えるので、`adapters.rateLimiter` を切り替えてもこの予算は保たれる。そこでは既定値なので、構成が配線しないリミッターがこれを持っていても、boot はそのセクションの名前を出さない。変えるなら、配線したリミッターについて `config/application.conf` か自分のレイヤーで変えること。エントリがなければリミッターの `defaultLimit`（60 秒あたり 60）が適用される。MFA のロック — トランザクションごとの試行回数、バックオフ、週ごとの失敗回数 — は MFA パッケージ自身のもので、リミッターの設定はこれを変えない。
 
-**`adapters.attemptCounter` を Redis に向けること。** デフォルトは `"memory"` でカウンターを配線しない: ログイン（device grant を加えたときはデバイス検証も）は試行をプロセスごとに数えるので、N レプリカでは `session.rateLimit.login`（と `device-grant.rateLimit`）が上限の N 倍を許し、デプロイのたびにリセットされる。`CORE_DEPLOYMENT_MODE=multi` は起動を拒否する。`"redis"`（`ADAPTERS_ATTEMPT_COUNTER=redis`）は共有の Redis ソケットの上に `redisAttemptCounterModule` を入れる。その Redis は `maxmemory-policy noeviction`（Redis のデフォルト）で動かすこと: 追い出された窓は数え直しになるからである。モジュールは読み取れたほかのポリシーでは起動を拒否するが、サーバーが答えない（`INFO` と `CONFIG` が拒否・改名されている）ときは `attempt_counter_durability_unchecked` を警告して起動するので、ポリシーはサーバーの設定側で確かめること。どちらも閉じる側に倒れる: カウンターが答えられない間、`/session/login` と `POST /oauth/device/verification` は `redis-rate-limiter.failMode` が何であっても `503` を返す。
+**`adapters.attemptCounter` を Redis に向けること。** デフォルトは `"memory"` でカウンターを配線しない: ログイン（device grant を加えたときはデバイス検証も）は試行をプロセスごとに数えるので、N レプリカでは `session.rateLimit.login`（と `device-grant.rateLimit`）が上限の N 倍を許し、デプロイのたびにリセットされる。`CORE_DEPLOYMENT_MODE=multi` は起動を拒否する。`"redis"`（`ADAPTERS_ATTEMPT_COUNTER=redis`）は共有の Redis ソケットの上に `redisAttemptCounterModule` を入れる。その Redis は `maxmemory-policy noeviction`（Redis のデフォルト）で動かすこと: 追い出された窓は数え直しになるからである。モジュールはほかのポリシーでは起動を拒否する。サーバーがポリシーを答えないときも、`REDIS_CLIENTS_ASSUME_NO_EVICTION=true`（上記）でない限り拒否する。どちらも閉じる側に倒れる: カウンターが答えられない間、`/session/login` と `POST /oauth/device/verification` は `redis-rate-limiter.failMode` が何であっても `503` を返す。
 
 **BFF の背後では、必要になる前に `limits.token` を上げておくこと。** OAuth エンドポイントの rate limit は `req.ip` をキーにする（`packages/core/src/ratelimit/guard.mts` はバケットキーを `<endpoint>:ip:<req.ip>` として組み立てる）。クライアントがブラウザやネイティブアプリで、このプロバイダーと直接通信しているなら、これは正しい identity である。しかし backend-for-frontend 構成 — サーバー側アプリがセッションを保持し、ユーザーに代わってコード交換と refresh を行う構成 — では誤った identity になる: すべての `/oauth/token` と `/oauth/introspect` の呼び出しが BFF の単一アドレスから届き、デプロイ全体で 1 つのバケットを共有する。デフォルトの 60 秒あたり 60 リクエストでは、**全ユーザー合計で毎分およそ 60 回の session グラント交換**が上限になる — しかもそれは rate limit として表に出てこない。BFF は想定していない `429` を受け取り、それを自分の呼び出し元への `502` に変え、ユーザーが報告する症状は「サインインがときどき壊れる」になる。それは起き始めるトラフィック量に達した時点で現れ、それより前には現れない。
 
@@ -100,7 +102,7 @@ redis-rate-limiter {
 
 **2 つ以上のレプリカを動かすようになったら `CORE_DEPLOYMENT_MODE=multi` を設定すること。** すると、共有が必要な in-memory ストアがまだ配線されていれば起動が*失敗*し、該当するものすべてと、それぞれの代償が名指しされる — ユーザーセッションの分岐（back-channel logout が 1 つのレプリカにしか届かず、ログアウトしたセッションが他のレプリカでは有効なまま）、rate limit カウンターの倍増、アクセストークン失効の未伝播、一度きりのクライアントアサーションや WebAuthn チャレンジがレプリカごとに 1 回ずつ再利用できてしまうこと。このチェックはライブラリのモジュール名のリストではなく、インストールされた各モジュールが自身の manifest に持つ宣言を読むため、このテンプレート独自の in-memory モジュール — ユーザーセッションストア（`ADAPTERS_USER_SESSION_STORES=memory`）、認可コードリポジトリ（`ADAPTERS_CODE_REPOSITORY=memory`）、フェデレーショントークンストア（`ADAPTERS_FEDERATION_TOKEN_STORE=memory`、デフォルト） — も名指しで拒否される。`SESSION_STORE_STORAGE_TYPE=memory` のときの express-session 自身のストア（#474）と、デフォルトの memory の rate limiter（`core-rate-limiter-memory`、`ADAPTERS_RATE_LIMITER=memory`）も同様である。モードが未設定なら何も拒否されない: これらはすべて、起動時の 1 件の `replica_unsafe_adapters` 警告に列挙される。（WebAuthn-options のルートは個別に警告するプロセス単位のフォールバック limiter を持つが、それが働くのは `rateLimiter` をまったく配線しない構成だけで、このテンプレートは常に配線する。ログインは `ADAPTERS_ATTEMPT_COUNTER=memory` のときプロセスごとに数える: `multi` ではログインを名指しして起動が拒否され、モード未設定なら `attempt_counter_not_shared` を警告する。オペレーター runbook を参照。）`CORE_DEPLOYMENT_MODE=single` ではチェックは何も言わない。レプリカは 1 つだと宣言したからである。このテンプレートは DPoP をインストールしない。DPoP を加えた構成では、受け入れた DPoP proof はすべて `private_key_jwt` と同じ replay seen-set（`ADAPTERS_REPLAY_SEEN_SET`）に記録されるため、同じ扱いを受ける — `memory` は `CORE_DEPLOYMENT_MODE=multi` のもとで拒否され、モード未設定なら警告に列挙される。同梱の `redis` なら DPoP の記録もレプリカ間で共有される。dpop パッケージの [operator requirements](../../packages/dpop/README.md#operator-requirements) を参照。
 
-この変数は `core.deployment.mode` を設定する。旧名の `DEPLOYMENT_MODE` は、単独で、または `CORE_DEPLOYMENT_MODE` と異なる値で設定されているとブートを拒否し、同じ値で並べて設定されていればブートする。
+この変数は `core.deployment.mode` を設定する。旧名の `DEPLOYMENT_MODE` は、設定されていれば、単独でも `CORE_DEPLOYMENT_MODE` と並べても、値が何であれブートを拒否する。外すこと。
 
 このチェックに*できない*ことも把握しておくこと: `CORE_DEPLOYMENT_MODE` を一度も設定しないまま N レプリカにスケールしても、何も失敗しない。すべての状態を自分のメモリに持つプロセスには、他のピアに気づくための共有媒体が無い — その状態は、まさにそれが真であるときに内側からは検出できない。この変数はスケールの一環として設定し、何かが壊れてからにしないこと。
 
@@ -236,7 +238,7 @@ overlay の値は `application.conf` より優先される。scaffold には `de
 | `ADAPTERS_USER_REPOSITORY` | `http` | `adapters.userRepository`: `http`、`yaml` または `static`（core の `yaml` の別名）。[ユーザーリポジトリ](#ユーザーリポジトリ) を参照 |
 | `ADAPTERS_AUDIT_SINK` | `logger` | `adapters.auditSink`: セキュリティイベントの送り先、`logger`（stdout への pino エンベロープ付き NDJSON）または `console`（イベントの JSON そのまま）。`none` は存在しない。[監査ログ](#監査ログ) を参照 |
 
-移動する前の場所 — `rateLimiter.adapter`、`oauth.code.adapter`、`audit.sink.type`、`repositories.user.type` など — にまだ書かれた選択や、それとともに改名された変数（`RATE_LIMITER_ADAPTER`、`CLIENT_TYPE` など）が単独で、または別の値で設定されていると、新しいパスと変数を名指しして boot の前に失敗する。古い変数が新しい変数と同じ値で並んでいるなら受け入れる。
+移動する前の場所 — `rateLimiter.adapter`、`oauth.code.adapter`、`audit.sink.type`、`repositories.user.type` など — にまだ書かれた選択や、それとともに改名された変数（`RATE_LIMITER_ADAPTER`、`CLIENT_TYPE` など）が設定されていれば、単独でも新しい変数と並べても、値が何であれ、新しいパスと変数を名指しして boot の前に失敗する。古い変数は外すこと。
 
 ### HTTP
 
@@ -301,7 +303,7 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 
 `expires_in` リクエストパラメータを読むのは token exchange（RFC 8693）だけで、他のグラントはそれを無視してデフォルトを発行する。
 
-デフォルトの旧名 `OAUTH_ACCESS_TOKEN_EXPIRES_IN`（config キーでは `oauth.accessToken.expiresIn`）は、単独で、または `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` と異なる値で設定されているとブートを拒否し、同じ値で並べて設定されていればブートする。旧キーは値が何であれブートを拒否する。値は消さずに新しい名前へ移すこと: 消すとデフォルトは `3600` になる。
+デフォルトの旧名 `OAUTH_ACCESS_TOKEN_EXPIRES_IN`（config キーでは `oauth.accessToken.expiresIn`）は、設定されていれば、単独でも `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` と並べても、値が何であれブートを拒否する。旧キーは値が何であれブートを拒否する。値は消さずに新しい名前へ移すこと: 消すとデフォルトは `3600` になる。
 
 ### グラントタイプ
 
@@ -313,7 +315,7 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 | `OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED` | `false` | client credentials グラントタイプを有効化 |
 | `OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED` | `false` | jwt-bearer グラントタイプ（RFC 7523）を有効化 |
 
-スイッチはそれぞれモジュールのキー — `oauth-session.enabled`、ほかは `oauth-authorization.grants.<grant>.enabled` — である。どちらのモジュールも常に読み込まれ、自分のスイッチを boot がパースする設定から boot で読む。テンプレートはそのどれも boot の前には読まない。旧名の `OAUTH_GRANTS_<GRANT>_ENABLED` は、単独で、または新名と違う値で設定されていると boot を拒否し、同じ値なら boot する。
+スイッチはそれぞれモジュールのキー — `oauth-session.enabled`、ほかは `oauth-authorization.grants.<grant>.enabled` — である。どちらのモジュールも常に読み込まれ、自分のスイッチを boot がパースする設定から boot で読む。テンプレートはそのどれも boot の前には読まない。旧名の `OAUTH_GRANTS_<GRANT>_ENABLED` は、設定されていれば、単独でも新名と並べても、値が何であれ boot を拒否する。
 
 ### Session
 
@@ -330,7 +332,7 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 | `SESSION_STORE_STORAGE_REDIS_URL` | `redis://localhost:6379` | セッションストア用 Redis 接続 URL |
 | `SESSION_STORE_STORAGE_REDIS_PASSWORD` | — | セッションストア用 Redis パスワード |
 
-cookie とそのストアはセッションストアのセクション `session-store` のもので、CSRF トークンの寿命、ログインページ、ログインの予算は session モジュールのセクション `session` のもの。`SESSION_STORE_*` の旧名 `SESSION_<KEY>` は、単独で、または新名と違う値で設定されていると boot を拒否し、同じ値なら boot する。
+cookie とそのストアはセッションストアのセクション `session-store` のもので、CSRF トークンの寿命、ログインページ、ログインの予算は session モジュールのセクション `session` のもの。`SESSION_STORE_*` の旧名 `SESSION_<KEY>` は、設定されていれば、単独でも新名と並べても、値が何であれ boot を拒否する。
 
 ローカルの HTTP 開発のために `SESSION_STORE_SECURE=false` を設定する場合や、ドメインを共有する Cookie のために `SESSION_STORE_DOMAIN` を設定する場合は、`SESSION_STORE_NAME` も `auth.sid` のような `__Host-` でない値にすること — `SESSION_STORE_SECURE=false` なら接頭辞の無い値にする: `__Secure-` の名前も `SESSION_STORE_SECURE=true` を要する。`__Host-` や `__Secure-`（大文字小文字は問わない）の Cookie 名が、ブラウザがその prefix に対して拒否する属性と組み合わされると、`SESSION_STORE_NAME` が Cookie の名前（RFC 6265 のトークン: 空白、`;` などの区切り文字を含まない）でないと、また `SESSION_STORE_DOMAIN` がホスト名でない（スキーム、ポート、パスを含む）と、サーバーは fail-fast する。
 
@@ -379,7 +381,7 @@ http.cors {
 
 ### Google フェデレーション
 
-フェデレーションは core のものである: `core.federations`、各フェデレーションに到達する名前（`/session/oauth/federation/<name>`）をキーとする 1 つのマップ。各キーは、そのパスから名付けた変数 `CORE_FEDERATIONS_<NAME>_<KEY>` に束縛される。トップレベルに書いたマップ（`federations { ... }`）は、各キーの `core.federations` の下のパスを名指しして起動を拒否する。`FEDERATIONS_GOOGLE_*` や `FEDERATIONS_OIDC_*` の変数が単独で、または新しい名前と異なる値で設定されていると、どのモジュールを選ぶよりも前に拒否される。
+フェデレーションは core のものである: `core.federations`、各フェデレーションに到達する名前（`/session/oauth/federation/<name>`）をキーとする 1 つのマップ。各キーは、そのパスから名付けた変数 `CORE_FEDERATIONS_<NAME>_<KEY>` に束縛される。トップレベルに書いたマップ（`federations { ... }`）は、各キーの `core.federations` の下のパスを名指しして起動を拒否する。`FEDERATIONS_GOOGLE_*` や `FEDERATIONS_OIDC_*` の変数が設定されていれば、単独でも新しい名前と並べても、値が何であれ、どのモジュールを選ぶよりも前に拒否される。
 
 すべてのエントリは自分の `type` を書き、boot は有効化された各エントリを、その type を扱うモジュールにエントリの名前で渡す。テンプレートは同梱する 2 つの type — `google`（`@o3co/auth-provider-federation-google`）と `oidc`（`@o3co/auth-provider-federation-oidc`）— を、マップの内容にかかわらず常に読み込み、エントリを自分では読まない: エントリが持つキーは core と type のスキーマが読み、不正なものはそのパス（`core.federations.<name>.<key>`）を名指しして拒否される。`type` の無いエントリは、有効かどうかにかかわらず `core.federations.<name>.type` で拒否される（`config-validation-failed`）。読み込んだどのモジュールも扱わない type の有効なエントリは、そのエントリを名指しして起動を拒否する（`federation-type-unhandled`）。GitHub と Apple は同梱しない: 使いたいデプロイは、そのパッケージとモジュールを `buildModules` に加える — GitHub は type モジュール `githubFederationTypeModule()` と `type = "github"` のエントリで、Apple はその [README](../../packages/federation-apple/README.md) に従う。
 
@@ -479,7 +481,7 @@ core.federations {
 | `REDIS_CODE_REPOSITORY_KEY_PREFIX` | `oauth:code:` | `redis-code-repository.keyPrefix`: Redis のリポジトリのキー名前空間（[Redis の名前空間](#redis-の名前空間) を参照） |
 | `STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN` | `600` | `standalone-in-memory-code-repository.defaultExpiresIn`: in-process のリポジトリのもの。正の整数（秒） |
 
-`CLIENT_CODE_DEFAULT_EXPIRES_IN` と `CLIENT_CODE_KEY_PREFIX` はこれらとともに改名され、`CLIENT_CODE_ENDPOINT_URI` と `CLIENT_CODE_PASSWORD` は削除された。改名されたものが単独で、または新しい名前と異なる値で設定されていると、そして削除されたものが設定されていると、代わりに設定すべきものを名指しして起動に失敗する。
+`CLIENT_CODE_DEFAULT_EXPIRES_IN` と `CLIENT_CODE_KEY_PREFIX` はこれらとともに改名され、`CLIENT_CODE_ENDPOINT_URI` と `CLIENT_CODE_PASSWORD` は削除された。改名されたものが、単独でも新しい名前と並べても、値が何であれ設定されていると、そして削除されたものが設定されていると、代わりに設定すべきものを名指しして起動に失敗する。
 
 ### フェデレーショントークンストア
 
@@ -510,7 +512,7 @@ core.federations {
 | 変数 | デフォルト | 説明 |
 |---|---|---|
 | `MFA_MODE` | `required` | `mfaMode`: `required`、`optional` または `off` |
-| `MFA_ENCRYPTION_KEY` | — | MFA の鍵リングの最初の鍵で、すべての要素のデータを封じる: 32 バイトの canonical な base64（`openssl rand -base64 32`）。MFA が有効なら必須。`CONFIG_ENV=development` では `config/development.conf` が代わりに MFA パッケージの公開サンプル鍵を置く: 自分の鍵はそこに書く。そのリングの横でこの変数を設定すると boot は拒否される。サンプル鍵は `CONFIG_ENV` か `NODE_ENV` が `production` か `staging` のとき、また `CORE_DEPLOYMENT_MODE=multi` のもとでは拒否される |
+| `MFA_ENCRYPTION_KEY` | — | MFA の鍵リングの最初の鍵で、すべての要素のデータを封じる: 32 バイトの canonical な base64（`openssl rand -base64 32`）。MFA が有効なら必須。`CONFIG_ENV=development` では `config/development.conf` が代わりに MFA パッケージの公開サンプル鍵を置く: 自分の鍵はそこに書く。そのリングの横でこの変数を設定すると boot は拒否される。サンプル鍵が受け入れられるのは、`CONFIG_ENV` と `NODE_ENV` のうち設定されているものがすべて `development` か `test` を示すときだけで、`CORE_DEPLOYMENT_MODE=multi` のもとでは拒否される |
 | `MFA_PAGE_URL` | `/mfa` | デプロイの MFA ページ。ログインの第二要素とステップアップはここから始まる。テンプレートはページを同梱しない: ページの契約は [MFA パッケージのもの](../../packages/mfa/README.md#the-routes) |
 | `MFA_STORE_TIMEOUT_MS` | `5000` | `mfa.storeTimeoutMs`、Store の呼び出し 1 回の時間: 各ストアの呼び出しごとのタイムアウト以上でなければならない。Store を呼ぶ構成（`ADAPTERS_USER_REPOSITORY=http`、または要素を Store に置く）で `REPOSITORIES_USER_HTTP_TIMEOUT` を下回ると boot を拒否するので、二つは一緒に上げる。37500 ms を超えても拒否する |
 | `STANDARD_SMTP_MAIL_SENDER_HOST` | — | development 以外での SMTP リレー。MFA はここにアカウントのメールの証明とメール要素のコードを送る。MFA が有効なら、boot にはこれと `STANDARD_SMTP_MAIL_SENDER_FROM` が要る |
@@ -718,11 +720,13 @@ docker run -e HTTP_PORT=8080 -p 8080:8080 my-auth-provider
 docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 ```
 
+最初に実行する前に、自分の鍵を `.env` に `MFA_ENCRYPTION_KEY` として書く（`openssl rand -base64 32`）。この実行は development のサンプル鍵を使わず、鍵が無ければ boot は拒否される。
+
 メールは <http://localhost:8025> で読む。Mailpit はメールを保持し、先へは何も配送しない。素の `docker compose up`（`make dev`）は Mailpit を起動せず、本番用のファイルにも Mailpit は無い。開発専用である: デプロイでは `STANDARD_SMTP_MAIL_SENDER_*` の変数で実際のリレーを指定する（[多要素認証](#多要素認証)）。
 
 オーバーレイが app サービスに設定するもの:
 
-- `CONFIG_ENV=mailpit`。`development` ではテンプレートは各コードをログに出す送信者を入れる（[モジュール合成順序](#モジュール合成順序) のルール 7）。[`config/mailpit.conf`](config/mailpit.conf) は `development.conf` を include するので、それ以外は MFA のサンプル鍵も含めて development の実行と同じである。
+- `CONFIG_ENV=mailpit`。`development` ではテンプレートは各コードをログに出す送信者を入れる（[モジュール合成順序](#モジュール合成順序) のルール 7）。[`config/mailpit.conf`](config/mailpit.conf) は `development.conf` を include しない。`development.conf` の唯一の設定は MFA のサンプル鍵で、MFA パッケージがそれを受け入れるのは、設定されている環境名がすべて `development` か `test` を示すときだけだからである。鍵リングの最初の鍵は、MFA パッケージの `reference.conf` が束ねるとおり `MFA_ENCRYPTION_KEY` である。
 - `MFA_MODE` は設定しない: MFA はテンプレートの出荷どおり、または `.env` が設定するとおりに有効である。MFA が off ならメールを送るものが無い。
 - `ADAPTERS_MFA_FACTOR_STORE=redis` と `ADAPTERS_MFA_TRANSACTION_STORE=redis`（compose の Redis 上、`docker-compose.yml` と同じ）: `development` と `test` 以外の名前では、MFA のストアをメモリに置けない。
 - `STANDARD_SMTP_MAIL_SENDER_HOST=localhost`、`STANDARD_SMTP_MAIL_SENDER_PORT=1025`、`STANDARD_SMTP_MAIL_SENDER_SECURE=none`、`STANDARD_SMTP_MAIL_SENDER_FROM=auth@example.com`。SMTP 送信者が平文で送るのはループバックのホストにだけなので、Mailpit は app コンテナのネットワーク名前空間で動き（`network_mode: service:app`）、その `localhost` で待ち受ける。そのため Mailpit の Web UI のポートは、Mailpit ではなく app サービスがループバックに公開する。

package/templates/standalone/README.md

@@ -112,6 +112,8 @@ 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.
+
 **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.
 
 It takes four shapes, all of them Express's own:
@@ -131,7 +133,7 @@ An allowlist is a network control, not a cryptographic one. The edge must also *
 
 **The MFA routes' budget is the limiter's.** The MFA package ships no budget for its routes: every `/session/mfa` POST is limited per client address under the prefix `mfa` by the wired limiter alone. `config/reference.conf` gives both limiters `limits.mfa { limit = 60, windowSeconds = 300 }` (`core-rate-limiter-memory.limits.mfa`, `redis-rate-limiter.limits.mfa`), so switching `adapters.rateLimiter` keeps it. It is a default there, so the limiter the composition does not wire carries it without boot naming its section; change it for the wired limiter in `config/application.conf` or a layer of your own. Without an entry the limiter's `defaultLimit`, 60 per 60 s, applies. The MFA lock — attempts per transaction, the backoff, the weekly failures — is the MFA package's own and no limiter setting changes it.
 
-**Point `adapters.attemptCounter` at Redis.** It defaults to `"memory"`, which wires no counter: the login — and device verification, when you add the device grant — counts its attempts per process, so with N replicas `session.rateLimit.login` (and `device-grant.rateLimit`) allows N times its limit and resets on every deploy, and `CORE_DEPLOYMENT_MODE=multi` refuses the boot. `"redis"` (`ADAPTERS_ATTEMPT_COUNTER=redis`) installs `redisAttemptCounterModule` on the shared Redis socket. Its Redis must run `maxmemory-policy noeviction` (Redis's default): an evicted window would start the count over. The module refuses to boot on any other policy it reads; when the server will not tell it (`INFO` and `CONFIG` refused or renamed) it boots and warns `attempt_counter_durability_unchecked`, so confirm the policy where the server is configured. Both fail closed: while the counter cannot answer, `/session/login` and `POST /oauth/device/verification` answer `503`, whatever `redis-rate-limiter.failMode` says.
+**Point `adapters.attemptCounter` at Redis.** It defaults to `"memory"`, which wires no counter: the login — and device verification, when you add the device grant — counts its attempts per process, so with N replicas `session.rateLimit.login` (and `device-grant.rateLimit`) allows N times its limit and resets on every deploy, and `CORE_DEPLOYMENT_MODE=multi` refuses the boot. `"redis"` (`ADAPTERS_ATTEMPT_COUNTER=redis`) installs `redisAttemptCounterModule` on the shared Redis socket. Its Redis must run `maxmemory-policy noeviction` (Redis's default): an evicted window would start the count over. The module refuses to boot on any other policy. It also refuses on a policy the server will not report, unless `REDIS_CLIENTS_ASSUME_NO_EVICTION=true` (above). Both fail closed: while the counter cannot answer, `/session/login` and `POST /oauth/device/verification` answer `503`, whatever `redis-rate-limiter.failMode` says.
 
 **Behind a BFF, raise `limits.token` before you need to.** The OAuth-endpoint
 rate limits key on `req.ip` (`packages/core/src/ratelimit/guard.mts` builds the
@@ -179,7 +181,7 @@ where per-user identity still exists.
 
 **Set `CORE_DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, a single-use client assertion or WebAuthn challenge replayable once per replica. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`ADAPTERS_USER_SESSION_STORES=memory`), the authorization-code repository (`ADAPTERS_CODE_REPOSITORY=memory`) and the federation token store (`ADAPTERS_FEDERATION_TOKEN_STORE=memory`, the default) — are refused by name too. So are express-session's own store under `SESSION_STORE_STORAGE_TYPE=memory` (#474) and the default memory rate limiter (`core-rate-limiter-memory`, `ADAPTERS_RATE_LIMITER=memory`). With the mode unset nothing is refused: every one of them is listed in a single `replica_unsafe_adapters` warning at boot. (The WebAuthn-options route carries a per-process fallback limiter that warns on its own, but only in a composition that wires no `rateLimiter` at all, which this template never does. The login counts per process under `ADAPTERS_ATTEMPT_COUNTER=memory`: `multi` refuses the boot, naming the login, and an unset mode warns `attempt_counter_not_shared`; see the operator runbook.) With `CORE_DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica. This template does not install DPoP; a composition that adds it records every accepted proof in the same replay seen-set as `private_key_jwt` (`ADAPTERS_REPLAY_SEEN_SET`), so it gets the same answer — `memory` is refused under `CORE_DEPLOYMENT_MODE=multi` and listed in the unset-mode warning, and the shipped `redis` shares DPoP's records across replicas — see the dpop package's [operator requirements](../../packages/dpop/README.md#operator-requirements).
 
-The variable sets `core.deployment.mode`. `DEPLOYMENT_MODE`, its old name, refuses boot set alone or beside `CORE_DEPLOYMENT_MODE` at a different value; beside it at the same value, it boots.
+The variable sets `core.deployment.mode`. `DEPLOYMENT_MODE`, its old name, refuses boot while it is set, alone or beside `CORE_DEPLOYMENT_MODE` at any value: unset it.
 
 Be aware of what this check *cannot* do: if you scale to N replicas without ever setting `CORE_DEPLOYMENT_MODE`, nothing fails. A process holding all its state in its own memory has no shared medium through which to notice peers — the condition is undetectable from inside exactly when it is true. Set the variable as part of scaling, not after something breaks.
 
@@ -410,9 +412,8 @@ fails before boot, naming it.
 A selection still written where it was — `rateLimiter.adapter`,
 `oauth.code.adapter`, `audit.sink.type`, `repositories.user.type` and the
 like — or a variable renamed with it (`RATE_LIMITER_ADAPTER`, `CLIENT_TYPE`,
-…) set alone or to a different value, fails before boot, naming the new path
-and variable; the old variable beside the new one at the same value is
-accepted.
+…) set, alone or beside the new one at any value, fails before boot, naming
+the new path and variable: unset the old variable.
 
 ### HTTP
 
@@ -491,9 +492,8 @@ Only token exchange (RFC 8693) reads an `expires_in` request parameter; every
 other grant ignores it and mints the default.
 
 The default's old name, `OAUTH_ACCESS_TOKEN_EXPIRES_IN` (config key
-`oauth.accessToken.expiresIn`), refuses boot set alone or beside
-`OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` at a different value; beside it at the
-same value, it boots. The old key refuses boot at any value. Move the value to
+`oauth.accessToken.expiresIn`), refuses boot while it is set, alone or beside
+`OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` at any value. The old key refuses boot at any value. Move the value to
 the new name rather than deleting it: without it, the default is `3600`.
 
 ### Grant Types
@@ -510,8 +510,8 @@ Each switch is its module's key — `oauth-session.enabled`, and
 `oauth-authorization.grants.<grant>.enabled` for the others. Both modules are
 always loaded and read their switches at boot, from the configuration boot
 parses; the template reads none of them before boot. `OAUTH_GRANTS_<GRANT>_ENABLED`,
-the old names, refuse boot set alone or beside the new name at a different
-value; beside it at the same value, they boot.
+the old names, refuse boot while they are set, alone or beside the new name at
+any value.
 
 ### Session
 
@@ -531,8 +531,8 @@ value; beside it at the same value, they boot.
 The cookie and its store are the session store's section, `session-store`; the
 CSRF token's lifetime, the login page and the login's budget are the session
 module's, `session`. `SESSION_<KEY>`, the old names of the `SESSION_STORE_*`
-variables, refuse boot set alone or beside the new name at a different value;
-beside it at the same value, they boot.
+variables, refuse boot while they are set, alone or beside the new name at any
+value.
 
 If you set `SESSION_STORE_SECURE=false` for local HTTP development or set `SESSION_STORE_DOMAIN`
 for shared-domain cookies, also set `SESSION_STORE_NAME` to a non-`__Host-` value such as
@@ -637,8 +637,8 @@ each is reached at (`/session/oauth/federation/<name>`). A key of one is bound
 to the variable named after its path, `CORE_FEDERATIONS_<NAME>_<KEY>`. The map
 written at the top level (`federations { ... }`) refuses boot, naming each
 key's path under `core.federations`; a `FEDERATIONS_GOOGLE_*` or
-`FEDERATIONS_OIDC_*` variable set alone, or beside its new name at a different
-value, is refused before any module is chosen.
+`FEDERATIONS_OIDC_*` variable set, alone or beside its new name at any value,
+is refused before any module is chosen.
 
 Every entry names its `type`, and boot hands each enabled entry to the module
 that handles that type, under the entry's name. The template always loads the
@@ -806,8 +806,8 @@ its own.
 
 `CLIENT_CODE_DEFAULT_EXPIRES_IN` and `CLIENT_CODE_KEY_PREFIX` were renamed
 with them, and `CLIENT_CODE_ENDPOINT_URI` and `CLIENT_CODE_PASSWORD` removed. A
-renamed one set alone, or beside its new name at a different value, and a
-removed one set at all, fails boot naming what to set instead.
+renamed one set, alone or beside its new name at any value, and a removed one
+set at all, fails boot naming what to set instead.
 
 ### Federation Token Store
 
@@ -874,7 +874,7 @@ in development too, or every password login stops there.
 | Variable | Default | Description |
 |---|---|---|
 | `MFA_MODE` | `required` | `mfaMode`: `required`, `optional` or `off` |
-| `MFA_ENCRYPTION_KEY` | — | The MFA key ring's first key, which seals every factor's data: canonical base64 of 32 bytes (`openssl rand -base64 32`). Required with MFA on. Under `CONFIG_ENV=development`, `config/development.conf` puts the MFA package's published sample key in its place: write your own key there instead, since this variable set beside that ring refuses the boot. The sample key is refused under `CONFIG_ENV` or `NODE_ENV` `production` or `staging` and under `CORE_DEPLOYMENT_MODE=multi` |
+| `MFA_ENCRYPTION_KEY` | — | The MFA key ring's first key, which seals every factor's data: canonical base64 of 32 bytes (`openssl rand -base64 32`). Required with MFA on. Under `CONFIG_ENV=development`, `config/development.conf` puts the MFA package's published sample key in its place: write your own key there instead, since this variable set beside that ring refuses the boot. The sample key is accepted only where `CONFIG_ENV` and `NODE_ENV`, each where set, say `development` or `test`, and is refused under `CORE_DEPLOYMENT_MODE=multi` |
 | `MFA_PAGE_URL` | `/mfa` | The deployment's MFA page, where a login's second factor and a step-up start. The template ships no page: the page contract is the [MFA package's](../../packages/mfa/README.md#the-routes) |
 | `MFA_STORE_TIMEOUT_MS` | `5000` | `mfa.storeTimeoutMs`, one Store call's time: at least every store's own per-call timeout. Below `REPOSITORIES_USER_HTTP_TIMEOUT` where the Store is called (`ADAPTERS_USER_REPOSITORY=http`, or the factors in the Store) the boot is refused, so raise the two together; above 37500 ms it is refused too |
 | `STANDARD_SMTP_MAIL_SENDER_HOST` | — | The SMTP relay outside development, where MFA mails the account-email proof and the email factor's codes. With MFA on, the boot needs it and `STANDARD_SMTP_MAIL_SENDER_FROM` |
@@ -1214,6 +1214,10 @@ development sender, which only logs each code:
 docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 ```
 
+Before the first run, write a key of your own into `.env` as
+`MFA_ENCRYPTION_KEY` (`openssl rand -base64 32`): this run does not use the
+development sample key, and without a key the boot is refused.
+
 Read the mail at <http://localhost:8025>. Mailpit keeps it and delivers
 nothing onward. A plain `docker compose up` (`make dev`) starts no Mailpit, and
 the production file names none. It is for development only: a deployment
@@ -1224,9 +1228,11 @@ What the overlay sets on the app service:
 
 - `CONFIG_ENV=mailpit`. Under `development` the template installs the sender
   that logs each code ([Module Composition Order](#module-composition-order),
-  rule 7). [`config/mailpit.conf`](config/mailpit.conf) includes
-  `development.conf`, so the run is otherwise the development one, the MFA
-  sample key included.
+  rule 7). [`config/mailpit.conf`](config/mailpit.conf) does not include
+  `development.conf`, whose one setting is the MFA sample key: the MFA
+  package accepts that key only where every environment name set says
+  `development` or `test`. The key ring's first key is `MFA_ENCRYPTION_KEY`,
+  as the MFA package's `reference.conf` binds it.
 - Nothing of `MFA_MODE`: MFA is on as the template ships it, or as your
   `.env` sets it. With MFA off nothing sends mail.
 - `ADAPTERS_MFA_FACTOR_STORE=redis` and `ADAPTERS_MFA_TRANSACTION_STORE=redis`,

package/templates/standalone/config/application.conf

@@ -347,4 +347,5 @@ http {
 redis-clients {
   url = ${?REDIS_CLIENTS_URL}
   password = ${?REDIS_CLIENTS_PASSWORD}
+  assumeNoEviction = ${?REDIS_CLIENTS_ASSUME_NO_EVICTION}
 }

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

@@ -50,6 +50,14 @@
 #   verifier itself as the challenge and so proves nothing against anyone who
 #   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.
+#
+# `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.
 
 # 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

package/templates/standalone/config/development.conf

@@ -10,8 +10,8 @@
 # The MFA key ring's development key: the MFA package's published sample key
 # (MFA_DEVELOPMENT_SAMPLE_KEY), which everyone holds. It stands in for
 # MFA_ENCRYPTION_KEY here: to use a key of your own in development, write it
-# in place of this one. It is refused where the configuration is selected as
-# production or staging, where NODE_ENV is either, and under
+# in place of this one. It is accepted only where the configuration's name and
+# NODE_ENV, each where set, say development or test, and is refused under
 # `core.deployment.mode = "multi"`; boot warns while it is in use
 # (mfa_development_sample_key_in_use). Read only while MFA_MODE installs MFA.
 mfa.encryptionKeys = [{ key = "bzNjbzptZmE6ZGV2ZWxvcG1lbnQtc2FtcGxlLWtleSE=" }]

package/templates/standalone/config/mailpit.conf

@@ -1,8 +1,13 @@
 # Environment overlay for a development run whose mail goes to Mailpit
 # (docker-compose.mailpit.yml). Loaded when CONFIG_ENV is "mailpit".
 #
-# The development overlay under another name: the template installs the
-# sender that logs each code only where the configuration is selected as
-# "development", and the SMTP sender under any other name. For development
-# only; a deployment names its own relay.
-include "development.conf"
+# The template installs the sender that logs each code only where the
+# configuration is selected as "development", and the SMTP sender under any
+# other name. For development only; a deployment names its own relay.
+#
+# It does not include development.conf, whose one setting is the MFA
+# development sample key: the MFA package accepts that key only where every
+# environment name set says development or test, and this run is selected as
+# "mailpit". The key ring's first key is MFA_ENCRYPTION_KEY, as the MFA
+# package's reference.conf binds it: write a key of your own
+# (openssl rand -base64 32) into .env; without one the boot is refused.

package/templates/standalone/config/reference.conf

@@ -130,11 +130,17 @@ key-store {
 
 # `redis-clients`: the one ioredis socket per replica every Redis-backed store
 # shares. More than one replica needs a shared Redis 7.2+ here; localhost
-# inside a container is the container itself.
+# inside a container is the container itself. The Redis stores that keep
+# durable keys refuse to boot unless the server reports maxmemory-policy
+# `noeviction`. `assumeNoEviction = true` asserts it for a server that will not
+# report it (INFO and CONFIG refused to the connection's user); a policy the
+# server does report always decides.
 redis-clients {
   url = "redis://localhost:6379"
   url = ${?REDIS_CLIENTS_URL}
   password = ${?REDIS_CLIENTS_PASSWORD}
+  assumeNoEviction = false
+  assumeNoEviction = ${?REDIS_CLIENTS_ASSUME_NO_EVICTION}
 }
 
 # `repositories`: the client registry, and the user repository's settings for
@@ -319,8 +325,8 @@ redis-rate-limiter.limits.mfa { limit = 60, windowSeconds = 300 }
 # (`rateLimiter.adapter`, `oauth.code.adapter`, ...) are refused before the
 # modules are chosen, and so are the variables renamed with them. What the
 # resolution saw of each variable they renamed: each name null, then its value
-# when set. Boot refuses an old name set unless its new name is set to the
-# same value, and removes this section before it parses the configuration.
+# when set. Boot refuses an old name set, whether or not its new name is set,
+# and removes this section before it parses the configuration.
 # Never write it in another layer.
 renamed-variables {
   LOG_LEVEL = null

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

@@ -4,6 +4,9 @@
 #
 #   docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 #
+# Write MFA_ENCRYPTION_KEY into .env first (openssl rand -base64 32): this run
+# reads its MFA key from it, not the development sample key.
+#
 # Mailpit keeps every mail the provider sends and delivers none; read them at
 # http://localhost:8025. Never use it in production, where
 # STANDARD_SMTP_MAIL_SENDER_* name a real relay. Leave every

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.17.0-rc.2",
+	"version": "0.17.0-rc.3",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {

package/templates/standalone/src/__tests__/adapters.test.mts

@@ -211,7 +211,9 @@ describe("a path a selection moved from, written in the operator's own layer", (
 		"adapters.%s: refused where it was, %s's old path, naming the new path and ADAPTERS_%s",
 		(key, name, oldPath, _oldName, value) => {
 			const err = refusal({}, `${oldPath} = "${value}"\n`);
-			expect(err.message).toContain(`${oldPath} has moved to adapters.${key}`);
+			expect(err.message).toContain(
+				`${oldPath} has moved to adapters.${key}; see the upgrade guide (docs/upgrading-from-v0.16.0.md).`,
+			);
 			expect(err.message).toContain(`ADAPTERS_${name}`);
 			expect(err.reason).toBe("config-path-relocated");
 			expect(err.details).toEqual({
@@ -251,8 +253,9 @@ describe("a variable renamed with a selection", () => {
 		"adapters.%s: %s's old variable set alone is refused, naming ADAPTERS_%s",
 		(key, name, _oldPath, oldName, value) => {
 			const err = refusal({ [oldName]: value });
-			expect(err.message).toContain(`${oldName} was renamed ADAPTERS_${name}`);
-			expect(err.message).toContain(`adapters.${key}`);
+			expect(err.message).toContain(
+				`${oldName} was renamed ADAPTERS_${name}, the variable adapters.${key} is bound to; see the upgrade guide (docs/upgrading-from-v0.16.0.md).`,
+			);
 			expect(err.reason).toBe("environment-variable-renamed");
 			expect(err.details).toEqual({
 				reason: "environment-variable-renamed",
@@ -282,9 +285,12 @@ describe("a variable renamed with a selection", () => {
 	);
 
 	it.each(SELECTIONS)(
-		"adapters.%s: the old variable beside ADAPTERS_%s at the same value is read",
-		(key, name, _oldPath, oldName, value) => {
-			expect(adaptersFrom({ [oldName]: value, [`ADAPTERS_${name}`]: value })[key]).toBe(value);
+		"adapters.%s: the old variable beside ADAPTERS_%s at the same value is refused all the same",
+		(_key, name, _oldPath, oldName, value) => {
+			const err = refusal({ [oldName]: value, [`ADAPTERS_${name}`]: value });
+			expect(err.reason).toBe("environment-variable-renamed");
+			expect(err.message).toContain(`unset ${oldName}`);
+			expect(err.details).toMatchObject({ renamed: [{ from: oldName, state: "different" }] });
 		},
 	);
 });

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

@@ -78,6 +78,10 @@ vi.mock("ioredis", () => {
 		quit: async () => "OK",
 		disconnect: () => undefined,
 		ping: async () => "PONG",
+		// The Redis stores' eviction gate reads the policy from INFO memory: a
+		// default server's.
+		info: async (section: string) =>
+			section === "memory" ? "# Memory\r\nmaxmemory_policy:noeviction\r\n" : null,
 	};
 	const makeMockRedis = (): object =>
 		new Proxy(
@@ -182,12 +186,16 @@ describe('every module on, every shared store on Redis, core.deployment.mode = "
 		expect(current.handle.components.deploymentMode).toBe("multi");
 	});
 
-	it("boots as multi on DEPLOYMENT_MODE=multi beside CORE_DEPLOYMENT_MODE=multi, as the umbrella sets them", async () => {
-		current = await compose({
-			...MULTI,
-			env: { ...MULTI_ENV, DEPLOYMENT_MODE: "multi", CORE_DEPLOYMENT_MODE: "multi" },
+	it("refuses DEPLOYMENT_MODE=multi beside CORE_DEPLOYMENT_MODE=multi: the old name must be unset", async () => {
+		await expect(
+			compose({
+				...MULTI,
+				env: { ...MULTI_ENV, DEPLOYMENT_MODE: "multi", CORE_DEPLOYMENT_MODE: "multi" },
+			}),
+		).rejects.toMatchObject({
+			reason: "environment-variable-renamed",
+			details: { renamed: [{ from: "DEPLOYMENT_MODE", state: "different" }] },
 		});
-		expect(current.handle.components.deploymentMode).toBe("multi");
 	});
 
 	/**

package/templates/standalone/src/__tests__/config-notices.test.mts

@@ -149,6 +149,9 @@ describe("configDefaultsFor", () => {
 
 	it("takes nothing from the process's environment", () => {
 		vi.stubEnv("REDIS_CLIENTS_URL", "redis://operator.test:6379");
-		expect(configDefaultsFor(modules)[NOT_LOADED]).toEqual({ url: "redis://localhost:6379" });
+		expect(configDefaultsFor(modules)[NOT_LOADED]).toEqual({
+			url: "redis://localhost:6379",
+			assumeNoEviction: false,
+		});
 	});
 });

package/templates/standalone/src/__tests__/configured-mfa-mode.fixture.mts

@@ -0,0 +1,48 @@
+/*
+ * 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 MFA switch, `mfaMode`, as this project's own configuration files write
+ * it with `MFA_MODE` unset: `{environment}.conf` over `application.conf` over
+ * the template's `config/reference.conf`. The template ships it `required`;
+ * a project `create-auth-provider --no-mfa` scaffolds writes it `off` at the
+ * end of its `application.conf`. A suite whose subject depends on the switch
+ * asserts what MFA on (`required`, as the template ships it) or off (as
+ * `--no-mfa` writes it) implies, so the suite that ships with a scaffold holds
+ * in either project. A project whose files write another mode, such as
+ * `optional`, is not what these suites claim to cover.
+ *
+ * Read with the HOCON parser alone, not through phase one (`readSwitches`),
+ * so that a suite about phase one can state what phase one should answer.
+ */
+
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type Config, empty, parseFile } from "@o3co/ts.hocon";
+import { type MfaSwitch, mfaSwitchSchema } from "#/sections.mjs";
+
+const configDir = fileURLToPath(new URL("../../config", import.meta.url));
+
+/** `mfaMode` as the files selected by `environment` write it, with no variable set. */
+export function configuredMfaMode(environment: string): MfaSwitch {
+	const resolved = [`${environment}.conf`, "application.conf", "reference.conf"]
+		.reduce<Config>(
+			(layered, file) => layered.withFallback(parseFile(join(configDir, file), { env: {} })),
+			empty(),
+		)
+		.toObject() as Record<string, unknown>;
+	return mfaSwitchSchema.parse(resolved.mfaMode);
+}