@o3co/create-auth-policy-verifier 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-policy-verifier",
-  "version": "0.9.0",
+  "version": "0.10.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.4.0",
-    "vitest": "^4.1.11"
+    "@types/node": "^26.5.1",
+    "vitest": "^5.0.0"
   },
   "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:24-alpine@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 AS node-base
+FROM node:26-alpine@sha256:ef24c5053d50fdc3e4e56eb4e7ddb7861874ab0fdc797046ba897581deb8e868 AS node-base
 
 ENV HOME=/home/node
 

package/templates/standalone/README.ja.md

@@ -45,10 +45,11 @@ OAUTH_JWT_SECRET=$(openssl rand -hex 32) \
 | `OAUTH_JWT_JWKS_CACHE_MAX_AGE_MS` | `600000` | 取得した JWKS をキャッシュから返す期間 |
 | `OAUTH_JWT_TOKEN_TYPE` | `at+jwt` | 受け入れる `typ` ヘッダ。同じ鍵で署名された id/refresh/logout token を拒否する。`*` で pin しない（その場合 `audience` を OIDC client id にしてはいけない） |
 | `OAUTH_JWT_AUDIENCE_CLAIM` | `aud` | audience を読む claim。`azp`（Clerk）、`client_id`（Cognito）。`aud` 以外を指定すると `aud` は一切見ない |
-| `OAUTH_AUTHENTICATOR` | `jwt` | subject を確立する token authenticator。他の名前は `main.mts` で module が登録したもの |
+| `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`） |
 | `VERIFY_MAX_BATCH_SIZE` | `50` | `POST /verify/batch` の件数上限 |
+| `VERIFY_CREDENTIAL_TO_COLLECTORS` | `never` | `expose` は生の資格情報を `context.credential` として collector に渡す — subject として下流 API を呼ぶ collector のためだけの設定。既定では collector は検証済みクレームだけを扱う。資格情報はリプレイ可能であり、context がログに出ればそれが漏れる |
 | `LOG_LEVEL` | `info` | 出力する最低レベル: `trace`\|`debug`\|`info`\|`warn`\|`error`\|`fatal`\|`silent`。decision ログのスイッチも兼ねる — [可観測性](#可観測性)を参照 |
 
 ## HS256 シークレットの強度
@@ -102,7 +103,7 @@ Authorization: Bearer <jwt>
 **このテンプレートは初期状態でまさにその組み合わせです。** `docker-compose.yml` が `HTTP_HOSTNAME=0.0.0.0` を設定する一方、`HTTP_CALLER_AUTH_TOKEN` はどこにも設定されていません。したがって publish したポートがホスト外から到達できる状態で `docker compose up` すると、未認証の判定エンドポイントが公開されます。ローカル開発では問題なく、だからこそ warn に留めています。実トラフィックを流す前に、次のいずれかを行ってください。
 
 - **ポートをプライベートネットワークに置く。** セキュリティグループ、プライベートサブネット、Kubernetes の `NetworkPolicy` など、誰が接続してよいかを決める仕組みです。compose の `3000:3000` の publish はこれに該当しません — そのホストに到達できるすべてに到達を許します。
-- **`.env` に `HTTP_CALLER_AUTH_TOKEN` を設定する。** ポートに到達できるだけでは判定を要求できなくなります。攻撃者が既にネットワーク境界の内側にいる場合でも有効なのは、2 つのうちこちらだけです。なお Go の enforcement 層（[protobuf.interceptors](https://github.com/o3co/protobuf.interceptors)）がこのヘッダを送るオプションを備えるのは**次のリリースから**です。それまで、同ライブラリを使う呼び出し元にはネットワーク側の制御が必要です。
+- **`.env` に `HTTP_CALLER_AUTH_TOKEN` を設定する。** ポートに到達できるだけでは判定を要求できなくなります。攻撃者が既にネットワーク境界の内側にいる場合でも有効なのは、2 つのうちこちらだけです。なお Go の enforcement 層（[protobuf.interceptors](https://github.com/o3co/protobuf.interceptors)）は v0.3.0 以降、`endpoint.WithO3coHeaders` でこのヘッダを送れます。それより前のバージョンで作られた呼び出し元にはネットワーク側の制御が必要です。
 - **あるいは `HTTP_HOSTNAME` を外し、verifier をサイドカーとして動かす。** enforcement 層とネットワーク名前空間を共有すれば、ループバックで足ります。
 
 `GET /metrics` も非ゲートです。理由と、ループバック以外に bind したときに何を意味するかは [`/metrics` への到達方法](#metrics-への到達方法)を参照してください。
@@ -289,6 +290,31 @@ make dev
 を読み込みます。資格情報は供給**しません** — `HTTP_CALLER_AUTH_TOKEN` はその
 `.env` に置いてください。
 
+### プロセス外の Cedar: `--profile cedar`
+
+[Cedar](../../packages/cedar/README.md) のポリシーをプロセス外で評価するデプロイは、
+アプリの隣でエージェントを起動します:
+
+```sh
+echo "CEDAR_AUTHENTICATION=$(openssl rand -hex 32)" >> .env
+docker compose --profile cedar up --build
+```
+
+`CEDAR_AUTHENTICATION` は必須です: エージェントはこれをトークンとして起動され、
+アプリはすべての呼び出しでこれを送ります。認証されていないエージェントは、
+到達できる何者にもポリシーセットの差し替えを許してしまうからです。未設定の
+ままだとエージェントはすべての呼び出しを拒否し、verifier は起動時にこれを
+設定するよう伝えます。profile を付けない素の `docker compose up` では不要です。
+
+`cedar-engine` サービスはアプリコンテナとネットワーク名前空間を共有するので、
+verifier の `http` engine は `http://127.0.0.1:8180` でそれを見つけます — engine
+には既定のアドレスがないため、これは compose ファイルがアプリに設定する
+`CEDAR_ENDPOINT` です。verifier は起動時に `config/policies` をそこへ push し、
+このコンテナの組の外からは誰も到達できません。この profile は、アプリが
+`cedarPolicyModule` を組み込むまで何もしません。パッケージ・モジュール・config
+エントリについては cedar の README を、どういうときにこの形が in-process の形に
+勝るかについてはその sizing 表を参照してください。
+
 ### `pnpm-lock.yaml` はビルド入力
 
 同じソースからの 2 回のビルドが 2 つの異なるイメージを生まないようにするのが

package/templates/standalone/README.md

@@ -103,7 +103,7 @@ Leaving the credential unset is supported and is fine on loopback. On a non-loop
 **This template is that combination out of the box.** `HTTP_HOSTNAME=0.0.0.0` is set in `docker-compose.yml` and `HTTP_CALLER_AUTH_TOKEN` is not set anywhere, so a `docker compose up` with the published port reachable from off-host is an unauthenticated decision endpoint. That is fine for local development and is why the warning is a warning. Before it carries traffic, do one of:
 
 - **Put the port on a private network.** A security group, a private subnet, a Kubernetes `NetworkPolicy` — something that decides who may connect. Publishing `3000:3000` from compose is not this: it reaches everything that can route to the host.
-- **Set `HTTP_CALLER_AUTH_TOKEN` in `.env`.** Then reaching the port is not enough to ask for a decision, which is the only one of the two that still holds against an attacker already inside the network boundary. Note that the Go enforcement layer ([protobuf.interceptors](https://github.com/o3co/protobuf.interceptors)) gains the option to send this header **from its next release**; until then a caller built on it needs the network control instead.
+- **Set `HTTP_CALLER_AUTH_TOKEN` in `.env`.** Then reaching the port is not enough to ask for a decision, which is the only one of the two that still holds against an attacker already inside the network boundary. Note that the Go enforcement layer ([protobuf.interceptors](https://github.com/o3co/protobuf.interceptors)) sends this header from v0.3.0 on, through `endpoint.WithO3coHeaders`; a caller built on an earlier version needs the network control instead.
 - **Or drop `HTTP_HOSTNAME` and run the verifier as a sidecar**, sharing a network namespace with the enforcement layer so loopback is enough.
 
 `GET /metrics` is not gated either — see [Reaching `/metrics`](#reaching-metrics) for why, and for what that means when the bind is not loopback.
@@ -293,6 +293,31 @@ make dev
 `.env`. It does **not** supply the credential — put `HTTP_CALLER_AUTH_TOKEN` in
 that `.env`.
 
+### Out-of-process Cedar: `--profile cedar`
+
+A deployment that evaluates [Cedar](../../packages/cedar/README.md) policies
+out of process starts the agent beside the app:
+
+```sh
+echo "CEDAR_AUTHENTICATION=$(openssl rand -hex 32)" >> .env
+docker compose --profile cedar up --build
+```
+
+`CEDAR_AUTHENTICATION` is required: the agent is started with it as its token
+and the app sends it on every call, because an unauthenticated agent lets
+anything that reaches it replace the policy set. Left unset, the agent refuses
+every call and the verifier's boot says to set it; a plain `docker compose up`
+without the profile does not need it.
+
+The `cedar-engine` service shares the app container's network namespace, so
+the verifier's `http` engine finds it at `http://127.0.0.1:8180` — the
+`CEDAR_ENDPOINT` the compose file sets on the app, since the engine has no
+default address — pushes `config/policies` into
+it at boot, and nothing outside the container pair can reach it. The profile
+does nothing until the app composes `cedarPolicyModule`; see cedar's README
+for the packages, the module and the config entry — and its sizing table for
+when this shape beats the in-process one.
+
 ### `pnpm-lock.yaml` is a build input
 
 `pnpm install --frozen-lockfile` is what keeps two builds of the same source

package/templates/standalone/config/application.conf

@@ -328,6 +328,16 @@ 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
+  # take to answer. Same budget and ceiling as one collector; overrun = deny.
+  ruleTimeoutMs = 2000
+  ruleTimeoutMs = ${?VERIFY_RULE_TIMEOUT_MS}
+  # How long all of a decision's asynchronous rules may take together. Rule
+  # groups run one after another, so `ruleTimeoutMs` bounds each rule and not
+  # the phase; this does, the way `collectorDeadlineMs` does for collectors.
+  # An asynchronous rule runs under whichever ends first. Overrun = deny.
+  evaluateDeadlineMs = 5000
+  evaluateDeadlineMs = ${?VERIFY_EVALUATE_DEADLINE_MS}
 
   # `collectorDeadlineMs` is the whole fan-out, per pipeline. The per-collector
   # budget cannot bound a SET: once collectors queue, enough of them each

package/templates/standalone/docker-compose.yml

@@ -15,6 +15,45 @@ 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.
+      # 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
+      # literal value would ignore a CEDAR_ENDPOINT set in .env for another agent.
+      - CEDAR_ENDPOINT=${CEDAR_ENDPOINT:-http://127.0.0.1:8180}
+      # The token the app sends the agent, from the same interpolation the
+      # `cedar-engine` service below starts the agent with — so a value from the
+      # shell or `--env-file` reaches both sides, not only the agent.
+      - CEDAR_AUTHENTICATION=${CEDAR_AUTHENTICATION:-}
     env_file:
       - path: .env
         required: false
+
+  # Out-of-process Cedar engine, for deployments that evaluate Cedar policies
+  # through @o3co/auth.policy-verifier.cedar without the in-process wasm
+  # package (its README, "Running out of process"). Opt in per run:
+  #
+  #   docker compose --profile cedar up --build
+  #
+  # It shares the app container's network namespace, so the verifier reaches
+  # it on loopback at CEDAR_ENDPOINT (http://127.0.0.1:8180, set on the app
+  # above), and nothing outside the pair can reach it at all —
+  # the same trust boundary the verifier's own bind address draws. The
+  # verifier pushes its config/policies into the agent at boot; nothing is
+  # mounted here. Pinned by digest for the reason the base image is.
+  cedar-engine:
+    image: permitio/cedar-agent:0.2.2@sha256:2a7713bce95220eb2ad870ba311f1ae8a4d6e607d13720747d75b96cb0c551ca
+    profiles: ["cedar"]
+    network_mode: "service:app"
+    environment:
+      - CEDAR_AGENT_ADDR=127.0.0.1
+      - CEDAR_AGENT_PORT=8180
+      # Required: an unauthenticated agent is a write oracle over the policy set
+      # — anything that reaches its port can PUT a `permit` for everyone. Set
+      # CEDAR_AUTHENTICATION in .env; the app reads the same variable and sends
+      # it. Unset, the agent starts with an empty token and refuses every call,
+      # and the verifier's boot says to set CEDAR_AUTHENTICATION. (Not compose's
+      # required-variable form: it is interpolated for every service, profile or
+      # not, and would refuse a plain `docker compose up` too.)
+      - CEDAR_AGENT_AUTHENTICATION=${CEDAR_AUTHENTICATION:-}

package/templates/standalone/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "@o3co/auth-policy-verifier-standalone",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"private": true,
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.29.3",
 	"type": "module",
 	"engines": {
-		"node": ">=22.0.0"
+		"node": ">=22.12.0"
 	},
 	"scripts": {
 		"build": "tsc",
@@ -24,12 +24,12 @@
 		"pino": "^10.3.1"
 	},
 	"devDependencies": {
-		"@types/node": "^26.4.0",
+		"@types/node": "^26.5.1",
 		"@types/supertest": "^7.2.1",
-		"jose": "^6.2.10",
+		"jose": "^6.2.12",
 		"supertest": "^7.2.2",
-		"tsx": "^4.23.12",
+		"tsx": "^4.23.13",
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.11"
+		"vitest": "^5.0.0"
 	}
 }

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

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+import { readFileSync } from "node:fs";
+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)", () => {
+	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,
+		// resource);`. The token comes from the same CEDAR_AUTHENTICATION the app
+		// 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).
+		expect(compose).toMatch(/- CEDAR_AUTHENTICATION=\$\{CEDAR_AUTHENTICATION:-\}/);
+	});
+
+	it("does not make a plain `docker compose up` depend on it", () => {
+		// `${VAR:?}` is interpolated for every service, profile or not, so it
+		// would refuse the app-only stack too. Unset, the agent is started with
+		// an empty token, refuses every call, and the verifier's boot names
+		// CEDAR_AUTHENTICATION — closed, without breaking the default stack.
+		expect(compose).not.toMatch(/:\?/);
+	});
+});

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

@@ -55,6 +55,8 @@ const envKeys = [
 	"VERIFY_COLLECTOR_TIMEOUT_MS",
 	"VERIFY_COLLECTOR_DEADLINE_MS",
 	"VERIFY_COLLECTOR_CONCURRENCY",
+	"VERIFY_RULE_TIMEOUT_MS",
+	"VERIFY_EVALUATE_DEADLINE_MS",
 ] as const;
 
 /** application.conf leaves issuer/audience unset, so every load must supply them. */
@@ -268,6 +270,8 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 		process.env.VERIFY_COLLECTOR_TIMEOUT_MS = "750";
 		process.env.VERIFY_COLLECTOR_DEADLINE_MS = "1500";
 		process.env.VERIFY_COLLECTOR_CONCURRENCY = "4";
+		process.env.VERIFY_RULE_TIMEOUT_MS = "900";
+		process.env.VERIFY_EVALUATE_DEADLINE_MS = "2500";
 
 		const config = loadAppConfig(configDirPath, "development");
 
@@ -286,6 +290,8 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 		expect(config.verify.collectorTimeoutMs).toBe(750);
 		expect(config.verify.collectorDeadlineMs).toBe(1_500);
 		expect(config.verify.collectorConcurrency).toBe(4);
+		expect(config.verify.ruleTimeoutMs).toBe(900);
+		expect(config.verify.evaluateDeadlineMs).toBe(2_500);
 	});
 
 	it.each([
@@ -304,6 +310,8 @@ describe("loadAppConfig — numeric knobs through the real 3-tier resolution (#1
 		["VERIFY_COLLECTOR_TIMEOUT_MS", "0"],
 		["VERIFY_COLLECTOR_DEADLINE_MS", "-1"],
 		["VERIFY_COLLECTOR_CONCURRENCY", "0"],
+		["VERIFY_RULE_TIMEOUT_MS", "0"],
+		["VERIFY_EVALUATE_DEADLINE_MS", "-1"],
 	])("refuses to boot on %s=%s", (key, value) => {
 		setRequiredEnv();
 		process.env[key] = value;
@@ -381,7 +389,7 @@ rule { collectors = [ { collector = ResourceActionScopeRuleCollector } ] }
 
 		const config = loadAppConfig(withoutVerify(), "development");
 
-		// All eleven, spelled out. A knob that reached the shape but not the
+		// All twelve, spelled out. A knob that reached the shape but not the
 		// block's `.default()` literal is `undefined` here, and `toEqual` says
 		// which one.
 		expect(config.verify).toEqual({
@@ -392,6 +400,8 @@ rule { collectors = [ { collector = ResourceActionScopeRuleCollector } ] }
 			maxContextEntries: 64,
 			maxContextValueLength: 1_024,
 			collectorTimeoutMs: 2_000,
+			ruleTimeoutMs: 2_000,
+			evaluateDeadlineMs: 5_000,
 			collectorDeadlineMs: 5_000,
 			collectorConcurrency: 8,
 			batchConcurrency: 8,

package/templates/versions.json

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