@o3co/create-auth-provider 0.15.0 → 0.16.0

package/templates/standalone/README.md

@@ -1,21 +1,85 @@
 # @o3co/auth-provider-standalone
 
+Last updated: 2026-09-26
+
 Deployable server template for auth.provider. This is the composition root — it reads config, loads modules, and starts the Express server. Generated by `@o3co/create-auth-provider`.
 
+## Responsibility
+
+**Role.** The composition root and the starting point for a deployment. It is
+not a library: nothing imports it. `@o3co/create-auth-provider` copies it into
+a new project, and from then on the operator owns and edits the copy. It sits
+on top of the packages: it composes `@o3co/auth-provider-oauth`, `-session`,
+the Google and generic OpenID Connect federation adapters, `-federation-grants`,
+`-redis` and `-foundation` over `@o3co/auth-provider-core`.
+
+**Owns** the choices that are specific to one deployment:
+
+- which modules are composed, in what order, and which adapter fills each
+  store slot — [`src/buildModules.mts`](src/buildModules.mts) (see
+  [Module Composition Order](#module-composition-order));
+- the modules only this scaffold has — the signing key store, the client and
+  user repositories, the audit sink, the one shared Redis connection, the
+  in-memory user-session stores, code repository and federation token store,
+  and the federation config bridges — [`src/modules.mts`](src/modules.mts).
+  They are the scaffold's rather than a package's because each builds its
+  component from this template's configuration sections; a deployment that
+  wants another source wires its own module of the same shape;
+- where configuration comes from and how its layers stack —
+  [`src/configPath.mts`](src/configPath.mts) and [`config/`](config/);
+- the host process: the Express app, its security headers and startup —
+  [`src/app.mts`](src/app.mts); the health, readiness and metrics routes, the
+  composed router and core's terminal error handler after them, in the order
+  they are mounted — [`src/routes.mts`](src/routes.mts); the listener, which logs `server_listening`
+  (info, `port`) once its socket is bound, fails boot with the bind error
+  when it cannot be, and logs any later server error as `server_error`
+  (error) — [`src/listen.mts`](src/listen.mts). Every error this code logs — an unhandled
+  request error, the shared Redis connection's `error` event, a failed
+  shutdown — is logged as core's
+  [`loggableError`](../../packages/core/README.md#logger) projection, never the
+  error, which can carry what an upstream or Redis said (the connection's
+  error carries the `AUTH` handshake, password included, when the server
+  refuses it);
+- the concrete logger and audit stream (pino) —
+  [`src/logger.mts`](src/logger.mts) — and the metrics
+  ([`src/metrics.mts`](src/metrics.mts));
+- process lifecycle: signal handling with a drain deadline —
+  [`src/shutdown.mts`](src/shutdown.mts);
+- packaging: the `Dockerfile`, the compose files, the `Makefile`;
+- its tests: `src/__tests__/`, which `pnpm run test` and `make test` run against
+  this composition, and `tests/`, a separate black-box API suite with its own
+  `package.json`, run against a server that is already up (`API_BASE_URL`).
+  Among what `src/__tests__/` holds: every module this template can turn on
+  boots together and keeps the contracts that exist only when they meet — one
+  discovery document, each module's body rules in either mount order, a store
+  or repository outage answered 503 and logged once — pinned by
+  `all-modules-composition.test.mts`.
+
+**Does not own** the HTTP API, the grants, the token format, how each store
+behaves, or the config schema — the packages do. Change those upstream, not
+here.
+
+**Why separate.** Everything above is a per-deployment decision, so it is kept
+out of the published libraries and put in a tree the operator is expected to
+modify. It is `"private": true` and never published itself; it reaches users
+only through the scaffolder. A scaffolded copy carries this README too; its
+relative links into `../../docs` and `../../packages` resolve only inside this
+repository.
+
 ## Requirements
 
 - **Node.js** `>=22.0.0`
 - **`bcrypt` native binary**: this template depends transitively on `bcrypt@6.x`, which ships **prebuilt N-API binaries** for `darwin-arm64`, `darwin-x64`, `linux-x64` (glibc and musl), `linux-arm64` (glibc and musl), `linux-arm`, `win32-x64`, and `win32-arm64`. On these platforms `pnpm install` succeeds without compiling from source, and no extra toolchain is required (the `darwin-*`, `node:*-alpine`, and `node:*-bookworm` images all match a shipped prebuild). On platforms or libc/arch combinations that have no matching prebuild, `pnpm install` falls back to compiling, which then requires a C++ compiler and Python (the standard Node.js native-addon toolchain): Debian/Ubuntu `apt-get install build-essential python3`, Alpine `apk add make g++ python3`, macOS `xcode-select --install`. The pnpm 10 `onlyBuiltDependencies` allowlist for `bcrypt` lives in `pnpm-workspace.yaml` — pnpm ≥10.29 reads it only from there, in single-package projects too. `create-auth-provider` writes that file into the project it scaffolds (inside this monorepo, the allowlist sits in the workspace root's `pnpm-workspace.yaml`); without it a fresh `pnpm install` silently skips the install hook on those platforms.
 - **Redis 7.2 LTS or later** for any Redis-backed adapter (refresh token family store, code repository, federation token store, session store). The `pExpireGT` flag pair on which several adapters depend was introduced in Redis 7.0+; 7.2 LTS is the tested floor. Tested against AWS ElastiCache for Redis 7.2, Upstash Redis, Redis Cloud 7.2, and self-managed `redis:7.2-alpine`.
-- **ioredis** `^6.0.0` (direct runtime dependency). Every `@o3co/auth-provider-redis` adapter this template wires — refresh-token families, authorization codes, rate-limit counters, the access-token denylist, the user-session stores, the federation-token store — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica (`makeIoredisClients`). The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
+- **ioredis** `^6.0.0` (direct runtime dependency). Every `@o3co/auth-provider-redis` adapter this template wires — refresh-token families, authorization codes, rate-limit counters, the access-token denylist, the replay seen-set, the user-session stores, the federation-token store, the consent stores and the federation-grant stores — runs off the one ioredis connection `standaloneRedisClientsModule` opens per replica. The same module provides the client of every other store the Redis package ships — the device-code store and the WebAuthn challenge store — so a deployment that adds the device grant or WebAuthn to `buildModules.mts` with a Redis store finds its client there. The `redis` npm package (`^6.2.1`) stays a dependency for one thing: `connect-redis` takes a node-redis client, so the `express-session` store behind `SESSION_STORAGE_TYPE=redis` is a second, separate connection (the `session-store` probe in `/readyz`).
 
 ## First-party clients
 
-`GET /authorize` mints an authorization code as soon as the user's session is authenticated. There is **no consent step**: the user is never asked whether this client may have their identity.
+For a client marked `firstParty: true`, `GET /authorize` mints an authorization code as soon as the user's session is authenticated. There is **no consent step**: the user is never asked whether this client may have their identity.
 
 That is a coherent model for a **first-party** OP — one where every registered client is operated by you — and it is coherent nowhere else. A page you do not control can force a top-level navigation to `/authorize?client_id=X&redirect_uri=...&code_challenge=<theirs>`, a logged-in user's browser mints a code bound to *their* session, it is delivered to X's registered `redirect_uri`, and whoever chose the `code_challenge` redeems it for tokens carrying that user's identity.
 
-So the assumption is enforced rather than assumed. A client must carry `firstParty: true` in its registration to use `/authorize`; anything else is refused with `unauthorized_client`. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
+So the assumption is enforced rather than assumed. Every other client — one with no `firstParty` field and one carrying `false` alike — goes through the consent step: the user is asked on your consent page before a code is minted. That step needs a consent store, and the template ships none (`CONSENT_STORE_ADAPTER=none`), so on the defaults such a client is refused at `/authorize` with `unauthorized_client`; see [Consent Store](#consent-store) to serve it. Mark a client first-party only if you would be comfortable with it receiving a user's identity **without the user being asked**.
 
 ```yaml
 # config/clients.yaml
@@ -31,9 +95,9 @@ A machine client can authenticate with a key instead of a shared secret (#484):
 [oauth package README](../../packages/oauth/README.md#client-authentication-private_key_jwt-rfc-7523-22).
 Nothing secret lives in `clients.yaml` for such a client.
 
-**What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident. The step that changes the former is a consent screen, tracked separately.
+**What this does not do.** It does not make `/authorize` safe against forced navigation for a client that *is* first-party — that remains the accepted model here. What it prevents is a client that should never have been trusted with a silent code being registered into that position by accident.
 
-**Migrating.** Registrations that predate the field are refused at `/authorize` until you mark them — a client with no `firstParty` field and one carrying an explicit `false` are treated alike. Mark every client you operate before pointing it at `/authorize`; there is no admit-with-warning window. The one-time `oauth.authorize.allowUnmarkedClients` migration flag was removed before it ever shipped in a release, and a config or environment still setting it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot with migration instructions rather than being silently ignored.
+**Unmarked registrations.** A registration without the field is not first-party: on the defaults it is refused at `/authorize` until you mark it, with no admit-with-warning window. Mark every client you operate before pointing it at `/authorize`. `oauth.authorize.allowUnmarkedClients` is not a setting: a config or environment that sets it (`OAUTH_AUTHORIZE_ALLOW_UNMARKED_CLIENTS`, any value) fails at boot with migration instructions rather than being silently ignored.
 
 ## Multi-replica deployments
 
@@ -41,9 +105,9 @@ The [operator runbook](../../docs/operator-runbook.md) covers the operational si
 
 When running multiple instances of the standalone server behind a load balancer, point `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` at a **shared** Redis 7.2+ instance. Without a shared Redis URL, every replica holds refresh-token families in its own connection (and any local-only Redis), so a refresh request that lands on a replica that did not issue the token returns `invalid_grant` on every other request in a round-robin LB.
 
-**Set `HTTP_TRUST_PROXY` to your proxy's address behind a load balancer.** It defaults to `false`, which makes `req.ip` the *load balancer's* address rather than the client's. Every rate limit keyed by IP — the OAuth endpoint limiters and the `POST /session/login` brute-force guard — then shares **one bucket across all users**: the first 20 login attempts from anyone exhaust the window and every subsequent user gets `429`. The failure reads like an attack rather than a misconfiguration, which is what makes it expensive to diagnose at 3am. Set it whenever anything terminates TLS or proxies in front of this service, and make sure that hop is the one setting `X-Forwarded-For`.
+**Set `HTTP_TRUST_PROXY` to your proxy's address behind a load balancer.** It defaults to `false`, which makes `req.ip` the *load balancer's* address rather than the client's. Every rate limit keyed by IP — the OAuth endpoint limiters and the `POST /session/login` brute-force guard — then shares **one bucket across all users**: the first 20 login attempts from anyone exhaust the window and every subsequent user gets `429`. The failure reads like an attack rather than a misconfiguration, which is what makes it expensive to diagnose at 3am. Set it whenever anything terminates TLS or proxies in front of this service, and make sure that hop is the one setting `X-Forwarded-For`. An audit event with no `ip` means the request's address was not an address — `req.ip` came from an `X-Forwarded-For` that held something else — so check that `HTTP_TRUST_PROXY` trusts only the hop that sets the header.
 
-Since #292 it takes four shapes, all of them Express's own:
+It takes four shapes, all of them Express's own:
 
 | Value | Meaning |
 |---|---|
@@ -56,7 +120,7 @@ Since #292 it takes four shapes, all of them Express's own:
 
 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.
 
-**Point `rateLimiter.adapter` at Redis.** It defaults to `"memory"`, which is per-process: with N replicas every configured limit is effectively N times larger and resets on every deploy. The memory adapter is also **evadable under bucket exhaustion**: it caps itself at 10,000 buckets and, at the cap, admitting a new key evicts the bucket closest to reset — so an attacker who can present many source IPs (and `req.ip` is client-influenced whenever `HTTP_TRUST_PROXY` is broader than your actual hops) can churn the table until a target's counter is evicted and starts over. That is acceptable for one dev process; it is not a production rate limit. Since #270 the login guard runs on this same shared component, so one setting covers both the OAuth endpoints and `/session/login`. The login window and limit stay configured at `rateLimit.login`; both adapters seed their own `limits.login` from it, so there is nothing to restate.
+**Point `rateLimiter.adapter` at Redis.** It defaults to `"memory"`, which is per-process: with N replicas every configured limit is effectively N times larger and resets on every deploy. The memory adapter is also **evadable under bucket exhaustion**: it caps itself at 10,000 buckets and, at the cap, admitting a new key evicts the bucket closest to reset — so an attacker who can present many source IPs (and `req.ip` is client-influenced whenever `HTTP_TRUST_PROXY` is broader than your actual hops) can churn the table until a target's counter is evicted and starts over. That is acceptable for one dev process; it is not a production rate limit. The login guard runs on this same shared component, so one setting covers both the OAuth endpoints and `/session/login`. The login window and limit stay configured at `rateLimit.login`; both adapters seed their own `limits.login` from it, so there is nothing to restate.
 
 **Behind a BFF, raise `limits.token` before you need to.** The OAuth-endpoint
 rate limits key on `req.ip` (`packages/core/src/ratelimit/guard.mts` builds the
@@ -101,7 +165,7 @@ raising it globally to accommodate one topology would weaken it for the other.
 Put the throttling that protects the BFF's *own* users in front of the BFF,
 where per-user identity still exists.
 
-**Set `DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, DPoP proof-replay detection forking. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`USER_SESSION_STORES_ADAPTER=memory`), the authorization-code repository (`OAUTH_CODE_ADAPTER=memory`) and the federation token store (`FEDERATION_TOKEN_STORE_TYPE=memory`, the default) — are refused by name too; before #455 they booted under `multi`. Since #474 that includes express-session's own store under `SESSION_STORAGE_TYPE=memory` and the login / WebAuthn-options rate limiters when no shared `rateLimiter` is wired; with the mode unset those three warn instead (see the operator runbook). With the mode unset you get one `replica_unsafe_adapters` warning at boot instead; with `DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica.
+**Set `DEPLOYMENT_MODE=multi` once you run more than one replica.** Boot then *fails* if any in-memory store that has to be shared is still wired, naming every offender and what it costs — user sessions forking (back-channel logout reaches one replica, a logged-out session stays valid on the others), rate-limit counters multiplying, access-token revocation not propagating, a single-use client assertion or WebAuthn challenge replayable once per replica. The check reads the declaration each installed module carries on its own manifest rather than a list of library module names, so this template's own in-memory modules — the user-session stores (`USER_SESSION_STORES_ADAPTER=memory`), the authorization-code repository (`OAUTH_CODE_ADAPTER=memory`) and the federation token store (`FEDERATION_TOKEN_STORE_TYPE=memory`, the default) — are refused by name too. So are express-session's own store under `SESSION_STORAGE_TYPE=memory` (#474) and the default memory rate limiter (`core-rate-limiter-memory`, `RATE_LIMITER_ADAPTER=memory`). With the mode unset nothing is refused: every one of them is listed in a single `replica_unsafe_adapters` warning at boot. (The login and WebAuthn-options routes carry per-process fallback limiters that warn on their own, but only in a composition that wires no `rateLimiter` at all, which this template never does; see the operator runbook.) With `DEPLOYMENT_MODE=single` the check is silent, because you have said there is one replica. This template does not install DPoP; a composition that adds it records every accepted proof in the same replay seen-set as `private_key_jwt` (`REPLAY_SEEN_SET_ADAPTER`), so it gets the same answer — `memory` is refused under `DEPLOYMENT_MODE=multi` and listed in the unset-mode warning, and the shipped `redis` shares DPoP's records across replicas — see the dpop package's [operator requirements](../../packages/dpop/README.md#operator-requirements).
 
 Be aware of what this check *cannot* do: if you scale to N replicas without ever setting `DEPLOYMENT_MODE`, nothing fails. A process holding all its state in its own memory has no shared medium through which to notice peers — the condition is undetectable from inside exactly when it is true. Set the variable as part of scaling, not after something breaks.
 
@@ -111,7 +175,7 @@ Other multi-replica considerations covered by the default modules:
 
 - The `express-session` store (`sessionStoreModule`) is its own connection: `SESSION_STORAGE_TYPE=redis` with `SESSION_STORAGE_REDIS_URL` (`session.storage.redis.url`) pointing at the shared instance.
 - The user-session stores switch on `userSessionStores.adapter = "redis"` (`USER_SESSION_STORES_ADAPTER`), which wires `redisSessionStoresModule` off the shared ioredis connection — the one `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` configures.
-- The authorization-code repository switches on `oauth.code.adapter` (`OAUTH_CODE_ADAPTER`); the template ships `"redis"`, on that same connection. The older `repositories.code.type = "redis"` (`CLIENT_CODE_TYPE`) switch is still honoured with a deprecation warning at boot. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is still bound by `config/application.conf` but nothing reads it: the Redis code repository has run on the shared connection since the `{ endpointUri }` builder shape was retired, so there is one Redis URL for every adapter and that variable is legacy.
+- The authorization-code repository switches on `oauth.code.adapter` (`OAUTH_CODE_ADAPTER`); the template ships `"redis"`, on that same connection. `oauth.code.adapter` wins; the deprecated `repositories.code.type` (`CLIENT_CODE_TYPE`) is read, with a `config_key_deprecated` warning at boot, only when it is unset — which the shipped `config/application.conf` never leaves it. `CLIENT_CODE_ENDPOINT_URI` (`repositories.code.redis.endpointUri`) is bound by `config/application.conf` but nothing reads it: the Redis code repository runs on the shared connection, so there is one Redis URL for every adapter.
 - 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).
@@ -119,32 +183,93 @@ Other multi-replica considerations covered by the default modules:
 
 ## Usage
 
+`pnpm run debug` runs `src/app.mts` under `tsx watch` on this machine. It reads
+no `.env` file — its configuration is `config/` plus the environment of the
+shell that starts it — and it does not boot until that environment supplies:
+
+- `OAUTH_JWT_ISSUER` — this server's origin (`http` is accepted for a loopback
+  host);
+- a signing key pair, `OAUTH_JWT_PRIVATE_KEY_PATH` / `OAUTH_JWT_PUBLIC_KEY_PATH`
+  (see [OAuth JWT](#oauth-jwt));
+- `SESSION_SECRET`, at least 32 bytes;
+- `CLIENT_USER_AUTHENTICATE_URL` and `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` —
+  your user service ("the Store"), `https`, or `http` on a loopback host. Boot
+  checks their form, not that anything answers; logins fail until something
+  does (see [User Repository](#user-repository));
+- a Redis it can reach at `redis://localhost:6379`. The shipped configuration
+  keeps the browser session store there (`SESSION_STORAGE_REDIS_URL`), and
+  opens one shared connection (`REFRESH_TOKEN_FAMILY_STORE_REDIS_URL`) for the
+  refresh-token families, the authorization codes, the access-token denylist
+  and the replay seen-set — and for the user-session stores, with the setting
+  below.
+
+Plain HTTP also needs `SESSION_SECURE=false` and a session cookie name without
+the `__Host-` prefix (see [Session](#session)). And set
+`USER_SESSION_STORES_ADAPTER=redis`: the browser session store is in Redis, the
+user-session stores default to memory, and `tsx watch` restarts the process on
+every save — split, a restart leaves the browser's session pointing at a
+`UserSession` that is gone, and `/authorize` loops (see [Docker](#docker)).
+
+The key pair below is generated with Node, which every machine running this
+already has. `openssl genpkey -algorithm ed25519` works too, with OpenSSL 1.1.1
+or later — not with the LibreSSL that macOS ships as `/usr/bin/openssl`.
+
 ```bash
-# Install dependencies
 pnpm install
 
-# Copy environment file and fill in required values
-cp .env.example .env
+# A signing key pair (Ed25519) and a local Redis
+node -e '
+const { generateKeyPairSync } = require("node:crypto");
+const fs = require("node:fs");
+const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+fs.writeFileSync("jwt-private.pem", privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
+fs.writeFileSync("jwt-public.pem", publicKey.export({ type: "spki", format: "pem" }));
+'
+docker run -d --name auth-redis -p 127.0.0.1:6379:6379 redis:7.2-alpine
+
+# What boot requires (replace the user-service URLs with your Store's)
+export OAUTH_JWT_ISSUER=http://localhost:3000 \
+  OAUTH_JWT_PRIVATE_KEY_PATH=./jwt-private.pem \
+  OAUTH_JWT_PUBLIC_KEY_PATH=./jwt-public.pem \
+  SESSION_SECRET="$(openssl rand -hex 32)" \
+  SESSION_SECURE=false SESSION_NAME=auth.sid \
+  USER_SESSION_STORES_ADAPTER=redis \
+  CLIENT_USER_AUTHENTICATE_URL=http://localhost:8080/authenticate \
+  CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=http://localhost:8080/authenticate-by-token
 
 # Start in development mode (hot reload)
 pnpm run debug
 
-# Build and start in production mode
+# Build, then run the compiled server (CONFIG_ENV or NODE_ENV selects config/<env>.conf)
 pnpm run build
-pnpm start
+pnpm run start
 ```
 
+`.env` is read only by the compose files (`env_file`). `make dev`
+(`docker compose up --build`) runs the same debug server in a container beside
+a Redis service, with its environment from `.env` — copied from
+`.env.example`, whose Redis URLs name that service. Values there are resolved
+inside the container, which holds no key files: only `src/`, `config/`, the
+package manifests and what installing and building them produced. A key path or
+a `localhost` URL that works on the host does not work there. The deployable
+image and its compose file are under [Docker](#docker).
+
 ## Configuration
 
 Configuration is loaded from `config/application.conf` (HOCON format). Each value can be overridden with the corresponding environment variable.
 
 ### Environment-specific config overlay
 
-`src/app.mts` loads configuration in two layers:
+`src/app.mts` loads configuration in three layers, highest precedence first:
 
-1. **`config/application.conf`** — base defaults for the app.
-2. **`config/{ENV}.conf`** — overlay for the current environment, where
+1. **`config/{ENV}.conf`** — overlay for the current environment, where
    `ENV = CONFIG_ENV || NODE_ENV || "development"`.
+2. **`config/application.conf`** — this deployment's settings.
+3. **`reference.conf` of `@o3co/auth-provider-core`** — the library defaults,
+   resolved from the installed package
+   (`import.meta.resolve("@o3co/auth-provider-core/reference.conf")`, in
+   [`src/configPath.mts`](src/configPath.mts)). A key neither file above sets
+   takes its value from here.
 
 Values in the overlay take precedence over `application.conf`. The scaffold
 ships with `development.conf` and `production.conf`. To add another
@@ -182,7 +307,7 @@ fail fast rather than silently falling back to defaults.
 | `OAUTH_CIMD_STALE_IF_ERROR_MS` | `300000` | How long a registration already validated is still served after a revalidation that failed for a reason that is not the document's (a DNS blip, a 5xx, a timeout) — an outage should not break a working client. A document that was *rejected* is dropped immediately. `0` disables it. |
 | `OAUTH_CIMD_NEGATIVE_CACHE_MS` | `60000` | How long a refusal is remembered, so the same `client_id` is not resolved and fetched again on every request. Short, so a client that fixes its document is not locked out. |
 | `OAUTH_CIMD_MAX_CONCURRENT_FETCHES` | `8` | How many documents may be in flight at once, across every `client_id`. Bounds what an unauthenticated caller can make this server dial. |
-| `OAUTH_JWT_KID` | `v0` | Key ID included in the JWT header |
+| `OAUTH_JWT_KID` | `v0` | Key ID included in the JWT header. 1 to 256 characters with no control character; anything else fails boot, including a variable exported but empty (which used to sign under the kid `""`; tokens issued that way are refused once it is corrected, so their users sign in again) |
 | `OAUTH_JWT_PRIVATE_KEY` | — | PEM-encoded private key (asymmetric algorithms) |
 | `OAUTH_JWT_PRIVATE_KEY_PATH` | — | Path to PEM private key file |
 | `OAUTH_JWT_PUBLIC_KEY` | — | PEM-encoded public key |
@@ -214,7 +339,7 @@ every relying party must be handed the shared secret — which also lets it
 |---|---|---|
 | `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` | `3600` | Access token lifetime in seconds that every grant mints when the request asks for none. Whole positive number, at most one year (`31536000`). |
 | `OAUTH_ACCESS_TOKEN_MAX_EXPIRES_IN` | the default | The most a token-exchange request's `expires_in` parameter can obtain; a larger request is clamped to it. Unset means the default, so no token is extended unless you set this. A default above it is a boot failure naming both keys. It also bounds how long an exchanged token outlives a revocation at a resource server that validates it offline. |
-| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | — | **Deprecated** alias of `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` (config key `oauth.accessToken.expiresIn`, of `oauth.accessToken.defaultExpiresIn`), read only while the new one is unset. Move the value to the new variable. |
+| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | — | **Deprecated** alias of `OAUTH_ACCESS_TOKEN_DEFAULT_EXPIRES_IN` (config key `oauth.accessToken.expiresIn`, of `oauth.accessToken.defaultExpiresIn`), read only while the new one is unset; while it still decides the default, boot logs `config_key_deprecated` (warn). Move the value to the new variable. |
 | `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | Refresh token lifetime in seconds. Whole positive number, at most one year (`31536000`). |
 
 Exporting one of these as an empty string is a boot failure, not a fallback:
@@ -336,6 +461,7 @@ all — no headers, no `Vary`, nothing changed.
 | `FEDERATIONS_GOOGLE_CLIENT_ID` | — | Google OAuth client ID |
 | `FEDERATIONS_GOOGLE_CLIENT_SECRET` | — | Google OAuth client secret |
 | `FEDERATIONS_GOOGLE_CALLBACK_URL` | `http://localhost:3000/session/oauth/federation/google/callback` | Google OAuth callback URL |
+| `FEDERATIONS_GOOGLE_ACCESS_TYPE` | unset (`offline`) | `offline`: every sign-in shows Google's consent screen and every session gets a refresh token. `online`: consent on the first sign-in only, and no refresh token at all. See [federation-google](../../packages/federation-google/README.md#refresh-tokens-and-the-consent-screen) |
 
 ### OIDC Federation (any OpenID Connect provider)
 
@@ -393,6 +519,7 @@ is documented in [its README](../../packages/federation-oidc/README.md).
 | `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_BEARER_TOKEN` | — | Optional. The credential this server presents to the Store: every Store request carries `Authorization: Bearer <token>`. A bare token (no `Bearer ` prefix) of at least 32 bytes — `openssl rand -hex 32`. Unset, no `Authorization` header is sent (see below) |
 | `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 |
 
@@ -405,11 +532,42 @@ only for a loopback host — `localhost`, an address in `127.0.0.0/8`, or `[::1]
 deployment does not control end to end. Boot fails if either URL, the timeout,
 or the response cap is unusable, rather than at the first login attempt.
 
+Each URL must be the endpoint that answers, not one that redirects: no request
+follows a `3xx`, so a URL that redirects fails every call — see
+[What the Store must enforce itself](../../packages/foundation/README.md#what-the-store-must-enforce-itself).
+
+**Who may call the Store.** What the token-based login and account linking
+send is an identifier, not a secret, so a Store that answers any caller
+resolves a known identity to its user — or links one to any account — for
+anyone who can reach it. Set `CLIENT_USER_BEARER_TOKEN` and have the Store
+answer every request whose `Authorization` is not exactly `Bearer <that token>`
+with `401` and `WWW-Authenticate: Bearer error="invalid_token"` (or `403` and
+`error="insufficient_scope"`). The one token goes to every Store URL above, so
+those endpoints must be one trust domain. With `CLIENT_USER_TYPE=http` — this
+template's default — boot fails if the token is weaker than 32 bytes
+(measured like `SESSION_SECRET`), malformed, or exported but empty; it appears
+in no error this server throws. With that challenge, a token the Store does not
+accept is an outage on every Store call: logins answer
+`503 temporarily_unavailable` and log an error naming the refused credential,
+not the token, and so do federation-grants connects
+(`federation_grant_callback_unavailable`). A `401` or `403` without the
+challenge keeps its old meaning — at login "no such user", at a `?link=1`
+link a refusal, and at the federation-grants identity lookup an outage like
+any other non-`2xx` — so a mismatch then shows only as every login failing
+and every link refused; and a Store must not put a `Bearer` challenge on a
+user's wrong password or a link it refuses. A Store that cannot be reached,
+closes the connection before a complete response, or answers with a malformed
+HTTP response is logged as such, with at most a transport code
+(`ECONNREFUSED`, `UND_ERR_SOCKET`, `ERR_SSL_WRONG_VERSION_NUMBER`, …), and
+never with what the transport quoted. Without the token, admit only this server to the Store
+by network policy or platform mutual TLS. Rotation, what each caller logs, and
+what the Store checks are in the same foundation README section.
+
 ### Code Repository
 
 | Variable | Default | Description |
 |---|---|---|
-| `CLIENT_CODE_TYPE` | `redis` | Deprecated alias of `OAUTH_CODE_ADAPTER` (`repositories.code.type`); honoured with a boot warning |
+| `CLIENT_CODE_TYPE` | `redis` | Deprecated alias of `OAUTH_CODE_ADAPTER` (`repositories.code.type`); read, with a `config_key_deprecated` warning at boot, only when `oauth.code.adapter` is unset — the shipped config sets it |
 | `CLIENT_CODE_ENDPOINT_URI` | — | Legacy; bound to `repositories.code.redis.endpointUri` but not read — codes use the shared `REFRESH_TOKEN_FAMILY_STORE_REDIS_URL` connection |
 | `CLIENT_CODE_PASSWORD` | — | Redis password for code storage |
 | `CLIENT_CODE_DEFAULT_EXPIRES_IN` | `600` | Default authorization code lifetime in seconds |
@@ -601,37 +759,25 @@ Use values that include the deployment name, for example `tenant-a:ss:`,
 | `ENDPOINTS_LOGIN_URL` | `/login` | URL of the login page (for redirects) |
 | `ENDPOINTS_CONSENT_URL` | `/consent` | URL of the consent page a client that is not first-party is routed through, with `?challenge=<id>` (#527) |
 
-`ENDPOINTS_CLIENT_URL` and `ENDPOINTS_AUTH_CALLBACK_URL` were removed (IH-10) —
-no production consumer read them, and the config lines leaked values into
-`AppConfig` that nothing consumed. Federation callback URLs are configured
-per-provider (`FEDERATIONS_GOOGLE_CALLBACK_URL`).
+There is no deployment-wide client or callback URL: federation callback URLs
+are configured per federation (`FEDERATIONS_GOOGLE_CALLBACK_URL`,
+`FEDERATIONS_OIDC_CALLBACK_URL`).
 
 ## Module Composition Order
 
-`src/buildModules.mts` is the single source of truth for the manifest; this is its order. The boot planner resolves `requires` / `provides` topologically, so list position matters only where a module says so — `sessionStoreModule` must stay first, because it wires the `express-session` middleware every session-consuming route needs. Entries marked *adapter switch* are one of a memory/Redis pair, chosen by config; both provide the same slot, so exactly one is wired.
-
-1. **`sessionStoreModule`** (`@o3co/auth-provider-session`) — `express-session` middleware and its store (`session.storage.type`)
-2. **`oauthModule`** — `POST /oauth/token`, `POST /oauth/introspect`, `POST /oauth/revoke`, `GET /oauth/authorize`, and OIDC discovery when an issuer is configured
-3. **`oauthSessionModule`** — session grant (exchanges an authenticated session for a token)
-4. **`oauthAuthorizationModule`** — authorization-code and refresh-token grants
-5. **`jwksModule`** (`@o3co/auth-provider-core`) — `GET /.well-known/jwks.json` (or `oauth.jwt.jwksPath`); a signing provider publishes its verification keys whether or not an issuer is set
-6. **`sessionModule`** — `POST /session/login`, `POST /session/logout`, `GET/POST /session/oauth/federation/*`. `/session/logout` deletes the `UserSession` record (so `/oauth/introspect` and `/oauth/userinfo` stop honouring tokens minted from that session), the subject index and the federation entries — but it does **not** revoke refresh-token families; `POST /oauth/logout` is the endpoint that runs the full cascade. See [Which logout endpoint invalidates what](../../docs/operator-runbook.md#which-logout-endpoint-invalidates-what).
-7. **`googleFederationModule`** + **`googleFederationConfigModule`** — only when `federations.google.enabled = true`
-8. **`keyStoreModule`** — the signing key store from `oauth.jwt.signingKey`
-9. **`repositoriesModule`** — client and user repositories from `repositories.client` / `repositories.user`
-10. **`auditSinkModule`** — always wired; `audit.sink.type` picks `logger` (default) or `console`
-11. **`standaloneRedisClientsModule`** — the one shared ioredis connection; present whenever any switch below is `"redis"`
-12. **`redisFederationTokenStoreModule`** / **`inMemoryFederationTokenStoreModule`** — *adapter switch*: upstream federation tokens per session (`federationTokenStore.type`; see [Multi-replica deployments](#multi-replica-deployments))
-13. **`redisSessionStoresModule`** / **`inMemorySessionStoresModule`** — *adapter switch*: user-session stores (`userSessionStores.adapter`)
-14. **`redisRateLimiterModule`** / **`memoryRateLimiterModule`** — *adapter switch*: the rate limiter behind the OAuth endpoints and `POST /session/login` (`rateLimiter.adapter`)
-15. **`redisCodeRepositoryModule`** / **`inMemoryCodeRepositoryModule`** — *adapter switch*: authorization codes (`oauth.code.adapter`)
-16. **`redisAccessTokenDenylistModule`** / **`memoryAccessTokenDenylistModule`** — *adapter switch*: RFC 7009 access-token denylist (`accessTokenDenylist.adapter`)
-17. **`redisRefreshTokenFamilyStoreModule`** — refresh-token families; Redis unless a test override swaps in the memory store
-18. **`defaultRefreshTokenFamilyRotationModule`**, **`defaultRefreshTokenFamilyRevocationModule`** — rotation and revocation policies over the family store
+[`src/buildModules.mts`](src/buildModules.mts) is the single source of truth for which modules are composed and in what order — read it rather than a copy of it. The boot planner resolves `requires` / `provides` topologically, but it mounts routes and middleware in list order unless a module declares `before` / `after` — so position matters for anything that mounts. These are the rules to keep when you edit the list:
+
+1. **`sessionStoreModuleFor(config)` stays first.** It mounts the `express-session` middleware and declares no `before` / `after`, so its position in the list is what puts it ahead of every route that reads `req.session`. It is built from `config` so that `session.storage.type = "memory"` declares itself replica-unsafe.
+2. **Under `/oauth`, the order does not matter.** `federationGrantsModules` (while federation grants are enabled), `oauthModule` and any module of your own may all mount routes under `/oauth`. `oauthModule`'s router parses the bodies of its own routes only, so each module's requests reach its own parsers whatever the list order — provided every module under `/oauth` parses its own body and scopes its parsers to exactly its own paths, as the shipped ones do — a route (`router.all(path, parser)` or the route's own handler list), not `router.use(path, parser)`, which matches every path beneath `path` as well. The federation grants browser half orders itself after the session middleware with its own `after`.
+3. **One module per store slot.** Each adapter switch — `federationTokenStore.type`, `userSessionStores.adapter`, `rateLimiter.adapter`, `oauth.code.adapter`, `accessTokenDenylist.adapter`, `replaySeenSet.adapter`, `consentStore.adapter`, and the two federation-grant store switches — picks one of a memory / Redis pair. Both provide the same slot, so wiring both is a boot-time slot collision. `consentStore.adapter = "none"` wires neither, and the federation-grant stores are wired only while the feature is enabled.
+4. **The shared Redis connection comes with the first Redis-backed module.** `standaloneRedisClientsModule` opens the one ioredis connection every Redis adapter here uses, and is added whenever a composed module needs one. The refresh-token family store is on Redis in the shipped composition, so a deployment always has it; the in-memory family store is a test override (`overrides.refreshTokenFamilyModules`).
+5. **A federation adapter comes with its config bridge.** `googleFederationModule` with `googleFederationConfigModule` — only for an enabled `federations.google` section whose `type` is `google`, so a `type = "oidc"` section named `google` is not composed twice — and one `oidcFederationModule(name)` per enabled `type = "oidc"` section, with the one `oidcFederationConfigModule` they share. A bridge's provider throws when its section is absent, so the pair is included at composition time rather than gated inside it.
+
+`jwksModule` (from core) is always composed: a provider that signs tokens publishes its verification keys whether or not an issuer is configured. What each route module mounts is in its package's README. One behaviour to know when composing: `sessionModule`'s `POST /session/logout` deletes the `UserSession` record (so `/oauth/introspect` and `/oauth/userinfo` stop honouring tokens minted from that session), the subject index and the federation entries — but it does **not** revoke refresh-token families; `POST /oauth/logout` is the endpoint that runs the full cascade. See [Which logout endpoint invalidates what](../../docs/operator-runbook.md#which-logout-endpoint-invalidates-what).
 
 ## Built-in Routes
 
-`src/app.mts` mounts these on the host app ahead of the composed auth router, so they keep answering while the auth pipeline is degraded — which is when an operator needs them. The JWKS route is not one of them: `jwksModule` contributes it (see above).
+`src/routes.mts` mounts these on the host app ahead of the composed auth router, so they keep answering while the auth pipeline is degraded — which is when an operator needs them — and core's terminal error handler after all of them, so an error one of them lets through is answered as the auth routes' are (`500 server_error`, logged once as `unhandled_request_error`). The JWKS route is not one of them: `jwksModule` contributes it (see above).
 
 | Method | Path | Description |
 |---|---|---|
@@ -688,8 +834,8 @@ merely stored badly. The same applies to `.env`; keep both out of git.
 
 The production file also pins `SESSION_SECURE=true` and the `__Host-` cookie
 name in its `environment:` block, which wins over `env_file`. `.env.example`
-ships `SESSION_SECURE=false` so a plain-HTTP local run works, and this file
-requires that same `.env` — behind the TLS it assumes, a non-Secure session
+ships `SESSION_SECURE=false` so that a plain-HTTP compose run (`make dev`) does
+not trip the `__Host-` cookie check, and this file requires that same `.env` — behind the TLS it assumes, a non-Secure session
 cookie is the session handed to anyone who can read one plaintext hop.
 
 The image installs with `pnpm install --frozen-lockfile`, so a committed
@@ -699,7 +845,7 @@ the result. Rebuilding the same source then produces the same dependency tree.
 
 The production image sets `ENV HTTP_PORT=3000` and uses it for both `EXPOSE`
 and the Docker-native healthcheck against `/_healthcheck`. The HOCON config
-also reads `${?HTTP_PORT}` for `http.port`, so `app.listen()` and the
+also reads `${?HTTP_PORT}` for `http.port`, so the listener and the
 healthcheck cannot drift apart. To run on a different port:
 
 ```bash
@@ -756,7 +902,8 @@ changing the image.
 ```
 
 The failure's *reason* is deliberately absent from the body and goes to the log
-instead (`readiness_probe_failed`, with the full per-check detail). A driver
+instead (`readiness_probe_failed`, with each failing check's error as core's
+`loggableError` projection). A driver
 error reads `connect ECONNREFUSED 10.0.3.14:6379` — an internal host and port —
 and this endpoint is unauthenticated because an orchestrator has no credentials
 to present. Set `includeErrorDetail: true` on `createReadinessRouter` only when
@@ -772,9 +919,10 @@ rules.
 Probes are registered by whichever builder opened the connection, so the list
 reflects what this deployment actually wired: the shared ioredis client
 (`redis`) and the connect-redis session client (`session-store`) when the
-Redis adapters are selected, and **nothing at all** for a memory-only
-deployment — which is therefore always ready, because it has no dependency to
-be unready for.
+Redis adapters are selected, and **nothing at all** for a composition with no
+Redis-backed module — which would therefore always be ready, having no
+dependency to be unready for. The shipped composition is never that: its
+refresh-token families are always in Redis, so `redis` is always probed.
 
 `http.readinessTimeoutMs` (env `HTTP_READINESS_TIMEOUT_MS`, default `1000`)
 is the per-probe deadline. Keep it below the orchestrator's own probe timeout;
@@ -783,43 +931,22 @@ unready one.
 
 ## Adding Custom Modules
 
-To add a custom module, import it in `src/buildModules.mts` and include it in the `modules` array passed to `createApp`:
-
-```typescript
-// src/buildModules.mts
-import { myCustomModule } from "./modules/my-custom-module.mjs";
-
-export function buildModules(config: AppConfig, overrides: BuildModulesOverrides = {}): Module[] {
-  const googleEnabled =
-    (config.federations?.google as { enabled?: boolean } | undefined)?.enabled === true;
-
-  return [
-    oauthModule({ config }),
-    oauthSessionModule({ config }),
-    oauthAuthorizationModule({ config }),
-    sessionModule,
-    ...(googleEnabled ? [googleFederationModule, googleFederationConfigModule] : []),
-    myCustomModule, // add here
-    overrides.keyStoreModule ?? keyStoreModule,
-    overrides.repositoriesModule ?? repositoriesModule,
-    overrides.storesModule ?? storesModule,
-  ];
-}
-
-// src/app.mts
-const handle = await createApp({
-  modules: buildModules(config),
-  bootstrapComponents: {
-    config,
-    pathResolver: import.meta.resolve,
-  },
-});
-
-app.use(handle.router);
-const server = app.listen(config.http.port);
-installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
+To add a custom module, import it in `src/buildModules.mts` and add it to the array `buildModules` returns. The boot planner resolves dependencies by what modules `require` and `provide`, but it mounts routes and middleware in list order wherever no `before` / `after` says otherwise. So position matters for middleware that other routes depend on — the session store module, rule 1 of [Module Composition Order](#module-composition-order). A route under a prefix another module also uses, such as `/oauth`, needs no particular position (rule 2), provided it parses its own body and scopes its parsers to exactly its own paths: `oauthModule`'s router parses only its own routes', and a parser that ran for every request under the prefix would read other modules' bodies for them. A module that mounts nothing of the first kind can go at the end:
+
+```diff
+ // src/buildModules.mts
++import { myCustomModule } from "./my-custom-module.mjs";
+ …
+ 	return [
+ 		sessionStoreModuleFor(config),
+ 		…
+ 		...(federationGrantsEnabled ? [subjectRevocationServiceModule] : []),
++		myCustomModule,
+ 	];
 ```
 
+Keep the other rules there too: the session store module stays first, and a module that fills a store slot replaces that slot's adapter switch rather than being added beside it. [`src/app.mts`](src/app.mts) needs no change: it passes `buildModules(config, …)` to `createApp`, mounts the router `createApp` returns, and wires the server's lifetime — `installGracefulShutdown` (below) drains it and calls `handle.dispose()`.
+
 ### Shutdown guarantees
 
 `src/shutdown.mts` is deliberately part of the scaffold rather than a dependency (#290): for the component that terminates every user session, *"does SIGTERM wait for in-flight requests, and for how long?"* has to be answerable from the code you deploy.
@@ -828,7 +955,7 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 2. **New connections stop immediately**, and idle keep-alive sockets are released — they hold the server open with no request behind them, so a quiet server would otherwise wait out the whole deadline for nothing.
 3. **In-flight requests get `drainTimeoutMs`** (default **10s**) to finish.
 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.
+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) as `shutdown_cleanup_failed` (or `shutdown_cleanup_timed_out`) and reflected in the exit code; every stage is its own event — `shutdown_draining`, `shutdown_drain_deadline_exceeded`, `shutdown_server_close_failed`, `shutdown_complete`. A dispose that throws still exits; it never wedges the process. The line carries core's [`loggableError`](../../packages/core/README.md#logger) projection of the failure, never the error itself: `dispose()` rejects with an AggregateError of every cleanup's own error, and the line names each of them with its code (`aggregateErrors`, the first five) and nothing of what it holds — a store write that failed, with what it was writing, can be one of them.
 
 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.
 
@@ -839,9 +966,9 @@ installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 | Script | Description |
 |---|---|
 | `pnpm run build` | Compile TypeScript to `dist/` |
-| `pnpm start` | Start the compiled server |
+| `pnpm run start` | Start the compiled server |
 | `pnpm run debug` | Start with hot reload via `tsx watch` (development mode) |
-| `pnpm test` | Run tests with Vitest |
+| `pnpm run test` | Typecheck (`tsc --noEmit`), then run the tests with Vitest |
 
 ## See Also
 

package/templates/standalone/config/application.conf

@@ -313,6 +313,14 @@ federations {
     # 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}
+
+    # Whether sign-in asks Google for a refresh token. Unset is "offline":
+    # every sign-in shows Google's consent screen, because Google issues a
+    # refresh token only there, and every session gets one that
+    # 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}
   }
 
   # Any OpenID Connect provider (Okta, Entra ID, Auth0, Keycloak, your own
@@ -371,25 +379,40 @@ repositories {
       # 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.
+      # 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 rule as the two URLs above.
+      # 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 rule. Declare what the Store
+      # 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

package/templates/standalone/gitignore

@@ -1,6 +1,7 @@
 # #407: without this file, the first `git add .` in a scaffolded project
-# commits the two things the README's own setup steps tell you to create right
-# here — the `.env` holding SESSION_SECRET, and the signing key pair.
+# commits the two things a local setup creates right here — the signing key
+# pair the README's Usage generates, and the `.env` (holding SESSION_SECRET)
+# the compose files read.
 
 # Secrets and per-machine configuration
 .env

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {