@o3co/create-auth-provider 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",

package/templates/standalone/.env.example

@@ -63,6 +63,28 @@ SESSION_STORAGE_REDIS_URL=redis://redis:6379
 # container, so leaving it unset makes the compose boot dial nothing.
 REFRESH_TOKEN_FAMILY_STORE_REDIS_URL=redis://redis:6379
 
+# --- Federation grants (#593, optional) --------------------------------------
+# Offline delegation of an upstream IdP's tokens to a backend or an agent, on a
+# consent that survives logout. Off by default; on, boot refuses what is
+# missing by name. The consent page is yours (README: Federation Grants). The
+# connections and the encryption key ring are lists, so they live in a HOCON
+# layer, not here. Both stores ship on Redis; Redis GRANTS need
+# USER_SESSION_STORES_ADAPTER=redis beside them (the compose files set it) —
+# the grants would outlive a memory boundary that ends them.
+# FEDERATION_GRANTS_ENABLED=true
+# FEDERATION_GRANTS_CONSENT_URL=/consent/grants
+# `required` seals credentials under federationGrants.encryptionKeys (HOCON);
+# `allow-plaintext` is refused in production/staging and under multi.
+# FEDERATION_GRANTS_ENCRYPTION_MODE=required
+# `required` needs a user repository that covers every connection's
+# registration: the shipped http one asks your Store at the URL below and
+# covers what repositories.user.http.federatedIdentityLookupCoverage (HOCON)
+# declares; `unsupported` records that the check is not made.
+# FEDERATION_GRANTS_IDENTITY_LOOKUP=required
+# CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL=https://users.example.com/find-subject-by-federated-identity
+# FEDERATION_GRANT_STORE_ADAPTER=redis
+# FEDERATION_GRANT_INTENT_STORE_ADAPTER=redis
+
 # Development (override for local HTTP).
 # The default cookie name carries the `__Host-` prefix, which browsers only
 # accept on a Secure cookie — so dropping Secure means renaming the cookie too,

package/templates/standalone/README.ja.md

@@ -155,6 +155,7 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 | `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | トークン認証用のユーザー認証 URL。**https 必須**（下記参照） |
 | `CLIENT_USER_TIMEOUT` | `5000` | HTTP リクエストタイムアウト（ミリ秒）。`2147483647` 以下の正の整数 |
 | `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | 上流レスポンスボディの受け入れ上限（バイト） |
+| `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` | — | 任意。上流 identity の持ち主を Store に問う URL（#613、フェデレーショングラントの check 5）。設定したら Store が cover する registration を `repositories.user.http.federatedIdentityLookupCoverage`（HOCON）に宣言する。**https 必須** |
 
 ユーザー認証 URL は 2 つとも上流ストアへ**平文のユーザー資格情報**を運ぶため、いずれも絶対 `https://` URL でなければならない。`http://` は loopback ホスト（`localhost`、`127.0.0.0/8` 内のアドレス、`[::1]`）に限って許可され、ローカル開発で証明書を用意せずに済むようにしている。プライベートレンジのアドレス（`http://10.0.0.5/…`）やコンテナネットワークのサービス名（`http://user-service/…`）には `https://` が必要 — これらはデプロイが端から端まで制御していないネットワークを越えるため。URL・タイムアウト・レスポンス上限のいずれかが不正なら、最初のログイン時ではなく起動時に失敗する。
 
@@ -167,6 +168,76 @@ openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 | `CLIENT_CODE_PASSWORD` | — | コードストア用 Redis パスワード |
 | `CLIENT_CODE_DEFAULT_EXPIRES_IN` | `600` | 認可コードのデフォルト有効期間（秒） |
 
+### フェデレーショングラント（#593）
+
+上流 IdP のトークンをオフラインで委譲する仕組み。ユーザーが一度同意すると、クライアント（バックエンドやエージェント）は本人不在のまま、後から HTTP で上流のアクセストークンを取得できる。グラントは**ログアウトを越えて残り**、資格情報の変更（subject-revocation service）で終わる。既定はオフで、オフなら何もインストールされない。ルートと各応答の意味は[パッケージ README](../../packages/federation-grants/README.md)、IdP ごとに必要な設定は [`docs/offline-access.md`](../../packages/federation-grants/docs/offline-access.md) を参照。
+
+| 変数 | デフォルト | 説明 |
+|---|---|---|
+| `FEDERATION_GRANTS_ENABLED` | `false` | ルート、下記 2 つのストア、subject-revocation service をインストールする |
+| `FEDERATION_GRANTS_CONSENT_URL` | — | グラント用の同意ページ（デプロイ側が用意する）。パス、またはプロバイダー origin 上の絶対 URL。既定値なし — 有効化は「ページがある」という宣言で、無ければ起動を拒否する |
+| `FEDERATION_GRANTS_IDENTITY_LOOKUP` | `required` | connect callback で、別ローカルユーザーに紐づいた上流アカウントを拒否するか。`required` は各 connection の registration を cover するユーザーリポジトリが必要（下記）。`unsupported` は「この検査をしない」という記録された決定 |
+| `FEDERATION_GRANT_STORE_ADAPTER` | `redis` | グラントの保存先: `memory`（1 レプリカ、再起動で消え全ユーザーが再接続）/ `redis`（共有ソケット） |
+| `FEDERATION_GRANT_INTENT_STORE_ADAPTER` | `redis` | 取得フローの記録（intent、同意チャレンジ、connect トランザクション）の保存先: `memory`（1 レプリカ、再起動で進行中のフローだけ失う）/ `redis` |
+| `FEDERATION_GRANTS_ENCRYPTION_MODE` | `required` | `required` / `allow-plaintext`。平文は production/staging と `DEPLOYMENT_MODE=multi` で拒否される（`FEDERATION_TOKENS_ALLOW_INSECURE=1` を除く） |
+| `FEDERATION_GRANTS_ALLOW_KEEP_ON_SUBJECT_REVOCATION` | `false` | subject 全体の失効で、確立済みグラントを残すよう*求められる*ことを許すか。許可であって指示ではない |
+| `REDIS_FEDERATION_GRANT_STORE_KEY_PREFIX` | `fg:` | Redis グラントストアのキー名前空間 |
+
+**環境変数の形を持たないものが 2 つ**ある — connection と暗号鍵リング。リストは HOCON のものなので、デプロイ側のレイヤー（例: `config/production.conf`）に書く:
+
+```hocon
+federationGrants {
+  encryptionKeys = [
+    # 先頭の鍵で封じ、列挙した全鍵で開く。GRANT_KEY_2026_09 は自分で決める名前
+    # (openssl rand -base64 32) で、テンプレートの override ではない。
+    { id = "2026-09", key = ${GRANT_KEY_2026_09} }
+  ]
+  connections {
+    files {
+      federation = "entra-files"   # 有効な type = "oidc" の federations.<name>。専用の app registration を持つ
+      scopes = ["openid", "profile", "offline_access", "Files.Read"]
+      boundary = "production"
+      maxAccessTokenLifetime = 3600
+      # グラントフロー自身の callback（このプロバイダーの origin 上）。federation のログイン callback ではない
+      callbackURL = "https://auth.example/session/federation-grants/callback/files"
+      allowScopeSubsets = false
+      identityClaims = ["oid", "tid"]
+    }
+  }
+}
+```
+
+**起動時に拒否されるもの**（ユーザーがフロー途中で出会う代わりに、名指しで）: 同意ページ未設定 / `callbackURL` のない connection、無効な federation を指す connection、委譲 capability を持たないアダプターの federation（持つのは汎用 OIDC アダプターだけ — Google の connection は `type = "oidc"` の federation にする）/ `required` なのに connection の registration を cover しないユーザーリポジトリ / Redis グラント + memory のユーザーセッションストア（`USER_SESSION_STORES_ADAPTER=memory` — グラントがそれを終わらせる境界より長生きしてしまう。compose 2 本は `redis` を設定済み）/ Redis グラントストアで `encryptionMode = "required"` なのにリングに鍵がない（memory ストアは何も封じないので鍵不要）/ `DEPLOYMENT_MODE=multi` でどちらかのストアが `memory`。
+
+**ユーザーリポジトリ。** `required` では、起動時に各 connection の registration を cover するかをリポジトリに問い、connect callback で上流アカウントの持ち主を問う。テンプレート既定の `http` リポジトリはこれを Store に問う（#613）: `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` にエンドポイントを設定し、そのエンドポイントが cover するもの（registration ごとに 1 エントリ、Store の戦略が必要とする claim 付き）を HOCON レイヤーに宣言する:
+
+```hocon
+repositories.user.http.federatedIdentityLookupCoverage = [
+  { provider = "entra-files", issuer = "https://login.microsoftonline.com/<tenant>/v2.0",
+    clientId = "<グラント用 app registration>", requiredClaims = ["tid", "oid"] }
+]
+```
+
+起動時にすべての connection がこれと突き合わされる: registration が宣言されていない、または `identityClaims` に必要な claim が欠けている connection は名指しで拒否される。Store が実装する wire 契約と、`unlinked` と答えるために何を確認していなければならないかは [foundation README](../../packages/foundation/README.md#the-identity-lookup-613) にある。起動時に Store は問われない。同梱の in-memory リポジトリはどの registration も cover しない。cover する Store が無いなら `FEDERATION_GRANTS_IDENTITY_LOOKUP=unsupported`（別ローカルユーザーが既に持つ上流アカウントを拒否しない、という記録された決定）にする。connection が無ければ何も要求されない。
+
+**クライアント登録。** `config/clients.yaml` で、グラントを持てる confidential クライアントに、要求できる connection とブラウザの戻り先を書く。`allowedRedirectUris` や `firstParty` はどちらも代わりにならない:
+
+```yaml
+worker:
+  tokenEndpointAuthMethod: "client_secret_basic"
+  clientSecret: "$2b$10$…"
+  allowedFederationGrantConnections: ["files"]
+  federationGrantRedirectUris: ["https://worker.example/connected"]
+```
+
+**クライアント側から見たフロー。** `POST /oauth/federation-grants`（クライアント認証）で `sub` に対する intent を登録すると `grant_id` と `connect_uri` が返るので、ユーザーのブラウザをそこへ送る。プロバイダーは必要ならログインさせ、同意ページを見せ、上流へ送り、`grant_id` と `state` を付けてクライアントの `redirect_uri` に戻す — トークンは決して載らない。以後クライアントは自身の資格情報とユーザーの `sub` で `/oauth/federation-grants/:grantId/token` / `/status` / `/revoke` を呼ぶ。本人は不在でよい。
+
+**同意ページ**はデプロイ側のもので、プロバイダーと same-origin。契約は `/oauth/consent` と同じなので 1 ページで両方を担える。`GET /session/federation-grants/consent?challenge=…` は JSON を返す: `client_id`、`client_name`、`connection`、`scopes`、`resource`、`grant_expires_in`（承認後の期間。日付ではない）、`continues_after_logout`（ページが必ず表示するもの）、`expires_in`（フローの残り時間）。`POST` に `challenge` と `decision`（`accept` | `deny`）を送ると `303` — 上流へ、または クライアントへ戻る。取得も更新も必ずここを通る。
+
+**ログインページ**は `ENDPOINTS_LOGIN_URL` のもので、`redirect_to=<connect リンク>` 付きで呼ばれる。ログイン後はそのリンクへそのまま戻す（`/oauth/authorize` と同じ往復）。そのリンクを `POST /session/login` の `redirect_to` に送ってはいけない — あちらの完全一致 allowlist はランディングページ用で、フローごとの handle を拒否する。
+
+**運用。** 鍵リングのローテーションは[オペレーター runbook](../../docs/operator-runbook.md)の手順で（新しい鍵を末尾に → 先頭に、古い鍵は 365 日残す）。シャットダウンは機能が有効なら cleanup に 45 秒を与え（`upstreamHardTimeoutMs` / `persistRetryBudgetMs` / `lockWaitMs` を上げればその合計 + 余裕まで増える）、compose 2 本はプロセスに 60 秒を与える（[シャットダウンの保証](#シャットダウンの保証)）。無効化は失効ではない: グラントは失効させるまで Redis に残るので、先に終わらせること。一時停止中も鍵と失効境界は保持する。
+
 ### エンドポイント
 
 | 変数 | デフォルト | 説明 |
@@ -297,7 +368,9 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 4. **deadline を超えたら残接続を切り、プロセスは非ゼロ終了する。** 常に `0` しか見えない orchestrator では、正常な drain と時間切れの強制切断を区別できない。
 5. **`cleanup` は drain 後・exit 前**に走る(`handle.dispose()` = 逆トポロジカルなコンポーネント cleanup + Redis/タイマーの drain)。失敗はこのサービス自身の logger(他の行と同じ NDJSON)に出し、exit code にも反映する。dispose が throw してもプロセスは終了する。
 
-**`drainTimeoutMs` は orchestrator の kill grace period より短く設定すること** — Kubernetes の `terminationGracePeriodSeconds`、compose の `stop_grace_period` はいずれも既定 30 秒。他人の都合の `SIGKILL` が来る前に、自分の都合で閉じるのが目的。
+6. **フェデレーショングラントが有効なら `cleanup` に「refresh の最長の尻尾 + 余裕」**（`src/shutdown.mts` の `cleanupAllowanceFor`）: `federationGrants.upstreamHardTimeoutMs` + `persistRetryBudgetMs` + `lockWaitMs` + 12 秒、下限 45 秒 — 同梱の予算（25 + 3 + 5 + 12）ではちょうど 45 秒。drain の 10 秒を継承しないのは、dispose がローテーションした上流資格情報の書き込みを待つため。予算を上げれば allowance も増えるので、orchestrator の grace も合わせて上げる。無効なら cleanup の予算は drain のまま。
+
+**`drainTimeoutMs` と `cleanupTimeoutMs` の合計が orchestrator の kill grace period を下回るようにすること。** Kubernetes の `terminationGracePeriodSeconds` は既定 30 秒、compose の `stop_grace_period` は既定 10 秒。フェデレーショングラントが有効なときの最悪値は drain 10 秒 + cleanup 45 秒 = 55 秒なので、**grace は 60 秒以上**にする — 同梱の compose 2 本はそうしてあり、Kubernetes では `terminationGracePeriodSeconds: 60` を自分で設定する。さもないとローリング再起動のたびに、cleanup が待っている書き込みの途中で `SIGKILL` される。他人の都合の `SIGKILL` が来る前に、自分の都合で閉じるのが目的。
 
 ## npm スクリプト
 

package/templates/standalone/README.md

@@ -115,6 +115,7 @@ Other multi-replica considerations covered by the default modules:
 - The replay seen-set — the `jti` single-use record behind `private_key_jwt` client authentication (#484) — switches on `replaySeenSet.adapter` (`REPLAY_SEEN_SET_ADAPTER`); the template ships `"redis"` on the shared connection, and `memory` is refused under `DEPLOYMENT_MODE=multi` because a captured client assertion would replay once per replica.
 - The consent step for clients that are not first-party (#527) switches on `consentStore.adapter` (`CONSENT_STORE_ADAPTER`). It is off (`none`) by default; `memory` is refused under `DEPLOYMENT_MODE=multi`, because a consent granted on one replica would be asked for again on every other and a consent page's parked request would be unknown to the replica that receives the answer. `redis` (#561) keeps both on the shared connection. See [Consent Store](#consent-store).
 - The federation token store defaults to memory. Set `FEDERATION_TOKEN_STORE_TYPE=redis` (`federationTokenStore.type = "redis"`) and supply `REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY` — 32 bytes, base64-encoded (`openssl rand -base64 32`); the store encrypts the upstream refresh tokens it holds. It shares the ioredis socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`. See [Federation Token Store](#federation-token-store).
+- Federation grants (#593), when enabled, keep two more stores: the grants themselves (`FEDERATION_GRANT_STORE_ADAPTER`) and acquisition's records (`FEDERATION_GRANT_INTENT_STORE_ADAPTER`). Both ship `redis` on the shared socket; `memory` for either is refused under `DEPLOYMENT_MODE=multi`, and Redis grants beside memory user-session stores are refused on any replica count, because the grants would outlive the boundary that ends them. See [Federation Grants](#federation-grants).
 
 ## Usage
 
@@ -391,6 +392,7 @@ is documented in [its README](../../packages/federation-oidc/README.md).
 | `CLIENT_USER_AUTHENTICATE_URL` | — | URL for password-based user authentication. **https required** (see below) |
 | `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | URL for token-based user authentication. **https required** (see below) |
 | `CLIENT_USER_LINK_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store links a federated identity at (#482); enables `?link=1` on the federation start route. **https required** |
+| `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` | — | Optional. URL the Store answers who holds an upstream identity at (#613, federation grants' check 5). With it, declare what the Store covers in `repositories.user.http.federatedIdentityLookupCoverage` (HOCON). **https required** |
 | `CLIENT_USER_TIMEOUT` | `5000` | HTTP request timeout in milliseconds. Positive integer ≤ `2147483647` |
 | `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | Largest upstream response body accepted, in bytes |
 
@@ -443,6 +445,139 @@ socket configured by `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`.
 |---|---|---|
 | `CONSENT_STORE_ADAPTER` | `none` | Consent store for clients that are not first-party (#527): `none` (such clients are refused), `memory` (single replica) or `redis` (shared, #561) |
 
+### Federation Grants
+
+Offline delegation of an upstream IdP's tokens (#593): a user consents once
+that a client — a backend, an agent — may obtain access tokens for one
+upstream connection on their behalf, and the client obtains them over HTTP
+later, with the user not present. A grant **survives logout**; a credential
+change ends it through the subject-revocation service. Off by default, and
+off installs nothing. The routes and what each answer means are in the
+[package README](../../packages/federation-grants/README.md); what each IdP
+needs before it issues a refresh token is in
+[`docs/offline-access.md`](../../packages/federation-grants/docs/offline-access.md).
+
+| Variable | Default | Description |
+|---|---|---|
+| `FEDERATION_GRANTS_ENABLED` | `false` | Installs the routes, the two stores below and the subject-revocation service |
+| `FEDERATION_GRANTS_CONSENT_URL` | — | The deployment's consent page for grants: a path, or an absolute URL on the provider's origin. No default — enabling grants is a statement that the page exists, and boot refuses without it |
+| `FEDERATION_GRANTS_IDENTITY_LOOKUP` | `required` | Whether the connect callback refuses an upstream account already linked to another local user. `required` needs a user repository that covers every connection's registration (below); `unsupported` records that the check is not made |
+| `FEDERATION_GRANT_STORE_ADAPTER` | `redis` | Where grants live: `memory` (one replica; lost on restart, every user reconnects) or `redis` (the shared socket) |
+| `FEDERATION_GRANT_INTENT_STORE_ADAPTER` | `redis` | Where acquisition's records live — the intent a backend lodged, the consent challenge, the connect transaction: `memory` (one replica; a restart loses flows in progress and nothing else) or `redis` |
+| `FEDERATION_GRANTS_ENCRYPTION_MODE` | `required` | `required` or `allow-plaintext`. Plaintext is refused in production/staging and under `DEPLOYMENT_MODE=multi` unless `FEDERATION_TOKENS_ALLOW_INSECURE=1` |
+| `FEDERATION_GRANTS_ALLOW_KEEP_ON_SUBJECT_REVOCATION` | `false` | Whether a subject-wide revocation may be *asked* to leave established grants standing. An allowance, not an instruction |
+| `REDIS_FEDERATION_GRANT_STORE_KEY_PREFIX` | `fg:` | Key namespace of the Redis grant store |
+
+**Two things have no environment form**, because a list is HOCON's: the
+connections, and the encryption key ring. Write them in a deployment-owned
+layer — `config/production.conf`, say:
+
+```hocon
+federationGrants {
+  encryptionKeys = [
+    # The first key seals; every listed key opens. GRANT_KEY_2026_09 is a name
+    # you choose (openssl rand -base64 32), not a template override.
+    { id = "2026-09", key = ${GRANT_KEY_2026_09} }
+  ]
+  connections {
+    files {
+      federation = "entra-files"   # an enabled federations.<name> of type "oidc", with an app registration of its own
+      scopes = ["openid", "profile", "offline_access", "Files.Read"]
+      boundary = "production"
+      maxAccessTokenLifetime = 3600
+      # The grant flow's own callback on this provider's origin — not the
+      # federation's login callback.
+      callbackURL = "https://auth.example/session/federation-grants/callback/files"
+      allowScopeSubsets = false
+      identityClaims = ["oid", "tid"]
+    }
+  }
+}
+```
+
+**What boot refuses**, each named, rather than met by a user mid-flow: no
+consent page; a connection without `callbackURL`, on a federation that is not
+enabled, or on one whose adapter lacks the delegated capability — only the
+generic OIDC adapter has it, so a Google connection is a `type = "oidc"`
+federation; `required` with a user repository that does not cover a
+connection's registration; Redis grants beside memory user-session stores
+(`USER_SESSION_STORES_ADAPTER=memory` — the grants would outlive the boundary
+that ends them; both compose files set `redis`); the Redis grant store under
+`encryptionMode = "required"` with no key in the ring (the memory store seals
+nothing and needs none); `memory` for either store under `DEPLOYMENT_MODE=multi`.
+
+**The user repository.** Under `required`, boot asks the repository whether it
+covers each connection's registration, and the connect callback asks it who
+holds the upstream account. The template's `http` repository asks your Store
+(#613): set `CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL` to the
+endpoint, and declare what that endpoint covers — one entry per registration,
+with the claims the Store's strategy needs — in a HOCON layer:
+
+```hocon
+repositories.user.http.federatedIdentityLookupCoverage = [
+  { provider = "entra-files", issuer = "https://login.microsoftonline.com/<tenant>/v2.0",
+    clientId = "<the grants app registration>", requiredClaims = ["tid", "oid"] }
+]
+```
+
+Boot then holds every connection to it: one whose registration is not
+declared, or whose `identityClaims` misses a required claim, is refused by
+name. The wire contract the Store implements — and what "unlinked" obliges it
+to have checked — is in the
+[foundation README](../../packages/foundation/README.md#the-identity-lookup-613);
+the Store is not asked at boot. The bundled in-memory repository covers no
+registration. Without a covering Store, set
+`FEDERATION_GRANTS_IDENTITY_LOOKUP=unsupported` — the recorded decision not to
+refuse an upstream account another local user already holds. With no
+connection configured nothing is required.
+
+**Registering a client.** In `config/clients.yaml`, a confidential client that
+may hold grants names the connections it may ask for and where the browser
+may be returned. Neither its `allowedRedirectUris` nor `firstParty` grants
+either:
+
+```yaml
+worker:
+  tokenEndpointAuthMethod: "client_secret_basic"
+  clientSecret: "$2b$10$…"
+  allowedFederationGrantConnections: ["files"]
+  federationGrantRedirectUris: ["https://worker.example/connected"]
+```
+
+**The flow, from the client's side.** `POST /oauth/federation-grants`
+(client-authenticated) lodges an intent for a `sub` and answers a `grant_id`
+and a `connect_uri`; the client sends the user's browser there. The provider
+signs the user in if needed, shows your consent page, sends them to the
+upstream, and returns the browser to the client's `redirect_uri` with
+`grant_id` and `state` — never a token. The client then calls
+`/oauth/federation-grants/:grantId/token`, `/status` and `/revoke` with its
+own credentials and the user's `sub`, with no user present.
+
+**The consent page** is yours, same-origin with the provider, and its contract
+is `/oauth/consent`'s, so one page can serve both. `GET
+/session/federation-grants/consent?challenge=…` answers JSON: `client_id`,
+`client_name`, `connection`, `scopes`, `resource`, `grant_expires_in` (a
+duration after approval, not a date), `continues_after_logout` (which the page
+must show), and `expires_in` (what is left of the flow). `POST` with
+`challenge` and `decision` (`accept` | `deny`) answers `303` — to the upstream,
+or back to the client. Every acquisition and renewal goes through it.
+
+**The login page** is the one `ENDPOINTS_LOGIN_URL` names, reached with
+`redirect_to=<the connect link>`; it signs the user in and navigates back to
+that link unchanged, as it does for `/oauth/authorize`. Do not submit the link
+to `POST /session/login` as its `redirect_to`: that route's exact-match
+allowlist is for landing pages and refuses a per-flow handle.
+
+**Operating it.** Rotate the key ring by the procedure in the
+[operator runbook](../../docs/operator-runbook.md) — new key last, then first,
+old key kept 365 days. A shutdown gives cleanup 45 seconds while the feature
+is on — more if you raise `upstreamHardTimeoutMs`, `persistRetryBudgetMs` or
+`lockWaitMs`, since the allowance is their sum plus a margin — and both
+compose files give the process 60; see
+[Shutdown guarantees](#shutdown-guarantees). Disabling the feature is not
+revoking: grants stay in Redis until revoked, so end them first, and keep the
+keys and the revocation boundaries through any temporary shutdown.
+
 ### Redis Namespacing
 
 For multi-tenant Redis clusters, set deployment-specific key prefixes so two
@@ -695,7 +830,9 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 4. **Past the deadline the remaining connections are cut and the process exits non-zero.** An orchestrator that only ever sees `0` cannot tell a clean drain from one that ran out of time.
 5. **`cleanup` runs after draining, before exit** — `handle.dispose()`, i.e. reverse-topological component cleanup plus the Redis/timer drain. A failure there is logged through this service's own logger (NDJSON, like every other line) and reflected in the exit code. A dispose that throws still exits; it never wedges the process.
 
-**Size `drainTimeoutMs` below your orchestrator's kill grace period** — Kubernetes `terminationGracePeriodSeconds` and compose `stop_grace_period` are both 30s by default. The point is to close on your terms before `SIGKILL` arrives on someone else's.
+6. **With federation grants on, `cleanup` gets the longest refresh tail plus a margin** (`cleanupAllowanceFor` in `src/shutdown.mts`): `federationGrants.upstreamHardTimeoutMs` + `persistRetryBudgetMs` + `lockWaitMs` + 12 s, never below 45 s — exactly 45 s under the shipped budgets (25 + 3 + 5 + 12) — instead of inheriting the drain's ten, because the dispose waits for a rotated upstream credential's write. Raise a budget and the allowance grows with it; raise your orchestrator's grace to match. Off, the cleanup budget stays the drain's.
+
+**Size `drainTimeoutMs` and `cleanupTimeoutMs` together below your orchestrator's kill grace period.** Kubernetes `terminationGracePeriodSeconds` is 30s by default and compose's `stop_grace_period` is 10s; with federation grants on, the worst case is drain (10s) + cleanup (45s) = 55s, so **set the grace to 60s or more** — the shipped compose files do, and a Kubernetes deployment must set `terminationGracePeriodSeconds: 60` itself, or a rolling restart SIGKILLs the process in the middle of the write the cleanup exists to finish. The point is to close on your terms before `SIGKILL` arrives on someone else's.
 
 ## npm Scripts
 

package/templates/standalone/config/application.conf

@@ -159,6 +159,44 @@ replaySeenSet {
   adapter = ${?REPLAY_SEEN_SET_ADAPTER}
 }
 
+# #593: federation grants — a user's standing consent that a backend or an
+# agent may obtain upstream IdP tokens with no session behind the call. Off by
+# default; FEDERATION_GRANTS_ENABLED=true installs the routes, the two stores
+# below and the subject-revocation service. Enabling it is a statement that
+# the deployment has a consent page (FEDERATION_GRANTS_CONSENT_URL, no default),
+# a `callbackURL` on every connection, and a user repository that covers each
+# connection's registration (or FEDERATION_GRANTS_IDENTITY_LOOKUP=unsupported,
+# the recorded decision not to make that check) — each refused at boot when
+# missing. Connections and the encryption key ring have no environment form;
+# write them in a deployment-owned HOCON layer (README: Federation Grants).
+federationGrants {
+  enabled = false
+  enabled = ${?FEDERATION_GRANTS_ENABLED}
+  identityLookup = "required"
+  identityLookup = ${?FEDERATION_GRANTS_IDENTITY_LOOKUP}
+  consent {
+    url = ${?FEDERATION_GRANTS_CONSENT_URL}
+  }
+  encryptionMode = "required"
+  encryptionMode = ${?FEDERATION_GRANTS_ENCRYPTION_MODE}
+}
+
+# "redis" for both, as for the denylist above: a grant is an offline credential
+# that must outlive a restart, and every store this file already selects shares
+# the same socket. Redis grants need the subject boundary in Redis too
+# (USER_SESSION_STORES_ADAPTER=redis, which both compose files set) — boot
+# refuses the pairing with a memory boundary, because the grants would outlive
+# what ends them. Single-instance local work can set both to "memory".
+federationGrantStore {
+  adapter = "redis"
+  adapter = ${?FEDERATION_GRANT_STORE_ADAPTER}
+}
+
+federationGrantIntentStore {
+  adapter = "redis"
+  adapter = ${?FEDERATION_GRANT_INTENT_STORE_ADAPTER}
+}
+
 # #527: where consent to a client that is not first-party is recorded.
 # "none" (the default) wires no store and such clients are refused at
 # /authorize; "memory" is single-replica only (refused under
@@ -269,6 +307,12 @@ federations {
 
     # Where the browser goes after a callback carrying no `redirect_to`.
     # clientUrl = ${?FEDERATIONS_GOOGLE_CLIENT_URL}
+
+    # RFC 9207: Google always returns `iss` on the callback, so a callback
+    # without one is refused. `false` is the way out if Google ever stops
+    # sending it. It permits a missing `iss` only — one that is sent and is not
+    # Google's is refused either way.
+    # requireAuthorizationResponseIss = ${?FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS}
   }
 
   # Any OpenID Connect provider (Okta, Entra ID, Auth0, Keycloak, your own
@@ -338,6 +382,14 @@ repositories {
       # layer this file gets the same override.
       # Without it, link=1 is refused with link_unsupported.
       linkFederatedIdentityUrl = ${?CLIENT_USER_LINK_FEDERATED_IDENTITY_URL}
+      # #613: optional. The Store's identity lookup for federation grants —
+      # what lets this deployment keep FEDERATION_GRANTS_IDENTITY_LOOKUP=required
+      # with a connection configured. Same https rule. Declare what the Store
+      # covers, per registration, in a HOCON layer (README: Federation Grants):
+      #   federatedIdentityLookupCoverage = [
+      #     { provider = "entra-files", issuer = "...", clientId = "...", requiredClaims = ["tid", "oid"] }
+      #   ]
+      findSubjectByFederatedIdentityUrl = ${?CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL}
       # Positive integer, milliseconds, <= 2147483647. Boot fails otherwise —
       # including on a blank env override, which HOCON substitutes as "".
       timeout = 5000

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

@@ -49,6 +49,13 @@ services:
       # security group, a firewall rule, or the proxy's own network. Do not
       # widen this line and call it done.
       - "127.0.0.1:3000:3000"
+    # #593 slice 7: compose's default grace is ten seconds — the HTTP drain
+    # budget alone. With federation grants on, `src/app.mts` gives cleanup 45
+    # more for the drain of a rotated upstream credential's write, and SIGKILL
+    # has to arrive after that: drain (10) + cleanup (45) + an exit margin.
+    # The cleanup allowance grows by itself with `federationGrants.upstreamHardTimeoutMs`,
+    # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
+    stop_grace_period: 60s
     depends_on:
       redis:
         condition: service_healthy

package/templates/standalone/docker-compose.yml

@@ -8,6 +8,13 @@ services:
     volumes:
       - ./src:/home/node/src
       - ./config:/home/node/config
+    # #593 slice 7: compose's default grace is ten seconds — the HTTP drain
+    # budget alone. With federation grants on, `src/app.mts` gives cleanup 45
+    # more for the drain of a rotated upstream credential's write, and SIGKILL
+    # has to arrive after that: drain (10) + cleanup (45) + an exit margin.
+    # The cleanup allowance grows by itself with `federationGrants.upstreamHardTimeoutMs`,
+    # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
+    stop_grace_period: 60s
     depends_on:
       redis:
         condition: service_healthy

package/templates/standalone/package.json

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

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

@@ -174,6 +174,20 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	REDIS_FEDERATION_TOKEN_STORE_KEY_PREFIX: "ft:",
 	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_MODE: "required",
 	REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=",
+	// #593: federation grants — a user's standing consent that a client may
+	// obtain upstream tokens without them. The overrides `reference.conf`
+	// declares, and (slice 7) the two adapter switches the template composes
+	// the feature from.
+	FEDERATION_GRANTS_ENABLED: "true",
+	FEDERATION_GRANT_STORE_ADAPTER: "redis",
+	FEDERATION_GRANT_INTENT_STORE_ADAPTER: "redis",
+	FEDERATION_GRANTS_ENCRYPTION_MODE: "required",
+	FEDERATION_GRANTS_ALLOW_KEEP_ON_SUBJECT_REVOCATION: "false",
+	// Slice 6: acquisition's two deployment decisions — whether the callback
+	// refuses an upstream account linked to another user, and the consent page.
+	FEDERATION_GRANTS_IDENTITY_LOOKUP: "required",
+	FEDERATION_GRANTS_CONSENT_URL: "/consent/grants",
+	REDIS_FEDERATION_GRANT_STORE_KEY_PREFIX: "fg:",
 
 	// --- federation ---------------------------------------------------
 	FEDERATIONS_GOOGLE_ENABLED: "true",
@@ -195,6 +209,9 @@ const DOCUMENTED_ENV: Readonly<Record<string, string>> = {
 	CLIENT_USER_AUTHENTICATE_URL: "https://users.example.com/authenticate",
 	CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL: "https://users.example.com/authenticate-by-token",
 	CLIENT_USER_LINK_FEDERATED_IDENTITY_URL: "https://users.example.com/link-federated-identity",
+	// #613: the Store's identity lookup for federation grants (D7 check 5).
+	CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL:
+		"https://users.example.com/find-subject-by-federated-identity",
 	CLIENT_USER_TIMEOUT: "5000",
 	CLIENT_USER_MAX_RESPONSE_BYTES: "1048576",
 	CLIENT_CODE_TYPE: "redis",
@@ -323,6 +340,10 @@ describe("#288: the shipped config boots with every documented override supplied
 		expect(config.oauth.resourceIndicator?.enabled).toBe(true);
 		expect(config.federations.google?.enabled).toBe(true);
 		expect(config.federations.oidc?.enabled).toBe(true);
+		// #593: the newest one, and the one where a leftover string would be
+		// read as "on" by a truthiness check and as "off" by `=== true` — a
+		// feature whose whole default is off.
+		expect(config.federationGrants?.enabled).toBe(true);
 	});
 
 	it("turns every non-boolean override into its declared type", () => {