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

package/templates/standalone/config/clients.yaml

@@ -1,2 +1,4 @@
 # Client definitions loaded via loadYamlMap into InMemoryClientRepository.
 # Add client entries here. See clients.yaml.example for format.
+# Per-deployment: `.gitignore` keeps this file out of git and `.dockerignore`
+# out of the image (#705).

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

@@ -1,6 +1,10 @@
 # Example client definitions loaded via loadYamlMap into InMemoryClientRepository.
 # Copy this file to clients.yaml and customize for your deployment.
 #
+# clients.yaml is per-deployment (#705): `.gitignore` keeps it out of git and
+# `.dockerignore` out of the image, and docker-compose.production.yml mounts it
+# as the secret `client_registry`. This example is the committed one.
+#
 # `tokenEndpointAuthMethod` is REQUIRED (RFC 6749 §2.3 / RFC 7591 §2):
 #   - "client_secret_basic": HTTP Basic Authorization header — recommended for confidential clients
 #   - "client_secret_post":  form-encoded body parameters

package/templates/standalone/config/development.conf

@@ -2,7 +2,16 @@
 # Loaded when CONFIG_ENV (or NODE_ENV) is "development" — the default.
 # Values here override application.conf.
 #
-# Most values are controlled via environment variables (see ${?VAR}
-# substitutions in application.conf). Override entries here only when
-# you need a fixed development-specific value that cannot come from
-# an environment variable.
+# Most values are controlled via environment variables (see the ${?VAR}
+# substitutions in application.conf and reference.conf). Override entries
+# here only when you need a fixed development-specific value that cannot come
+# from an environment variable.
+
+# 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
+# `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

@@ -0,0 +1,8 @@
+# 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"

package/templates/standalone/config/production.conf

@@ -2,14 +2,13 @@
 # Loaded when CONFIG_ENV (or NODE_ENV) is "production".
 # Values here override application.conf.
 #
-# Most production-sensitive values (SESSION_SECRET, the JWT signing key, REDIS
+# Most production-sensitive values (SESSION_STORE_SECRET, the JWT signing key, REDIS
 # URLs, federation client secrets, etc.) should be supplied via environment
-# variables — see the ${?VAR} substitutions in application.conf.
+# variables — see the ${?VAR} substitutions in application.conf and
+# reference.conf.
 #
-# #407: this used to name OAUTH_JWT_SECRET as the typical example. That is the
-# HMAC secret, and it stopped being the default when EdDSA became one (#282) —
-# the shipped path is now a key pair delivered as files
-# (OAUTH_JWT_PRIVATE_KEY_PATH / OAUTH_JWT_PUBLIC_KEY_PATH), which
+# The signing key is a key pair delivered as files
+# (KEY_STORE_LOCAL_PRIVATE_KEY_PATH / KEY_STORE_LOCAL_PUBLIC_KEY_PATH), which
 # docker-compose.production.yml mounts as compose secrets.
 #
 # Override entries here only when a value must be fixed per-environment rather

package/templates/standalone/config/reference.conf

@@ -0,0 +1,418 @@
+# Defaults of the standalone template's own modules (src/modules.mts), each in
+# the section named after its module, and of its own `adapters` and
+# `mfaMode`, each key with its variable, named after its path, and the MFA
+# routes' budget in each rate limiter's section (below `mfaMode`). Layered
+# beneath application.conf and {env}.conf: set a deployment's own values
+# there, not here. A value either file sets wins over
+# the variable bound here, except for HTTP_PORT, HTTP_TRUST_PROXY,
+# HTTP_CORS_ALLOWED_ORIGINS and REDIS_CLIENTS_URL / _PASSWORD, which
+# application.conf binds again in its last lines, so they win over a value it
+# sets above them.
+
+# `logging`: trace | debug | info | warn | error | fatal | silent. `trace` and
+# `debug` carry request-shaped detail; `silent` spares only the audit trail.
+logging {
+  level = "info"
+  level = ${?LOGGING_LEVEL}
+}
+
+# `http`: the listener, the trusted forwarding hops, the readiness deadline and
+# the CORS list.
+http {
+  port = 3000
+  port = ${?HTTP_PORT}
+  # Express `trust proxy`: whether X-Forwarded-For may rewrite `req.ip`
+  # (every IP-keyed rate limit) and X-Forwarded-Proto may rewrite
+  # `req.protocol`.
+  #
+  # Four shapes, all of them Express's own:
+  #
+  #   false          trust nothing. `req.ip` is the socket peer. The default.
+  #   <address list> trust these hops, and only these. An IP literal, a CIDR
+  #                  range (10.0.0.0/8, fc00::/7), or a named range
+  #                  (loopback, linklocal, uniquelocal). This is the only
+  #                  shape that says WHICH hop is trusted, and it is the one
+  #                  to reach for. Via env var, comma-separate:
+  #                  HTTP_TRUST_PROXY=10.0.0.0/8,192.168.0.0/16
+  #   <hop count>    trust that many hops back from the socket peer, e.g. 1
+  #                  for exactly one reverse proxy in front of this process.
+  #   true           trust every hop, i.e. believe the leftmost
+  #                  X-Forwarded-For entry from whoever opened the connection.
+  #                  Correct ONLY when nothing but the proxy can route to this
+  #                  process; otherwise a client that reaches it directly, or
+  #                  through one more hop than you accounted for, forges its
+  #                  own `req.ip` and with it any IP-keyed rate-limit identity.
+  #
+  # Entries are validated at boot: a hostname, a mistyped keyword or a
+  # malformed prefix length fails loudly rather than becoming a rule that
+  # never matches.
+  #
+  # An allowlist is a network control, not a cryptographic one. The edge must
+  # also STRIP inbound X-Forwarded-* headers rather than appending to them,
+  # and the hop between it and this process must not be reachable by anyone
+  # able to spoof a source address.
+  #
+  # Unrelated to `mtls.trustedProxies`, which shares this vocabulary but
+  # answers a different question (may this peer forward a client certificate?)
+  # and is deliberately not derived from this key.
+  trustProxy = false
+  trustProxy = ${?HTTP_TRUST_PROXY}
+  # Per-probe deadline for /readyz and the metrics scrape's probes. Keep it
+  # below the orchestrator's own probe timeout so an unreachable dependency
+  # answers 503 rather than letting the probe hang.
+  readinessTimeoutMs = 1000
+  readinessTimeoutMs = ${?HTTP_READINESS_TIMEOUT_MS}
+  # `cors`: the browser origins allowed to read the token, userinfo,
+  # revocation and discovery/JWKS responses. Empty (the default) means CORS
+  # is off.
+  #
+  # Matching against the `Origin` request header is exact string equality,
+  # so each entry is a bare origin: scheme, host, and a port only when it is
+  # not the scheme's default; no trailing slash, no path, no wildcard. https
+  # is required except for a loopback host (localhost, 127.0.0.0/8, [::1]).
+  # Each rule is checked at boot.
+  #
+  #   cors.allowedOrigins = ["https://app.example.com", "http://localhost:5173"]
+  #
+  # No credentials are ever allowed: an allowlisted origin can read these
+  # responses and cannot use the browser's session cookie. This list confers
+  # no CSRF trust; that is `session.csrf.trustedOrigins`. The variable takes a
+  # comma-separated list.
+  cors {
+    allowedOrigins = []
+    allowedOrigins = ${?HTTP_CORS_ALLOWED_ORIGINS}
+  }
+}
+
+# `key-store`: the JWT signing key.
+key-store {
+  provider = "local"
+  provider = ${?KEY_STORE_PROVIDER}
+  local {
+    # The default is asymmetric. HS256 leaves a relying party with two bad
+    # options: verify nothing (there is no public key to publish, so
+    # /.well-known/jwks.json has nothing to serve), or hold the shared
+    # secret, which also lets it mint tokens. EdDSA (Ed25519) publishes a
+    # real JWKS and keeps signing capability here.
+    #
+    # There is no key material default and no fallback: a deployment that
+    # configures nothing fails at boot naming the keys to set, rather than
+    # quietly signing with a guessable secret.
+    #
+    #   openssl genpkey -algorithm ed25519 -out jwt-private.pem
+    #   openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
+    #
+    # HS256 remains selectable (KEY_STORE_LOCAL_ALGORITHM=HS256) for
+    # deployments that verify in-process and publish no JWKS. It then requires
+    # KEY_STORE_LOCAL_SECRET with at least 32 bytes (256 bits) of random material
+    # (`openssl rand -hex 32`). Hex and base64 values are measured decoded, so
+    # a 32-character hex string is only 16 bytes and is refused.
+    algorithm = "EdDSA"
+    algorithm = ${?KEY_STORE_LOCAL_ALGORITHM}
+    kid = "v0"
+    kid = ${?KEY_STORE_LOCAL_KID}
+    secret = ${?KEY_STORE_LOCAL_SECRET}
+    privateKeyPath = ${?KEY_STORE_LOCAL_PRIVATE_KEY_PATH}
+    publicKeyPath = ${?KEY_STORE_LOCAL_PUBLIC_KEY_PATH}
+    privateKey = ${?KEY_STORE_LOCAL_PRIVATE_KEY}
+    publicKey = ${?KEY_STORE_LOCAL_PUBLIC_KEY}
+    # Key rotation is shaped per algorithm family. Asymmetric algorithms
+    # (RS256, ES256, EdDSA) use `previousKeys` (kid, publicKey or
+    # publicKeyPath, expiresAt); HS256 uses `previousSecrets` (kid, secret,
+    # expiresAt). The schema is a discriminated union and the key store
+    # refuses the other family's field, so the wrong shape fails at boot
+    # rather than being dropped at verification time. Neither is declared
+    # here: the default algorithm is EdDSA, and an empty
+    # `previousSecrets = []` under it would be exactly that wrong shape. Add
+    # the one matching your algorithm in your own layer.
+  }
+}
+
+# `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.
+redis-clients {
+  url = "redis://localhost:6379"
+  url = ${?REDIS_CLIENTS_URL}
+  password = ${?REDIS_CLIENTS_PASSWORD}
+}
+
+# `repositories`: the client registry, and the user repository's settings for
+# each adapter it may be (`adapters.userRepository`). The two YAML paths are
+# cwd-relative.
+repositories {
+  client {
+    yaml {
+      path = "./config/clients.yaml"
+      path = ${?REPOSITORIES_CLIENT_YAML_PATH}
+    }
+  }
+  user {
+    yaml {
+      path = "./config/users.yaml"
+      path = ${?REPOSITORIES_USER_YAML_PATH}
+    }
+    # The Store's HTTP endpoints. Every URL here carries what a Store must
+    # never receive in the clear -- user credentials to the first two, a
+    # verified federation token and its claims to the link and the lookup, a
+    # subject's MFA enrollment witness to the last -- so each must be an
+    # absolute https URL; http:// is accepted only for a loopback host
+    # (localhost, 127.0.0.0/8, [::1]). Each must be the endpoint that answers:
+    # no request follows a 3xx. Boot fails otherwise.
+    http {
+      authenticateUrl = ${?REPOSITORIES_USER_HTTP_AUTHENTICATE_URL}
+      authenticateByTokenUrl = ${?REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL}
+      # Optional. With it, a signed-in user can link a second federated
+      # identity (GET /session/oauth/federation/<name>?link=1) and the Store
+      # decides; without it, link=1 is refused with `link_unsupported`.
+      linkFederatedIdentityUrl = ${?REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL}
+      # Optional. The Store's identity lookup for federation grants. With it,
+      # declare what the lookup covers, per registration, in a HOCON layer (a
+      # list has no environment form):
+      #   federatedIdentityLookupCoverage = [
+      #     { provider = "entra-files", issuer = "...", clientId = "...", requiredClaims = ["tid", "oid"] }
+      #   ]
+      findSubjectByFederatedIdentityUrl = ${?REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL}
+      federatedIdentityLookupCoverage = []
+      # Optional. The Store's MFA enrollment witness endpoint: with it, the
+      # provider writes whether a subject has a second factor, which keeps a
+      # lost factor store from opening a first binding; without it, a boot
+      # with MFA on warns (`mfa_enrollment_witness_unwritable`). The Store
+      # must then answer `mfaEnrolled` on both authenticate URLs.
+      markMfaEnrolledUrl = ${?REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_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) of 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.
+      bearerToken = ${?REPOSITORIES_USER_HTTP_BEARER_TOKEN}
+      # Positive integer, milliseconds, <= 2147483647.
+      timeout = 5000
+      timeout = ${?REPOSITORIES_USER_HTTP_TIMEOUT}
+      # Largest upstream response body accepted, in bytes. Positive integer.
+      maxResponseBytes = 1048576
+      maxResponseBytes = ${?REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES}
+    }
+  }
+}
+
+# `standalone-in-memory-code-repository`: the in-process authorization-code
+# repository (`adapters.codeRepository = "memory"`), single-replica only. Its
+# codes' default lifetime, in positive whole seconds.
+standalone-in-memory-code-repository {
+  defaultExpiresIn = 600
+  defaultExpiresIn = ${?STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN}
+}
+
+# `audit-sink`: each sink's options, under the sink's name, for the sink
+# `adapters.auditSink` selects -- `audit-sink { splunk-hec { ... } }` for a sink
+# a deployment registers in the audit-sink module (src/modules.mts). The
+# template's `logger` and core's `console` take none.
+audit-sink {}
+
+# `adapters`: the composition root's own section -- which adapter fills each
+# slot. The template reads it before it chooses its modules, and hands it to
+# no module. Each value is what the template ships.
+#
+# More than one replica needs every shared store on Redis: `memory` forks per
+# replica, and `core.deployment.mode = "multi"` refuses each memory store by
+# name. Each Redis store shares the one socket `redis-clients` opens.
+adapters {
+  # The rate-limit counters: the OAuth endpoints' and the MFA routes'.
+  rateLimiter = "memory"
+  rateLimiter = ${?ADAPTERS_RATE_LIMITER}
+  # The counter behind /session/login's own attempt limit
+  # (session.rateLimit.login), and device verification's
+  # (device-grant.rateLimit) when the device grant is added. `memory` wires
+  # none: each counts per process, which `core.deployment.mode = "multi"`
+  # refuses. `redis` needs a server whose maxmemory-policy is `noeviction`.
+  attemptCounter = "memory"
+  attemptCounter = ${?ADAPTERS_ATTEMPT_COUNTER}
+  # The four user-session stores and the subject-level revocation pair. They
+  # must be on Redis whenever express-session's store is, or a restart leaves
+  # every browser a session whose user session is gone.
+  userSessionStores = "memory"
+  userSessionStores = ${?ADAPTERS_USER_SESSION_STORES}
+  # The RFC 7009 access-token denylist, which POST /oauth/revoke writes and
+  # verification reads. On Redis, so a token revoked on one replica is revoked
+  # on every one.
+  accessTokenDenylist = "redis"
+  accessTokenDenylist = ${?ADAPTERS_ACCESS_TOKEN_DENYLIST}
+  # The `jti` single-use record behind private_key_jwt client authentication.
+  replaySeenSet = "redis"
+  replaySeenSet = ${?ADAPTERS_REPLAY_SEEN_SET}
+  # Consent to a client that is not first-party: "none" wires no store and
+  # such clients are refused at /authorize; "memory" is single-replica only;
+  # "redis" keeps the consent records and parked requests on the shared
+  # socket (key namespace REDIS_CONSENT_STORE_KEY_PREFIX).
+  consentStore = "none"
+  consentStore = ${?ADAPTERS_CONSENT_STORE}
+  # The upstream IdP tokens held for a session. "redis" needs its encryption
+  # key, REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY.
+  federationTokenStore = "memory"
+  federationTokenStore = ${?ADAPTERS_FEDERATION_TOKEN_STORE}
+  # Federation grants and acquisition's records, read only while
+  # `federation-grants.enabled`: "none" (the default) wires no store, and an
+  # enabled feature refuses boot naming the one it lacks; "memory" is
+  # single-replica only; "redis" is the shared socket. Redis grants need the
+  # subject boundary in Redis too (`userSessionStores = "redis"`): boot
+  # refuses the pairing with a memory one.
+  federationGrantStore = "none"
+  federationGrantStore = ${?ADAPTERS_FEDERATION_GRANT_STORE}
+  federationGrantIntentStore = "none"
+  federationGrantIntentStore = ${?ADAPTERS_FEDERATION_GRANT_INTENT_STORE}
+  # Where MFA factors ("memory", "redis" or "store") and MFA transactions
+  # ("memory" or "redis") are kept, for a composition that installs MFA.
+  mfaFactorStore = "memory"
+  mfaFactorStore = ${?ADAPTERS_MFA_FACTOR_STORE}
+  mfaTransactionStore = "memory"
+  mfaTransactionStore = ${?ADAPTERS_MFA_TRANSACTION_STORE}
+  # The authorization-code repository ("memory" loses codes on restart and
+  # across replicas).
+  codeRepository = "redis"
+  codeRepository = ${?ADAPTERS_CODE_REPOSITORY}
+  # The client registry (YAML), and the user repository: the Store's HTTP
+  # endpoints, or a YAML directory.
+  clientRepository = "yaml"
+  clientRepository = ${?ADAPTERS_CLIENT_REPOSITORY}
+  userRepository = "http"
+  userRepository = ${?ADAPTERS_USER_REPOSITORY}
+  # Where the audit trail goes: "logger" writes each event through the pino
+  # stream every other line takes; core's "console" writes the bare event.
+  # There is no "none": a name no sink is registered under refuses boot.
+  auditSink = "logger"
+  auditSink = ${?ADAPTERS_AUDIT_SINK}
+}
+
+# `mfaMode`: the composition root's own key -- whether the template installs
+# MFA. Read before it chooses its modules, and handed to no module, as
+# `adapters` is. "required" (the default: every password login has a second
+# factor) and "optional" (users with a factor are challenged) install the MFA
+# package's modules over the two MFA stores above, declare `mfa` in
+# core.sessionRequirements.expected and write `mfa.mode` from this; "off"
+# installs nothing of MFA. Anything else is refused before boot. A
+# configuration that writes `mfa.mode` itself must write what this says, or
+# boot is refused.
+#
+# With MFA on outside development, it needs its two stores on "redis" (or the
+# factors in the "store"), MFA_ENCRYPTION_KEY, an SMTP relay
+# (STANDARD_SMTP_MAIL_SENDER_HOST and _FROM) or the deployment's own mail
+# sender, and a page served at MFA_PAGE_URL (/mfa unless set); a deployment
+# that wants none of it sets MFA_MODE=off.
+mfaMode = "required"
+mfaMode = ${?MFA_MODE}
+
+# The MFA routes' budget: the one setting this file writes in sections of
+# modules other than the template's own. Every /session/mfa POST is limited
+# per client address under the prefix `mfa` (`mfa:ip:<ip>`) by the wired
+# limiter alone: the MFA package ships no budget of its own. Both limiters
+# carry it, so switching `adapters.rateLimiter` keeps it; written here, beside
+# each package's own defaults, the limiter not wired has it as a default
+# rather than as a setting nothing reads. Without an entry the limiter's
+# `defaultLimit` (60 per 60 s) applies. The MFA lock is separate and unchanged.
+core-rate-limiter-memory.limits.mfa { limit = 60, windowSeconds = 300 }
+redis-rate-limiter.limits.mfa { limit = 60, windowSeconds = 300 }
+
+# The old paths of these sections refuse boot naming the new ones: `cors`,
+# `oauth.jwt.signingKey`, `refreshTokenFamilyStore.redis`,
+# `repositories.code` and `audit.sink`; the old adapter switches
+# (`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.
+# Never write it in another layer.
+renamed-variables {
+  LOG_LEVEL = null
+  LOG_LEVEL = ${?LOG_LEVEL}
+  LOGGING_LEVEL = null
+  LOGGING_LEVEL = ${?LOGGING_LEVEL}
+  CORS_ALLOWED_ORIGINS = null
+  CORS_ALLOWED_ORIGINS = ${?CORS_ALLOWED_ORIGINS}
+  HTTP_CORS_ALLOWED_ORIGINS = null
+  HTTP_CORS_ALLOWED_ORIGINS = ${?HTTP_CORS_ALLOWED_ORIGINS}
+  OAUTH_JWT_SIGNING_KEY_PROVIDER = null
+  OAUTH_JWT_SIGNING_KEY_PROVIDER = ${?OAUTH_JWT_SIGNING_KEY_PROVIDER}
+  KEY_STORE_PROVIDER = null
+  KEY_STORE_PROVIDER = ${?KEY_STORE_PROVIDER}
+  OAUTH_JWT_ALGORITHM = null
+  OAUTH_JWT_ALGORITHM = ${?OAUTH_JWT_ALGORITHM}
+  KEY_STORE_LOCAL_ALGORITHM = null
+  KEY_STORE_LOCAL_ALGORITHM = ${?KEY_STORE_LOCAL_ALGORITHM}
+  OAUTH_JWT_KID = null
+  OAUTH_JWT_KID = ${?OAUTH_JWT_KID}
+  KEY_STORE_LOCAL_KID = null
+  KEY_STORE_LOCAL_KID = ${?KEY_STORE_LOCAL_KID}
+  OAUTH_JWT_SECRET = null
+  OAUTH_JWT_SECRET = ${?OAUTH_JWT_SECRET}
+  KEY_STORE_LOCAL_SECRET = null
+  KEY_STORE_LOCAL_SECRET = ${?KEY_STORE_LOCAL_SECRET}
+  OAUTH_JWT_PRIVATE_KEY_PATH = null
+  OAUTH_JWT_PRIVATE_KEY_PATH = ${?OAUTH_JWT_PRIVATE_KEY_PATH}
+  KEY_STORE_LOCAL_PRIVATE_KEY_PATH = null
+  KEY_STORE_LOCAL_PRIVATE_KEY_PATH = ${?KEY_STORE_LOCAL_PRIVATE_KEY_PATH}
+  OAUTH_JWT_PUBLIC_KEY_PATH = null
+  OAUTH_JWT_PUBLIC_KEY_PATH = ${?OAUTH_JWT_PUBLIC_KEY_PATH}
+  KEY_STORE_LOCAL_PUBLIC_KEY_PATH = null
+  KEY_STORE_LOCAL_PUBLIC_KEY_PATH = ${?KEY_STORE_LOCAL_PUBLIC_KEY_PATH}
+  OAUTH_JWT_PRIVATE_KEY = null
+  OAUTH_JWT_PRIVATE_KEY = ${?OAUTH_JWT_PRIVATE_KEY}
+  KEY_STORE_LOCAL_PRIVATE_KEY = null
+  KEY_STORE_LOCAL_PRIVATE_KEY = ${?KEY_STORE_LOCAL_PRIVATE_KEY}
+  OAUTH_JWT_PUBLIC_KEY = null
+  OAUTH_JWT_PUBLIC_KEY = ${?OAUTH_JWT_PUBLIC_KEY}
+  KEY_STORE_LOCAL_PUBLIC_KEY = null
+  KEY_STORE_LOCAL_PUBLIC_KEY = ${?KEY_STORE_LOCAL_PUBLIC_KEY}
+  REFRESH_TOKEN_FAMILY_STORE_REDIS_URL = null
+  REFRESH_TOKEN_FAMILY_STORE_REDIS_URL = ${?REFRESH_TOKEN_FAMILY_STORE_REDIS_URL}
+  REDIS_CLIENTS_URL = null
+  REDIS_CLIENTS_URL = ${?REDIS_CLIENTS_URL}
+  REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD = null
+  REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD = ${?REFRESH_TOKEN_FAMILY_STORE_REDIS_PASSWORD}
+  REDIS_CLIENTS_PASSWORD = null
+  REDIS_CLIENTS_PASSWORD = ${?REDIS_CLIENTS_PASSWORD}
+  CLIENT_PATH = null
+  CLIENT_PATH = ${?CLIENT_PATH}
+  REPOSITORIES_CLIENT_YAML_PATH = null
+  REPOSITORIES_CLIENT_YAML_PATH = ${?REPOSITORIES_CLIENT_YAML_PATH}
+  CLIENT_USER_PATH = null
+  CLIENT_USER_PATH = ${?CLIENT_USER_PATH}
+  REPOSITORIES_USER_YAML_PATH = null
+  REPOSITORIES_USER_YAML_PATH = ${?REPOSITORIES_USER_YAML_PATH}
+  CLIENT_USER_AUTHENTICATE_URL = null
+  CLIENT_USER_AUTHENTICATE_URL = ${?CLIENT_USER_AUTHENTICATE_URL}
+  REPOSITORIES_USER_HTTP_AUTHENTICATE_URL = null
+  REPOSITORIES_USER_HTTP_AUTHENTICATE_URL = ${?REPOSITORIES_USER_HTTP_AUTHENTICATE_URL}
+  CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL = null
+  CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL = ${?CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL}
+  REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL = null
+  REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL = ${?REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL}
+  CLIENT_USER_LINK_FEDERATED_IDENTITY_URL = null
+  CLIENT_USER_LINK_FEDERATED_IDENTITY_URL = ${?CLIENT_USER_LINK_FEDERATED_IDENTITY_URL}
+  REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL = null
+  REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL = ${?REPOSITORIES_USER_HTTP_LINK_FEDERATED_IDENTITY_URL}
+  CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL = null
+  CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL = ${?CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL}
+  REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL = null
+  REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL = ${?REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL}
+  CLIENT_USER_BEARER_TOKEN = null
+  CLIENT_USER_BEARER_TOKEN = ${?CLIENT_USER_BEARER_TOKEN}
+  REPOSITORIES_USER_HTTP_BEARER_TOKEN = null
+  REPOSITORIES_USER_HTTP_BEARER_TOKEN = ${?REPOSITORIES_USER_HTTP_BEARER_TOKEN}
+  CLIENT_USER_TIMEOUT = null
+  CLIENT_USER_TIMEOUT = ${?CLIENT_USER_TIMEOUT}
+  REPOSITORIES_USER_HTTP_TIMEOUT = null
+  REPOSITORIES_USER_HTTP_TIMEOUT = ${?REPOSITORIES_USER_HTTP_TIMEOUT}
+  CLIENT_USER_MAX_RESPONSE_BYTES = null
+  CLIENT_USER_MAX_RESPONSE_BYTES = ${?CLIENT_USER_MAX_RESPONSE_BYTES}
+  REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES = null
+  REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES = ${?REPOSITORIES_USER_HTTP_MAX_RESPONSE_BYTES}
+  CLIENT_CODE_DEFAULT_EXPIRES_IN = null
+  CLIENT_CODE_DEFAULT_EXPIRES_IN = ${?CLIENT_CODE_DEFAULT_EXPIRES_IN}
+  STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN = null
+  STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN = ${?STANDALONE_IN_MEMORY_CODE_REPOSITORY_DEFAULT_EXPIRES_IN}
+  CLIENT_CODE_ENDPOINT_URI = null
+  CLIENT_CODE_ENDPOINT_URI = ${?CLIENT_CODE_ENDPOINT_URI}
+  CLIENT_CODE_PASSWORD = null
+  CLIENT_CODE_PASSWORD = ${?CLIENT_CODE_PASSWORD}
+}

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

@@ -0,0 +1,36 @@
+# Mailpit for the SMTP mail sender: a DEVELOPMENT overlay on
+# docker-compose.yml, for a run with MFA on (the template's default, or
+# MFA_MODE in .env) whose mail you can read.
+#
+#   docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
+#
+# 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
+# STANDARD_SMTP_MAIL_SENDER_* unset in .env for this run, USER and PASSWORD
+# included: the overlay sets HOST, PORT, SECURE and FROM, not the credentials.
+#
+# The SMTP sender sends in plaintext (`none`) only to a loopback host, so
+# Mailpit shares the app container's network namespace and listens on its
+# localhost, and the app service publishes Mailpit's web UI. The configuration
+# is selected as `mailpit` (config/mailpit.conf, the development overlay
+# under another name), since under `development` the template installs the
+# sender that logs each code instead. Under that name the MFA stores may not
+# be kept in memory, so both are on the Redis docker-compose.yml runs.
+
+services:
+  app:
+    ports:
+      - "127.0.0.1:8025:8025"
+    environment:
+      CONFIG_ENV: mailpit
+      ADAPTERS_MFA_FACTOR_STORE: redis
+      ADAPTERS_MFA_TRANSACTION_STORE: redis
+      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
+
+  mailpit:
+    image: axllent/mailpit:v1.31.3
+    network_mode: service:app