@o3co/create-auth-provider 0.9.0 → 0.11.0

package/templates/standalone/config/application.conf

@@ -9,10 +9,46 @@
 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.
+#
+# "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.
+#
+# 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).
+#
+# 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}
+  }
+}
+
 oauth {
   grants {
     # Template is a typical web-app OP — enable the universal user-auth path.
@@ -30,13 +66,18 @@ oauth {
       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}
-      pkce {
-        requireS256 = false
-        requireS256 = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_PKCE_REQUIRE_S256}
-      }
     }
     refresh_token {
       enabled = true
@@ -53,10 +94,44 @@ oauth {
   # 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).
+  # #267: /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
+  # 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.
+  #
+  # Deployments that genuinely do not revoke access tokens (short-lived tokens
+  # plus refresh-token revocation only) set "unsupported" instead, and the
+  # endpoint then answers `unsupported_token_type` for
+  # `token_type_hint = access_token`. Refresh-token revocation works in both
+  # modes and needs no denylist.
+  revocation {
+    accessToken = "denylist"
+    accessToken = ${?OAUTH_REVOCATION_ACCESS_TOKEN}
+  }
+}
+
+# #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}
 }
 
 session {
@@ -74,6 +149,17 @@ session {
   sameSite = ${?SESSION_SAME_SITE}
   domain = null
   domain = ${?SESSION_DOMAIN}
+  # #405: 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).
+  redirectAllowlist = []
   storage {
     type = "redis"
     type = ${?SESSION_STORAGE_TYPE}
@@ -113,6 +199,39 @@ federations {
     clientSecret = ${?FEDERATIONS_GOOGLE_CLIENT_SECRET}
     callbackURL = "http://localhost:3000/session/oauth/federation/google/callback"
     callbackURL = ${?FEDERATIONS_GOOGLE_CALLBACK_URL}
+
+    # Every URL a `redirect_to` query parameter may name on
+    # /session/oauth/federation/google. Matching is EXACT — scheme, host, port,
+    # path, query and fragment all count — so list each landing page in full.
+    # There is no wildcard and no subdomain matching.
+    #
+    # 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.
+    #
+    # 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
+    # client on an ephemeral loopback listener work without a certificate. The
+    # port is still part of the match, so list the port the client binds.
+    #
+    #   redirectAllowlist = [
+    #     "https://app.example.com/welcome"
+    #     "http://localhost:5173/welcome"
+    #   ]
+    redirectAllowlist = []
+
+    # 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}
+
+    # 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}
+
+    # Where the browser goes after a callback carrying no `redirect_to`.
+    # clientUrl = ${?FEDERATIONS_GOOGLE_CLIENT_URL}
   }
 }
 
@@ -132,10 +251,19 @@ repositories {
       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.
       authenticateUrl = ${?CLIENT_USER_AUTHENTICATE_URL}
       authenticateByTokenUrl = ${?CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL}
+      # 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 {

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

@@ -7,24 +7,78 @@
 #   - "none":                public client — no clientSecret; PKCE/S256 mandatory at /authorize
 #
 # Secret format (only for confidential clients — basic / post):
-#   - Plain text: "my-secret"
-#   - Bcrypt hash: "$2b$10$..." (generate with: node -e "require('bcrypt').hash('secret',10).then(console.log)")
+#   - Bcrypt hash: "$2b$10$..."  <-- use this
+#   - Plain text: "my-secret"     <-- accepted, for local development only
+#
+# Generate a real one:
+#   SECRET=$(openssl rand -base64 32)
+#   node -e "require('bcrypt').hash(process.argv[1],10).then(console.log)" "$SECRET"
+# Give $SECRET to the client; put the hash in this file.
+#
+# #407: the schema accepts any non-empty string here, unlike `session.secret`
+# and the JWT signing secret, which have carried a 256-bit floor since #282.
+# That is deliberate — this field also holds a bcrypt hash, whose shape those
+# floors would reject — but it means NOTHING stops you from shipping
+# `clientSecret: "changeme"`. A client secret authenticates a confidential
+# client at the token endpoint; treat it as you would any other credential
+# and give it 256 bits of randomness.
+#
+# `firstParty` (#267): REQUIRED to be `true` for a client to use `/authorize`.
+#   `/authorize` mints a code as soon as the session is authenticated, with no
+#   consent step, so a forced top-level navigation from an attacker's page
+#   makes a logged-in user's browser mint one for whatever client is named.
+#   That is defensible for clients you operate and only for those. Mark a
+#   client `firstParty: true` only if you would be comfortable with it
+#   receiving the user's identity without the user being asked.
+#
+#   A client without it is refused at `/authorize`, as is one carrying an
+#   explicit `firstParty: false`. There is no opt-out: mark every client you
+#   operate before pointing it at `/authorize`.
+#
+# `allowPlainPkce` (#273): PKCE is mandatory for EVERY client — confidential
+#   ones included — and `S256` is the only method accepted. There is no
+#   server-wide setting that changes either half. This per-client flag is the
+#   one exception hatch, and only for the method: `allowPlainPkce: true` lets
+#   that one client use the RFC 7636 `plain` challenge, which stores the
+#   verifier itself as the challenge and so proves nothing against anyone who
+#   can read the authorization request. Set it only for a legacy client that
+#   genuinely cannot compute SHA-256, and treat it as a migration deadline.
 
 my-app:
   tokenEndpointAuthMethod: "client_secret_basic"
+  firstParty: true
   clientSecret: "$2b$10$REPLACE_WITH_BCRYPT_HASH"
   allowedRedirectUris:
     - "http://localhost:3000/callback"
   allowedScopes:
     - "read"
     - "write"
+  # What an omitted `scope` parameter grants (#396). Must be a subset of
+  # allowedScopes (checked at boot). Without this, a request that omits
+  # `scope` is refused with invalid_scope — the old behavior granted the
+  # ENTIRE allowlist, which made "forgot to send scope" the maximum grant.
+  # Declare what an unscoped request should mean, not the ceiling.
+  defaultScopes:
+    - "read"
 
 # Public client example (e.g., a single-page app or mobile app):
 # my-spa:
 #   tokenEndpointAuthMethod: "none"
+#   firstParty: true
 #   # clientSecret MUST be absent for "none" clients.
 #   allowedRedirectUris:
 #     - "https://app.example/callback"
 #   allowedScopes:
 #     - "openid"
 #     - "profile"
+
+# Legacy client that cannot compute SHA-256 (#273). Prefer fixing the client.
+# my-legacy-device:
+#   tokenEndpointAuthMethod: "client_secret_basic"
+#   firstParty: true
+#   clientSecret: "$2b$10$REPLACE_WITH_BCRYPT_HASH"
+#   allowPlainPkce: true
+#   allowedRedirectUris:
+#     - "https://legacy.example/callback"
+#   allowedScopes:
+#     - "openid"

package/templates/standalone/config/production.conf

@@ -2,9 +2,15 @@
 # Loaded when CONFIG_ENV (or NODE_ENV) is "production".
 # Values here override application.conf.
 #
-# Most production-sensitive values (OAUTH_JWT_SECRET, SESSION_SECRET, REDIS URLs,
-# federation client secrets, etc.) should be supplied via environment variables —
-# see the ${?VAR} substitutions in application.conf.
+# Most production-sensitive values (SESSION_SECRET, the JWT signing key, REDIS
+# URLs, federation client secrets, etc.) should be supplied via environment
+# variables — see the ${?VAR} substitutions in application.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
+# docker-compose.production.yml mounts as compose secrets.
 #
 # Override entries here only when a value must be fixed per-environment rather
 # than per-deployment (e.g. feature flags turned on only in production).

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

@@ -0,0 +1,132 @@
+# Production compose example (#293 item 16).
+#
+# `docker-compose.yml` is a DEVELOPMENT file: it builds the `develop` target
+# and bind-mounts ./src and ./config into the container, so copy-paste
+# deploying it ships a hot-reload server running your working tree. This file
+# is the deployable shape: the `runtime` target (compiled JS only, tini,
+# healthcheck), no source mounts, restart policies, and a Redis that is
+# reachable from the app network only and persists to a volume.
+#
+#   openssl genpkey -algorithm ed25519 -out jwt-private.pem
+#   openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
+#   chmod 600 jwt-private.pem
+#   docker compose -f docker-compose.production.yml up -d --build
+#
+# The pem pair is required: EdDSA is the default and there is no key-material
+# default, so a deployment that generates none fails at boot naming the keys to
+# set. It reaches the container as a compose secret rather than through
+# `config/`, which the image COPYs — see the `secrets:` block below.
+#
+# What this file deliberately does NOT do:
+#
+# - **TLS.** Terminate it in front (reverse proxy / load balancer), and set
+#   HTTP_TRUST_PROXY to that hop's address so `req.ip` — and every IP-keyed
+#   rate limit — means the client, not the proxy. See README
+#   "Multi-replica deployments".
+# - **Scale out.** This is one replica (DEPLOYMENT_MODE=single). Before
+#   `--scale app=N`, set DEPLOYMENT_MODE=multi and read that same README
+#   section — boot will then refuse any in-memory store that must be shared.
+# - **Invent secrets.** SESSION_SECRET (and any client secrets referenced by
+#   config/clients.yaml) come from `.env`, which is required here — chmod 600
+#   it, keep it out of git (`git local-files` or your secret manager of
+#   choice), and never bake it into the image.
+
+services:
+  app:
+    build:
+      context: .
+      target: runtime
+    restart: unless-stopped
+    ports:
+      # Loopback-bound on purpose (#407). This file assumes TLS is terminated
+      # in front, and the README says to keep `/metrics` off the public
+      # listener — a bare "3000:3000" publishes on every interface and
+      # contradicts both. A reverse proxy on the same host reaches it here.
+      #
+      # If your load balancer is on another host, publish it instead
+      # (`- "3000:3000"`) and put the access control somewhere real: a
+      # security group, a firewall rule, or the proxy's own network. Do not
+      # widen this line and call it done.
+      - "127.0.0.1:3000:3000"
+    depends_on:
+      redis:
+        condition: service_healthy
+    env_file:
+      # Required, unlike the dev file: a production boot without
+      # SESSION_SECRET (or with the sample one) must fail loudly here, not
+      # serve quietly with a guessable secret.
+      - path: .env
+        required: true
+    secrets:
+      # The signing keys. EdDSA is the default algorithm and there is no key
+      # material default, so the process needs the pem pair at boot — and the
+      # `runtime` image deliberately does not contain it: `Dockerfile` COPYs
+      # `config/`, so a key parked there is baked into a layer that travels
+      # with every image push. Compose secrets mount read-only under
+      # /run/secrets and are the reason the env below overrides the
+      # `./jwt-*.pem` paths in `.env.example`.
+      #
+      # Generate them next to this file before the first `up`:
+      #   openssl genpkey -algorithm ed25519 -out jwt-private.pem
+      #   openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
+      #   chmod 600 jwt-private.pem
+      - jwt_private_key
+      - jwt_public_key
+    environment:
+      NODE_ENV: production
+      DEPLOYMENT_MODE: single
+      # Point the process at the mounted secrets rather than the working-copy
+      # paths `.env` carries for local runs.
+      OAUTH_JWT_PRIVATE_KEY_PATH: /run/secrets/jwt_private_key
+      OAUTH_JWT_PUBLIC_KEY_PATH: /run/secrets/jwt_public_key
+      # `environment` wins over `env_file`, which is the point here:
+      # `.env.example` ships SESSION_SECURE=false / SESSION_NAME=auth.sid so a
+      # plain-HTTP local run works, and this file requires that same `.env`.
+      # Behind the TLS this compose assumes, a non-Secure session cookie is the
+      # session handed to anyone who can read one plaintext hop. The default
+      # `__Host-` cookie name is restored with it — the prefix browsers only
+      # honour on a Secure cookie.
+      SESSION_SECURE: "true"
+      SESSION_NAME: __Host-auth.session
+      # Every Redis-backed store shares the compose-network Redis below.
+      REFRESH_TOKEN_FAMILY_STORE_REDIS_URL: redis://redis:6379
+      SESSION_STORAGE_TYPE: redis
+      SESSION_STORAGE_REDIS_URL: redis://redis:6379
+      # The memory rate limiter is per-process and evadable under bucket
+      # exhaustion (see README) — production points it at Redis.
+      RATE_LIMITER_ADAPTER: redis
+
+  redis:
+    # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
+    # and that argument holds here too — a tag is mutable, so two `up`s a month
+    # apart can run different Redis builds. Pin the digest for a production
+    # deployment you need to reproduce:
+    #   image: redis:7.2-alpine@sha256:<digest>
+    # Left as a tag in the template because a digest goes stale the week it is
+    # written and a scaffold that ships a stale one teaches nothing (#407).
+    image: redis:7.2-alpine
+    restart: unless-stopped
+    # No `ports:`, deliberately — the app reaches Redis over the compose
+    # network, and nothing else should. The dev file publishes 6379 to
+    # loopback for redis-cli convenience; a published production Redis with
+    # no AUTH is an incident.
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  redis-data:
+
+secrets:
+  # File-backed, so the pem pair stays on the host and reaches the container
+  # read-only at /run/secrets. Keep both out of git alongside `.env`; a key
+  # committed or COPYed into the image is a key you have to rotate.
+  jwt_private_key:
+    file: ./jwt-private.pem
+  jwt_public_key:
+    file: ./jwt-public.pem

package/templates/standalone/docker-compose.yml

@@ -16,6 +16,13 @@ services:
         required: false
 
   redis:
+    # Tag-pinned, not digest-pinned. The Dockerfile argues for digests (#289)
+    # and that argument holds here too — a tag is mutable, so two `up`s a month
+    # apart can run different Redis builds. Pin the digest for a production
+    # deployment you need to reproduce:
+    #   image: redis:7.2-alpine@sha256:<digest>
+    # Left as a tag in the template because a digest goes stale the week it is
+    # written and a scaffold that ships a stale one teaches nothing (#407).
     image: redis:7.2-alpine
     ports:
       - "127.0.0.1:6379:6379"

package/templates/standalone/gitignore

@@ -0,0 +1,21 @@
+# #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.
+
+# Secrets and per-machine configuration
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+config/clients.yaml
+config/*.local.conf
+
+# Build output and dependencies
+node_modules/
+dist/
+coverage/
+
+# Editor / OS noise
+.DS_Store
+*.log

package/templates/standalone/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@o3co/auth-provider-standalone",
-	"version": "0.9.0",
+	"version": "0.11.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"engines": {
-		"node": ">=18.19.0"
+		"node": ">=22.0.0"
 	},
 	"packageManager": "pnpm@10.29.3",
 	"type": "module",
@@ -23,33 +23,28 @@
 	"dependencies": {
 		"@o3co/auth-provider-core": "workspace:*",
 		"@o3co/auth-provider-federation-google": "workspace:*",
-		"@o3co/auth-provider-oauth": "workspace:*",
-		"@o3co/auth-provider-session": "workspace:*",
 		"@o3co/auth-provider-foundation": "workspace:*",
+		"@o3co/auth-provider-oauth": "workspace:*",
 		"@o3co/auth-provider-redis": "workspace:*",
-		"@o3co/auth.utils": "^0.0.4",
-		"@o3co/ts.hocon": "^1.2.0",
-		"connect-redis": "^9.0.0",
+		"@o3co/auth-provider-session": "workspace:*",
+		"@o3co/ts.hocon": "^1.13.0",
+		"connect-redis": "^10.0.0",
 		"express": "^5.2.1",
 		"express-session": "^1.19.0",
-		"helmet": "^8.1.0",
-		"ioredis": "^5.11.0",
+		"helmet": "^8.3.0",
+		"ioredis": "^6.0.0",
 		"pino": "^10.3.1",
-		"redis": "^5.12.1"
+		"prom-client": "^15.1.3",
+		"redis": "^6.2.1"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/express-session": "^1",
-		"@types/node": "^25.9.1",
-		"@types/supertest": "^7.2.0",
+		"@types/node": "^26.2.0",
+		"@types/supertest": "^7.2.1",
 		"supertest": "^7.1.0",
-		"tsx": "^4.22.3",
-		"typescript": "^5.9.3",
-		"vitest": "^4.1.8"
-	},
-	"pnpm": {
-		"onlyBuiltDependencies": [
-			"bcrypt"
-		]
+		"tsx": "^4.23.10",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.11"
 	}
 }