@o3co/create-auth-policy-verifier 0.14.0 → 0.16.0

package/dist/index.d.mts

@@ -1,12 +1,10 @@
 /**
  * Decides whether one entry of the template tree is copied into a new project.
  *
- * The exclusion is judged on the path RELATIVE to the template root, which is
- * the whole point: the scaffolder ships inside `node_modules` whenever it is
- * run the documented way (`npm create`, `npx`), so every absolute source path
- * it copies from contains a `node_modules` segment. Matching against the
- * absolute path therefore rejected the entire template and produced an empty
- * project directory — the scaffolder only ever worked from a source checkout.
+ * The exclusion is judged on the path relative to the template root. Run the
+ * documented way (`npm create`, `npx`), the scaffolder sits inside
+ * `node_modules`, so every absolute source path contains a `node_modules`
+ * segment and matching on it would exclude the whole template.
  */
 export declare const isTemplateEntryIncluded: (templatesDir: string, source: string) => boolean;
 export declare const isValidProjectName: (name: string) => boolean;
@@ -29,18 +27,14 @@ export type LockfileResult = {
     readonly reason: string;
 };
 /**
- * Generates `pnpm-lock.yaml` inside an already-scaffolded `targetDir`.
+ * Generates `pnpm-lock.yaml` inside an already-scaffolded `targetDir`, for the
+ * template's `pnpm install --frozen-lockfile` build. The lockfile cannot ship
+ * with the template: its dependency set exists only once `scaffold` has
+ * replaced every `workspace:*` with a published version.
  *
- * This is what makes the template's `pnpm install --frozen-lockfile` build
- * possible: the lockfile cannot be shipped with the template, because the
- * template's dependency set does not exist until `scaffold` has replaced every
- * `workspace:*` with a published version. So it is resolved here, once, against
- * the rewritten `package.json`, and the project commits the result.
- *
- * Best-effort by design: it needs a package manager and a reachable registry,
- * and neither is guaranteed on the machine running the scaffolder. Failure is
- * reported, never thrown — the generated project is perfectly usable without
- * it, the operator just has to run `pnpm install` before `docker build`.
+ * Best-effort: it needs a package manager and a reachable registry. Failure is
+ * reported, never thrown; the project is usable without the lockfile once the
+ * operator runs `pnpm install` before `docker build`.
  */
 export declare const generateLockfile: (targetDir: string) => LockfileResult;
 /**

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AA2BA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GAAI,cAAc,MAAM,EAAE,QAAQ,MAAM,KAAG,OAI9E,CAAC;AAMF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IA0CjE,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;AAyBnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AAyDF;;;;GAIG;AACH,eAAO,MAAM,IAAI,QAAO,IAgEvB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AA2BA;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAI,cAAc,MAAM,EAAE,QAAQ,MAAM,KAAG,OAI9E,CAAC;AAMF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IAwCjE,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;AAsBnD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AAyDF;;;;GAIG;AACH,eAAO,MAAM,IAAI,QAAO,IAgEvB,CAAC"}

package/dist/index.mjs

@@ -23,12 +23,10 @@ const EXCLUDED_DIRS = new Set(["node_modules", "dist"]);
 /**
  * Decides whether one entry of the template tree is copied into a new project.
  *
- * The exclusion is judged on the path RELATIVE to the template root, which is
- * the whole point: the scaffolder ships inside `node_modules` whenever it is
- * run the documented way (`npm create`, `npx`), so every absolute source path
- * it copies from contains a `node_modules` segment. Matching against the
- * absolute path therefore rejected the entire template and produced an empty
- * project directory — the scaffolder only ever worked from a source checkout.
+ * The exclusion is judged on the path relative to the template root. Run the
+ * documented way (`npm create`, `npx`), the scaffolder sits inside
+ * `node_modules`, so every absolute source path contains a `node_modules`
+ * segment and matching on it would exclude the whole template.
  */
 export const isTemplateEntryIncluded = (templatesDir, source) => {
     const rel = relative(templatesDir, source);
@@ -74,11 +72,9 @@ export const scaffold = (targetDir, projectName) => {
     const pkgPath = resolve(targetDir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
     pkg.name = projectName;
-    // `"private": true` is deliberately KEPT (#126 item 4). The scaffold is an
-    // authorization service — policy code and config — 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 kept: the scaffold is an authorization service —
+    // policy code and config — and the field makes an accidental `npm publish`
+    // fail. An operator who means to publish removes it.
     // Replace all workspace:* references with per-package published versions
     const versions = getPackageVersions();
     for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
@@ -109,28 +105,21 @@ const LOCKFILE_ARGS = ["install", "--lockfile-only", "--ignore-workspace"];
  * covers a machine that only has Node, and honours the `packageManager` field
  * the template ships.
  *
- * The fallback is narrow on purpose: it applies to `ENOENT` and nothing else,
- * because `ENOENT` is the one failure that means "this binary is not here" and
- * is therefore the only one a different launcher can answer. Any other launch
- * error (`EACCES`, `EPERM`, …) says the binary IS there and could not be run,
- * and a package manager that ran and exited non-zero has already reported that
- * resolution failed — retrying either would hide the real cause behind
- * "package manager missing" and hand the operator the wrong instruction.
+ * Only `ENOENT` (the binary is not here) moves on to the next launcher. Any
+ * other launch error (`EACCES`, `EPERM`, …) means the binary is there and could
+ * not be run, and a non-zero exit means resolution failed; retrying either
+ * would hide the real cause behind "package manager missing".
  */
 const LOCKFILE_LAUNCHERS = [["pnpm"], ["corepack", "pnpm"]];
 /**
- * Generates `pnpm-lock.yaml` inside an already-scaffolded `targetDir`.
+ * Generates `pnpm-lock.yaml` inside an already-scaffolded `targetDir`, for the
+ * template's `pnpm install --frozen-lockfile` build. The lockfile cannot ship
+ * with the template: its dependency set exists only once `scaffold` has
+ * replaced every `workspace:*` with a published version.
  *
- * This is what makes the template's `pnpm install --frozen-lockfile` build
- * possible: the lockfile cannot be shipped with the template, because the
- * template's dependency set does not exist until `scaffold` has replaced every
- * `workspace:*` with a published version. So it is resolved here, once, against
- * the rewritten `package.json`, and the project commits the result.
- *
- * Best-effort by design: it needs a package manager and a reachable registry,
- * and neither is guaranteed on the machine running the scaffolder. Failure is
- * reported, never thrown — the generated project is perfectly usable without
- * it, the operator just has to run `pnpm install` before `docker build`.
+ * Best-effort: it needs a package manager and a reachable registry. Failure is
+ * reported, never thrown; the project is usable without the lockfile once the
+ * operator runs `pnpm install` before `docker build`.
  */
 export const generateLockfile = (targetDir) => {
     const attempts = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-policy-verifier",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Scaffold a new o3co/auth.policy-verifier project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,8 +28,8 @@
     "templates"
   ],
   "devDependencies": {
-    "@types/node": "^26.6.2",
-    "vitest": "^5.0.1"
+    "@types/node": "^26.6.3",
+    "vitest": "^5.0.2"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/Dockerfile

@@ -1,14 +1,13 @@
-# 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. The digest is the multi-arch index, so amd64 and arm64 both resolve
+# The base image is pinned by digest, not just by tag: a tag is a moving
+# pointer, so the same source would build a different image on each rebuild. 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:dbaa92e5758cbbcf85d65d5403fdb530fe3442cbe8c6dbfb7ef23365450d5070 AS node-base
+FROM node:26-alpine@sha256:0b36e8c136b94cd4fcf02188228e76c31ad5872eef3fec8cbd2eee500cfd9e80 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
+# corepack is pinned too. An unpinned `npm install -g corepack` resolves
+# whatever is latest at build time, 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 \
@@ -23,7 +22,7 @@ FROM node-base AS deps
 # pnpm-lock.yaml is a required build input: `create-auth-policy-verifier`
 # 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.
+# every dependency range is what requiring it prevents.
 COPY --chown=node:node package.json pnpm-lock.yaml ./
 
 USER node
@@ -76,7 +75,7 @@ EXPOSE ${HTTP_PORT}
 
 # Probes the container's own routable address, NOT 127.0.0.1 — deliberately.
 #
-# `application.conf` binds loopback by default (#108), because /verify answers
+# `application.conf` binds loopback by default, because /verify answers
 # with an authorization decision and a reachable port is a decision oracle. A
 # container that keeps that default is reachable from nothing: the published
 # port never connects. A probe against 127.0.0.1 passes anyway — inside the

package/templates/standalone/README.ja.md

@@ -1,6 +1,6 @@
 # @o3co/auth-policy-verifier-standalone
 
-最終更新: 2026-09-23
+最終更新: 2026-10-01
 
 auth.policy-verifier のデプロイ可能なサーバーテンプレートです。このパッケージはコンポジションルートとして機能し、設定の読み込み・モジュールのロード・Express サーバーの起動を担います。`@o3co/create-auth-policy-verifier` によって生成されます。
 
@@ -77,10 +77,10 @@ OAUTH_JWT_SECRET=$(openssl rand -hex 32) \
 | `OAUTH_JWT_AUDIENCE_CLAIM` | `aud` | audience を読む claim。`azp`（Clerk）、`client_id`（Cognito）。`aud` 以外を指定すると `aud` は一切見ない |
 | `OAUTH_AUTHENTICATOR` | `jwt` | subject を確立する token authenticator。他の名前は `main.mts` で module が登録したものでなければならない |
 | `OAUTH_JWT_MODE` | `verify` | `verify` はトークンを完全検証。明示的な `insecure-decode`（テスト専用）は署名検証なしでデコードする — `exp`/`nbf` は引き続き強制される |
-| `RULE_ON_EMPTY_RULE_SET` | `deny` | ルールが 1 つも集まらなかったときの決定（`deny` \| `allow`） |
+| `RULE_ON_EMPTY_RULE_SET` | `deny` | 許可するルールが 1 つも集まらなかったときの決定（`deny` \| `allow`） |
 | `VERIFY_MAX_BATCH_SIZE` | `50` | `POST /verify/batch` の件数上限 |
 | `VERIFY_CREDENTIAL_TO_COLLECTORS` | `never` | `expose` は生の資格情報を `context.credential` として collector に渡す — subject として下流 API を呼ぶ collector のためだけの設定。既定では collector は検証済みクレームだけを扱う。資格情報はリプレイ可能であり、context がログに出ればそれが漏れる |
-| `VERIFY_EVALUATION_IN_RESPONSE` | `omit` | `include` にすると、policy を背後に持つ各 Rule の `evaluation`（status と、評価した policy revision。#244）を決定の response に載せる。どの revision が操作を許可したかを記録する呼び出し側サービス向け。`decision` ログイベントにはどちらの設定でも載る。受理される token の保持者全員に「policy set がいつ変わったか」を伝えることになるので、それが問題になる環境では `HTTP_CALLER_AUTH_TOKEN` と併用する |
+| `VERIFY_EVALUATION_IN_RESPONSE` | `omit` | `include` にすると、policy を背後に持つ各 Rule の `evaluation`（status、評価した policy revision（#244）、完了した answer ではそれを決めた policy（#199））を決定の response に載せる。どの revision が操作を許可したかを記録する呼び出し側サービス向け。`decision` ログイベントにはどちらの設定でも載る。受理される token の保持者全員に「policy set がいつ変わったか」「各 answer をどの policy が決めたか」を伝えることになるので、それが問題になる環境では `HTTP_CALLER_AUTH_TOKEN` と併用する |
 | `LOG_LEVEL` | `info` | 出力する最低レベル: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`。decision ログのスイッチも兼ねる — [可観測性](#可観測性)を参照 |
 
 ## HS256 シークレットの強度
@@ -157,7 +157,7 @@ Authorization: Bearer <jwt>
 | `resource` / `action` | 呼び出し元が送ったそのままの値 |
 | `decision` | `allow` または `deny` |
 | `code` | deny のみ — 呼び出し元がワイヤ上で受け取ったコードと同じ |
-| `satisfiedBy` | allow のみ — 各グループを満たしたルールの `{ruleType, code}` |
+| `satisfiedBy` | allow のみ — 許可する各グループを満たしたルールの `{ruleType, code}`。`onEmptyRuleSet = "allow"` が通したときは空 |
 | `deniedBy` | deny のみ — 最初に失敗したグループと、そこで拒否した全代替ルール |
 | `requestId` | 呼び出し元が送った `x-request-id`（サーバーが受け入れる形のもの。[失敗イベント](#失敗イベント) を参照）。無い場合は省略される |
 | `durationMs` | Collector パイプラインと evaluator に費やした時間。HTTP の往復時間ではない |
@@ -193,11 +193,11 @@ Authorization: Bearer <jwt>
 | `collector_threw` | コレクターが reject / throw した |
 | `attribute_conflict` | 2 つの attribute コレクターが同じスカラーキーに異なる値を書いた |
 | `rule_timeout` | 非同期ルールが予算を、またはルールフェーズがデッドラインを超えた |
-| `rule_threw` | ルールの `verify` が throw した、または `decide` が reject した |
+| `rule_threw` | ルールの `verify` が throw した、`decide` が reject した、またはその `ruleType` のグループに絞るルールと許可するルールが混在した |
 | `body_rejected` | JSON body parser が、deny エンベロープが 4xx に対応付けていない形で失敗した |
 | `internal` | decision 自身の collect や評価から出てきたのではないもの — throw した resource parser や authenticator（何を throw したかによらず） |
 
-この集合は閉じています: アラートとフィルタは `err.message` ではなく `category` の等値に対して張ってください。`collector` は `config/application.conf` の `attribute.collectors` / `rule.collectors` 内のエントリ位置とクラス名です。JWKS に到達できないことは category ではありません — `401` で応答され、`jwt_verification_unavailable` としてログに出ます（後述）。
+この集合は閉じています: アラートとフィルタは `err.message` ではなく `category` の等値に対して張ってください。`collector` は `config/application.conf` の `attribute.collectors` / `rule.collectors` 内のエントリ位置とクラス名です。JWKS に到達できないことは category ではありません — 判定の前に `503 verification_unavailable` で応答され、`jwt_verification_unavailable` としてログに出ます（後述）。
 
 サーバーがこれらの行に加えるものは、トークン・クレーム・`context` のいずれも含みません。collector はその decision についてコレクターのランナーが記録したもので、エラーから読んだ名前ではなく、何も記録されていないタイムアウトは `collector: "unattributed"` です。ルールの `ruleType` と `code` はルールコレクターがリクエストごとにルールを組み立てうるため、識別子の形（英字で始まり、英数字・`_`・`.`・`-` が続く 64 文字以内）の場合だけ載り、それ以外は `redacted` になります。リクエスト ID は検証済みです。`err` は throw されたエラーそのものですが、例外が 1 つあります: core が定義する 3 つの deny エラー（`CollectorTimeoutError`、`RuleTimeoutError`、`AttributeConflictError`）はメッセージと自身のフィールドにコレクター・ルール・属性キーを含むため、分類されたコレクターやルール、同じ識別子の形に制限した属性キー、ヘッダ行だけの stack で組み立て直したものを記録します。それ以外のエラーのメッセージは、その作者の責任です。
 
@@ -251,7 +251,7 @@ scrape_configs:
 
 `HTTP_PATH_PREFIX` は他のエンドポイントと同様にこのパスも動かします。`HTTP_PATH_PREFIX=/pdp` なら `/pdp/metrics` になり、scrape config の `metrics_path` も合わせる必要があります。
 
-**まだ公開していないもの:** 依存先ごとの `up` ゲージ（auth.provider はバックエンドストア向けに持っています）。ここでの相当物は JWKS エンドポイントですが、サンプリング対象になる readiness probe のレジストリがありません。依存先の一覧を別途手で持つゲージは、auth.provider が probe をサンプリングすることで避けた drift そのものです。そのレジストリができるまで、JWKS 障害は `jwt_verification_unavailable` ログイベントとして見えます — アラートを張れるようにこれは `error` で出力されています。
+**まだ公開していないもの:** 依存先ごとの `up` ゲージ（auth.provider はバックエンドストア向けに持っています）。ここでの相当物は JWKS エンドポイントですが、サンプリング対象になる readiness probe のレジストリがありません。依存先の一覧を別途手で持つゲージは、auth.provider が probe をサンプリングすることで避けた drift そのものです。そのレジストリができるまで、JWKS 障害は `jwt_verification_unavailable` ログイベントとして見えます — アラートを張れるようにこれは `error` で出力されています。HTTP リクエストのヒストグラムにも `503` の応答として現れます。
 
 ## デフォルトコレクター
 
@@ -289,7 +289,7 @@ resource parser を 1 つ（`DotNotationResourceParser`）登録します。各
 リクエスト対象の resource と action に対して `<action>:<resourceType>` を bearer
 トークンが持っているときにちょうど許可されます。スコープを発行する IdP があれば
 認可ストアを別途立てなくてもそのまま機能し、かつ fail-closed です — スコープを
-持たないトークンや誤ったスコープは拒否され、ルールが 1 つも集まらなかった
+持たないトークンや誤ったスコープは拒否され、許可するルールが 1 つも集まらなかった
 リクエストも拒否されます（`rule.onEmptyRuleSet = "deny"`）。
 
 ルールは種類ごとにグループ化され、**すべてのグループが通る必要があります**。

package/templates/standalone/README.md

@@ -1,6 +1,6 @@
 # @o3co/auth-policy-verifier-standalone
 
-Last updated: 2026-09-23
+Last updated: 2026-10-01
 
 Deployable server template for auth.policy-verifier. This is the composition root — it reads config, loads modules, and starts the Express server. Generated by `@o3co/create-auth-policy-verifier`.
 
@@ -79,10 +79,10 @@ Individual values can also be overridden with environment variables.
 | `OAUTH_JWT_AUDIENCE_CLAIM` | `aud` | Claim the audience is read from: `azp` (Clerk), `client_id` (Cognito). Anything but `aud` means `aud` is not consulted at all |
 | `OAUTH_AUTHENTICATOR` | `jwt` | Which token authenticator establishes the subject; another name must be registered by a module in `main.mts` |
 | `OAUTH_JWT_MODE` | `verify` | `verify` fully verifies tokens; the explicit `insecure-decode` (test-only) decodes without signature verification — `exp`/`nbf` are still enforced |
-| `RULE_ON_EMPTY_RULE_SET` | `deny` | Decision when no rule is collected (`deny` \| `allow`) |
+| `RULE_ON_EMPTY_RULE_SET` | `deny` | Decision when no granting rule is collected (`deny` \| `allow`) |
 | `VERIFY_MAX_BATCH_SIZE` | `50` | Cap on `POST /verify/batch` entries |
 | `VERIFY_CREDENTIAL_TO_COLLECTORS` | `never` | `expose` hands collectors the raw credential as `context.credential` — only for a collector that calls a downstream API as the subject. The default keeps collectors on verified claims; the credential is replayable and a logged context would leak it |
-| `VERIFY_EVALUATION_IN_RESPONSE` | `omit` | `include` puts each policy-backed rule's `evaluation` — its status and the policy revision it evaluated (#244) — on the decision response, for a calling service that records which revision authorized an operation. The `decision` log event carries it either way. It tells any holder of an accepted token when the policy set changed, so pair it with `HTTP_CALLER_AUTH_TOKEN` where that matters |
+| `VERIFY_EVALUATION_IN_RESPONSE` | `omit` | `include` puts each policy-backed rule's `evaluation` — its status, the policy revision it evaluated (#244) and, for a completed answer, the policies that determined it (#199) — on the decision response, for a calling service that records which revision authorized an operation. The `decision` log event carries it either way. It tells any holder of an accepted token when the policy set changed and which policies determined each answer, so pair it with `HTTP_CALLER_AUTH_TOKEN` where that matters |
 | `LOG_LEVEL` | `info` | Minimum level emitted: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`. Also the switch for the decision log — see [Observability](#observability) |
 
 ## HS256 secret strength
@@ -159,7 +159,7 @@ Every decision emits one structured event named `decision`, at `info`:
 | `resource` / `action` | Exactly as the caller sent them |
 | `decision` | `allow` or `deny` |
 | `code` | Deny only — the same code the caller got on the wire |
-| `satisfiedBy` | Allow only — the `{ruleType, code}` of the rule that satisfied each group |
+| `satisfiedBy` | Allow only — the `{ruleType, code}` of the rule that satisfied each granting group; empty when `onEmptyRuleSet = "allow"` let the request through |
 | `deniedBy` | Deny only — the first failing group, and every alternative in it that refused |
 | `requestId` | `x-request-id` as sent, when the caller sent one the server carries (see [Failure events](#failure-events)). Omitted otherwise |
 | `durationMs` | Time in the collector pipelines and the evaluator — not the HTTP round trip |
@@ -195,11 +195,11 @@ A decision that could not be made is logged at `error` (level 50), and the line
 | `collector_threw` | A collector rejected or threw |
 | `attribute_conflict` | Two attribute collectors wrote different values to one scalar key |
 | `rule_timeout` | An asynchronous rule overran its budget, or the rule phase its deadline |
-| `rule_threw` | A rule's `verify` threw or its `decide` rejected |
+| `rule_threw` | A rule's `verify` threw or its `decide` rejected, or its `ruleType` group mixed restricting and granting rules |
 | `body_rejected` | The JSON body parser failed in a way the deny envelope does not map to a 4xx |
 | `internal` | Anything that did not come out of a decision's own collect or evaluation — a resource parser or authenticator that threw, whatever it threw |
 
-The set is closed: alert and filter on `category` by equality, never on `err.message`. `collector` is the entry's position in `attribute.collectors` / `rule.collectors` in `config/application.conf`, plus its class. An unreachable JWKS is not a category — it is answered `401` and logged as `jwt_verification_unavailable` (see below).
+The set is closed: alert and filter on `category` by equality, never on `err.message`. `collector` is the entry's position in `attribute.collectors` / `rule.collectors` in `config/application.conf`, plus its class. An unreachable JWKS is not a category — it is answered `503 verification_unavailable` before any decision, and logged as `jwt_verification_unavailable` (see below).
 
 Nothing the server adds to these lines carries the token, the claims or `context`. The collector is the one the collector runner recorded for that decision, never a name read off an error, and a timeout nothing recorded is `collector: "unattributed"`. A rule's `ruleType` and `code` are carried only when identifier-shaped (a letter, then letters, digits, `_`, `.` or `-`, at most 64 characters) and are `redacted` otherwise, because a rule collector may build rules per request. The request id is validated. `err` is the error as thrown, with one exception: the three deny errors core defines (`CollectorTimeoutError`, `RuleTimeoutError`, `AttributeConflictError`) name a collector, a rule or an attribute key in their message and their own fields, so each is logged rebuilt — the classified collector or rule, the key held to the same identifier shape, and a stack of the header line only. Any other error's message is its author's responsibility.
 
@@ -253,7 +253,7 @@ scrape_configs:
 
 `HTTP_PATH_PREFIX` moves the endpoint with everything else: with `HTTP_PATH_PREFIX=/pdp` the path is `/pdp/metrics`, and `metrics_path` in the scrape config has to match.
 
-**Not published yet:** a per-dependency `up` gauge (auth.provider has one for its backing stores). The equivalent here is the JWKS endpoint, and there is no readiness-probe registry to sample — a gauge built from a second, hand-maintained list of dependencies is exactly the drift auth.provider avoided by sampling its probes. Until such a registry exists, a JWKS outage is visible as the `jwt_verification_unavailable` log event, which is emitted at `error` precisely so it can be alerted on.
+**Not published yet:** a per-dependency `up` gauge (auth.provider has one for its backing stores). The equivalent here is the JWKS endpoint, and there is no readiness-probe registry to sample — a gauge built from a second, hand-maintained list of dependencies is exactly the drift auth.provider avoided by sampling its probes. Until such a registry exists, a JWKS outage is visible as the `jwt_verification_unavailable` log event, which is emitted at `error` precisely so it can be alerted on, and as `503` responses on the HTTP request histogram.
 
 ## Default Collectors
 
@@ -293,7 +293,7 @@ else: a request is allowed exactly when the bearer token carries
 `<action>:<resourceType>` for the resource and action it asks about. It is
 functional against any issuer that mints scopes, with no authorization store to
 stand up first, and it is fail-closed — a token with no scope, or the wrong one,
-is denied, and so is a request that collects no rule at all
+is denied, and so is a request that collects no granting rule
 (`rule.onEmptyRuleSet = "deny"`).
 
 Rules are grouped by kind and **every group must pass**. A rule collector enabled

package/templates/standalone/config/application.conf

@@ -199,7 +199,9 @@ attribute {
   collectors = [
     # The token's `scope` claim, split into the list the scope rule reads.
     # `claim = "scp"` reads Okta's scope array instead; pair it with the same
-    # `claim` on ResourceActionScopeRuleCollector below (#219).
+    # `claim` on ResourceActionScopeRuleCollector below, which reads that claim
+    # to tell whether the token asserted scopes at all — nothing checks that
+    # the two names agree.
     { collector = "PayloadScopeCollector" }
     # The token's `sub`, which becomes the `subject` on the decision response
     # and the `sub` field on the audit log line.
@@ -207,13 +209,14 @@ attribute {
   ]
   # Deliberately absent: anything supplying permissions or roles. This
   # deployment authorizes from the token's scopes alone. Adding a permission
-  # rule means adding its supplier here in the same edit (#113).
+  # rule means adding its supplier here in the same edit.
 }
 
 rule {
-  # Decision for a request that collects no rule at all. "deny" (the default)
-  # keeps the verifier fail-closed; "allow" is an explicit opt-out and makes
-  # any request that matches no rule succeed.
+  # Decision for a request that collects no granting rule. "deny" (the
+  # default) keeps the verifier fail-closed; "allow" is an explicit opt-out and
+  # makes any request that collects no granting rule succeed, provided it
+  # passes the restricting rules it collected (a delegated token's range, say).
   onEmptyRuleSet = "deny"
   onEmptyRuleSet = ${?RULE_ON_EMPTY_RULE_SET}
 
@@ -221,12 +224,12 @@ rule {
   # request is allowed exactly when the token carries "<action>:<resourceType>".
   # It works against any issuer that mints scopes without an authorization store
   # to stand up first, and it stays fail-closed — a token carrying no scope, or
-  # the wrong one, is denied, as is a request that collects no rule at all.
+  # the wrong one, is denied, as is a request that collects no granting rule.
   #
   # Rules are grouped by kind and every GROUP must pass, so one group nothing can
   # satisfy denies every request the deployment ever sees. That is what enabling
   # a rule collector without the attribute collector feeding it does, and it is
-  # why the permission rule below is off rather than merely unconfigured (#113).
+  # why the permission rule below is off rather than merely unconfigured.
   collectors = [
     # Scope matching is exact and case-sensitive (RFC 6749 §3.3): the token must
     # carry "<action>:<resourceType>" verbatim. If your issuer emits bare resource
@@ -328,7 +331,7 @@ verify {
   # the concurrency cap does not spend it.
   collectorTimeoutMs = 2000
   collectorTimeoutMs = ${?VERIFY_COLLECTOR_TIMEOUT_MS}
-  # How long one asynchronous rule (an out-of-process policy engine, #225) may
+  # How long one asynchronous rule (an out-of-process policy engine) may
   # take to answer. Same budget and ceiling as one collector; overrun = deny.
   ruleTimeoutMs = 2000
   ruleTimeoutMs = ${?VERIFY_RULE_TIMEOUT_MS}
@@ -361,8 +364,8 @@ verify {
   batchConcurrency = 8
   batchConcurrency = ${?VERIFY_BATCH_CONCURRENCY}
 
-  # Whether collectors receive the raw credential as `context.credential`
-  # (#175). "never" (the default): collectors get verified claims only — the
+  # Whether collectors receive the raw credential as `context.credential`.
+  # "never" (the default): collectors get verified claims only — the
   # credential is replayable, and a collector that logs its context would leak
   # a live token. Set "expose" ONLY when a project-side collector calls a
   # downstream API as the subject (token forwarding / exchange); this line is
@@ -371,13 +374,16 @@ verify {
   credentialToCollectors = ${?VERIFY_CREDENTIAL_TO_COLLECTORS}
 
   # Whether a decision RESPONSE carries what each policy-backed rule reported
-  # about the evaluation behind its answer — its status, and the policy revision
-  # it evaluated (#244). The `decision` log event always carries it; this is
-  # only about the wire. "omit" (the default): the response is key-for-key what
-  # it was. Set "include" when the calling service records which policy
-  # revision authorized an operation. It tells any holder of an accepted token
-  # when the policy set changed and whether a denial was a policy's or the
-  # engine failing, so pair it with `http.callerAuth` where that matters.
+  # about the evaluation behind its answer — its status, the policy revision it
+  # evaluated and, for a completed answer, the policies that determined it.
+  # The `decision` log event always carries it; this is only about the wire.
+  # "omit" (the default): no rule outcome in the response carries an
+  # `evaluation` key.
+  # Set "include" when the calling service records which policy revision
+  # authorized an operation. It tells any holder of an accepted token when the
+  # policy set changed, whether a denial was a policy's or the engine failing,
+  # and which policies determined each answer, so pair it with
+  # `http.callerAuth` where that matters.
   evaluationInResponse = "omit"
   evaluationInResponse = ${?VERIFY_EVALUATION_IN_RESPONSE}
 }

package/templates/standalone/docker-compose.yml

@@ -15,8 +15,9 @@ services:
       # and it is why HTTP_CALLER_AUTH_TOKEN is worth setting in .env: past the
       # container boundary, anyone who can reach the port can ask for decisions.
       - HTTP_HOSTNAME=0.0.0.0
-      # Where the Cedar http engine finds the `cedar-engine` profile below — read
-      # only when the app composes cedarPolicyModule without the wasm package.
+      # Where the Cedar http engine finds the `cedar-engine` service below
+      # (profile `cedar`) — read only when the app composes cedarPolicyModule
+      # without the wasm package.
       # The engine has no default address (a missing one refuses to start,
       # naming this variable and the wasm package), so it is stated here, as an
       # interpolation default: an `environment` entry outranks `env_file`, so a

package/templates/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@o3co/auth-policy-verifier-standalone",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.29.3",
@@ -24,12 +24,12 @@
 		"pino": "^10.3.1"
 	},
 	"devDependencies": {
-		"@types/node": "^26.6.2",
+		"@types/node": "^26.6.3",
 		"@types/supertest": "^7.2.1",
 		"jose": "^6.2.12",
-		"supertest": "^7.2.2",
+		"supertest": "^7.3.0",
 		"tsx": "^4.23.15",
 		"typescript": "^5.9.3",
-		"vitest": "^5.0.1"
+		"vitest": "^5.0.2"
 	}
 }

package/templates/standalone/src/__tests__/dockerCompose.test.mts

@@ -6,7 +6,7 @@ import { describe, expect, it } from "vitest";
 
 const compose = readFileSync(new URL("../../docker-compose.yml", import.meta.url), "utf8");
 
-describe("docker-compose.yml — the cedar profile's agent is authenticated (v0.10.0 audit)", () => {
+describe("docker-compose.yml — the cedar profile's agent is authenticated", () => {
 	it("starts the agent with the token the app sends", () => {
 		// An unauthenticated cedar-agent is a write oracle over the policy set:
 		// anything that reaches its port can PUT `permit(principal, action,
@@ -14,8 +14,7 @@ describe("docker-compose.yml — the cedar profile's agent is authenticated (v0.
 		// reads, so the two cannot disagree.
 		expect(compose).toMatch(/- CEDAR_AGENT_AUTHENTICATION=\$\{CEDAR_AUTHENTICATION:-\}/);
 		// And the app from the same interpolation, not only through `env_file`:
-		// a shell variable or `--env-file` would otherwise reach the agent alone
-		// (review).
+		// a shell variable or `--env-file` would otherwise reach the agent alone.
 		expect(compose).toMatch(/- CEDAR_AUTHENTICATION=\$\{CEDAR_AUTHENTICATION:-\}/);
 	});
 

package/templates/standalone/src/__tests__/loadConfig.test.mts

@@ -7,9 +7,9 @@
  * These read the real files under templates/standalone/config/, so they cover
  * the shipped layering rather than a hand-built object: an env overlay that
  * contains only comments is an empty HOCON document, and it must fall back to
- * application.conf instead of failing to parse. Nothing else in the suite
- * exercises parseFile, so a HOCON parser regression is otherwise invisible
- * until the container fails to start.
+ * application.conf instead of failing to parse. The smoke test boots from the
+ * development overlay too; only this file asserts what each shipped overlay
+ * resolves to.
  */
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -22,7 +22,7 @@ const configDirPath = fileURLToPath(new URL("../../config/", import.meta.url));
 
 /**
  * 64 hex characters — 32 decoded bytes, the entropy floor the schema enforces
- * on every HS256 secret (#114). A short value now fails to load at all.
+ * on every HS256 secret. A shorter value fails to load.
  */
 const TEST_SECRET = "11".repeat(32);
 
@@ -43,10 +43,7 @@ const envKeys = [
 	"OAUTH_JWT_CLOCK_TOLERANCE_SECONDS",
 	"VERIFY_MAX_BATCH_SIZE",
 	// Every VERIFY_* the cases below set has to be listed, or it leaks into the
-	// tests after it. Only `VERIFY_MAX_BATCH_SIZE` was here while the #118 cases
-	// set five more, and the leak was invisible for as long as no later case
-	// loaded the shipped config and asserted on `verify` — the first one that
-	// did got a boot failure from an env var a test three screens up had set.
+	// tests after it.
 	"VERIFY_MAX_BODY_BYTES",
 	"VERIFY_MAX_RESOURCE_LENGTH",
 	"VERIFY_MAX_ACTION_LENGTH",
@@ -82,7 +79,7 @@ describe("loadAppConfig", () => {
 
 			const config = loadAppConfig(configDirPath, env);
 
-			// Loopback by default (#108): the shipped config is a sidecar config,
+			// Loopback by default: the shipped config is a sidecar config,
 			// and reaching the port from another host is an explicit opt-in. The
 			// callerAuth block exists but carries no token, which means the gate is off.
 			expect(config.http).toEqual({
@@ -110,7 +107,7 @@ describe("loadAppConfig", () => {
 			"PayloadScopeCollector",
 			"PayloadSubjectIdCollector",
 		]);
-		// Scope-only, and the two lists are one decision (#113). Rule groups are
+		// Scope-only, and the two lists are one decision. Rule groups are
 		// ANDed, so a rule reading an attribute no collector above produces is a
 		// group nothing satisfies — which is a verifier that denies every request.
 		// A permission rule may only join this list together with its supplier.
@@ -137,7 +134,7 @@ describe("loadAppConfig", () => {
 		});
 	});
 
-	it("enables caller authentication from the environment (#108)", () => {
+	it("enables caller authentication from the environment", () => {
 		setRequiredEnv();
 		process.env.HTTP_CALLER_AUTH_TOKEN = "caller-secret";
 
@@ -165,7 +162,7 @@ describe("loadAppConfig", () => {
 		expect(() => loadAppConfig(configDirPath, "development")).toThrow(/callerAuth[.,\s\S]*token/);
 	});
 
-	it("selects insecure-decode mode via OAUTH_JWT_MODE, requiring no key material (#134)", () => {
+	it("selects insecure-decode mode via OAUTH_JWT_MODE, requiring no key material", () => {
 		// The value is the consent: only the literal string "insecure-decode"
 		// selects the decode-only path, so a stray boolean-ish env value cannot.
 		process.env.OAUTH_JWT_MODE = "insecure-decode";
@@ -175,7 +172,7 @@ describe("loadAppConfig", () => {
 		expect(config.oauth.jwt?.mode).toBe("insecure-decode");
 	});
 
-	it("rejects a boolean-ish OAUTH_JWT_MODE left over from the removed OAUTH_JWT_VALIDATE", () => {
+	it('rejects a boolean-ish OAUTH_JWT_MODE such as "false"', () => {
 		setRequiredEnv();
 		process.env.OAUTH_JWT_MODE = "false";
 
@@ -190,9 +187,9 @@ describe("loadAppConfig", () => {
 
 	it.each([
 		["a one-character OAUTH_JWT_SECRET", "s"],
-		["the README's old example value", "your-secret"],
+		["a placeholder value", "your-secret"],
 		["32 hex characters — 16 decoded bytes", "ab".repeat(16)],
-	])("refuses to load %s (#114)", (_label, secret) => {
+	])("refuses to load %s", (_label, secret) => {
 		// The floor applies to the shipped config as loaded, not only to
 		// hand-built objects: `secret = ${?OAUTH_JWT_SECRET}` is where a weak
 		// value actually enters a deployment.
@@ -209,7 +206,7 @@ describe("loadAppConfig", () => {
 	});
 });
 
-describe("loadAppConfig — RFC 9068 requirements (#105)", () => {
+describe("loadAppConfig — RFC 9068 requirements", () => {
 	it("fails to load when the issuer is not supplied", () => {
 		process.env.OAUTH_JWT_SECRET = TEST_SECRET;
 		process.env.OAUTH_JWT_AUDIENCE = "https://api.test";
@@ -225,13 +222,12 @@ describe("loadAppConfig — RFC 9068 requirements (#105)", () => {
 	});
 });
 
-describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#157)", () => {
-	// The knobs are read by `resolveBound` at both boundaries now, and this is the
-	// path that proves the schema half still works where it actually runs: HOCON
+describe("loadAppConfig — numeric knobs through the real 3-tier resolution", () => {
+	// The knobs are read by `resolveBound` at both boundaries, and this is the
+	// path that proves the schema half works where it actually runs: HOCON
 	// substitutes `${?VAR}` as a STRING, and the ts.hocon zod adapter's coercion
 	// walk only rewrites fields it recognises as numbers. A knob it cannot see
-	// through must therefore coerce the string itself — which is exactly what
-	// `resolveBound` does, and what a hand-built config already relied on.
+	// through must coerce the string itself, which `resolveBound` does.
 
 	it("takes the numbers application.conf states when nothing overrides them", () => {
 		setRequiredEnv();
@@ -245,7 +241,7 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 		expect(config.oauth.jwt?.maxTokenAgeSeconds).toBe(86_400);
 		expect(config.oauth.jwt?.clockToleranceSeconds).toBe(0);
 		expect(config.verify.maxBatchSize).toBe(50);
-		// The request limits (#118) travel the same path.
+		// The request limits travel the same path.
 		expect(config.verify.maxBodyBytes).toBe(65_536);
 		expect(config.verify.maxResourceLength).toBe(512);
 		expect(config.verify.maxActionLength).toBe(64);
@@ -341,21 +337,18 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 	});
 });
 
-describe("loadAppConfig — a config with no verify block at all (#115, #118)", () => {
+describe("loadAppConfig — a config with no verify block at all", () => {
 	/*
 	 * The shipped `application.conf` writes out every `verify` knob, so loading
 	 * it exercises the schema's per-key defaults and never the block-level one.
-	 * The block-level default is what serves the OTHER shape, and it is the
-	 * common one: an overlay config repeats only the sections it changes, and a
-	 * deployment that has no opinion about batch sizes or collector deadlines
-	 * simply never writes a `verify` block.
+	 * The block-level default serves the common shape: an overlay config that
+	 * repeats only the sections it changes and never writes a `verify` block.
 	 *
 	 * zod takes `.default(() => ({…}))` verbatim rather than parsing it back
-	 * through the shape, so a knob missing from that literal is `undefined` for
-	 * exactly this shape — silently, with nothing failing. That is why it is
-	 * proved here through the real loader (`parseFile` → `withFallback` →
-	 * `validate`) rather than inferred from the schema unit tests, which all
-	 * write a `verify` block and would go on passing.
+	 * through the shape, so a knob missing from that literal is silently
+	 * `undefined` for exactly this shape. The schema unit tests all write a
+	 * `verify` block, so it is proved here through the real loader
+	 * (`parseFile` → `withFallback` → `validate`).
 	 */
 	const withoutVerify = (): string => {
 		const dir = mkdtempSync(path.join(tmpdir(), "policy-verifier-config-"));

package/templates/standalone/src/__tests__/logger.test.mts

@@ -2,14 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /*
- * The composition root's logger (#107).
- *
- * The template previously created its logger through `@o3co/auth.utils`, whose
- * shape cannot satisfy the `Logger` port `createApp` accepts — so nothing the
- * template configured ever reached the server's failure events. `createAppLogger`
- * returns a pino instance (newline-delimited JSON on stdout, the shape every
- * log aggregator ingests without a parser), which satisfies the port
- * structurally and honours `logging.level` from the application config.
+ * The composition root's logger. `createAppLogger` returns a pino instance
+ * (newline-delimited JSON on stdout, which log aggregators ingest without a
+ * parser) that satisfies the `Logger` port `createApp` accepts structurally,
+ * so the server's failure events reach it, and that honours `logging.level`
+ * from the application config.
  */
 import type { Logger } from "@o3co/auth.policy-verifier.core";
 import { AppConfigSchema } from "@o3co/auth.policy-verifier.server";

package/templates/standalone/src/__tests__/shutdown.test.mts

@@ -2,20 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * Shutdown was delegated to `@o3co/auth.utils@0.0.4`, whose guarantees no
- * contract in this repository pinned.
- *
- * Reading its 22 lines answered the question and the answer was the reason to
- * move it: **there was no force-close deadline**. `server.close()` waits for
- * in-flight requests indefinitely, so one stuck decision meant the process
- * never exited on its own and the orchestrator's SIGKILL took it down
- * mid-flight. Its cleanup-failure path also wrote to `console.error`, a bare
- * line in a composition root whose every other line is NDJSON (#107), and
- * every exit was zero.
- *
- * The behaviour lives in the template now, with a deadline and the app's own
- * logger, and these tests are the contract that was missing. `auth.provider`'s
- * standalone template made the same move in its issue #290.
+ * The contract of the template's graceful shutdown (`shutdown.ts`): a
+ * force-close deadline, since `server.close()` waits for in-flight requests
+ * indefinitely; failures logged through the app's own logger; and a non-zero
+ * exit whenever the shutdown was not clean.
  */
 import type { Server } from "node:http";
 import type { Logger } from "@o3co/auth.policy-verifier.core";
@@ -190,9 +180,9 @@ describe("installGracefulShutdown", () => {
 	});
 
 	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
-		// `finish` awaited cleanup with no deadline, and the drain deadline was
-		// already cleared by then, so a dispose that never settled meant `exit`
-		// was never reached — the wedge the deadline was added to remove.
+		// The drain deadline is already cleared when cleanup runs, so only the
+		// cleanup budget stands between a dispose that never settles and an
+		// `exit` that is never reached.
 		vi.useFakeTimers();
 		try {
 			const { signals, finishDraining, exit, logger } = install({
@@ -228,7 +218,7 @@ describe("installGracefulShutdown", () => {
 		}
 	});
 
-	it("defers the real exit a turn so pino's buffered destination can flush (#210 review)", async () => {
+	it("defers the real exit a turn so pino's buffered destination can flush", async () => {
 		// `createAppLogger` uses pino's default (non-synchronous) destination, so
 		// exiting in the same tick as the last `logger.error` can drop exactly the
 		// `cleanup failed` line an operator would go looking for.
@@ -240,9 +230,9 @@ describe("installGracefulShutdown", () => {
 	});
 
 	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
-		// `exitCode` became 1 while `reason` still said "drained", so the one line
-		// an operator alerts on contradicted itself. The drain outcome is still
-		// carried, under its own key, so neither fact is lost.
+		// `reason` names what decided the exit code, so the line an operator
+		// alerts on never says "drained" beside a non-zero code. The drain
+		// outcome is carried under its own key.
 		const { signals, finishDraining, logger, exit } = install({
 			cleanup: () => Promise.reject(new Error("teardown failed")),
 		});

package/templates/standalone/src/__tests__/smoke.test.mts

@@ -6,18 +6,12 @@
  *
  * These tests boot the app from `config/application.conf` — the file the image
  * ships and an operator deploys — read through `loadAppConfig`, the same
- * function `main.mts` calls. Nothing here restates the policy: the thing under
- * test is the thing that ships.
- *
- * That is the point of #113. The suite used to assemble its own config, minus
- * the one collector that made the shipped file deny every request, and stayed
- * green while the product was non-functional. A config the tests hand-write can
- * agree with `application.conf` only by vigilance, and it stopped agreeing.
+ * function `main.mts` calls. Nothing here restates the policy: a config the
+ * tests hand-wrote could disagree with the shipped file and stay green.
  *
  * The three values the file deliberately does not carry — the HS256 secret, the
  * issuer and the audience — come from the environment here exactly as they do
- * in a deployment. A credential must never be written in a config file, so
- * supplying them is loading the shipped config, not editing it.
+ * in a deployment: a credential is never written in a config file.
  */
 import { fileURLToPath } from "node:url";
 import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
@@ -29,7 +23,7 @@ import request from "supertest";
 import { describe, expect, it } from "vitest";
 import { loadAppConfig } from "../loadConfig.js";
 
-/** 64 hex characters — 32 decoded bytes, the entropy floor #114 enforces. */
+/** 64 hex characters — 32 decoded bytes, the entropy floor the config schema enforces. */
 const JWT_SECRET = "11".repeat(32);
 const secretKey = new TextEncoder().encode(JWT_SECRET);
 const ISSUER = "https://issuer.test";
@@ -42,7 +36,7 @@ async function signToken(payload: Record<string, unknown>): Promise<string> {
 		new SignJWT(payload)
 			.setProtectedHeader({ alg: "HS256", typ: "at+jwt" })
 			.setIssuedAt()
-			// iat and exp are both mandatory now (#110).
+			// iat and exp are both mandatory.
 			.setExpirationTime("1h")
 			.setIssuer(ISSUER)
 			.setAudience(AUDIENCE)
@@ -62,17 +56,12 @@ const DEPLOYMENT_ENV = {
  * overlay resolved against `config/application.conf`, with the deployment's
  * three values in the environment.
  *
- * `process.env` is process-wide, and a test file does not own it. So each
- * variable's prior value is **restored**, not deleted — and "was absent" is
- * restored as absent rather than as `""`, which is a different state this very
- * config distinguishes (an exported-empty credential is refused rather than read
- * as "unset"). Deleting unconditionally would hand any file sharing the worker a
- * value this one happened to clear.
- *
- * The window is nil as well as tidy: every step here is synchronous —
- * `loadAppConfig` parses and validates without awaiting — and this runs at module
- * scope, so no other file's code can be scheduled between the assignment and the
- * restore.
+ * `process.env` is process-wide, so each variable's prior value is
+ * **restored**, not deleted — and "was absent" is restored as absent rather
+ * than as `""`, a different state this config distinguishes (an exported-empty
+ * credential is refused rather than read as "unset"). Every step is synchronous
+ * and this runs at module scope, so no other file's code can run between the
+ * assignment and the restore.
  */
 function loadShippedConfig(): AppConfig {
 	const saved: Array<[key: string, previous: string | undefined]> = Object.keys(DEPLOYMENT_ENV).map(
@@ -103,7 +92,7 @@ function createShippedApp(config: AppConfig = shippedConfig) {
 describe("standalone smoke", () => {
 	it("GET /_healthcheck returns 200", async () => {
 		// The liveness path the Dockerfile's HEALTHCHECK probes, and the one every
-		// component of the stack answers on (o3co/auth.provider#293).
+		// component of the stack answers on.
 		const app = await createShippedApp();
 
 		const res = await request(app).get("/_healthcheck");
@@ -111,8 +100,7 @@ describe("standalone smoke", () => {
 	});
 
 	it("GET /healthcheck returns 200 as a compatibility alias", async () => {
-		// The path this image probed before; a probe config that still names it
-		// must keep working.
+		// A probe config that names this path must keep working.
 		const app = await createShippedApp();
 
 		const res = await request(app).get("/healthcheck");
@@ -225,9 +213,9 @@ describe("standalone smoke", () => {
 	it("POST /verify allows a bare scope once allowBareScopeRewrite is configured", async () => {
 		// The one config in this file that is deliberately NOT the shipped one:
 		// it exercises the opt-in application.conf documents in a comment beside
-		// the collector, which is the only path a deployment has to re-enable the
-		// old rewrite. It is derived from the shipped config rather than written
-		// out, so the single key under test is the single thing that differs.
+		// the collector, the only path a deployment has to enable the bare-scope
+		// rewrite. It is derived from the shipped config rather than written out,
+		// so the single key under test is the single thing that differs.
 		const rewritingConfig: AppConfig = {
 			...shippedConfig,
 			rule: {
@@ -265,8 +253,8 @@ describe("standalone smoke", () => {
 });
 
 /*
- * #111. The template is the deployable shape, so these assert what an operator
- * of *this* composition actually gets — not what the library can be wired to do.
+ * The template is the deployable shape, so these assert what an operator of
+ * *this* composition actually gets — not what the library can be wired to do.
  */
 describe("standalone observability", () => {
 	it("GET /metrics serves the Prometheus text format with the decision counters", async () => {

package/templates/standalone/src/logger.ts

@@ -5,20 +5,18 @@ import type { AppConfig } from "@o3co/auth.policy-verifier.server";
 import { pino, stdSerializers } from "pino";
 
 /**
- * The composition root's logger, injected into `createApp` so the verify
- * router's failure events (`jwt_token_rejected`, `jwt_verification_unavailable`,
- * `verify_internal_error`) reach an aggregator-ready sink (#107).
+ * The composition root's logger, injected into `createApp` so the failure
+ * events of the verify router (`verify_internal_error` and the
+ * `collector_timeout` / `rule_timeout` / `attribute_conflict` denies) and of
+ * the JWT authenticator `createApp` builds (`jwt_token_rejected`,
+ * `jwt_verification_unavailable`) reach an aggregator-ready sink.
  *
- * pino, emitting newline-delimited JSON on stdout — the shape every log
- * aggregator ingests without a parser, and the reason the `Logger` port carries
- * pino's two-overload call signature. A pino instance therefore satisfies the
- * port structurally, with no adapter. pino drops sub-threshold calls before
- * formatting, so `logging.level` is honoured at zero cost for the levels it
- * excludes.
- *
- * The same wiring exists in the auth.provider standalone template; keeping the
- * two composition roots symmetric is what lets one aggregator pipeline serve
- * the whole stack.
+ * pino, emitting newline-delimited JSON on stdout, which log aggregators ingest
+ * without a parser. The `Logger` port carries pino's two-overload call
+ * signature, so a pino instance satisfies it with no adapter. pino drops
+ * sub-threshold calls before formatting, so `logging.level` costs nothing for
+ * the levels it excludes. The auth.provider standalone template wires the
+ * same, so one aggregator pipeline serves the whole stack.
  */
 export function createAppLogger(config: AppConfig) {
 	return pino({

package/templates/standalone/src/shutdown.ts

@@ -5,27 +5,13 @@ import type { Server } from "node:http";
 import type { Logger } from "@o3co/auth.policy-verifier.core";
 
 /**
- * Graceful shutdown for the scaffolded server.
+ * Graceful shutdown for the scaffolded server. It lives in the template rather
+ * than a dependency so that "does SIGTERM wait for in-flight decisions, and for
+ * how long?" is answerable from the code an operator deploys. auth.provider's
+ * standalone template carries the same; keeping the two composition roots
+ * symmetric lets one aggregator pipeline serve the whole stack.
  *
- * ## Why this is in the template rather than a dependency
- *
- * It used to be `gracefulShutdown` from `@o3co/auth.utils@0.0.4`. For a
- * component every protected call waits on, "does SIGTERM wait for in-flight
- * decisions, and for how long?" has to be answerable from the code an operator
- * deploys — and it was answerable only by reading a pre-1.0 package no
- * contract here pinned. Reading it answered the question, and the answer was
- * the reason to move it: **there was no deadline**. `server.close()` waits
- * indefinitely, so one stuck decision meant the process never exited on its
- * own and the orchestrator's SIGKILL took it down mid-flight — the opposite of
- * a graceful shutdown, arriving only under the load that produces a stuck
- * request. The cleanup-failure path also wrote to `console.error`, one bare
- * line in a composition root that went to the trouble of wiring NDJSON (#107).
- *
- * `auth.provider`'s standalone template made the same move for the same
- * reasons (o3co/auth.provider#290); keeping the two composition roots
- * symmetric is what lets one aggregator pipeline serve the whole stack.
- *
- * ## The guarantees, stated
+ * The guarantees:
  *
  * 1. **SIGTERM and SIGINT** both start it; a second signal is ignored rather
  *    than starting a second cleanup over the first one's work.
@@ -33,21 +19,20 @@ import type { Logger } from "@o3co/auth.policy-verifier.core";
  *    sockets are released (`closeIdleConnections`) — they hold the server open
  *    with no request behind them, so a quiet server would otherwise wait out
  *    the whole deadline for nothing.
- * 3. **In-flight requests get `drainTimeoutMs`** (default 10s) to finish.
+ * 3. **In-flight requests get `drainTimeoutMs`** (default 10s) to finish;
+ *    `server.close()` alone waits indefinitely.
  * 4. **Past the deadline, remaining connections are cut**
- *    (`closeAllConnections`) and the process exits **non-zero** — an
- *    orchestrator that only ever sees `0` cannot tell a clean drain from one
- *    that ran out of time.
+ *    (`closeAllConnections`) and the process exits **non-zero**, so an
+ *    orchestrator can tell a clean drain from one that ran out of time.
  * 5. **`cleanup` runs after draining, before exit**, logged through the app
  *    logger and reflected in the exit code. It is bounded by
  *    `cleanupTimeoutMs`, so a dispose that never settles cannot wedge the
- *    process the way an unbounded `await` did.
+ *    process.
  * 6. **A `close` that fails is not reported as a clean drain.**
  *
  * Size `drainTimeoutMs` **below** the orchestrator's own kill grace period
  * (Kubernetes `terminationGracePeriodSeconds`, compose `stop_grace_period`,
- * both 30s by default) — the point is to close on our terms before SIGKILL
- * arrives on someone else's.
+ * both 30s by default), so the process closes on its own terms before SIGKILL.
  */
 export interface GracefulShutdownOptions {
 	readonly logger: Logger;

package/templates/versions.json

@@ -1,5 +1,5 @@
 {
-	"@o3co/auth.policy-verifier.core": "0.14.0",
-	"@o3co/auth.policy-verifier.builtins": "0.14.0",
-	"@o3co/auth.policy-verifier.server": "0.14.0"
+	"@o3co/auth.policy-verifier.core": "0.16.0",
+	"@o3co/auth.policy-verifier.builtins": "0.16.0",
+	"@o3co/auth.policy-verifier.server": "0.16.0"
 }