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

package/templates/standalone/config/application.conf

@@ -1,121 +1,102 @@
 # Application-level overrides for the standalone template.
 #
-# The library ships its declarative defaults in
-#   @o3co/auth-provider-core/reference.conf
-# (resolved at boot via standalone/src/app.mts withFallback chain).
-# Values omitted here inherit from that baseline; add overrides only
-# for keys this deployment intentionally diverges on.
+# Defaults come from config/reference.conf (the template's own modules) and
+# from the reference.conf of each package its modules come from, core's last.
+# Values omitted here inherit from them; add overrides only for keys this
+# deployment intentionally diverges on. Write a value for a key the last
+# block of this file binds above that block: one written below it wins over
+# the variable.
 
-http {
-  port = 3000
-  port = ${?HTTP_PORT}
-  # false | true | <hop count> | <address list>. Prefer naming the proxy:
-  # HTTP_TRUST_PROXY=10.0.0.0/8 (or `loopback` for a sidecar) rather than
-  # `true`, which trusts a forwarded client address from anyone who can reach
-  # this process. See the header comment in the library's reference.conf.
-  trustProxy = false
-  trustProxy = ${?HTTP_TRUST_PROXY}
-}
-
-# #287: where the audit trail goes. Before this block the template wired no
-# sink at all, so every security event the routes emit -- token.issued.failure,
-# authorize.rejected / authorize.granted, logout.cascade_failed, and the shared
-# rate-limit guard's rate_limit.unavailable -- was discarded by the artifact
-# operators deploy. Nothing failed and nothing warned: `emitAuditEvent` is a
-# no-op when the slot is empty.
+# Which adapter fills each slot -- the stores, the repositories, the audit
+# sink -- is the template's own `adapters` section, whose defaults
+# config/reference.conf holds with each one's variable (ADAPTERS_*). Override
+# one in a layer of your own or with its variable:
 #
-# "logger" rather than reference.conf's "console": both write newline-delimited
-# JSON to stdout, but "logger" writes it through the same pino stream that
-# carries every other line this template emits, so a log aggregator ingests
-# application logs and audit events with one parser and separates them on
-# `name` ("provider" vs "audit"). "console" writes the bare event with no log
-# envelope -- no level, no time -- which most pipelines then timestamp by
-# ingestion. Set AUDIT_SINK_TYPE=console if that is what your pipeline wants.
+#   adapters.rateLimiter = "redis"
 #
 # The audit stream's level is FIXED at info and `logging.level` does not gate
-# it. LOG_LEVEL=warn is an ordinary production setting and LOG_LEVEL=silent a
-# legitimate one; either silencing the audit trail would be #287 again, reached
-# from the operator's side. Where events go is chosen here, and this selector
-# has no "none" -- an unknown type fails boot naming the sinks that exist,
-# rather than producing a deployment with no audit trail (#304).
+# it: LOGGING_LEVEL=warn is an ordinary production setting and
+# LOGGING_LEVEL=silent a legitimate one, and either silencing the audit trail
+# would lose the record of every security event.
+
+# The grant switches, each in the section of the module that installs the
+# grant. The template is a typical web-app OP, so it turns on the universal
+# user-auth path: the session grant (oauth-session) and the authorization-code
+# and refresh-token grants (oauth-authorization). client_credentials and the
+# jwt-bearer grant stay off; deployments that need M2M flows set
+# OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED=true or write
+# `oauth-authorization.grants.clientCredentials.enabled = true` in their own
+# layer.
+#
+# The modules read these switches at boot, from the configuration boot parses;
+# the template reads none of them before. This file writes the template's
+# choices and binds each variable again: the env-override line is repeated
+# after each value because a layer's own value wins over a variable bound
+# below it.
 #
-# To point this at a real sink (SIEM, log pipeline, message bus): register the
-# builder in `auditSinkModule` (src/modules.mts), name it here, and put its
-# options in this block -- `sink { type = "splunk-hec", splunk-hec { ... } }`.
-audit {
-  sink {
-    type = "logger"
-    type = ${?AUDIT_SINK_TYPE}
+# PKCE is mandatory for every authorization-code client and `S256` is the only
+# method the provider accepts -- fixed policy (OAuth 2.1 §4.1.1 / RFC 9700
+# §2.1.1), not a deployment setting. A legacy client that genuinely cannot
+# compute SHA-256 is opted into `plain` one client at a time, with
+# `allowPlainPkce: true` in clients.yaml.
+oauth-session {
+  enabled = true
+  enabled = ${?OAUTH_SESSION_ENABLED}
+}
+
+oauth-authorization.grants {
+  authorizationCode {
+    enabled = true
+    enabled = ${?OAUTH_AUTHORIZATION_GRANTS_AUTHORIZATION_CODE_ENABLED}
+  }
+  refreshToken {
+    enabled = true
+    enabled = ${?OAUTH_AUTHORIZATION_GRANTS_REFRESH_TOKEN_ENABLED}
+  }
+  clientCredentials {
+    enabled = false
+    enabled = ${?OAUTH_AUTHORIZATION_GRANTS_CLIENT_CREDENTIALS_ENABLED}
+  }
+  jwtBearer {
+    enabled = false
+    enabled = ${?OAUTH_AUTHORIZATION_GRANTS_JWT_BEARER_ENABLED}
   }
 }
 
 oauth {
-  grants {
-    # Template is a typical web-app OP — enable the universal user-auth path.
-    # client_credentials remains off (reference.conf default); deployments that
-    # need M2M flows set OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED=true or add
-    # `client_credentials { enabled = true }` in their own application.conf.
-    #
-    # The env-override line (`enabled = ${?OAUTH_GRANTS_*_ENABLED}`) is repeated
-    # at this layer because HOCON precedence: application.conf wins over
-    # reference.conf, so without the env-override line at the template layer,
-    # an operator setting OAUTH_GRANTS_SESSION_ENABLED=false (etc.) cannot
-    # disable the grant — the env var only takes effect at the layer where
-    # the substitution is written.
-    session {
-      enabled = true
-      enabled = ${?OAUTH_GRANTS_SESSION_ENABLED}
-    }
-    # #273: there is no `pkce` block here any more. PKCE is mandatory for
-    # every authorization-code client and `S256` is the only method the
-    # provider accepts — that is fixed policy (OAuth 2.1 §4.1.1 / RFC 9700
-    # §2.1.1), not a deployment setting, so `requireS256` / `required` /
-    # `defaultMethod` / `supportedMethods` are gone. A legacy client that
-    # genuinely cannot compute SHA-256 is opted into `plain` one client at a
-    # time, with `allowPlainPkce: true` in clients.yaml. The
-    # OAUTH_GRANTS_AUTHORIZATION_CODE_PKCE_REQUIRE_S256 tombstone in core's
-    # reference.conf makes a still-exported env var warn at boot.
-    authorization_code {
-      enabled = true
-      enabled = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_ENABLED}
-    }
-    refresh_token {
-      enabled = true
-      enabled = ${?OAUTH_GRANTS_REFRESH_TOKEN_ENABLED}
-    }
-    # client_credentials: omitted -> inherits reference.conf default (enabled = false).
-    # Operators that need M2M flows set OAUTH_GRANTS_CLIENT_CREDENTIALS_ENABLED=true
-    # or add `client_credentials { enabled = true }` here.
-  }
-  # OR-9: adapter switch for the OAuth authorization-code repository. When
-  # set to "redis", the standalone composition root wires
-  # `redisCodeRepositoryModule` against the shared ioredis socket
-  # (`standaloneRedisClientsModule`). Memory-only deployments lose codes on
-  # restart and across replicas — multi-replica production MUST use "redis".
-  # Supersedes the legacy `repositories.code.type` switch (kept below as
-  # deprecated for backward compat — see CHANGELOG for the removal version).
-  # #481: the Authentication Context Class References this deployment can
+  # The Authentication Context Class References this deployment can
   # vouch for, each mapped to the RFC 8176 `amr` values a session must carry
-  # (`pwd` for a password login, `hwk` for a passkey, `fed` for a federated
-  # login, `mfa` when a resumed MFA login records it). `/authorize` answers
+  # (`pwd` for a password login, `fed` for a federated login) — or to a list
+  # of such lists, any one of which satisfies it. `/authorize` answers
   # `acr_values` from this table alone — anything else is
   # `unmet_authentication_requirements` — and discovery advertises the keys.
   #
   #   authorize.acrValues {
   #     "urn:example:pwd" = ["pwd"]
-  #     "urn:example:mfa" = ["pwd", "mfa"]
   #   }
   #
-  # #267: /authorize refuses any client not marked `firstParty: true` in
+  # An entry nothing this deployment installs can satisfy is dropped at boot:
+  # not advertised, answered `unmet_authentication_requirements`, and logged
+  # once as `acr_value_unsatisfiable`. One that needs `fed` needs a
+  # federation installed; one that needs `mfa`, `hwk` or `swk` needs MFA
+  # installed (MFA_MODE, below), or a federation that trusts its upstream
+  # IdP's `amr`. One that lacks only a second factor while MFA is off is
+  # logged at info, not warn.
+  #
+  # While MFA_MODE installs MFA, the template adds `"urn:o3co:acr:mfa" =
+  # ["mfa"]`, met by a session with a verified second factor, unless this
+  # table writes that entry itself; with MFA off it adds nothing.
+  # Phishing-resistant authentication would be:
+  #
+  #   "urn:o3co:acr:phr" = [["hwk"], ["swk"]]
+
+  # /authorize refuses any client not marked `firstParty: true` in
   # clients.yaml — the template's example clients are marked. There is no
-  # opt-out: the one-time `allowUnmarkedClients` migration flag was removed
-  # (#330), and a config or environment still setting it fails at boot with
-  # migration instructions (via the tombstone in core's reference.conf).
-  code {
-    adapter = "redis"
-    adapter = ${?OAUTH_CODE_ADAPTER}
-  }
-  # #277: POST /oauth/revoke revokes access tokens by writing their `jti` to the
+  # opt-out: the one-time `allowUnmarkedClients` migration flag is removed,
+  # and a config or environment still setting it fails at boot: the oauth
+  # module refuses the key as removed, and an exported
+  # OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS as the variable of a removed key.
+  # POST /oauth/revoke revokes access tokens by writing their `jti` to the
   # denylist wired below, and boot FAILS if that denylist is missing — an
   # RFC 7009 endpoint must answer 200, so an unwired denylist would tell every
   # operator their token is revoked while it kept working until expiry.
@@ -131,149 +112,144 @@ oauth {
   }
 }
 
-# #277: backend for the access-token denylist.
-#
-# "redis" by default, not "memory": the memory adapter keeps revocations in one
-# process, so a token revoked on one replica stays valid on every other — and
-# `deployment.mode = "multi"` refuses it by name for exactly that reason. It
-# shares the ioredis socket configured under `refreshTokenFamilyStore.redis`
-# below, so switching it on costs no extra connection.
-#
-# Single-instance local development can set ACCESS_TOKEN_DENYLIST_ADAPTER=memory
-# to run without Redis.
-accessTokenDenylist {
-  adapter = "redis"
-  adapter = ${?ACCESS_TOKEN_DENYLIST_ADAPTER}
-}
+# The session requirements this deployment expects, in core's own section:
+# the extensions that change what "logged in" means, each registered by a
+# module (the MFA package's is named `mfa`). Boot compares the list with what
+# the installed modules register: a name here that nothing registers refuses
+# the boot (`session-requirement-missing`), and so does a registered
+# requirement the list leaves out (`session-requirements-undeclared`). When
+# MFA_MODE (`mfaMode`, config/reference.conf) installs MFA, the template
+# adds `mfa` to this list and writes `secondFactorAuthority = "mfa"` beside
+# it (one written here other than `mfa` refuses the boot); a deployment that
+# adds a module registering a
+# requirement of its own adds its name here. No environment variable sets the
+# list.
+core.sessionRequirements.expected = []
 
-# #484: backend for the replay seen-set — the `jti` single-use record behind
-# `private_key_jwt` client authentication (a client registered with `jwks` or
-# `jwksUri` in config/clients.yaml). Same reasoning as the denylist above:
-# "memory" forks per replica, so a captured client assertion would replay
-# once per replica, and `deployment.mode = "multi"` refuses it by name. It
-# shares the ioredis socket, so it costs no extra connection.
-#
-# Single-instance local development can set REPLAY_SEEN_SET_ADAPTER=memory.
-replaySeenSet {
-  adapter = "redis"
-  adapter = ${?REPLAY_SEEN_SET_ADAPTER}
-}
+# Multi-factor authentication, installed by MFA_MODE (`mfaMode`,
+# config/reference.conf): "off" (unset) installs nothing of it; "optional" or
+# "required" installs the MFA package's modules (the TOTP, recovery-code and
+# email factors, the operator reset) and writes `mfa.mode` from the switch.
+# The MFA package's reference.conf holds the `mfa` section with its
+# variables: the key ring's first key, MFA_ENCRYPTION_KEY (`openssl rand
+# -base64 32`; none, and the boot is refused), and the page a step-up starts
+# on, MFA_PAGE_URL (`/mfa`). One Store call's time, MFA_STORE_TIMEOUT_MS
+# (5000 ms), must be at least every store's own per-call timeout, the user
+# directory's REPOSITORIES_USER_HTTP_TIMEOUT among them: raise the two
+# together; above 37500 ms the boot is refused. Mail --
+# the account-email proof, the email factor's codes -- goes through the mail
+# sender, which needs STANDARD_SMTP_MAIL_SENDER_HOST and
+# STANDARD_SMTP_MAIL_SENDER_FROM outside development. While MFA is off,
+# nothing written under `mfa` is read.
 
-# #593: federation grants — a user's standing consent that a backend or an
+# 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
+# `adapters.federationGrantStore` and `.federationGrantIntentStore` select
+# (none by default, which boot refuses naming the store) 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}
-}
+# missing. Connections and the Redis grant store's key ring have no
+# environment form; write them in a deployment-owned HOCON layer (README:
+# Federation Grants). The section's defaults and its other variables
+# (FEDERATION_GRANTS_IDENTITY_LOOKUP, FEDERATION_GRANTS_CONSENT_URL) are the
+# federation-grants package's reference.conf, and the Redis grant store's
+# (REDIS_FEDERATION_GRANT_STORE_ENCRYPTION_MODE, "required" by default) the
+# Redis package's: each is layered only where a module of its package is
+# installed. The
+# template reads `federation-grants.enabled` before it chooses its modules,
+# from its own files, which is why this file binds FEDERATION_GRANTS_ENABLED;
+# unset, it writes nothing, and the feature is off.
+federation-grants.enabled = ${?FEDERATION_GRANTS_ENABLED}
 
-# "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
-# DEPLOYMENT_MODE=multi by name); "redis" (#561) keeps the consent records and
-# the requests parked while the consent page asks on the shared ioredis socket,
-# and is what a deployment of more than one replica selects. Its key namespace
-# is REDIS_CONSENT_STORE_KEY_PREFIX (default "consent:").
-consentStore {
-  adapter = "none"
-  adapter = ${?CONSENT_STORE_ADAPTER}
-}
-
-session {
-  secret = ${?SESSION_SECRET}
-  # MIN-2: __Host- prefix requires Secure, Path=/, and no Domain attribute.
-  # If SESSION_SECURE=false or SESSION_DOMAIN is set, also override
-  # SESSION_NAME to a non-__Host- value.
+# The session store's section: the session cookie and the store
+# express-session keeps sessions in. A memory store declares itself
+# replica-unsafe from this section.
+session-store {
+  secret = ${?SESSION_STORE_SECRET}
+  # A `__Host-` name requires Secure, Path=/ and no Domain attribute. If
+  # SESSION_STORE_SECURE=false or SESSION_STORE_DOMAIN is set, also set
+  # SESSION_STORE_NAME to a name without the prefix.
   name = "__Host-auth.session"
-  name = ${?SESSION_NAME}
+  name = ${?SESSION_STORE_NAME}
   maxAge = 3600000
-  maxAge = ${?SESSION_MAX_AGE}
+  maxAge = ${?SESSION_STORE_MAX_AGE}
   secure = true
-  secure = ${?SESSION_SECURE}
+  secure = ${?SESSION_STORE_SECURE}
   sameSite = "lax"
-  sameSite = ${?SESSION_SAME_SITE}
+  sameSite = ${?SESSION_STORE_SAME_SITE}
   domain = null
-  domain = ${?SESSION_DOMAIN}
-  # #405: every URL `POST /session/login` may accept as `redirect_to`, matched
+  domain = ${?SESSION_STORE_DOMAIN}
+  storage {
+    type = "redis"
+    type = ${?SESSION_STORE_STORAGE_TYPE}
+    redis {
+      url = "redis://localhost:6379"
+      url = ${?SESSION_STORE_STORAGE_REDIS_URL}
+      password = ${?SESSION_STORE_STORAGE_REDIS_PASSWORD}
+    }
+  }
+}
+
+# The session module's section: the login routes' settings.
+session {
+  # Every URL `POST /session/login` may accept as `redirect_to`, matched
   # EXACTLY -- scheme, host, port, path and query all significant. Empty (the
   # default) refuses every `redirect_to`, so leave it alone unless your login
   # page actually posts one.
   #
   #   redirectAllowlist = ["https://app.example.com/welcome"]
   #
-  # `http://` is accepted for loopback hosts only. With `domain` set above, an
-  # entry outside it fails boot rather than being silently ignored. The
-  # federation flow has a separate list per provider (see `federations` below).
+  # `http://` is accepted for loopback hosts only. With `session-store.domain`
+  # set above, an entry outside it fails boot rather than being silently
+  # ignored. The federation flow has a separate list per provider (see
+  # `core.federations` below).
   redirectAllowlist = []
-  storage {
-    type = "redis"
-    type = ${?SESSION_STORAGE_TYPE}
-    redis {
-      url = "redis://localhost:6379"
-      url = ${?SESSION_STORAGE_REDIS_URL}
-      password = ${?SESSION_STORAGE_REDIS_PASSWORD}
-    }
+  # POST /session/login's own attempt limit (brute-force protection), in
+  # windowMs (milliseconds), counted on the attempt counter
+  # (`adapters.attemptCounter`); kept in this layer so operators can tweak
+  # it. No rate limiter changes it. It does NOT govern OAuth endpoint rate
+  # limiting: the `rateLimiter` component
+  # (memoryRateLimiterModule or redisRateLimiterModule) reads its own section,
+  # `core-rate-limiter-memory` / `redis-rate-limiter` (with `windowSeconds`
+  # instead of `windowMs`). Switch via `adapters.rateLimiter = "memory" |
+  # "redis"` (see reference.conf). The Redis limiter's outage policy is its
+  # own key, `redis-rate-limiter.failMode` ("closed" by default;
+  # REDIS_RATE_LIMITER_FAIL_MODE sets it).
+  rateLimit {
+    login { windowMs = 900000, limit = 20 }
   }
 }
 
-# Rate limiting for SESSION routes (e.g. /session/login bruteforce protection).
-# Uses windowMs (milliseconds) — consumed by express-rate-limit in Session.mts.
-# NOTE (IH-18): this section does NOT govern OAuth endpoint rate limiting.
-#       For OAuth rate limiting (/token, /authorize), use the `rateLimiter`
-#       component (memoryRateLimiterModule or redisRateLimiterModule) with
-#       its own `memoryRateLimiter.*` / `redisRateLimiter.*` config section
-#       (uses `windowSeconds` instead of `windowMs`). Switch via
-#       `rateLimiter.adapter = "memory" | "redis"` (see reference.conf).
-rateLimit {
-  # `login` is per-deployment tuning (bruteforce-window + limit), kept in
-  # this layer so operators can tweak without forking reference.conf.
-  login { windowMs = 900000, limit = 20 }
-  # rateLimit.failMode: inherits reference.conf default ("closed").
-  # Deployments that prefer fail-open override here:
-  #   failMode = "open"
-  #   failMode = ${?RATE_LIMIT_FAIL_MODE}
-}
+# The MFA routes' budget, 60 per 300 s, is config/reference.conf's, given to
+# both limiters so that switching `adapters.rateLimiter` keeps it. Change it
+# for the limiter this deployment wires, in its own section:
+#
+#   redis-rate-limiter.limits.mfa { limit = 30, windowSeconds = 300 }
 
-federations {
+# The federations, in core's own section, keyed by the name 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>. Each entry
+# names its `type`, and boot hands an enabled entry to the module that handles
+# that type: the template loads the `google` and `oidc` types, so an entry of
+# either type under any name is a federation of its own. An entry without a
+# `type`, enabled or not, refuses the boot, and so does an enabled entry of a
+# type no loaded module handles.
+core.federations {
   # Template ships a Google federation declaration disabled-by-default.
-  # Operators enable + populate credentials via env vars.
+  # Operators enable + populate credentials via env vars. A second Google
+  # client is another entry with `type = "google"` and its own callbackURL.
   google {
     enabled = false
-    enabled = ${?FEDERATIONS_GOOGLE_ENABLED}
-    clientId = ${?FEDERATIONS_GOOGLE_CLIENT_ID}
-    clientSecret = ${?FEDERATIONS_GOOGLE_CLIENT_SECRET}
+    enabled = ${?CORE_FEDERATIONS_GOOGLE_ENABLED}
+    type = "google"
+    clientId = ${?CORE_FEDERATIONS_GOOGLE_CLIENT_ID}
+    clientSecret = ${?CORE_FEDERATIONS_GOOGLE_CLIENT_SECRET}
     callbackURL = "http://localhost:3000/session/oauth/federation/google/callback"
-    callbackURL = ${?FEDERATIONS_GOOGLE_CALLBACK_URL}
+    callbackURL = ${?CORE_FEDERATIONS_GOOGLE_CALLBACK_URL}
 
     # Every URL a `redirect_to` query parameter may name on
     # /session/oauth/federation/google. Matching is EXACT — scheme, host, port,
@@ -282,8 +258,8 @@ federations {
     #
     # An empty list refuses every `redirect_to`, which is the right setting for
     # a deployment that does not use the parameter. It is NOT a way to allow
-    # everything: before #278 an unset allowlist accepted any http(s) URL, which
-    # made this an open redirect. Nothing falls back to that any more.
+    # everything: nothing falls back to accepting any http(s) URL, which would
+    # make this an open redirect.
     #
     # https is required, except for a loopback host (localhost, 127.0.0.0/8,
     # [::1]) — that carve-out is what lets a local dev front-end and a native
@@ -299,20 +275,20 @@ federations {
     # Cookie / session domain. When set, every non-loopback redirectAllowlist
     # entry must be inside it, checked at boot — an entry outside it fails
     # startup rather than sitting here looking effective.
-    # sessionDomain = ${?FEDERATIONS_GOOGLE_SESSION_DOMAIN}
+    # sessionDomain = ${?CORE_FEDERATIONS_GOOGLE_SESSION_DOMAIN}
 
     # Post-callback bridge page. Required only if `redirect_to` is used at all:
     # the browser lands here as `<authCallbackUrl>?redirect_to=<encoded>`.
-    # authCallbackUrl = ${?FEDERATIONS_GOOGLE_AUTH_CALLBACK_URL}
+    # authCallbackUrl = ${?CORE_FEDERATIONS_GOOGLE_AUTH_CALLBACK_URL}
 
     # Where the browser goes after a callback carrying no `redirect_to`.
-    # clientUrl = ${?FEDERATIONS_GOOGLE_CLIENT_URL}
+    # clientUrl = ${?CORE_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}
+    # requireAuthorizationResponseIss = ${?CORE_FEDERATIONS_GOOGLE_REQUIRE_AUTHORIZATION_RESPONSE_ISS}
 
     # Whether sign-in asks Google for a refresh token. Unset is "offline":
     # every sign-in shows Google's consent screen, because Google issues a
@@ -320,11 +296,11 @@ federations {
     # POST /oauth/federation/google/token can refresh with. "online" shows the
     # consent screen on the first sign-in only and gets no refresh token at
     # all — for a deployment that uses Google to sign in and nothing more.
-    accessType = ${?FEDERATIONS_GOOGLE_ACCESS_TYPE}
+    accessType = ${?CORE_FEDERATIONS_GOOGLE_ACCESS_TYPE}
   }
 
   # Any OpenID Connect provider (Okta, Entra ID, Auth0, Keycloak, your own
-  # tenant) — `@o3co/auth-provider-federation-oidc` (#524). Disabled by
+  # tenant) — `@o3co/auth-provider-federation-oidc`. Disabled by
   # default; the env vars below switch this one instance on. The section
   # name is the federation name: the browser starts at
   # /session/oauth/federation/oidc and the identity handed to the Store is
@@ -333,19 +309,19 @@ federations {
   # another name (`okta { type = "oidc" ... }`) with its own callbackURL.
   oidc {
     enabled = false
-    enabled = ${?FEDERATIONS_OIDC_ENABLED}
+    enabled = ${?CORE_FEDERATIONS_OIDC_ENABLED}
     type = "oidc"
 
     # Issuer identifier, exactly as the IdP writes it into `iss`. Discovery
     # runs at boot from <issuer>/.well-known/openid-configuration and a
     # failure refuses boot. https only (plain http on localhost for dev).
-    issuer = ${?FEDERATIONS_OIDC_ISSUER}
-    clientId = ${?FEDERATIONS_OIDC_CLIENT_ID}
+    issuer = ${?CORE_FEDERATIONS_OIDC_ISSUER}
+    clientId = ${?CORE_FEDERATIONS_OIDC_CLIENT_ID}
     # client_secret_basic. For private_key_jwt drop clientSecret and set
     # privateKey (a PEM PKCS#8 key, or { pem, kid, alg }) instead.
-    clientSecret = ${?FEDERATIONS_OIDC_CLIENT_SECRET}
+    clientSecret = ${?CORE_FEDERATIONS_OIDC_CLIENT_SECRET}
     callbackURL = "http://localhost:3000/session/oauth/federation/oidc/callback"
-    callbackURL = ${?FEDERATIONS_OIDC_CALLBACK_URL}
+    callbackURL = ${?CORE_FEDERATIONS_OIDC_CALLBACK_URL}
     scopes = ["openid", "profile", "email"]
 
     # Same rules as the Google block above: exact URLs, https except on a
@@ -360,132 +336,15 @@ federations {
   }
 }
 
-repositories {
-  client {
-    type = "yaml"
-    type = ${?CLIENT_TYPE}
-    yaml {
-      path = "./config/clients.yaml"
-      path = ${?CLIENT_PATH}
-    }
-  }
-  user {
-    type = "http"
-    type = ${?CLIENT_USER_TYPE}
-    yaml {
-      path = "./config/users.yaml"
-    }
-    http {
-      # Both URLs carry plaintext user credentials, so both must be absolute
-      # https URLs. http:// is accepted only for a loopback host (localhost,
-      # 127.0.0.0/8, [::1]); a private-range address or a container-network
-      # service name still needs https. Boot fails if either is not. Each must
-      # also be the endpoint that answers: no request follows a 3xx, so a URL
-      # that redirects fails every call.
-      authenticateUrl = ${?CLIENT_USER_AUTHENTICATE_URL}
-      authenticateByTokenUrl = ${?CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL}
-      # #482: optional. When set, a signed-in user can link a second federated
-      # identity (GET /session/oauth/federation/<name>?link=1): the Store
-      # receives { userId, provider, sub, token, claims } and decides — never on
-      # an unverified or relay e-mail. Same https and no-redirect rule as the two URLs above.
-      # Also declared in core's reference.conf, so a composition that does not
-      # layer this file gets the same override.
-      # Without it, link=1 is refused with link_unsupported.
-      linkFederatedIdentityUrl = ${?CLIENT_USER_LINK_FEDERATED_IDENTITY_URL}
-      # #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 and no-redirect 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}
-      # Optional. Sent on every Store request as `Authorization: Bearer <token>`
-      # so the Store can refuse any caller but this deployment; unset, none is
-      # sent. A bare token (no "Bearer " prefix), at least 32 bytes of key
-      # material -- `openssl rand -hex 32`. Boot fails on a weak, malformed or
-      # blank value. One token goes to every URL above: one trust domain. A
-      # Store that refuses it with 401 (or 403) + `WWW-Authenticate: Bearer`
-      # makes every Store call an outage rather than a wrong password: 503 and
-      # a logged error at login, federation callbacks and the jwt-bearer
-      # grant; a temporarily_unavailable redirect and
-      # federation_grant_callback_unavailable (err.name
-      # StoreCredentialRefusedError) at the federation-grants callback. Also
-      # declared in core's reference.conf.
-      bearerToken = ${?CLIENT_USER_BEARER_TOKEN}
-      # Positive integer, milliseconds, <= 2147483647. Boot fails otherwise —
-      # including on a blank env override, which HOCON substitutes as "".
-      timeout = 5000
-      timeout = ${?CLIENT_USER_TIMEOUT}
-      # Largest upstream response body accepted, in bytes. Positive integer.
-      maxResponseBytes = 1048576
-      maxResponseBytes = ${?CLIENT_USER_MAX_RESPONSE_BYTES}
-    }
-  }
-  code {
-    type = "redis"
-    type = ${?CLIENT_CODE_TYPE}
-    memory {
-      defaultExpiresIn = 600
-      defaultExpiresIn = ${?CLIENT_CODE_DEFAULT_EXPIRES_IN}
-    }
-    redis {
-      defaultExpiresIn = 600
-      defaultExpiresIn = ${?CLIENT_CODE_DEFAULT_EXPIRES_IN}
-      endpointUri = ${?CLIENT_CODE_ENDPOINT_URI}
-      password = ${?CLIENT_CODE_PASSWORD}
-    }
-  }
-}
-
-endpoints {
-  login {
-    url = "/login"
-    url = ${?ENDPOINTS_LOGIN_URL}
-  }
-  # #527: the consent page a client that is not first-party is routed
-  # through (`?challenge=<id>`). Deployment-owned, like the login page: it
-  # reads GET /oauth/consent and posts to POST /oauth/consent.
-  consent {
-    url = "/consent"
-    url = ${?ENDPOINTS_CONSENT_URL}
-  }
-  # IH-10: `client { url }` and `authCallback { url }` removed — no
-  # production consumer reads them.
-}
-
-# #500: browser origins allowed to read the token, userinfo, revocation and
-# discovery/JWKS responses. Empty (the default) means CORS is off -- leave it
-# alone unless a browser app is served from a different origin than this
-# provider. See the library reference.conf for the full rules; the short
-# version is that matching is EXACT, so each entry is a bare origin with no
-# trailing slash, no path and no wildcard, and https is required off loopback.
-#
-#   allowedOrigins = ["https://app.example.com", "http://localhost:5173"]
-#
-# The env-override line is repeated at this layer for the HOCON precedence
-# reason the oauth.grants block above explains: application.conf wins over
-# reference.conf, so without it CORS_ALLOWED_ORIGINS could not take effect.
-# It takes a comma-separated list.
-#
-# Not to be confused with `session.csrf.trustedOrigins`, which answers the
-# other question (#272).
-cors {
-  allowedOrigins = []
-  allowedOrigins = ${?CORS_ALLOWED_ORIGINS}
+# The variables that set keys of the template's own modules, bound here, last,
+# so each wins over a value this file sets above it. Keep this block last.
+# config/reference.conf holds the defaults and binds the same variables.
+http {
+  port = ${?HTTP_PORT}
+  trustProxy = ${?HTTP_TRUST_PROXY}
+  cors.allowedOrigins = ${?HTTP_CORS_ALLOWED_ORIGINS}
 }
-
-# D-2 v2 + Wave 5d: ioredis connection-config consumed by the shared
-# `standaloneRedisClientsModule` in `templates/standalone/src/modules.mts`.
-# One ioredis socket per replica backs ALL Redis-typed clients (RT family
-# + 4 user-session stores + rate limiter). Multi-replica deployments MUST
-# point this at a shared Redis 7.2+ instance — without it, each replica
-# stores RT families in its own ioredis connection against a local-only
-# Redis, defeating the cross-replica persistence purpose.
-refreshTokenFamilyStore {
-  redis {
-    url = "redis://localhost:6379"
-    url = ${?REFRESH_TOKEN_FAMILY_STORE_REDIS_URL}
-    password = ${?REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD}
-  }
+redis-clients {
+  url = ${?REDIS_CLIENTS_URL}
+  password = ${?REDIS_CLIENTS_PASSWORD}
 }