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

package/dist/index.mjs

@@ -14,12 +14,46 @@
  * limitations under the License.
  */
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { shouldCopyTemplateEntry } from "./internal/template-filter.mjs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const TEMPLATES_DIR = resolve(__dirname, "../templates/standalone");
+const TEMPLATES_ROOT = resolve(__dirname, "../templates");
+/** The template a scaffold is made from when none is named. */
+export const DEFAULT_TEMPLATE = "standalone";
+/**
+ * The templates under `templatesRoot`: every directory — not a symbolic link,
+ * not dot-named — holding a `package.json`, sorted; none when the directory is
+ * missing. This is the rule `scripts/templates.mjs` copies templates by, read
+ * here from the copy, where `versions.json` sits beside them. A name is only
+ * ever looked up in this list, so nothing outside the templates directory can
+ * be named as a template.
+ */
+export const availableTemplates = (templatesRoot = TEMPLATES_ROOT) => {
+    if (!existsSync(templatesRoot))
+        return [];
+    return readdirSync(templatesRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        !entry.name.startsWith(".") &&
+        existsSync(resolve(templatesRoot, entry.name, "package.json")))
+        .map((entry) => entry.name)
+        .sort();
+};
+/**
+ * Why `template` cannot be scaffolded from `templates`, or `undefined` when it
+ * can: none is bundled (a checkout that never ran the prebuild script), or it
+ * is not one of them.
+ */
+export const templateRefusal = (template, templates) => {
+    if (templates.length === 0) {
+        return `No templates found at ${TEMPLATES_ROOT}. If developing locally, run the prebuild script first.`;
+    }
+    if (!templates.includes(template)) {
+        return `Unknown template '${template}'. Available templates: ${templates.join(", ")}.`;
+    }
+    return undefined;
+};
 const getPackageVersions = () => {
     const versionFile = resolve(__dirname, "../templates/versions.json");
     if (existsSync(versionFile)) {
@@ -44,35 +78,47 @@ export const isValidDirName = (name) => {
         return false;
     return UNSCOPED_NAME_RE.test(name);
 };
-export const scaffold = (targetDir, projectName) => {
-    if (!existsSync(TEMPLATES_DIR)) {
-        throw new Error(`Template directory not found at ${TEMPLATES_DIR}. If developing locally, run the prebuild script first.`);
-    }
+/**
+ * Appended to the scaffold's `config/application.conf` by `noMfa`: the
+ * template's switch `mfaMode` written off, then bound to `MFA_MODE` so the
+ * variable wins over the written value. The MFA package stays a dependency.
+ */
+const MFA_OFF_LINES = [
+    "",
+    "# written by create-app --no-mfa: MFA is off unless MFA_MODE turns it on",
+    'mfaMode = "off"',
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: a HOCON substitution, not a template
+    "mfaMode = ${?MFA_MODE}",
+];
+export const scaffold = (targetDir, projectName, template = DEFAULT_TEMPLATE, options = {}) => {
+    const refusal = templateRefusal(template, availableTemplates());
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    const templateDir = resolve(TEMPLATES_ROOT, template);
     // Copy template to target
-    cpSync(TEMPLATES_DIR, targetDir, {
+    cpSync(templateDir, targetDir, {
         recursive: true,
-        filter: (source) => shouldCopyTemplateEntry(source, TEMPLATES_DIR),
+        filter: (source) => shouldCopyTemplateEntry(source, templateDir),
     });
-    // #407: npm drops a file literally named `.gitignore` from a published
-    // package, so `copy-templates.mjs` stages it dot-less and it is restored
-    // here. Without it the first `git add .` in a scaffolded project commits
-    // the `.env` and the signing key the README's own setup steps say to
-    // create — and it would have shipped that way silently, because the file
-    // is present in the repository and only missing from the tarball.
+    // npm drops a file literally named `.gitignore` from a published package,
+    // so `copy-templates.mjs` stages it dot-less and it is restored here.
+    // Without it the first `git add .` in a scaffolded project commits the
+    // `.env` and the signing key the README's setup steps create.
     const stagedGitignore = resolve(targetDir, "gitignore");
     if (existsSync(stagedGitignore)) {
         renameSync(stagedGitignore, resolve(targetDir, ".gitignore"));
     }
+    if (options.noMfa === true) {
+        appendFileSync(resolve(targetDir, "config", "application.conf"), `${MFA_OFF_LINES.join("\n")}\n`);
+    }
     // Rewrite package.json
     const pkgPath = resolve(targetDir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
     pkg.name = projectName;
-    // `"private": true` is deliberately KEPT (o3co/auth.policy-verifier#126
-    // item 4, same code in both scaffolders). The scaffold is an identity
-    // provider — keys, config, policy — and deleting the field made an
-    // accidental `npm publish` succeed by default. Publishing a scaffolded
-    // service is the rare intent; the operator who has it states it by
-    // removing the field.
+    // `"private": true` is deliberately kept: the scaffold is an identity
+    // provider (keys, config, policy), so an accidental `npm publish` must fail
+    // by default. An operator who means to publish removes the field.
+    // o3co/auth.policy-verifier's scaffolder does the same; change the two together.
     // Replace all workspace:* references with per-package published versions
     const versions = getPackageVersions();
     for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
@@ -91,11 +137,9 @@ export const scaffold = (targetDir, projectName) => {
     }
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
     // pnpm ≥10.29 reads `onlyBuiltDependencies` only from pnpm-workspace.yaml,
-    // in single-package projects too — the template's former package.json
-    // `pnpm` block is silently ignored (#360). The template cannot ship the
-    // file: inside the monorepo it would shadow the workspace root for anyone
-    // running pnpm from the template directory. So the scaffold writes it,
-    // mirroring the allowlist the workspace root keeps for the same dependency.
+    // even in single-package projects. The template cannot ship the file:
+    // inside the monorepo it would shadow the workspace root. So the scaffold
+    // writes it, mirroring the workspace root's allowlist.
     writeFileSync(resolve(targetDir, "pnpm-workspace.yaml"), [
         "# pnpm (>= 10.29) reads onlyBuiltDependencies from this file, even in a",
         "# single-package project. bcrypt's install hook compiles the native addon",
@@ -114,25 +158,19 @@ export const scaffold = (targetDir, projectName) => {
  */
 const LOCKFILE_ARGS = ["install", "--lockfile-only", "--ignore-workspace"];
 /**
- * Launchers tried in order. `pnpm` on PATH is the common case; `corepack pnpm`
- * answers the machine that has Node's bundled corepack but no global pnpm.
- * The fallback fires only on ENOENT — the one launch error a different
- * launcher can answer. A non-zero exit (offline, private registry,
- * unpublished version) would fail identically through any launcher, and
- * EACCES-shaped errors surface as themselves rather than as "package manager
- * missing".
+ * Launchers tried in order: `pnpm` on PATH, then `corepack pnpm` for a machine
+ * with Node's bundled corepack but no global pnpm. Only ENOENT falls through to
+ * the next launcher; a non-zero exit would fail identically through any of
+ * them, and other launch errors surface as themselves.
  */
 const LOCKFILE_LAUNCHERS = [["pnpm"], ["corepack", "pnpm"]];
 /**
- * Resolve the scaffolded project's dependency graph into `pnpm-lock.yaml`.
- *
- * This is what makes the template's `pnpm install --frozen-lockfile` build
- * possible: the lockfile cannot be shipped with the template, because the
- * dependency set it would pin does not exist until `scaffold` has replaced
- * every `workspace:*` with a published version (#289). It is therefore
- * resolved once, here, against the rewritten `package.json`. Best-effort by
- * design — it needs a package manager and a reachable registry — so failure
- * is a result, not a throw.
+ * Resolve the scaffolded project's dependency graph into `pnpm-lock.yaml`,
+ * which the template's `pnpm install --frozen-lockfile` build needs. The
+ * lockfile cannot ship with the template: the dependency set it pins exists
+ * only after `scaffold` has replaced every `workspace:*`. Best-effort (it needs
+ * a package manager and a reachable registry), so failure is a result, not a
+ * throw.
  */
 export const generateLockfile = (targetDir) => {
     const attempts = [];
@@ -161,31 +199,39 @@ export const generateLockfile = (targetDir) => {
     }
     return { ok: false, reason: attempts.join("; ") };
 };
+/** The flags that take a value, as `--flag <value>` or `--flag=<value>`. */
+const VALUE_FLAGS = ["--dir", "--template"];
 const parseArgs = (args) => {
     const positionals = [];
-    let dir;
-    let dirSeen = false;
+    const values = new Map();
     let lockfile = true;
+    let noMfa = false;
+    const setValue = (flag, value) => {
+        if (values.has(flag))
+            throw new Error(`${flag} specified more than once`);
+        if (value === "")
+            throw new Error(`${flag} requires a value`);
+        values.set(flag, value);
+    };
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === "--dir") {
-            if (dirSeen)
-                throw new Error("--dir specified more than once");
+        const spaced = VALUE_FLAGS.find((flag) => a === flag);
+        const joined = VALUE_FLAGS.find((flag) => a.startsWith(`${flag}=`));
+        if (spaced !== undefined) {
             if (i + 1 >= args.length)
-                throw new Error("--dir requires a value");
-            dir = args[i + 1];
-            dirSeen = true;
+                throw new Error(`${spaced} requires a value`);
+            setValue(spaced, args[i + 1]);
             i++;
         }
-        else if (a.startsWith("--dir=")) {
-            if (dirSeen)
-                throw new Error("--dir specified more than once");
-            dir = a.slice("--dir=".length);
-            dirSeen = true;
+        else if (joined !== undefined) {
+            setValue(joined, a.slice(`${joined}=`.length));
         }
         else if (a === "--no-lockfile") {
             lockfile = false;
         }
+        else if (a === "--no-mfa") {
+            noMfa = true;
+        }
         else if (a.startsWith("-")) {
             // Treats `--` and any --unknown as an unknown flag.
             throw new Error(`unknown flag: ${a}`);
@@ -198,7 +244,13 @@ const parseArgs = (args) => {
         throw new Error("missing <project-name>");
     if (positionals.length > 1)
         throw new Error("too many positional arguments");
-    return { projectName: positionals[0], dir, lockfile };
+    return {
+        projectName: positionals[0],
+        dir: values.get("--dir"),
+        template: values.get("--template"),
+        lockfile,
+        noMfa,
+    };
 };
 const deriveDirName = (projectName, dir) => {
     if (dir !== undefined)
@@ -224,11 +276,13 @@ export const main = () => {
     }
     catch (e) {
         console.error(`Error: ${e.message}`);
-        console.error("Usage: @o3co/create-auth-provider <project-name> [--dir <dir-name>] [--no-lockfile]");
+        console.error("Usage: @o3co/create-auth-provider <project-name> [--template <name>] [--dir <dir-name>] [--no-lockfile] [--no-mfa]");
         console.error("<project-name> must be a valid npm package name (scoped like @scope/pkg, or unscoped).");
+        console.error(`--template names the template to copy (default: ${DEFAULT_TEMPLATE}); available: ${availableTemplates().join(", ")}.`);
         process.exit(1);
     }
-    const { projectName, dir, lockfile } = parsed;
+    const { projectName, dir, lockfile, noMfa } = parsed;
+    const template = parsed.template ?? DEFAULT_TEMPLATE;
     if (!isValidProjectName(projectName)) {
         console.error("Error: <project-name> must be a valid npm package name (scoped like @scope/pkg, or unscoped; max 214 chars; no backslashes; no extra '/' beyond the single scope separator).");
         process.exit(1);
@@ -237,14 +291,19 @@ export const main = () => {
         console.error("Error: --dir must be a valid unscoped package name (no '/', '\\', '@'; not '.' or '..'; max 214 chars).");
         process.exit(1);
     }
+    const refusal = templateRefusal(template, availableTemplates());
+    if (refusal !== undefined) {
+        console.error(`Error: ${refusal}`);
+        process.exit(1);
+    }
     const dirName = deriveDirName(projectName, dir);
     const targetDir = resolve(process.cwd(), dirName);
     if (existsSync(targetDir)) {
         console.error(`Error: Directory '${dirName}' already exists.`);
         process.exit(1);
     }
-    console.log(`Creating ${projectName}...`);
-    scaffold(targetDir, projectName);
+    console.log(`Creating ${projectName} from the ${template} template...`);
+    scaffold(targetDir, projectName, template, { noMfa });
     let lockfileGenerated = false;
     if (lockfile) {
         console.log("\nResolving dependencies into pnpm-lock.yaml...");

package/dist/internal/template-filter.d.mts

@@ -1,17 +1,14 @@
 /**
  * Decide whether `cpSync` should copy a given source path.
  *
- * Only segments INSIDE `templateRoot` are checked against EXCLUDED_DIRS — the
- * install-prefix path above the root (e.g. `~/.npm/_npx/<hash>/node_modules/...`
- * when the package is run via `npx`) is ignored. Otherwise the filter would
- * reject every file whenever the package itself happens to live under a
- * `node_modules` directory (which is the v0.5.0 npx regression this fixes).
+ * Only segments inside `templateRoot` are checked against EXCLUDED_DIRS; the
+ * install prefix above it (e.g. `~/.npm/_npx/<hash>/node_modules/...` under
+ * `npx`) is ignored, or every file would be rejected whenever the package
+ * itself lives under a `node_modules` directory.
  *
- * The `pathSep` parameter exists so unit tests can exercise both POSIX and
- * Windows separators regardless of the host platform; production callers omit
- * it and pick up `path.sep` of the running platform. DO NOT change this to a
- * hardcoded `"/"` — `cpSync` passes back-slash-delimited absolute paths on
- * Windows, so segment splitting must follow the platform separator.
+ * `pathSep` lets tests exercise POSIX and Windows separators on any host.
+ * Production callers keep the `path.sep` default: `cpSync` passes
+ * backslash-delimited paths on Windows.
  */
 export declare const shouldCopyTemplateEntry: (source: string, templateRoot: string, pathSep?: string) => boolean;
 //# sourceMappingURL=template-filter.d.mts.map

package/dist/internal/template-filter.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"template-filter.d.mts","sourceRoot":"","sources":["../../src/internal/template-filter.mts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GACnC,QAAQ,MAAM,EACd,cAAc,MAAM,EACpB,UAAS,MAAY,KACnB,OAMF,CAAC"}
+{"version":3,"file":"template-filter.d.mts","sourceRoot":"","sources":["../../src/internal/template-filter.mts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GACnC,QAAQ,MAAM,EACd,cAAc,MAAM,EACpB,UAAS,MAAY,KACnB,OAMF,CAAC"}

package/dist/internal/template-filter.mjs

@@ -22,17 +22,14 @@ const EXCLUDED_DIRS = new Set(["node_modules", "dist"]);
 /**
  * Decide whether `cpSync` should copy a given source path.
  *
- * Only segments INSIDE `templateRoot` are checked against EXCLUDED_DIRS — the
- * install-prefix path above the root (e.g. `~/.npm/_npx/<hash>/node_modules/...`
- * when the package is run via `npx`) is ignored. Otherwise the filter would
- * reject every file whenever the package itself happens to live under a
- * `node_modules` directory (which is the v0.5.0 npx regression this fixes).
+ * Only segments inside `templateRoot` are checked against EXCLUDED_DIRS; the
+ * install prefix above it (e.g. `~/.npm/_npx/<hash>/node_modules/...` under
+ * `npx`) is ignored, or every file would be rejected whenever the package
+ * itself lives under a `node_modules` directory.
  *
- * The `pathSep` parameter exists so unit tests can exercise both POSIX and
- * Windows separators regardless of the host platform; production callers omit
- * it and pick up `path.sep` of the running platform. DO NOT change this to a
- * hardcoded `"/"` — `cpSync` passes back-slash-delimited absolute paths on
- * Windows, so segment splitting must follow the platform separator.
+ * `pathSep` lets tests exercise POSIX and Windows separators on any host.
+ * Production callers keep the `path.sep` default: `cpSync` passes
+ * backslash-delimited paths on Windows.
  */
 export const shouldCopyTemplateEntry = (source, templateRoot, pathSep = sep) => {
     if (source === templateRoot)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.15.0",
-  "description": "Scaffold a new o3co/auth.provider project from the standalone template",
+  "version": "0.17.0-rc.1",
+  "description": "Scaffold a new o3co/auth.provider project from one of its templates",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -28,8 +28,10 @@
     "node": ">=22.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
-    "vitest": "^5.0.0"
+    "@o3co/ts.hocon": "^1.13.0",
+    "@types/node": "^26.6.3",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.2"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/.dockerignore

@@ -1,9 +1,22 @@
 node_modules
 dist
 .git
-.env*
-!.env.example
 Makefile
+# #705: the secrets and the per-deployment configuration that `.gitignore`
+# keeps out of git stay out of the build context as well. The builder stage
+# COPYs `config/` and the runtime image takes it from there, so a
+# `config/clients.yaml` in the working copy — client secrets included — was
+# baked into a layer that travels with every push; the production compose
+# mounts the registry instead. This is `.gitignore`'s secrets section, written
+# with `**/` where it matches at any depth: a `.dockerignore` pattern is
+# anchored at the context root. Keep the two in step; scaffold-assets.test.mts
+# checks that they are.
+**/.env*
+!**/.env.example
+**/*.pem
+**/*.key
+config/clients.yaml
+config/*.local.conf
 # .gitignore, the READMEs and the compose files stay in the context: the
 # `test` image copies them because the shipped suite reads them (#512). The
 # runtime image never copies them, so they cost the context a few kilobytes

package/templates/standalone/.env.example

@@ -12,10 +12,10 @@ OAUTH_JWT_ISSUER=
 #   openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
 #
 # Keep jwt-private.pem out of version control and off the image.
-OAUTH_JWT_PRIVATE_KEY_PATH=./jwt-private.pem
-OAUTH_JWT_PUBLIC_KEY_PATH=./jwt-public.pem
-# OAUTH_JWT_ALGORITHM=EdDSA          # EdDSA | ES256 | RS256 | HS256
-# OAUTH_JWT_KID=v0
+KEY_STORE_LOCAL_PRIVATE_KEY_PATH=./jwt-private.pem
+KEY_STORE_LOCAL_PUBLIC_KEY_PATH=./jwt-public.pem
+# KEY_STORE_LOCAL_ALGORITHM=EdDSA          # EdDSA | ES256 | RS256 | HS256
+# KEY_STORE_LOCAL_KID=v0
 #
 # HS256 alternative — symmetric, so /.well-known/jwks.json publishes NOTHING
 # and every relying party must hold a secret that can also MINT tokens. Only
@@ -23,22 +23,39 @@ OAUTH_JWT_PUBLIC_KEY_PATH=./jwt-public.pem
 #   openssl rand -hex 32
 # Hex/base64 values are measured DECODED, so a 32-character hex string counts
 # as 16 bytes and is refused.
-# OAUTH_JWT_ALGORITHM=HS256
-# OAUTH_JWT_SECRET=
+# KEY_STORE_LOCAL_ALGORITHM=HS256
+# KEY_STORE_LOCAL_SECRET=
 
 # --- Session (required) ------------------------------------------------------
 # Signs the cookie that IS the authenticated session, so guessing it forges
 # logins. Same >= 32-byte floor and same decoded measurement:
 #   openssl rand -hex 32
-SESSION_SECRET=
+SESSION_STORE_SECRET=
 
 # User repository
 # Both URLs carry plaintext user credentials to the upstream store, 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 compose service
 # name such as http://user-service:8080 still needs https. Boot fails otherwise.
-CLIENT_USER_AUTHENTICATE_URL=
-CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=
+# Each must be the endpoint that answers: no request follows a 3xx, so a URL that
+# redirects fails every call.
+REPOSITORIES_USER_HTTP_AUTHENTICATE_URL=
+REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL=
+# With MFA on: the Store's endpoint the MFA enrollment witness is written to,
+# so a Store that loses a subject's factors cannot open a first binding to
+# whoever holds the password. Your Store must then answer `mfaEnrolled` on
+# both URLs above. Unset, boot warns (mfa_enrollment_witness_unwritable).
+# REPOSITORIES_USER_HTTP_MARK_MFA_ENROLLED_URL=https://users.example.com/mfa/enrolled
+# The credential this server presents to the Store: every Store request carries
+# `Authorization: Bearer <token>`. Without one, anyone who can reach the Store
+# can resolve an identity to its user, so your Store should refuse any request
+# without it, with 401 and `WWW-Authenticate: Bearer error="invalid_token"`
+# (which this server then reports as an outage naming the refused credential).
+# The one token goes to every Store URL above: they must be one trust domain.
+# At least 32 bytes, measured like SESSION_STORE_SECRET; boot fails on a weak or
+# malformed value. Left commented out because a blank value is refused too:
+#   openssl rand -hex 32
+# REPOSITORIES_USER_HTTP_BEARER_TOKEN=
 
 # --- Reverse proxy (required in production) -----------------------------------
 # Express `trust proxy`. Set this to the address or CIDR range of whatever
@@ -53,44 +70,72 @@ CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=
 # limit shares one bucket. A plain-HTTP local run needs nothing here.
 HTTP_TRUST_PROXY=
 
-# Redis (code repository + session storage + the shared client socket)
+# Redis (session storage + the shared client socket)
 # Use redis://redis:6379 when running via docker compose
-CLIENT_CODE_ENDPOINT_URI=redis://redis:6379
-SESSION_STORAGE_REDIS_URL=redis://redis:6379
+SESSION_STORE_STORAGE_REDIS_URL=redis://redis:6379
 # #407: this one backs the SHARED ioredis socket -- the refresh-token family
 # store, the access-token denylist and the rate limiter all ride on it. It
 # defaults to redis://localhost:6379, which inside the container is the
 # container, so leaving it unset makes the compose boot dial nothing.
-REFRESH_TOKEN_FAMILY_STORE_REDIS_URL=redis://redis:6379
+REDIS_CLIENTS_URL=redis://redis:6379
 
 # --- Federation grants (#593, optional) --------------------------------------
 # Offline delegation of an upstream IdP's tokens to a backend or an agent, on a
 # consent that survives logout. Off by default; on, boot refuses what is
 # missing by name. The consent page is yours (README: Federation Grants). The
 # connections and the encryption key ring are lists, so they live in a HOCON
-# layer, not here. Both stores ship on Redis; Redis GRANTS need
-# USER_SESSION_STORES_ADAPTER=redis beside them (the compose files set it) —
+# layer, not here. Both stores ship as none: select each (redis, or memory on
+# one replica) with the two ADAPTERS_ lines below. Redis GRANTS need
+# ADAPTERS_USER_SESSION_STORES=redis beside them (the compose files set it) —
 # the grants would outlive a memory boundary that ends them.
 # FEDERATION_GRANTS_ENABLED=true
 # FEDERATION_GRANTS_CONSENT_URL=/consent/grants
-# `required` seals credentials under federationGrants.encryptionKeys (HOCON);
+# `required` seals credentials under redis-federation-grant-store.encryptionKeys (HOCON);
 # `allow-plaintext` is refused in production/staging and under multi.
-# FEDERATION_GRANTS_ENCRYPTION_MODE=required
+# REDIS_FEDERATION_GRANT_STORE_ENCRYPTION_MODE=required
 # `required` needs a user repository that covers every connection's
 # registration: the shipped http one asks your Store at the URL below and
 # covers what repositories.user.http.federatedIdentityLookupCoverage (HOCON)
 # declares; `unsupported` records that the check is not made.
 # FEDERATION_GRANTS_IDENTITY_LOOKUP=required
-# CLIENT_USER_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL=https://users.example.com/find-subject-by-federated-identity
-# FEDERATION_GRANT_STORE_ADAPTER=redis
-# FEDERATION_GRANT_INTENT_STORE_ADAPTER=redis
+# REPOSITORIES_USER_HTTP_FIND_SUBJECT_BY_FEDERATED_IDENTITY_URL=https://users.example.com/find-subject-by-federated-identity
+# ADAPTERS_FEDERATION_GRANT_STORE=redis
+# ADAPTERS_FEDERATION_GRANT_INTENT_STORE=redis
+
+# --- Multi-factor authentication (on by default) -----------------------------
+# MFA_MODE: required (the default: every password login needs a second
+# factor) | optional | off. The MFA page is yours (README: Multi-factor
+# authentication). Development needs nothing here: config/development.conf
+# holds a sample key, the codes are logged, and docker-compose.yml keeps the
+# two MFA stores on its Redis. Outside development, set all of the following,
+# or boot is refused naming them:
+# - the two MFA stores, which ship in memory, refused outside development and
+#   test since a restart empties them of every factor: redis (or, for the
+#   factors, store);
+# - a key of your own (openssl rand -base64 32);
+# - the SMTP relay the account-email proof and the email factor's codes go
+#   through.
+# The MFA page's URL defaults to /mfa, which you must serve, in development
+# too, or every password login stops there.
+# ADAPTERS_MFA_FACTOR_STORE=redis
+# ADAPTERS_MFA_TRANSACTION_STORE=redis
+# MFA_ENCRYPTION_KEY=
+# STANDARD_SMTP_MAIL_SENDER_HOST=smtp.example.com
+# STANDARD_SMTP_MAIL_SENDER_FROM=auth@example.com
+# MFA_PAGE_URL=/mfa
+# Or run without MFA:
+# MFA_MODE=off
+# To read the mail in development, leave every STANDARD_SMTP_MAIL_SENDER_*
+# unset (USER and PASSWORD included) and run the Mailpit
+# overlay, which sets them (README: Mailpit for the SMTP sender):
+#   docker compose -f docker-compose.yml -f docker-compose.mailpit.yml up --build
 
 # Development (override for local HTTP).
 # The default cookie name carries the `__Host-` prefix, which browsers only
 # accept on a Secure cookie — so dropping Secure means renaming the cookie too,
 # or boot refuses the combination.
-SESSION_SECURE=false
-SESSION_NAME=auth.sid
+SESSION_STORE_SECURE=false
+SESSION_STORE_NAME=auth.sid
 
 # Optional
 # HTTP_PORT=3000
@@ -101,5 +146,5 @@ SESSION_NAME=auth.sid
 # that one is unset.
 # OAUTH_ACCESS_TOKEN_EXPIRES_IN=3600
 # OAUTH_REFRESH_TOKEN_EXPIRES_IN=86400
-# SESSION_MAX_AGE=3600000
-# SESSION_SAME_SITE=lax             # `none` additionally requires SESSION_SECURE=true
+# SESSION_STORE_MAX_AGE=3600000
+# SESSION_STORE_SAME_SITE=lax             # `none` additionally requires SESSION_STORE_SECURE=true

package/templates/standalone/Dockerfile

@@ -3,7 +3,7 @@
 # rebuild (#289). The digest is the multi-arch index, so amd64 and arm64 both
 # resolve from it. Dependabot's `docker` ecosystem keeps the pair in step —
 # bump the tag and the digest together, never the tag alone.
-FROM node:26-alpine@sha256:ef24c5053d50fdc3e4e56eb4e7ddb7861874ab0fdc797046ba897581deb8e868 AS node-base
+FROM node:26-alpine@sha256:0b36e8c136b94cd4fcf02188228e76c31ad5872eef3fec8cbd2eee500cfd9e80 AS node-base
 
 ENV HOME=/home/node
 
@@ -48,6 +48,10 @@ FROM deps AS builder
 USER node
 
 COPY --chown=node:node tsconfig.json ./
+# What `.dockerignore` lets through (#705): the committed configuration layers
+# and the example, never `clients.yaml` or a key. The runtime image copies
+# this directory, so anything per-deployment here would be baked into it; the
+# production compose mounts the client registry instead.
 COPY --chown=node:node config/ ./config/
 COPY --chown=node:node src/ ./src/
 
@@ -92,7 +96,7 @@ EXPOSE ${HTTP_PORT}
 # per-service, which keeps the restart-driving signal out of it.
 #
 # Use the shell form so ${HTTP_PORT} expands at probe time. The HOCON
-# config reads `${?HTTP_PORT}` for `http.port`, so app.listen() and the
+# config reads `${?HTTP_PORT}` for `http.port`, so the listener and the
 # probe stay in sync regardless of the operator's port choice.
 HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
   CMD wget -q -O /dev/null "http://localhost:${HTTP_PORT}/_healthcheck" || exit 1
@@ -111,7 +115,7 @@ COPY --chown=node:node tests/ ./tests/
 # on files that were never a test's business. `.dockerignore` lets them into
 # the context for the same reason; nothing copies them into `runtime`.
 COPY --chown=node:node Dockerfile .dockerignore .env.example .gitignore README.md README.ja.md \
-  docker-compose.yml docker-compose.production.yml ./
+  docker-compose.yml docker-compose.production.yml docker-compose.mailpit.yml ./
 
 CMD ["pnpm", "run", "test", "--", "--passWithNoTests"]