@o3co/create-auth-provider 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -1,5 +1,25 @@
 export declare const isValidProjectName: (name: string) => boolean;
 export declare const isValidDirName: (name: string) => boolean;
 export declare const scaffold: (targetDir: string, projectName: string) => void;
+/** Outcome of the scaffold-time lockfile generation. */
+export type LockfileResult = {
+    readonly ok: true;
+    readonly command: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * 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.
+ */
+export declare const generateLockfile: (targetDir: string) => LockfileResult;
 export declare const main: () => void;
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IAsCjE,CAAC;AAsDF,eAAO,MAAM,IAAI,QAAO,IA+CvB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IAyEjE,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqBnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AA0DF,eAAO,MAAM,IAAI,QAAO,IAmEvB,CAAC"}

package/dist/index.mjs

@@ -13,7 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { shouldCopyTemplateEntry } from "./internal/template-filter.mjs";
@@ -52,11 +53,26 @@ export const scaffold = (targetDir, projectName) => {
         recursive: true,
         filter: (source) => shouldCopyTemplateEntry(source, TEMPLATES_DIR),
     });
+    // #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.
+    const stagedGitignore = resolve(targetDir, "gitignore");
+    if (existsSync(stagedGitignore)) {
+        renameSync(stagedGitignore, resolve(targetDir, ".gitignore"));
+    }
     // Rewrite package.json
     const pkgPath = resolve(targetDir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
     pkg.name = projectName;
-    delete pkg.private;
+    // `"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.
     // Replace all workspace:* references with per-package published versions
     const versions = getPackageVersions();
     for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
@@ -74,11 +90,82 @@ 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.
+    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",
+        "# on platforms with no shipped prebuild; without this allowlist pnpm",
+        "# silently skips the hook and bcrypt fails at require time there.",
+        "onlyBuiltDependencies:",
+        "  - bcrypt",
+        "",
+    ].join("\n"));
+};
+/**
+ * `--lockfile-only` resolves the dependency graph without installing or
+ * running any script. `--ignore-workspace` keeps the new project's lockfile
+ * its own even when the target directory happens to sit inside somebody
+ * else's pnpm workspace.
+ */
+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".
+ */
+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.
+ */
+export const generateLockfile = (targetDir) => {
+    const attempts = [];
+    for (const launcher of LOCKFILE_LAUNCHERS) {
+        const [bin, ...prefix] = launcher;
+        const args = [...prefix, ...LOCKFILE_ARGS];
+        const printable = [bin, ...args].join(" ");
+        const result = spawnSync(bin, args, {
+            cwd: targetDir,
+            stdio: "inherit",
+            shell: false,
+            env: { ...process.env, COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+        });
+        if (result.error) {
+            attempts.push(`${printable}: ${result.error.message}`);
+            // Only "not on PATH" is worth asking a different launcher about.
+            if (result.error.code === "ENOENT")
+                continue;
+            break;
+        }
+        if (result.status === 0)
+            return { ok: true, command: printable };
+        const how = result.status === null ? `killed by signal ${result.signal}` : `exit code ${result.status}`;
+        attempts.push(`${printable}: ${how}`);
+        break;
+    }
+    return { ok: false, reason: attempts.join("; ") };
 };
 const parseArgs = (args) => {
     const positionals = [];
     let dir;
     let dirSeen = false;
+    let lockfile = true;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (a === "--dir") {
@@ -96,6 +183,9 @@ const parseArgs = (args) => {
             dir = a.slice("--dir=".length);
             dirSeen = true;
         }
+        else if (a === "--no-lockfile") {
+            lockfile = false;
+        }
         else if (a.startsWith("-")) {
             // Treats `--` and any --unknown as an unknown flag.
             throw new Error(`unknown flag: ${a}`);
@@ -108,7 +198,7 @@ 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 };
+    return { projectName: positionals[0], dir, lockfile };
 };
 const deriveDirName = (projectName, dir) => {
     if (dir !== undefined)
@@ -134,11 +224,11 @@ export const main = () => {
     }
     catch (e) {
         console.error(`Error: ${e.message}`);
-        console.error("Usage: @o3co/create-auth-provider <project-name> [--dir <dir-name>]");
+        console.error("Usage: @o3co/create-auth-provider <project-name> [--dir <dir-name>] [--no-lockfile]");
         console.error("<project-name> must be a valid npm package name (scoped like @scope/pkg, or unscoped).");
         process.exit(1);
     }
-    const { projectName, dir } = parsed;
+    const { projectName, dir, lockfile } = parsed;
     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);
@@ -155,9 +245,22 @@ export const main = () => {
     }
     console.log(`Creating ${projectName}...`);
     scaffold(targetDir, projectName);
+    let lockfileGenerated = false;
+    if (lockfile) {
+        console.log("\nResolving dependencies into pnpm-lock.yaml...");
+        const result = generateLockfile(targetDir);
+        lockfileGenerated = result.ok;
+        if (!result.ok) {
+            console.error(`\nWarning: could not generate pnpm-lock.yaml (${result.reason}).`);
+            console.error(`Run 'pnpm install' in ${dirName} and commit pnpm-lock.yaml: the Dockerfile installs with --frozen-lockfile and will not build without it.`);
+        }
+    }
     console.log(`\nDone! Created ${projectName} at ${targetDir}`);
+    if (lockfileGenerated) {
+        console.log("\nCommit pnpm-lock.yaml along with the rest: it is what makes 'docker build' reproducible.");
+    }
     console.log(`\nNext steps:`);
     console.log(`  cd ${dirName}`);
-    console.log("  npm install");
-    console.log("  npm run debug");
+    console.log("  pnpm install");
+    console.log("  pnpm run debug");
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,11 +25,11 @@
     "templates"
   ],
   "engines": {
-    "node": ">=18.19.0"
+    "node": ">=22.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
-    "vitest": "^4.1.8"
+    "@types/node": "^26.2.0",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/.env.example

@@ -1,21 +1,65 @@
-# Required
-OAUTH_JWT_SECRET=
+# Canonical issuer stamped as `iss` on every token this deployment mints.
+# Absolute https URL (http only for a loopback host), no query or fragment.
+# Boot fails when unset — it is never derived from the Host header.
+OAUTH_JWT_ISSUER=
+
+# --- JWT signing key (required) ---------------------------------------------
+# The default algorithm is EdDSA (Ed25519). There is no key-material default:
+# a deployment that sets none fails at boot naming the keys to set, rather than
+# quietly signing with something guessable.
+#
+#   openssl genpkey -algorithm ed25519 -out jwt-private.pem
+#   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
+#
+# HS256 alternative — symmetric, so /.well-known/jwks.json publishes NOTHING
+# and every relying party must hold a secret that can also MINT tokens. Only
+# for deployments that verify in-process. Needs >= 32 bytes (256 bits):
+#   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=
+
+# --- 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=
 
 # 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=
 
-# Redis (code repository + session storage)
+# Redis (code repository + 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
+# #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
 
-# Development (override for local HTTP)
+# 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
 
 # Optional
 # HTTP_PORT=3000
-# OAUTH_JWT_ISSUER=
 # 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

package/templates/standalone/Dockerfile

@@ -1,9 +1,18 @@
-FROM node:24-alpine AS node-base
+# The base image is pinned by digest, not just by tag: `node:24-alpine` is a
+# moving pointer, so the same source produced a different image on every
+# 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:24-alpine@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 AS node-base
 
 ENV HOME=/home/node
 
+# corepack is pinned too. `npm install -g corepack --force` resolved whatever
+# was latest at build time, which is a mutable dependency of every build. The
+# pnpm version itself comes from the `packageManager` field in package.json,
+# which corepack reads.
 RUN apk add --no-cache tini \
- && npm install -g corepack --force \
+ && npm install -g corepack@0.35.0 --force \
  && corepack enable
 
 WORKDIR /home/node
@@ -11,11 +20,25 @@ WORKDIR /home/node
 #############################################
 FROM node-base AS deps
 
-COPY package.json ./
+# pnpm-lock.yaml is a required build input: `create-auth-provider` generates
+# it at scaffold time and the project commits it. Without it this COPY fails,
+# which is the intended outcome — a build that silently re-resolves every
+# dependency range is the thing this file stopped doing (#289).
+#
+# pnpm-workspace.yaml is required for the same reason and was missing (#407):
+# the scaffolder generates it to carry bcrypt's `onlyBuiltDependencies`
+# allowlist, and pnpm >= 10.29 reads that setting ONLY from this file, in
+# single-package projects too (#360). Installing without it runs
+# allowlist-less, so pnpm silently skips bcrypt's build hook — which costs
+# nothing while an alpine prebuild exists, and re-creates #360 the day one
+# is missing and the native addon has to compile.
+COPY --chown=node:node package.json pnpm-lock.yaml pnpm-workspace.yaml ./
 
 USER node
 
-RUN pnpm install
+# --frozen-lockfile: install exactly what the lockfile pins, and fail if
+# package.json and the lockfile disagree, rather than quietly rewriting it.
+RUN pnpm install --frozen-lockfile
 
 #############################################
 FROM deps AS builder
@@ -24,33 +47,53 @@ FROM deps AS builder
 # hardening invariant obvious in Dockerfile reviews.
 USER node
 
-COPY tsconfig.json ./
-COPY config/ ./config/
-COPY src/ ./src/
+COPY --chown=node:node tsconfig.json ./
+COPY --chown=node:node config/ ./config/
+COPY --chown=node:node src/ ./src/
 
 RUN pnpm run build
 
 #############################################
-FROM node-base AS runtime
+# Dependencies are resolved once, in `deps`. This stage drops the dev half of
+# that same tree instead of running a second `pnpm install --prod` in the
+# runtime stage: a second install is a second resolution, and therefore a
+# second chance for the runtime image to hold something the build never saw.
+FROM deps AS prod-deps
 
-ENV NODE_ENV=production
+USER node
 
-COPY --from=deps /home/node/package.json /home/node/pnpm-lock.yaml ./
+RUN pnpm prune --prod
 
-USER node
+#############################################
+FROM node-base AS runtime
 
-RUN pnpm install --prod \
- && pnpm store prune
+ENV NODE_ENV=production
 
+COPY --from=deps /home/node/package.json /home/node/pnpm-lock.yaml ./
+COPY --from=prod-deps /home/node/node_modules/ ./node_modules/
 COPY --from=builder /home/node/dist/ ./dist/
 COPY --from=builder /home/node/config/ ./config/
 
+USER node
+
 ENV HTTP_PORT=3000
 EXPOSE ${HTTP_PORT}
 
+# Probes /_healthcheck (liveness), NOT /readyz. Docker has exactly one health
+# signal, and on Swarm / ECS / autoheal-style supervisors an unhealthy
+# container is stopped and replaced. Pointing it at /readyz would mean a 90s
+# Redis failover marks every replica unhealthy and gets them all rescheduled —
+# which reconnects nothing and adds cold starts to the incident. Losing Redis
+# is a reason to stop routing to a replica, not to kill it.
+#
+# /readyz is the load-balancer / Kubernetes readinessProbe target; see the
+# "Health endpoints" section of README.md. A compose file that genuinely wants
+# `depends_on: condition: service_healthy` to mean "ready" can override this
+# 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
-# healthcheck stay in sync regardless of the operator's port choice.
+# 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
 
@@ -60,8 +103,8 @@ CMD ["node", "dist/app.mjs"]
 #############################################
 FROM builder AS test
 
-COPY vitest.config.mts ./
-COPY tests/ ./tests/
+COPY --chown=node:node vitest.config.mts ./
+COPY --chown=node:node tests/ ./tests/
 
 CMD ["pnpm", "run", "test", "--", "--passWithNoTests"]
 

package/templates/standalone/README.ja.md

@@ -42,27 +42,49 @@ overlay の値は `application.conf` を上書きします。scaffold には
 | 変数 | デフォルト | 説明 |
 |---|---|---|
 | `HTTP_PORT` | `3000` | サーバーがリッスンするポート |
-| `HTTP_TRUST_PROXY` | `false` | リバースプロキシの背後で動作する場合は `true` に設定 |
+| `HTTP_TRUST_PROXY` | `false` | Express の `trust proxy`。`false` / アドレス・CIDR のリスト (`10.0.0.0/8,loopback`) / ホップ数 (`1`) / `true` のいずれか。**ロードバランサ配下では必須** — 未設定だと `req.ip` が LB のアドレスになり、IP をキーとする全ての rate limit が全ユーザーで 1 バケットを共有する。`true` ではなく**実際のプロキシを名指しする**こと (#292): `true` は「接続してきた相手が誰であれ、その X-Forwarded-For の先頭を信じる」という意味で、プロセスに直接到達できる相手が自分で `req.ip` を選べてしまう。詳細は [Multi-replica deployments](#multi-replica-deployments) |
 
 ### OAuth JWT
 
 | 変数 | デフォルト | 説明 |
 |---|---|---|
-| `OAUTH_JWT_ALGORITHM` | `HS256` | JWT 署名アルゴリズム（例: `RS256`、`ES256`） |
-| `OAUTH_JWT_SECRET` | — | 署名シークレット（HMAC アルゴリズム用） |
-| `OAUTH_JWT_ISSUER` | — | JWT の `iss` クレーム値 |
+| `OAUTH_JWT_ALGORITHM` | `EdDSA` | JWT 署名アルゴリズム: `EdDSA` / `ES256` / `RS256` / `HS256`。デフォルトが非対称なので `/.well-known/jwks.json` が実際の検証鍵を公開する。 |
+| `OAUTH_JWT_SECRET` | — | 署名シークレット（**HMAC (`HS256`) 専用**）。32 バイト（256 bit）以上のランダム値が必須 — `openssl rand -hex 32`。hex / base64 値は**デコード後**の長さで測るため、32 文字の hex 文字列は 16 バイト扱いで拒否される。 |
+| `OAUTH_JWT_ISSUER` | **（必須）** | すべてのトークンの `iss` に刻まれる canonical issuer URL。絶対 `https` URL（`http` は loopback ホストのみ）で、query / fragment を含まないこと。未設定なら起動に失敗する — `Host` ヘッダから導出されることはない。 |
 | `OAUTH_JWT_KID` | `v0` | JWT ヘッダーに含まれる key ID |
 | `OAUTH_JWT_PRIVATE_KEY` | — | PEM エンコードされた秘密鍵（非対称アルゴリズム用） |
 | `OAUTH_JWT_PRIVATE_KEY_PATH` | — | PEM 秘密鍵ファイルのパス |
 | `OAUTH_JWT_PUBLIC_KEY` | — | PEM エンコードされた公開鍵 |
 | `OAUTH_JWT_PUBLIC_KEY_PATH` | — | PEM 公開鍵ファイルのパス |
 
+**署名鍵は必須。** デフォルトアルゴリズムは `EdDSA` で、鍵素材のデフォルト値は存在しない。
+何も設定しないデプロイは「推測可能なシークレットで黙って署名する」のではなく、設定すべき
+キー名を明示して起動に失敗する。Ed25519 鍵ペアの生成:
+
+```bash
+openssl genpkey -algorithm ed25519 -out jwt-private.pem
+openssl pkey -in jwt-private.pem -pubout -out jwt-public.pem
+```
+
+生成したら `OAUTH_JWT_PRIVATE_KEY_PATH` / `OAUTH_JWT_PUBLIC_KEY_PATH` を指すか、
+`OAUTH_JWT_PRIVATE_KEY` / `OAUTH_JWT_PUBLIC_KEY` に PEM をインラインで渡す。
+
+`HS256` も引き続き選択可能（`OAUTH_JWT_ALGORITHM=HS256` + 32 バイト以上の
+`OAUTH_JWT_SECRET`）だが、代償を理解した上で選ぶこと: 対称鍵には公開鍵の片割れが
+存在しないため `/.well-known/jwks.json` は `404 jwks_not_published` を返し、
+すべての RP に共有シークレットを渡す必要がある。それは検証だけでなく
+**トークンの発行（偽造）** も可能にする鍵である。
+
 ### トークン有効期限
 
 | 変数 | デフォルト | 説明 |
 |---|---|---|
-| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | `3600` | アクセストークンの有効期間（秒） |
-| `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | リフレッシュトークンの有効期間（秒） |
+| `OAUTH_ACCESS_TOKEN_EXPIRES_IN` | `3600` | アクセストークンの有効期間（秒）。正の整数、上限は 1 年（`31536000`）。 |
+| `OAUTH_REFRESH_TOKEN_EXPIRES_IN` | `86400` | リフレッシュトークンの有効期間（秒）。正の整数、上限は 1 年（`31536000`）。 |
+
+これらを空文字で export すると fallback ではなく起動失敗になる: HOCON は `FOO=` を
+`""` に解決し、それが `0` に coerce され、有効期間 0 は「発行時点で期限切れ」の
+トークンを作るため。
 
 ### グラントタイプ
 
@@ -76,15 +98,25 @@ overlay の値は `application.conf` を上書きします。scaffold には
 
 | 変数 | デフォルト | 説明 |
 |---|---|---|
-| `SESSION_SECRET` | — | **必須。** セッション署名シークレット |
-| `SESSION_MAX_AGE` | `3600000` | セッション Cookie の最大有効期間（ミリ秒） |
+| `SESSION_SECRET` | — | **必須。** 認証済みセッションそのものである Cookie に署名する鍵。推測されればログインを偽造できる。32 バイト（256 bit）以上 — `openssl rand -hex 32`。`OAUTH_JWT_SECRET` と同じく**デコード後**の長さで測る。 |
+| `SESSION_MAX_AGE` | `3600000` | セッション Cookie の最大有効期間（ミリ秒）。正の整数、上限は 1 年（`31536000000`）。 |
 | `SESSION_SECURE` | `true` | セッション Cookie に `Secure` フラグを設定 |
-| `SESSION_SAME_SITE` | `lax` | `SameSite` 属性（`lax`、`strict`、`none`） |
+| `SESSION_SAME_SITE` | `lax` | `SameSite` 属性（`lax`、`strict`、`none`）。`none` は `SESSION_SECURE=true` が**必須** — ブラウザは `Secure` でない `SameSite=None` Cookie を破棄するため、クライアント側で全ログインが無言で失敗するのを避けて起動時に拒否する。 |
 | `SESSION_DOMAIN` | — | Cookie ドメイン（デフォルト未設定） |
+| `SESSION_CSRF_TTL_SECONDS` | `7200` | 発行する CSRF トークンの有効期間（秒）。1〜86400 の整数で、外れると boot が失敗する（*空文字* は `0` に coerce され、トークン側の判定を無言で無効化してしまうため） |
 | `SESSION_STORAGE_TYPE` | `redis` | セッションストアのバックエンド: `redis` または `memory` |
 | `SESSION_STORAGE_REDIS_URL` | `redis://localhost:6379` | セッションストア用 Redis 接続 URL |
 | `SESSION_STORAGE_REDIS_PASSWORD` | — | セッションストア用 Redis パスワード |
 
+#### `/session/login` と `/session/logout` の CSRF 対策
+
+どちらのルートも、**same-origin（もしくは信頼した）`Origin` / `Referer`**、**または** 有効な double-submit CSRF トークンのいずれかを伴うリクエストのみ受理し、どちらも無いものは拒否する（#272）。ブラウザは自動的に条件を満たす。スクリプトのクライアントはまず `GET /session/csrf` を呼び、返ってきた `csrf_token` を `<SESSION_NAME>.csrf` cookie と `x-csrf-token` ヘッダー（または `csrf_token` フォームフィールド）の両方で送り返す。
+
+設定上の注意が 2 点:
+
+- TLS 終端プロキシの背後では `HTTP_TRUST_PROXY` にそのプロキシのアドレス／CIDR を設定する (例: `HTTP_TRUST_PROXY=10.0.0.0/8`)。設定しないと `req.protocol` は `http` のままでブラウザは `Origin: https://…` を送るため、origin 側の判定が全リクエストを拒否する。`true` は「プロキシ以外が絶対にプロセスへ到達できない」と言い切れる場合にのみ正しい (#292) — 英語版 README も同じ指針。
+- ログイン UI をプロバイダーと**別 origin** で配信している場合は、その origin を HOCON の `session.csrf.trustedOrigins` に列挙する。`cors.allowedOrigins` は CSRF 信頼を与えなくなった。
+
 ### Google フェデレーション
 
 | 変数 | デフォルト | 説明 |
@@ -106,9 +138,12 @@ overlay の値は `application.conf` を上書きします。scaffold には
 | 変数 | デフォルト | 説明 |
 |---|---|---|
 | `CLIENT_USER_TYPE` | `http` | ユーザーリポジトリのバックエンド: `http` |
-| `CLIENT_USER_AUTHENTICATE_URL` | — | パスワード認証用のユーザー認証 URL |
-| `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | トークン認証用のユーザー認証 URL |
-| `CLIENT_USER_TIMEOUT` | `5000` | HTTP リクエストタイムアウト（ミリ秒） |
+| `CLIENT_USER_AUTHENTICATE_URL` | — | パスワード認証用のユーザー認証 URL。**https 必須**（下記参照） |
+| `CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL` | — | トークン認証用のユーザー認証 URL。**https 必須**（下記参照） |
+| `CLIENT_USER_TIMEOUT` | `5000` | HTTP リクエストタイムアウト（ミリ秒）。`2147483647` 以下の正の整数 |
+| `CLIENT_USER_MAX_RESPONSE_BYTES` | `1048576` | 上流レスポンスボディの受け入れ上限（バイト） |
+
+ユーザー認証 URL は 2 つとも上流ストアへ**平文のユーザー資格情報**を運ぶため、いずれも絶対 `https://` URL でなければならない。`http://` は loopback ホスト（`localhost`、`127.0.0.0/8` 内のアドレス、`[::1]`）に限って許可され、ローカル開発で証明書を用意せずに済むようにしている。プライベートレンジのアドレス（`http://10.0.0.5/…`）やコンテナネットワークのサービス名（`http://user-service/…`）には `https://` が必要 — これらはデプロイが端から端まで制御していないネットワークを越えるため。URL・タイムアウト・レスポンス上限のいずれかが不正なら、最初のログイン時ではなく起動時に失敗する。
 
 ### コードリポジトリ
 
@@ -168,6 +203,38 @@ make test
 
 `docker-compose.yml` は認証サーバーと Redis コンテナをまとめて起動します。環境変数は `.env` で設定してください。
 
+`docker-compose.yml` は**開発用**です(`develop` target をビルドし `./src` / `./config` を bind-mount するため、そのままデプロイすると working tree を hot-reload で配信します)。デプロイ可能な形は
+[`docker-compose.production.yml`](docker-compose.production.yml) — `runtime` target・source mount なし・restart policy・ネットワーク内部限定の永続 Redis・**必須**の `.env`(実際の `SESSION_SECRET` が無い boot は大声で失敗すべき)です。TLS 終端 + `HTTP_TRUST_PROXY`、`--scale` 前の multi-replica 手順など「意図的に委ねる範囲」はファイル冒頭のコメントに明記しています。
+
+```bash
+# 署名鍵は必須の入力です。デフォルトは EdDSA で鍵のデフォルト値は存在しないため、
+# 鍵を生成していないデプロイは boot で失敗します。
+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
+```
+
+**コンテナへの鍵の渡し方**。pem のペアは compose の **secret** として
+`/run/secrets/` に read-only でマウントされ、compose 側が
+`OAUTH_JWT_*_KEY_PATH` をそこに向けます。`config/` には置かないでください —
+`Dockerfile` がこのディレクトリを `COPY` するため、置いた鍵はイメージレイヤに
+焼き込まれ、push のたびに一緒に運ばれます(保管場所を誤っただけでは済まず、
+ローテーションが必要になります)。`.env` も同様に git の外に置いてください。
+
+production ファイルは `environment:` で `SESSION_SECURE=true` と `__Host-`
+cookie 名も固定します(`environment` は `env_file` より優先されます)。
+`.env.example` は plain-HTTP のローカル実行のために `SESSION_SECURE=false` を
+出荷しており、このファイルはその同じ `.env` を要求するためです。前段で TLS を
+終端する前提の構成で非 Secure な session cookie を配ることは、平文区間を読める
+相手にセッションを渡すことと同じです。
+
+イメージは `pnpm install --frozen-lockfile` でインストールするため、コミット済みの
+`pnpm-lock.yaml` がビルドの必須入力です。`create-auth-provider` が scaffold 時に
+生成します。手元に無い場合は一度 `pnpm install` を実行して結果をコミットしてください。
+これにより同じソースからのリビルドは同じ依存ツリーになります。
+
 ## カスタムモジュールの追加
 
 カスタムモジュールを追加するには、`src/buildModules.mts` でインポートし、`createApp` に渡す `modules` 配列に追加します。
@@ -204,9 +271,21 @@ const handle = await createApp({
 
 app.use(handle.router);
 const server = app.listen(config.http.port);
-gracefulShutdown(server, () => handle.dispose());
+installGracefulShutdown(server, { logger, cleanup: () => handle.dispose() });
 ```
 
+### シャットダウンの保証
+
+`src/shutdown.mts` は依存パッケージではなく scaffold 側に置いてある (#290)。全ユーザーセッションを終端するコンポーネントについて「SIGTERM は in-flight リクエストを待つのか、待つなら何秒か」は、デプロイするコード自体から答えられる必要があるため。
+
+1. **`SIGTERM` / `SIGINT`** のどちらでも開始する。2 回目のシグナルは無視する（1 回目の dispose に重ねて 2 回目を走らせない）。
+2. **新規接続は即座に停止**し、idle な keep-alive ソケットは解放する。リクエストを持たないまま server を開いたままにするソケットなので、解放しないと閑散時に deadline を丸ごと待つことになる。
+3. **in-flight リクエストには `drainTimeoutMs`**(既定 **10 秒**)を与える。
+4. **deadline を超えたら残接続を切り、プロセスは非ゼロ終了する。** 常に `0` しか見えない orchestrator では、正常な drain と時間切れの強制切断を区別できない。
+5. **`cleanup` は drain 後・exit 前**に走る(`handle.dispose()` = 逆トポロジカルなコンポーネント cleanup + Redis/タイマーの drain)。失敗はこのサービス自身の logger(他の行と同じ NDJSON)に出し、exit code にも反映する。dispose が throw してもプロセスは終了する。
+
+**`drainTimeoutMs` は orchestrator の kill grace period より短く設定すること** — Kubernetes の `terminationGracePeriodSeconds`、compose の `stop_grace_period` はいずれも既定 30 秒。他人の都合の `SIGKILL` が来る前に、自分の都合で閉じるのが目的。
+
 ## npm スクリプト
 
 | スクリプト | 説明 |