@o3co/create-auth-provider 0.17.0 → 0.18.0-rc.1

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

@@ -1,229 +0,0 @@
-# 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. So does
-# the client registry, `config/clients.yaml` (#705): it is per-deployment, so
-# `.gitignore` keeps it out of git and `.dockerignore` out of the image, and
-# the image carries no registry of its own. Create it from
-# `config/clients.yaml.example` before the first `up`.
-#
-# What this file deliberately does NOT do:
-#
-# - **TLS.** Terminate it in front (reverse proxy / load balancer). The
-#   HTTP_TRUST_PROXY entry below then needs that hop's address so `req.ip` —
-#   and every IP-keyed rate limit — means the client, not the proxy; compose
-#   refuses to start until you supply it. See README "Multi-replica
-#   deployments".
-# - **Scale out.** This is one replica (CORE_DEPLOYMENT_MODE=single). Before
-#   `--scale app=N`, set CORE_DEPLOYMENT_MODE=multi and read that same README
-#   section — boot will then refuse any in-memory store that must be shared.
-# - **Invent secrets.** SESSION_STORE_SECRET comes 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. The client
-#   registry's secrets are yours to write too; give them as bcrypt hashes.
-
-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"
-    # Compose's default grace is ten seconds — the HTTP drain
-    # budget alone. With federation grants on, `src/app.mts` gives cleanup 45
-    # more for the drain of a rotated upstream credential's write, and SIGKILL
-    # has to arrive after that: drain (10) + cleanup (45) + an exit margin.
-    # The cleanup allowance grows by itself with `federation-grants.upstreamHardTimeoutMs`,
-    # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
-    stop_grace_period: 60s
-    depends_on:
-      redis:
-        condition: service_healthy
-    env_file:
-      # Required, unlike the dev file: a production boot without
-      # SESSION_STORE_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
-      # The client registry (#705), for the same reason: `config/clients.yaml`
-      # is per-deployment and may hold client secrets, so it is kept out of the
-      # image and mounted here. REPOSITORIES_CLIENT_YAML_PATH below points the process at it.
-      - client_registry
-    environment:
-      NODE_ENV: production
-      # One replica. Under `single` the replica-safety guard is SILENT by
-      # design — you have told it there are no peers — so it will not tell you
-      # that a store below is on memory while its sibling is on Redis. That is
-      # why the adapter block further down states every one of them explicitly
-      # instead of leaving them to inherit. Before `--scale app=N`, set `multi`
-      # and read the README's "Multi-replica deployments".
-      CORE_DEPLOYMENT_MODE: single
-      # Behind the TLS terminator this file assumes, `req.ip` is the proxy's
-      # address and `req.protocol` reads `http` until this names the hop. The
-      # README calls it required for exactly that reason, and the cost of
-      # leaving it unset is three failures at once: the Secure cookie pinned
-      # below is never set, the CSRF origin check 403s every browser POST
-      # (the browser sends `Origin: https://…`, the process believes it is
-      # serving http), and every IP-keyed rate limit — the OAuth endpoint
-      # limiters and the /session/login brute-force guard — shares ONE bucket
-      # across all users.
-      #
-      # It cannot be guessed and it is not defaulted: only you know what sits
-      # in front, and a default here would silently trust a hop you never
-      # chose. Put your edge's address or CIDR range in `.env` — `10.0.0.0/8`,
-      # or `loopback` for a sidecar on this host. Prefer that over `true`,
-      # which believes a forwarded client address from anyone able to reach
-      # this process. The `:?` form makes compose refuse to start until it is
-      # set, rather than starting wrong.
-      HTTP_TRUST_PROXY: ${HTTP_TRUST_PROXY:?set to your TLS terminator's address or CIDR range (e.g. 10.0.0.0/8, or `loopback` for a same-host sidecar) — never `true` behind an open network}
-      # Point the process at the mounted secrets rather than the working-copy
-      # paths `.env` carries for local runs.
-      KEY_STORE_LOCAL_PRIVATE_KEY_PATH: /run/secrets/jwt_private_key
-      KEY_STORE_LOCAL_PUBLIC_KEY_PATH: /run/secrets/jwt_public_key
-      REPOSITORIES_CLIENT_YAML_PATH: /run/secrets/client_registry
-      # `environment` wins over `env_file`, which is the point here:
-      # `.env.example` ships SESSION_STORE_SECURE=false / SESSION_STORE_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_STORE_SECURE: "true"
-      SESSION_STORE_NAME: __Host-auth.session
-      # Every Redis-backed store shares the compose-network Redis below.
-      #
-      # These are stated in full rather than inherited from
-      # `config/reference.conf`, so that the deployable file names its own
-      # topology: an operator reading only this one can see which stores
-      # survive a restart. `ADAPTERS_CODE_REPOSITORY` and
-      # `ADAPTERS_ACCESS_TOKEN_DENYLIST` already ship as `redis` in that file
-      # and are left there on purpose — restating a value that agrees is
-      # a second place to forget to change.
-      REDIS_CLIENTS_URL: redis://redis:6379
-      SESSION_STORE_STORAGE_TYPE: redis
-      SESSION_STORE_STORAGE_REDIS_URL: redis://redis:6379
-      # The UserSession stores: the provider's own record of who is signed in,
-      # the subject index and revocation boundaries beside it, and the session
-      # lifecycle records. They MUST be on Redis whenever the express-session
-      # store above is, and this line is the fix for what happens when they
-      # are not.
-      #
-      # express-session on Redis survives a restart; a memory UserSession store
-      # does not. So every browser comes back holding a session cookie whose
-      # express-session record still says `isAuthenticated: true`, while the
-      # `UserSession` that record points at is gone — /authorize sees an
-      # authenticated session, finds no user session behind it, and sends the
-      # browser to log in again, where the still-valid cookie puts it straight
-      # back. A login loop that clears only when the user deletes the cookie.
-      # `CORE_DEPLOYMENT_MODE: single` says nothing about it: the replica guard
-      # answers "can these stores be shared", not "do these two stores have the
-      # same lifetime".
-      ADAPTERS_USER_SESSION_STORES: redis
-      # The memory rate limiter is per-process and evadable under bucket
-      # exhaustion (see README) — production points it at Redis.
-      ADAPTERS_RATE_LIMITER: redis
-      # The counter behind the login's own attempt limit: on Redis, a restart
-      # does not reset it. Redis must keep `maxmemory-policy noeviction`.
-      ADAPTERS_ATTEMPT_COUNTER: redis
-      # The federation token store is deliberately left at its `memory`
-      # default, and that is coherent here rather than an oversight: this
-      # template ships every federation disabled, so nothing writes to the
-      # store, and switching it on would need a 32-byte AES key
-      # (REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY) that this file must not
-      # invent — the records are long-lived upstream refresh tokens. Enabling
-      # a federation means setting BOTH, together:
-      #   ADAPTERS_FEDERATION_TOKEN_STORE: redis
-      #   REDIS_FEDERATION_TOKEN_STORE_ENCRYPTION_KEY: <openssl rand -base64 32, from .env>
-      #
-      # MFA is on by default (MFA_MODE, `required`): every password login
-      # needs a second factor. Its two stores are left at their `memory`
-      # default, which the template refuses in production before boot; that
-      # refusal names everything MFA needs and the opt-out, so it is the first
-      # thing a deployment that has decided nothing about MFA meets. Decide in
-      # `.env`: either turn it on with all of
-      #   ADAPTERS_MFA_FACTOR_STORE=redis       (or `store`, the factors in your Store)
-      #   ADAPTERS_MFA_TRANSACTION_STORE=redis
-      #   MFA_ENCRYPTION_KEY=<openssl rand -base64 32>
-      #   STANDARD_SMTP_MAIL_SENDER_HOST=... and STANDARD_SMTP_MAIL_SENDER_FROM=...
-      #   MFA_PAGE_URL=<your MFA page, /mfa by default>
-      # or keep the provider without MFA:
-      #   MFA_MODE=off
-      # The Redis below persists (appendonly), as the MFA stores need: a lost
-      # factor lets whoever holds the password bind one of their own.
-
-  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 and the client registry stay on the host and
-  # reach the container read-only at /run/secrets. Keep them 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
-  client_registry:
-    file: ./config/clients.yaml

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

@@ -1,16 +0,0 @@
-services:
-  test:
-    build:
-      context: .
-      target: test
-    depends_on:
-      redis:
-        condition: service_healthy
-
-  redis:
-    image: redis:7.2-alpine
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 5s
-      timeout: 3s
-      retries: 5

package/templates/standalone/docker-compose.yml

@@ -1,67 +0,0 @@
-services:
-  app:
-    build:
-      context: .
-      target: develop
-    ports:
-      - "3000:3000"
-    volumes:
-      - ./src:/home/node/src
-      - ./config:/home/node/config
-    # Compose's default grace is ten seconds — the HTTP drain
-    # budget alone. With federation grants on, `src/app.mts` gives cleanup 45
-    # more for the drain of a rotated upstream credential's write, and SIGKILL
-    # has to arrive after that: drain (10) + cleanup (45) + an exit margin.
-    # The cleanup allowance grows by itself with `federation-grants.upstreamHardTimeoutMs`,
-    # `persistRetryBudgetMs` and `lockWaitMs`; raise this to match when you raise them.
-    stop_grace_period: 60s
-    depends_on:
-      redis:
-        condition: service_healthy
-    env_file:
-      - path: .env
-        required: false
-    environment:
-      # The same coherence the production file states, for the same reason,
-      # and it matters MORE here. `config/application.conf` already puts
-      # express-session, the authorization codes and the access-token denylist
-      # on the Redis this compose runs; only the UserSession stores were left
-      # on their `memory` default. That combination survives a restart on one
-      # side and not the other, so every browser comes back holding an
-      # express-session that still says `isAuthenticated` with no `UserSession`
-      # behind it and /authorize loops.
-      #
-      # A dev container restarts on every save (`target: develop` is hot
-      # reload), so the developer meets that loop constantly — and meets it
-      # while changing something else, which is the worst possible time to
-      # debug it. Redis is already running and already required by three other
-      # stores, so this costs nothing: the shared ioredis socket is open
-      # either way.
-      ADAPTERS_USER_SESSION_STORES: redis
-      # MFA is on by default (MFA_MODE). Its two stores ship in memory, which
-      # this run would empty on every save: every enrolled factor gone while
-      # the sessions above survive, so each password login after a save binds
-      # a factor anew. On the Redis above they last as the sessions do. These
-      # lines, like ADAPTERS_USER_SESSION_STORES above, override `.env`:
-      # compose's `environment:` wins over `env_file`. The key ring is
-      # config/development.conf's sample key and the mail sender logs each
-      # code; MFA_MODE=off in .env runs without MFA.
-      ADAPTERS_MFA_FACTOR_STORE: redis
-      ADAPTERS_MFA_TRANSACTION_STORE: 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
-    ports:
-      - "127.0.0.1:6379:6379"
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 5s
-      timeout: 3s
-      retries: 5

package/templates/standalone/gitignore

@@ -1,23 +0,0 @@
-# #407: without this file, the first `git add .` in a scaffolded project
-# 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
-# `.dockerignore` keeps the same out of the image (#705); change both together.
-.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,56 +0,0 @@
-{
-	"name": "@o3co/auth-provider-standalone",
-	"version": "0.17.0",
-	"private": true,
-	"license": "Apache-2.0",
-	"engines": {
-		"node": ">=22.0.0"
-	},
-	"packageManager": "pnpm@10.29.3",
-	"type": "module",
-	"scripts": {
-		"build": "tsc",
-		"start": "node dist/app.mjs",
-		"debug": "NODE_OPTIONS='--conditions=development' tsx watch src/app.mts",
-		"test": "tsc --noEmit && vitest run --passWithNoTests"
-	},
-	"imports": {
-		"#/*": {
-			"development": "./src/*",
-			"default": "./dist/*"
-		}
-	},
-	"dependencies": {
-		"@o3co/auth-provider-core": "workspace:*",
-		"@o3co/auth-provider-federation-google": "workspace:*",
-		"@o3co/auth-provider-federation-grants": "workspace:*",
-		"@o3co/auth-provider-federation-oidc": "workspace:*",
-		"@o3co/auth-provider-foundation": "workspace:*",
-		"@o3co/auth-provider-mfa": "workspace:*",
-		"@o3co/auth-provider-oauth": "workspace:*",
-		"@o3co/auth-provider-redis": "workspace:*",
-		"@o3co/auth-provider-session": "workspace:*",
-		"@o3co/auth-provider-standard": "workspace:*",
-		"@o3co/ts.hocon": "^1.13.0",
-		"connect-redis": "^10.0.0",
-		"express": "^5.2.1",
-		"express-session": "^1.19.0",
-		"helmet": "^8.3.0",
-		"ioredis": "^6.0.0",
-		"pino": "^10.4.0",
-		"prom-client": "^15.1.3",
-		"redis": "^6.3.0",
-		"zod": "^4.6.5"
-	},
-	"devDependencies": {
-		"@o3co/auth-provider-test-kit": "workspace:*",
-		"@types/express": "^5.0.6",
-		"@types/express-session": "^1",
-		"@types/node": "^26.6.4",
-		"@types/supertest": "^7.2.1",
-		"supertest": "^7.3.1",
-		"tsx": "^4.23.15",
-		"typescript": "^6.0.3",
-		"vitest": "^5.0.3"
-	}
-}