@o3co/create-auth-policy-verifier 0.12.0 → 0.13.0

package/README.ja.md

@@ -1,7 +1,32 @@
 # @o3co/create-auth-policy-verifier
 
+最終更新: 2026-09-23
+
 auth.policy-verifier 用の CLI スキャフォルダーです。組み込みテンプレートから新しいスタンドアロンサーバープロジェクトを生成します。
 
+## 責務と役割
+
+**役割.** リポジトリ内のテンプレート [`templates/standalone`](../templates/standalone)
+から、新しい独立したプロジェクトを生成する `npm create` / `npx` の入口です。
+オペレーターのマシン上で一度だけ実行されます。生成されたプロジェクトはこのパッケージを
+import せず、このパッケージも `packages/*` のライブラリを import しません。
+
+**所有するもの.** プロジェクト名とディレクトリ名の検証、テンプレートのコピー、生成された
+`package.json` の書き換え（name、`workspace:*` → 公開バージョン）、一度きりの
+`pnpm-lock.yaml` の解決。
+
+**所有しないもの.** 生成されるプロジェクトの中身 — ソース、設定、Dockerfile、テスト —
+はテンプレートの責務です（変更するのはこのパッケージではなく `templates/standalone`）。
+実行時の振る舞いは `@o3co/auth.policy-verifier.server` とテンプレートが依存する
+ライブラリの責務です。
+
+**別パッケージである理由.** `bin` を持つ単独のパッケージとして公開されるため、verifier を
+インストールせずに `npx` で実行できます。ビルド手順
+（[`scripts/copy-templates.mjs`](scripts/copy-templates.mjs)）がテンプレートの複製と
+現在のライブラリバージョン（`templates/versions.json`）を同梱し、`tsconfig.base.json`
+をテンプレートの `tsconfig.json` に展開します。公開 tarball にはモノレポのツリーが
+存在しないためです。
+
 ## 使い方
 
 ```sh
@@ -41,7 +66,7 @@ cd verifier
 2. 生成先ディレクトリ名を決定する: `--dir <value>` が指定されていればその値、そうでなければスコープ付き名のパッケージ部分、最終的には入力値そのもの。
 3. 生成先ディレクトリがすでに存在する場合はエラーを出力して終了する。
 4. `templates/standalone/` を生成先ディレクトリにコピーする（`node_modules/` と `dist/` は除外）。
-5. `package.json` を書き換える: `name` を `<project-name>` をそのまま設定し（スコープを保持）、`private` を削除し、`workspace:*` のバージョン参照を `templates/versions.json` の公開 semver バージョンに置き換える。
+5. `package.json` を書き換える: `name` に `<project-name>` をそのまま設定し（スコープを保持）、`"private": true` は意図的に残し（#126: 生成された認可サービスが誤って publish されないようにするため。本当に公開したい場合は自分でこのフィールドを削除する）、各 `workspace:*` のバージョン参照を `templates/versions.json` の `^<version>` に置き換える。
 6. その依存セットを `pnpm-lock.yaml` に解決する（`pnpm install --lockfile-only --ignore-workspace`）。`--no-lockfile` 指定時は省略。
 7. 次のステップの手順を表示する。
 
@@ -79,20 +104,13 @@ lockfile が無くても生成されたプロジェクトは問題なく使え
 
 ## 生成される構造
 
-```
-<project-name>/
-├── config/
-│   └── application.conf    # HOCON 設定ファイル（環境変数で上書き可）
-├── src/
-│   └── main.mts            # コンポジションルート — 設定を読み込みサーバーを起動する
-├── Dockerfile
-├── Makefile
-├── docker-compose.yml
-├── docker-compose.test.yml
-├── package.json
-├── pnpm-lock.yaml          # scaffold 時に生成 — コミットすること
-└── tsconfig.json
-```
+生成されるプロジェクトは [`templates/standalone`](../templates/standalone) の全体です —
+dotfile、テスト、テンプレート自身の README を含むすべてのファイルとディレクトリ —
+ただし `node_modules/` と `dist/` は除きます（[`src/index.mts`](src/index.mts) の
+`EXCLUDED_DIRS`）。リポジトリ内のテンプレートと内容が異なるのは、`tsconfig.json`（scaffolder のビルド時に
+ベース設定がインライン展開される）、`package.json`（手順 5）、新たに解決される
+`pnpm-lock.yaml`（手順 6、コミットすること）だけです。各ファイルの役割は
+テンプレートの README を参照してください。
 
 ## プログラム API
 

package/README.md

@@ -1,7 +1,32 @@
 # @o3co/create-auth-policy-verifier
 
+Last updated: 2026-09-23
+
 CLI scaffolder for auth.policy-verifier. Generates a new standalone server project from the built-in template.
 
+## Responsibility
+
+**Role.** The `npm create` / `npx` entry point that turns the in-repo template
+[`templates/standalone`](../templates/standalone) into a new, independent project.
+It runs once, on the operator's machine; nothing in the generated project imports
+it, and it imports none of the `packages/*` libraries.
+
+**Owns.** Project-name and directory validation, copying the template, rewriting
+the generated `package.json` (name, `workspace:*` → published versions), and the
+one-time `pnpm-lock.yaml` resolution.
+
+**Does not own.** The content of the generated project — source, config, Dockerfile,
+tests — which is the template's (edit `templates/standalone`, not this package).
+Runtime behaviour belongs to `@o3co/auth.policy-verifier.server` and the libraries
+the template depends on.
+
+**Why a separate package.** It is published on its own with a `bin`, so it can be
+run with `npx` without installing the verifier. Its build step
+([`scripts/copy-templates.mjs`](scripts/copy-templates.mjs)) embeds a copy of the
+template and the current library versions (`templates/versions.json`), and inlines
+`tsconfig.base.json` into the template's `tsconfig.json`, because the monorepo
+tree is not present in the published tarball.
+
 ## Usage
 
 ```sh
@@ -41,7 +66,7 @@ cd verifier
 2. Derives the target directory name: `--dir <value>` if given, else the unscoped part of a scoped name, else the name itself.
 3. Aborts with an error if the target directory already exists.
 4. Copies `templates/standalone/` to the target directory, excluding `node_modules/` and `dist/`.
-5. Rewrites `package.json`: sets `name` to `<project-name>` verbatim (scope-preserving), removes `private`, and replaces `workspace:*` dependency versions with published semver versions from `templates/versions.json`.
+5. Rewrites `package.json`: sets `name` to `<project-name>` verbatim (scope-preserving), keeps `"private": true` on purpose (#126: a scaffolded authorization service should not be publishable by accident — remove the field yourself if you really intend to publish), and replaces each `workspace:*` dependency version with `^<version>` from `templates/versions.json`.
 6. Resolves that dependency set into `pnpm-lock.yaml` (`pnpm install --lockfile-only --ignore-workspace`), unless `--no-lockfile` was passed.
 7. Prints next-step instructions.
 
@@ -79,20 +104,13 @@ The bundled template's `README.md` / `README.ja.md` still carry the upstream tit
 
 ## Generated Structure
 
-```
-<project-name>/
-├── config/
-│   └── application.conf    # HOCON config (env var overrides)
-├── src/
-│   └── main.mts            # Composition root — loads config and starts server
-├── Dockerfile
-├── Makefile
-├── docker-compose.yml
-├── docker-compose.test.yml
-├── package.json
-├── pnpm-lock.yaml          # Generated at scaffold time — commit it
-└── tsconfig.json
-```
+The generated project is the whole of [`templates/standalone`](../templates/standalone)
+— every file and directory, including dotfiles, tests and the template's own READMEs —
+except `node_modules/` and `dist/` (`EXCLUDED_DIRS` in [`src/index.mts`](src/index.mts)).
+The files that differ from the in-repo template are `tsconfig.json` (the base config
+is inlined into it when the scaffolder is built), `package.json` (step 5) and the
+newly resolved `pnpm-lock.yaml` (step 6; commit it). See the template's README for
+what each file does.
 
 ## Programmatic API
 

package/dist/cli.mjs

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 // SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
 // SPDX-License-Identifier: Apache-2.0
+/*
+ * The `create-auth-policy-verifier` executable: runs the scaffolder's `main`.
+ */
 import { main } from "./index.mjs";
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-policy-verifier",
-  "version": "0.12.0",
+  "version": "0.13.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.5.1",
-    "vitest": "^5.0.0"
+    "@types/node": "^26.6.2",
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "build": "tsc",

package/templates/standalone/Dockerfile

@@ -3,7 +3,7 @@
 # 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:ef24c5053d50fdc3e4e56eb4e7ddb7861874ab0fdc797046ba897581deb8e868 AS node-base
+FROM node:26-alpine@sha256:dbaa92e5758cbbcf85d65d5403fdb530fe3442cbe8c6dbfb7ef23365450d5070 AS node-base
 
 ENV HOME=/home/node
 

package/templates/standalone/README.ja.md

@@ -1,7 +1,37 @@
 # @o3co/auth-policy-verifier-standalone
 
+最終更新: 2026-09-23
+
 auth.policy-verifier のデプロイ可能なサーバーテンプレートです。このパッケージはコンポジションルートとして機能し、設定の読み込み・モジュールのロード・Express サーバーの起動を担います。`@o3co/create-auth-policy-verifier` によって生成されます。
 
+## 責務と役割
+
+**役割.** コンポジションルートであり、デプロイメントの出発点です。ライブラリではなく、
+これを import するものはありません。`@o3co/create-auth-policy-verifier` が新しい
+プロジェクトにコピーし、以後はオペレーターがそのコピーを所有・編集します。
+ライブラリ群の上に位置し、`@o3co/auth.policy-verifier.server`（`createApp`、
+`AppConfigSchema`、`builtinKeyResolversModule`）、`@o3co/auth.policy-verifier.builtins`
+（`builtinCollectorsModule`）、`@o3co/auth.policy-verifier.core`（`Logger` 型）を使います。
+
+**所有するもの** — デプロイメントごとに決まる選択:
+
+- アプリに組み込むモジュール — [`src/main.mts`](src/main.mts)
+- 設定の読み込み元と `{ENV}.conf` オーバーレイの重ね方 —
+  [`src/configPath.ts`](src/configPath.ts)、[`src/loadConfig.ts`](src/loadConfig.ts)
+  — および [`config/application.conf`](config/application.conf) の出荷時ポリシー
+- 具体的なロガー（pino） — [`src/logger.ts`](src/logger.ts)
+- プロセスのライフサイクル: drain の期限付きの SIGTERM 処理 —
+  [`src/shutdown.ts`](src/shutdown.ts)
+- パッケージング: `Dockerfile`、`docker-compose*.yml`、コンテナの healthcheck
+
+**所有しないもの.** HTTP API、判定パイプライン、トークン検証、設定スキーマ（いずれも
+`server`）、collector / rule / parser の実装（`builtins`）、`Module` 契約（`core`）。
+これらはここではなく上流で変更します。
+
+**別パッケージである理由.** 上記はすべてデプロイメントごとの判断なので、公開ライブラリ
+から切り離し、オペレーターが書き換えることを前提としたツリーに置いています。
+`"private": true` で、それ自体は公開されず、スキャフォルダー経由でのみ利用者に届きます。
+
 ## 使い方
 
 ```sh
@@ -225,18 +255,33 @@ scrape_configs:
 
 ## デフォルトコレクター
 
-以下のコレクターが `builtinCollectorsModule` を通じて登録されます。
-
-**Attribute collectors**:
-
-- `PayloadScopeCollector` — 検証済みサブジェクト属性（JWT のクレーム）から OAuth スコープを抽出する
-- `PayloadSubjectIdCollector` — 検証済みサブジェクト属性（JWT のクレーム）からサブジェクト識別子を抽出する
-- `RequestContextAttributeCollector` — リクエストボディの `context` の宣言済みフィールドを属性に昇格させる（既定では未接続。`attribute.collectors` に `attributes` マッピングを付けて追加する）
-
-**Rule collectors**（認可ルールを解決）:
-
-- `ResourceActionScopeRuleCollector` — トークンがスコープ `<action>:<resourceType>` を持つことを要求する
-- `ResourceActionPermissionRuleCollector` — パーミッション `<resource.raw>.perm:<action>` を要求する（既定では未接続。下記参照）
+ここで問題になる一覧は 2 つあり、同じではありません。
+
+**登録済み** — `builtinCollectorsModule`（`src/main.mts` で組み込み）が名前で
+*利用可能にする* もの。登録だけでは何も起きず、`config/application.conf` が名前を
+挙げたときに初めて使われます。このモジュールは attribute collector を 6 つ
+（`PayloadScopeCollector`、`PayloadSubjectIdCollector`、`StaticPermissionCollector`、
+`StaticRoleCollector`、`RequestContextAttributeCollector`、
+`PayloadClaimAttributeCollector`）、rule collector を 2 つ
+（`ResourceActionScopeRuleCollector`、`ResourceActionPermissionRuleCollector`）、
+resource parser を 1 つ（`DotNotationResourceParser`）登録します。各エントリの設定を含む
+正式な一覧は builtins の README —
+[Attribute Collectors](../../packages/builtins/README.ja.md#attribute-collectors)、
+[Rule Collectors](../../packages/builtins/README.ja.md#rule-collectors)、
+[builtinCollectorsModule](../../packages/builtins/README.ja.md#builtincollectorsmodule)
+— で、ソースは [`packages/builtins/src/module.mts`](../../packages/builtins/src/module.mts) です。
+
+**既定の設定で有効なもの** — 出荷時の `config/application.conf` が実際に接続しているもの:
+
+- `attribute.collectors`: `PayloadScopeCollector`（検証済みトークンのクレームから
+  OAuth スコープ）と `PayloadSubjectIdCollector`（サブジェクト識別子）
+- `rule.collectors`: `ResourceActionScopeRuleCollector` — トークンがスコープ
+  `<action>:<resourceType>` を持つことを要求する
+- `resource.parser`: `DotNotationResourceParser`
+
+それ以外は登録済みだが無効です。特に `ResourceActionPermissionRuleCollector`
+（パーミッション `<resource.raw>.perm:<action>` を要求する）は意図的に有効化していません
+— 下記参照。
 
 ### 出荷時のポリシー
 
@@ -284,9 +329,10 @@ const app = await createApp({
 | スクリプト | コマンド | 説明 |
 |---|---|---|
 | `build` | `tsc` | TypeScript を `dist/` にコンパイルする |
+| `typecheck` | `tsc --noEmit -p tsconfig.typecheck.json` | 出力せずにソースとテストを型検査する |
 | `start` | `node dist/main.mjs` | コンパイル済みサーバーを起動する |
 | `debug` | `NODE_OPTIONS='--conditions=development' tsx watch src/main.mts` | ホットリロードで開発サーバーを起動する |
-| `test` | `echo 'no tests configured'` | プレースホルダー（テスト未設定） |
+| `test` | `vitest run` | `src/__tests__` のテンプレートのテストを実行する |
 
 ## Docker
 

package/templates/standalone/README.md

@@ -1,7 +1,39 @@
 # @o3co/auth-policy-verifier-standalone
 
+Last updated: 2026-09-23
+
 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`.
 
+## Responsibility
+
+**Role.** The composition root and the starting point for a deployment. It is
+not a library: nothing imports it. `@o3co/create-auth-policy-verifier` copies it
+into a new project, and from then on the operator owns and edits the copy. It
+sits on top of the libraries — it uses `@o3co/auth.policy-verifier.server`
+(`createApp`, `AppConfigSchema`, `builtinKeyResolversModule`),
+`@o3co/auth.policy-verifier.builtins` (`builtinCollectorsModule`) and
+`@o3co/auth.policy-verifier.core` (the `Logger` type).
+
+**Owns** the choices that are specific to one deployment:
+
+- which modules are composed into the app — [`src/main.mts`](src/main.mts);
+- where config comes from and how the `{ENV}.conf` overlay is layered —
+  [`src/configPath.ts`](src/configPath.ts), [`src/loadConfig.ts`](src/loadConfig.ts)
+  — and the shipped policy in [`config/application.conf`](config/application.conf);
+- the concrete logger (pino) — [`src/logger.ts`](src/logger.ts);
+- process lifecycle: SIGTERM handling with a drain deadline —
+  [`src/shutdown.ts`](src/shutdown.ts);
+- packaging: `Dockerfile`, `docker-compose*.yml`, the container healthcheck.
+
+**Does not own** the HTTP API, the decision pipeline, token verification or the
+config schema (all `server`), the collector / rule / parser implementations
+(`builtins`), or the `Module` contract (`core`). Change those upstream, not here.
+
+**Why separate.** Everything above is a per-deployment decision, so it is kept
+out of the published libraries and put in a tree the operator is expected to
+modify. It is `"private": true` and never published itself; it reaches users only
+through the scaffolder.
+
 ## Usage
 
 ```sh
@@ -225,18 +257,34 @@ scrape_configs:
 
 ## Default Collectors
 
-The following collectors are registered via `builtinCollectorsModule`:
-
-**Attribute collectors**:
-
-- `PayloadScopeCollector` — extracts OAuth scopes from the verified subject attributes (the JWT's claims)
-- `PayloadSubjectIdCollector` — extracts the subject identifier from the verified subject attributes (the JWT's claims)
-- `RequestContextAttributeCollector` — promotes declared fields of the request body's `context` into attributes (not wired by default; add it to `attribute.collectors` with an `attributes` mapping list)
-
-**Rule collectors** (resolve authorization rules):
-
-- `ResourceActionScopeRuleCollector` — requires the token to carry the scope `<action>:<resourceType>`
-- `ResourceActionPermissionRuleCollector` — requires the permission `<resource.raw>.perm:<action>` (not wired by default; see below)
+Two different lists matter here, and they are not the same.
+
+**Registered** — what `builtinCollectorsModule` (composed in `src/main.mts`) makes
+*available* by name. Registering does nothing on its own; an entry is only used
+when `config/application.conf` names it. The module registers six attribute
+collectors (`PayloadScopeCollector`, `PayloadSubjectIdCollector`,
+`StaticPermissionCollector`, `StaticRoleCollector`,
+`RequestContextAttributeCollector`, `PayloadClaimAttributeCollector`), two rule
+collectors (`ResourceActionScopeRuleCollector`,
+`ResourceActionPermissionRuleCollector`) and one resource parser
+(`DotNotationResourceParser`). The authoritative list, with each entry's config,
+is the builtins README — [Attribute Collectors](../../packages/builtins/README.md#attribute-collectors),
+[Rule Collectors](../../packages/builtins/README.md#rule-collectors) and
+[builtinCollectorsModule](../../packages/builtins/README.md#builtincollectorsmodule)
+— and the source is [`packages/builtins/src/module.mts`](../../packages/builtins/src/module.mts).
+
+**Enabled by the default config** — what the shipped `config/application.conf`
+actually wires:
+
+- `attribute.collectors`: `PayloadScopeCollector` (OAuth scopes from the verified
+  token's claims) and `PayloadSubjectIdCollector` (the subject identifier).
+- `rule.collectors`: `ResourceActionScopeRuleCollector` — requires the token to
+  carry the scope `<action>:<resourceType>`.
+- `resource.parser`: `DotNotationResourceParser`.
+
+Everything else is registered but off. In particular
+`ResourceActionPermissionRuleCollector` (requires the permission
+`<resource.raw>.perm:<action>`) is deliberately not enabled — see below.
 
 ### The shipped policy
 
@@ -286,9 +334,10 @@ const app = await createApp({
 | Script | Command | Description |
 |---|---|---|
 | `build` | `tsc` | Compile TypeScript to `dist/` |
+| `typecheck` | `tsc --noEmit -p tsconfig.typecheck.json` | Type-check sources and tests without emitting |
 | `start` | `node dist/main.mjs` | Start the compiled server |
 | `debug` | `NODE_OPTIONS='--conditions=development' tsx watch src/main.mts` | Start with hot-reload for development |
-| `test` | `echo 'no tests configured'` | Placeholder (no tests configured) |
+| `test` | `vitest run` | Run the template's tests in `src/__tests__` |
 
 ## Docker
 

package/templates/standalone/package.json

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

package/templates/versions.json

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