@o3co/auth.policy-verifier.builtins 0.14.0 → 0.16.0

package/README.ja.md

@@ -1,6 +1,6 @@
 # @o3co/auth.policy-verifier.builtins
 
-最終更新: 2026-09-24
+最終更新: 2026-10-01
 
 auth.policy-verifier 向けの組み込み attribute collector、rule collector、および resource parser です。
 
@@ -10,7 +10,7 @@ auth.policy-verifier 向けの組み込み attribute collector、rule collector
 
 core のインターフェースを実装した、小さな既製のセットです: attribute collector、rule、rule collector、resource parser、そしてそれらを server の `createApp` などのホストに登録する `builtinCollectorsModule`。依存は `@o3co/auth.policy-verifier.core` だけです。`templates/standalone` がこれを組み込み、`server` はテストでのみ使います（`devDependencies`）。
 
-- **所有するもの:** これらの実装が何を読み、何を書き、どう照合するか — JWT クレーム（`sub`、`azp`、`scope`、宣言したクレーム）から属性キーへの対応（#170）、`HasScope` / `HasPermission` と比較ルールの照合規則、ドット記法のリソース文法。
+- **所有するもの:** これらの実装が何を読み、何を書き、どう照合するか — JWT クレーム（`sub`、`azp`、`scope`、宣言したクレーム）から属性キーへの対応（#170）、`HasScope` / `HasPermission` と比較ルールの照合規則、ドット記法のリソース文法、クレーム契約の委任 range の文法と包含ルールの実装（契約そのものは umbrella リポジトリのもの）。
 - **所有しないもの:** パイプライン、グルーピング、判定（core）、認証や HTTP（`server`）、ポリシーエンジンや `AsyncRule`（`cedar`）、I/O を行う collector（利用側が書くもの。[docs/extending.ja.md](../../docs/extending.ja.md)）。
 - **core と別パッケージである理由:** core はエンジン中立の契約で、subject のフィールドを一切名指ししません（#170）。クレームの語彙と具体的な照合はその線の反対側、つまりここに置きます（[AGENTS.md — Core Vocabulary Scope](../../AGENTS.md#core-vocabulary-scope)）。また任意導入でもあります: builtins は意図的に基本セットであってカタログではない（[docs/extending.ja.md](../../docs/extending.ja.md)）ので、collector と rule を自前で書くデプロイメントはインストール不要で、core もこれに合わせて肥大化しません。
 
@@ -36,6 +36,7 @@ npm install @o3co/auth.policy-verifier.builtins
 | `StaticRoleCollector` | — | `ATTR_ROLES: Role[]` | `{ roles: Role[] }` |
 | `RequestContextAttributeCollector` | `requestContext` の宣言済みフィールド | 運用者が決めたキー | `{ attributes: Mapping[] }` |
 | `PayloadClaimAttributeCollector` | 検証済み `subject` の宣言済みクレーム | 運用者が決めたキー、または core の 5 キー | `{ attributes: Mapping[] }` (#219) |
+| `DelegationRangeCollector` | トークンの `authorization_details` のうち、設定した type のエントリのパス | `ATTR_DELEGATION_RANGE: string[]` | `{ type: string, claim?: string }` — [委任トークン](#委任トークン-range-と-actor) |
 
 `StaticPermissionCollector` と `StaticRoleCollector` は、リクエストのコンテキストに関わらず、コンストラクタに渡した値を常に出力します。渡された値は構築時にコピーされます — 配列、そして `StaticRoleCollector` では各 `Role` とその `permissions` も — ので、構築後に config を変更しても出力は変わりません（#255）。`permissions` と `roles` は配列でなければなりません。それ以外の値は、文字列も含めて（`["posts.*"]` のつもりで `permissions = "posts.*"` と書いた場合など）構築時に `TypeError` で拒否され、デプロイは起動時に失敗します（#264）。
 
@@ -52,7 +53,7 @@ npm install @o3co/auth.policy-verifier.builtins
   ] }
 ```
 
-マッピングの形は `RequestContextAttributeCollector` と同じです（`{ from, to?, type? }`、完全一致するキーが dot path より優先、own property のみ）。違うのは読み取り元であり、したがって信頼度です: subject バッグは authenticator が検証したものなので、request-context コレクターが拒否する core の 5 キー — `scopes`、`permissions`、`roles`、`userId`、`clientId` — にもマッピングを着地させて**かまいません**。2 つのコレクターが 1 つのリストキーに書けば union されます。それはデプロイが issuer 由来の 2 つのソースを合成しているということであり、config にそう書かれています。一方、2 つのコレクターが異なる値で書いた*スカラー*キーは `AttributeConflictError` を投げ、すべてのリクエストを deny します — `PayloadSubjectIdCollector` も `userId` / `clientId` を書いている間は、そこへマッピングしないでください。別のパッケージが予約したキー（cedar の `request*`）は引き続き拒否されます。それらは subject ではなくリクエストから導出されるものだからです。そして、マッピングするのは IdP が自身の登録データや管理データから埋めるクレームだけにしてください: ユーザーが編集できるメタデータ（Clerk の `unsafe_metadata`、Auth0 の `user_metadata`）から発行されたクレームは、署名されてはいても信頼できるものではありません。
+マッピングの形は `RequestContextAttributeCollector` と同じです（`{ from, to?, type? }`、完全一致するキーが dot path より優先、own property のみ）。違うのは読み取り元であり、したがって信頼度です: subject バッグは authenticator が検証したものなので、request-context コレクターが拒否する core の 5 キー — `scopes`、`permissions`、`roles`、`userId`、`clientId` — にもマッピングを着地させて**かまいません**。2 つのコレクターが 1 つのリストキーに書けば union されます。それはデプロイが issuer 由来の 2 つのソースを合成しているということであり、config にそう書かれています。一方、2 つのコレクターが異なる値で書いた*スカラー*キーは `AttributeConflictError` を投げ、すべてのリクエストを deny します — `PayloadSubjectIdCollector` も `userId` / `clientId` を書いている間は、そこへマッピングしないでください。別のパッケージが予約したキーは引き続き拒否されます。そのパッケージが自分の collector で書くキーだからです（cedar の `request*` はリクエストから、このパッケージの `delegationRange` は `DelegationRangeCollector` が絞り込むクレームから）。クレームをそこへマッピングすると、2 つ目の書き手になります。そして、マッピングするのは IdP が自身の登録データや管理データから埋めるクレームだけにしてください: ユーザーが編集できるメタデータ（Clerk の `unsafe_metadata`、Auth0 の `user_metadata`）から発行されたクレームは、署名されてはいても信頼できるものではありません。
 
 scope クレームについては `PayloadScopeCollector { claim = "scp" }` を優先してください。こちらはスペース区切り文字列の形も読み、`ResourceActionScopeRuleCollector { claim = "scp" }` と組にすることで、両者が同じ claim を見ます（それぞれが自分の `claim` を持ち、一致は検査されないので両方に設定してください）。rule collector は claim の有無だけを見ます — 使える scope リストを持たない claim（`""`、数値）は scope を生まない一方、`scopeless = "skip"` では scope ありとして扱われます。
 
@@ -89,7 +90,7 @@ scope クレームについては `PayloadScopeCollector { claim = "scp" }` を
 { from = "scopes", to = "requestedScopes", type = "string[]" }
 ```
 
-予約集合は**このパッケージが保持するリストではありません**。core のレジストリ（`RESERVED_ATTRIBUTE_KEYS` / `reserveAttributeKeys` / `attributeKeyReservation`）です。core は自身の 5 キー — `scopes`、`permissions`、`roles`、`userId`、`clientId` — を予約し、属性語彙を持つ各パッケージはモジュールロード時に自分の語彙を予約します。`@o3co/auth.policy-verifier.cedar` は `requestAction` / `requestResourceType` / `requestResourceId` / `requestResourceRaw` を予約します。プロジェクト側の Collector も、書き込むキーを同じ方法で予約してください。設定でそのパッケージの Collector 名を書ける構成は、すでにそのパッケージを import しているため、このコレクターが構築される前にキーは登録済みです — core から見えない語彙まで guard が効くのはこのためです。拒否メッセージは所有パッケージ名を示し、それ自体が予約されていない代替名を提案します。
+予約集合は**このパッケージが保持するリストではありません**。core のレジストリ（`RESERVED_ATTRIBUTE_KEYS` / `reserveAttributeKeys` / `attributeKeyReservation`）です。core は自身の 5 キー — `scopes`、`permissions`、`roles`、`userId`、`clientId` — を予約し、属性語彙を持つ各パッケージはモジュールロード時に自分の語彙を予約します。`@o3co/auth.policy-verifier.cedar` は `requestAction` / `requestResourceType` / `requestResourceId` / `requestResourceRaw` を予約し、このパッケージは `delegationRange`（`ATTR_DELEGATION_RANGE`）を予約します。プロジェクト側の Collector も、書き込むキーを同じ方法で予約してください。設定でそのパッケージの Collector 名を書ける構成は、すでにそのパッケージを import しているため、このコレクターが構築される前にキーは登録済みです — core から見えない語彙まで guard が効くのはこのためです。拒否メッセージは所有パッケージ名を示し、それ自体が予約されていない代替名を提案します。
 
 `context` は呼び出し側のもので、これらのキーはデプロイ側のものです。既定のサーバーでは `scopes` / `userId` / `clientId` は**署名検証済みトークン**から読まれ、`permissions` / `roles` は builtin の Rule が判断に使う権限を、cedar の 4 キーはパース済みリクエストを運びます。信頼レベルがまったく異なり、リクエストボディがそれらと同じバケツに合流してはなりません。
 
@@ -97,6 +98,35 @@ scope クレームについては `PayloadScopeCollector { claim = "scp" }` を
 
 スカラーキーなら安全というわけでもなく、理由は 2 つあります。双方が書けば値が食い違い、`AttributeConflictError` でそのリクエストは拒否されます — fail-closed ではありますが、起動時の拒否ではなく予告のない拒否です。そして所有側のコレクターが*条件付きでしか*書かないキーには、そもそも競合相手がいません。cedar の `RequestFactsCollector` は `"document"` のような id を持たないリソースでは `requestResourceId` を書かないため、`{ from = "rid", to = "requestResourceId" }` は誰とも競合せずに着地し、Cedar の resource エンティティが呼び出し側のリクエストボディから組み立てられてしまいます。
 
+### 委任トークン: range と actor
+
+委任 grant が発行したトークン（subject のために client が動くもの）は、その range を 1 種類の type の RFC 9396 `authorization_details` エントリ（各 `{ "type": <その type>, "path": "<パス>" }`）として、動いている client を `act.sub`（RFC 8693 §4.1）として持ちます。パスの文法と包含ルールは、provider–verifier の[クレーム契約](https://github.com/o3co/auth/blob/develop/docs/claims-contract.md)のものです:
+
+- パスは `(type(:id)?.)*action`。`type` と `action` は `[a-z][a-z0-9_]*`、`id` は `[A-Za-z0-9_~-]` で、それ以外の文字は大文字の 16 進でパーセントエンコードします。id は書かれたとおりに比較されるので、`%41` と `A` は別の id です。issuer とリソースは同じようにエンコードしてください。
+- エントリがパスの先頭からセグメント単位の接頭辞になっていれば、そのエントリはパスを含みます。id を持たないエントリのセグメントは、同じ type の任意の id を含みます。`project:p1.report` は `project:p1.report:r7.run` を含みます。エントリの最後の要素は、action を名指すときも type として比較されるので、`project:p1.run` は `project:p1.run.more` を含みます。action の名前と type の名前は分けてください。
+
+range をポリシーと合わせて判定するには、1 か所から読んだ同じ `type` で 2 つを設定します:
+
+```hocon
+attribute { collectors = [
+  { collector = "PayloadScopeCollector" }
+  # issuer の委任 type。未設定なら両方のエントリに `type` がなく、起動が拒否される
+  { collector = "DelegationRangeCollector", type = ${?DELEGATION_TYPE} }
+  # 動いている client。ポリシーから参照する場合
+  { collector = "PayloadClaimAttributeCollector", attributes = [ { from = "act.sub", to = "actorId" } ] }
+] }
+rule { collectors = [
+  { collector = "ResourceActionScopeRuleCollector" }
+  { collector = "DelegationRangeRuleCollector", type = ${?DELEGATION_TYPE} }
+] }
+```
+
+- `DelegationRangeCollector` はエントリのパスを `ATTR_DELEGATION_RANGE`（`"delegationRange"`、このパッケージが予約）に書きます。文法外のパスは除外され、range が狭まる方向に働きます。その type のエントリはあるが読めるパスがないトークンは空の range になり、何も含みません。クレームが別の形（リストでない、またはエントリのオブジェクト以外を含むリスト）で存在するトークンも、エントリがどの type を名指すかにかかわらず同じです。`authorization_details` をほかの RFC 9396 の type と共有するトークンは、エントリのオブジェクトのリストとして持たないと、すべて deny されます。
+- `DelegationRangeRuleCollector` は、トークンが range を持つとき（その type のエントリがあるか、クレームが別の形で存在するとき）、リクエストのパス（`<resource.raw>.<action>`。`resource: "project:p1.report:r7"` と `action: "run"` なら `project:p1.report:r7.run`）について [`WithinDelegationRange`](#withindelegationrange) ルールを 1 つ生成し、持たないときは何も生成しません。action は文法上の 1 つの action でなければなりません。複数の要素からなる action（`report.delete`）は結合したパスの区切りを変えてしまい、親へのリクエストが range に含まれる子へのリクエストとして読めてしまうので、その場合ルールは fail します。このルールは独立したグループで、絞るルール（`restricts: true`）なので、委任トークンは range とポリシーの両方が許すものだけを許されます。ポリシーのルールが 1 つも適用されない委任トークンは、range だけで判定されることはなく、`rule.onEmptyRuleSet`（既定では `no_applicable_rule`）で判定されます。range のないトークンは、この 2 つがない場合と同じく判定されます。
+- 2 つには同じ `type` と `claim`（既定 `authorization_details`）を与えてください。一致しているかを確かめる仕組みはありません。食い違うと、2 通りに壊れます。ルール collector がトークンのエントリを見つけ、属性 collector が見つけない場合は、ルールが range を見つけられず、リクエストは deny されます。逆の場合はルールが生成されず、**range は適用されません**。
+- リクエストのパスは、設定したリソースパーサーにかかわらず、呼び出し元が送ったリソース文字列から作られます。別の文法で書かれたリソース（`projects/p1/reports/r7`）はパスとして読めず、委任されたリクエストはすべて deny されます。
+- リクエストが名指すリソースは、親の連鎖も含めて呼び出し元の主張です。連鎖に依拠するポリシー（包含、`in`）は、その連鎖を保存しているストアを読む独自の collector で、使う前に確かめる必要があります（[docs/extending.md](../../docs/extending.md#writing-a-custom-attributecollector)）。
+
 ## Rules
 
 ### HasPermission
@@ -141,6 +171,10 @@ new AttrMatchRule({ a: string, b: string, group?: string })
 - 純粋な述語です。`CollectorContext` を参照しません。比較対象の値はプロジェクト側の上流 `AttributeCollector` が attrs に格納し、プロジェクト側の `RuleCollector` でこの Rule を構築します。
 - `ruleType` の既定値は `"attr_match:${a}:${b}"` です。評価器は `ruleType` 内で OR、`ruleType` 間で AND を取るので、この既定値により異なる2つの比較は AND（両方必要）として扱われます。2つの比較を OR 結合したい場合（例「DID または email で一致」）は、両方の Rule に同じ `group` を指定してください。その `group` 値が `ruleType` として使われます。
 
+### WithinDelegationRange
+
+`ATTR_DELEGATION_RANGE` のエントリのどれかが、クレーム契約の包含ルール（[委任トークン](#委任トークン-range-と-actor)）でリクエストのパスを含むとき pass します。range がない場合や、パスを含む文字列が 1 つもない場合は fail し、文法外のリクエストパスも fail します。`ruleType` は `delegation_range`、`code` は `outside_delegation_range` です。絞るルールなので、ほかのルールが許すものを絞るだけで、それ自体は許可の根拠になりません。`DelegationRangeRuleCollector` が生成します。別の包含ルールが必要なデプロイは、`ATTR_DELEGATION_RANGE` を読む独自のルールと、それを生成するルール collector を書き、`DelegationRangeRuleCollector` の代わりに使います。
+
 ## Attribute Comparison Rules
 
 属性比較 Rule 群は 2 軸のマトリクスで構成されます: **family**（Literal または Pair）と **operator**（Equal、NotEqual、In、NotIn、Compare）。
@@ -248,13 +282,15 @@ new AttrPairCompare({ a: string, op: "lt" | "le" | "gt" | "ge", b: string, group
 | --- | --- | --- |
 | `ResourceActionPermissionRuleCollector` | `"<resource.raw>.perm:<action>"` | `[HasPermission(...)]` |
 | `ResourceActionScopeRuleCollector` | `"<action>:<resource.resourceType>"` | `[HasScope(...)]` |
+| `DelegationRangeRuleCollector` | `"<resource.raw>.<action>"`（range を持つトークンのとき） | `[WithinDelegationRange(...)]` または `[]` |
 
-`ResourceActionPermissionRuleCollector` にコンストラクタ引数はありません。
+`ResourceActionPermissionRuleCollector` にコンストラクタ引数はありません。`DelegationRangeRuleCollector` は `{ type: string, claim?: string }` を受け取ります — [委任トークン](#委任トークン-range-と-actor)。
 `ResourceActionScopeRuleCollector` は `{ scopeless?: "deny" | "skip", allowBareScopeRewrite?: boolean, claim?: string }` を受け取ります — `claim` はトークンが scope を主張していることを示す claim の名前です（既定 `scope`。`PayloadScopeCollector` が読むもの、例えば `scp` に合わせる）。
 
 - `scopeless`（既定 `"deny"`）: 既定ではリクエストごとに必ず `HasScope` ルールを生成するため、scope claim（`scope`、または `claim` が指す claim）を持たない
-  トークンはこのルールに落ちます。`"skip"` は scopeless トークンに対してルールを生成しませんが、ルールが 1 つも集まらない
-  リクエストは deny されるため、別のルールグループが認可を担うパイプラインでのみ使ってください。
+  トークンはこのルールに落ちます。`"skip"` は scopeless トークンに対してルールを生成しませんが、許可するルールが 1 つも集まらない
+  リクエストは deny されるため、許可する別のルールグループが認可を担うパイプラインでのみ使ってください。
+  [`WithinDelegationRange`](#withindelegationrange) のような絞るルールは認可になりません。
 - `allowBareScopeRewrite`（既定 `false`）: [`HasScope`](#hasscope) へそのまま渡されます。issuer が `{action}:{resourceType}`
   形式（`read:project`）ではなくプレフィックスなしのリソース名（`project`）を発行する場合にのみ `true` にしてください。
 
@@ -327,8 +363,10 @@ import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
 | `attributeCollector` | `"StaticRoleCollector"` | `(config) => new StaticRoleCollector(config)` |
 | `attributeCollector` | `"RequestContextAttributeCollector"` | `(config) => new RequestContextAttributeCollector(config)` |
 | `attributeCollector` | `"PayloadClaimAttributeCollector"` | `(config) => new PayloadClaimAttributeCollector(config)` |
+| `attributeCollector` | `"DelegationRangeCollector"` | `(config) => new DelegationRangeCollector(config)` |
 | `ruleCollector` | `"ResourceActionScopeRuleCollector"` | `(config) => new ResourceActionScopeRuleCollector(config)` |
 | `ruleCollector` | `"ResourceActionPermissionRuleCollector"` | `() => new ResourceActionPermissionRuleCollector()` |
+| `ruleCollector` | `"DelegationRangeRuleCollector"` | `(config) => new DelegationRangeRuleCollector(config)` |
 | `resourceParser` | `"DotNotationResourceParser"` | `() => new DotNotationResourceParser()` |
 
 ## 関連

package/README.md

@@ -1,6 +1,6 @@
 # @o3co/auth.policy-verifier.builtins
 
-Last updated: 2026-09-24
+Last updated: 2026-10-01
 
 Built-in attribute collectors, rule collectors, and resource parser for auth.policy-verifier.
 
@@ -16,8 +16,9 @@ a host such as the server's `createApp`. It depends on `@o3co/auth.policy-verifi
 
 - **Owns** what these implementations read, write and match: the mapping from JWT claims
   (`sub`, `azp`, `scope`, declared claims) to attribute keys (#170), the matching rules of
-  `HasScope` / `HasPermission` and the comparison rules, and the dot-notation resource
-  grammar.
+  `HasScope` / `HasPermission` and the comparison rules, the dot-notation resource
+  grammar, and the implementation of the claims contract's delegation-range grammar and
+  containment rule (the contract itself is the umbrella repository's).
 - **Does not own** the pipelines, the grouping or the decision (core), authentication or HTTP
   (`server`), policy engines or `AsyncRule`s (`cedar`), or collectors that do I/O — those are
   the consumer's to write ([docs/extending.md](../../docs/extending.md)).
@@ -51,6 +52,7 @@ All collectors implement `AttributeCollector`.
 | `StaticRoleCollector` | — | `ATTR_ROLES: Role[]` | `{ roles: Role[] }` |
 | `RequestContextAttributeCollector` | declared fields of `requestContext` | the operator's own keys | `{ attributes: Mapping[] }` |
 | `PayloadClaimAttributeCollector` | declared claims of the verified `subject` | the operator's own keys, or core's five | `{ attributes: Mapping[] }` (#219) |
+| `DelegationRangeCollector` | the paths of the token's `authorization_details` entries of the configured type | `ATTR_DELEGATION_RANGE: string[]` | `{ type: string, claim?: string }` — [Delegated tokens](#delegated-tokens-range-and-actor) |
 
 `StaticPermissionCollector` and `StaticRoleCollector` always emit the values supplied at construction time, regardless of request context. They copy what they were given at construction — the array, and for `StaticRoleCollector` each `Role` and its `permissions` — so mutating the config afterwards changes nothing they emit (#255). `permissions` and `roles` must be arrays: anything else, a string included (`permissions = "posts.*"` where `["posts.*"]` was meant), is refused with a `TypeError` at construction, so the deployment fails at boot (#264).
 
@@ -67,7 +69,7 @@ Promotes declared claims of the **verified subject** into attributes (#219) —
   ] }
 ```
 
-Same mapping shape as `RequestContextAttributeCollector` (`{ from, to?, type? }`, an exact key winning over a dot path, own properties only). What differs is the source, and therefore the trust: the subject bag is what the authenticator verified, so a mapping **may** land on core's five keys — `scopes`, `permissions`, `roles`, `userId`, `clientId` — where the request-context collector refuses them. Two collectors writing one list key union it; that is the deployment composing two issuer-derived sources, and it says so in config. A *scalar* key written by two collectors with different values throws `AttributeConflictError` and denies every request — do not map onto `userId` / `clientId` while `PayloadSubjectIdCollector` also writes them. Keys another package reserved (cedar's `request*`) stay refused, because they are derived from the request, not from the subject. And map only claims the IdP populates from its own registration or admin data: a claim minted from user-editable metadata (Clerk's `unsafe_metadata`, Auth0's `user_metadata`) is signed, not trusted.
+Same mapping shape as `RequestContextAttributeCollector` (`{ from, to?, type? }`, an exact key winning over a dot path, own properties only). What differs is the source, and therefore the trust: the subject bag is what the authenticator verified, so a mapping **may** land on core's five keys — `scopes`, `permissions`, `roles`, `userId`, `clientId` — where the request-context collector refuses them. Two collectors writing one list key union it; that is the deployment composing two issuer-derived sources, and it says so in config. A *scalar* key written by two collectors with different values throws `AttributeConflictError` and denies every request — do not map onto `userId` / `clientId` while `PayloadSubjectIdCollector` also writes them. Keys another package reserved stay refused, because that package writes them with a collector of its own — cedar's `request*` from the request, this package's `delegationRange` from the claim `DelegationRangeCollector` narrows — and a claim mapped onto one would be a second writer. And map only claims the IdP populates from its own registration or admin data: a claim minted from user-editable metadata (Clerk's `unsafe_metadata`, Auth0's `user_metadata`) is signed, not trusted.
 
 For the scope claim specifically, prefer `PayloadScopeCollector { claim = "scp" }`, which also reads the space-delimited string form and pairs with `ResourceActionScopeRuleCollector { claim = "scp" }` — set on both, since each keeps its own `claim` and nothing checks they match — so both look at the same claim. The rule collector checks only that the claim is present: a claim holding no usable scope list (`""`, a number) yields no scopes but still counts as scoped under `scopeless = "skip"`.
 
@@ -104,7 +106,7 @@ A mapping's `to` may not name a **reserved attribute key**. Naming one is a **co
 { from = "scopes", to = "requestedScopes", type = "string[]" }
 ```
 
-The reserved set is **not a list this package keeps**. It is core's registry (`RESERVED_ATTRIBUTE_KEYS`, `reserveAttributeKeys`, `attributeKeyReservation`): core reserves its own five — `scopes`, `permissions`, `roles`, `userId`, `clientId` — and every package that owns attribute vocabulary reserves its own at module load. `@o3co/auth.policy-verifier.cedar` reserves `requestAction`, `requestResourceType`, `requestResourceId` and `requestResourceRaw`; a project-side collector should reserve the keys it writes the same way. A composition that can name a package's collectors in config has already imported that package, so its keys are registered before this collector is constructed — which is why the guard covers vocabulary core cannot see. The refusal names the owning package, and suggests a rename that is not itself reserved.
+The reserved set is **not a list this package keeps**. It is core's registry (`RESERVED_ATTRIBUTE_KEYS`, `reserveAttributeKeys`, `attributeKeyReservation`): core reserves its own five — `scopes`, `permissions`, `roles`, `userId`, `clientId` — and every package that owns attribute vocabulary reserves its own at module load. `@o3co/auth.policy-verifier.cedar` reserves `requestAction`, `requestResourceType`, `requestResourceId` and `requestResourceRaw`, and this package reserves `delegationRange` (`ATTR_DELEGATION_RANGE`); a project-side collector should reserve the keys it writes the same way. A composition that can name a package's collectors in config has already imported that package, so its keys are registered before this collector is constructed — which is why the guard covers vocabulary core cannot see. The refusal names the owning package, and suggests a rename that is not itself reserved.
 
 `context` is the caller's, and those keys are the deployment's. Under the default server `scopes`, `userId` and `clientId` are read out of the **signature-verified token**, `permissions` / `roles` carry the entitlements the builtin rules decide from, and cedar's four carry the parsed request — so the two sides of such a mapping carry entirely different trust, and the request body must not join them in one bucket.
 
@@ -112,6 +114,35 @@ What makes it worth refusing rather than documenting is the merge: `AttributePip
 
 A scalar key is no safer, in two ways. Where both sides write it the values disagree and `AttributeConflictError` denies the request — fail-closed, but an unannounced denial rather than a refusal at boot. And where the owning collector writes its key only *sometimes* there is no second writer at all: cedar's `RequestFactsCollector` omits `requestResourceId` for an id-less resource such as `"document"`, so `{ from = "rid", to = "requestResourceId" }` would land unopposed and the Cedar resource entity would be built from the caller's own request body.
 
+### Delegated tokens: range and actor
+
+A token a delegation grant issued — a client acting for a subject — carries its range as RFC 9396 `authorization_details` entries of one type, each `{ "type": <that type>, "path": "<path>" }`, and the acting client as `act.sub` (RFC 8693 §4.1). The path grammar and the containment rule are the provider–verifier [claims contract](https://github.com/o3co/auth/blob/develop/docs/claims-contract.md)'s:
+
+- a path is `(type(:id)?.)*action`: `type` and `action` are `[a-z][a-z0-9_]*`, and `id` is `[A-Za-z0-9_~-]`, anything else percent-encoded in upper-case hex. An id is compared as written, so `%41` and `A` are two ids: the issuer and the resource must encode alike;
+- an entry contains a path when it is a segment-wise prefix of it, and an entry segment that names no id contains the same type with any id: `project:p1.report` contains `project:p1.report:r7.run`. The entry's last element is compared as a type even when it names an action, so `project:p1.run` contains `project:p1.run.more`: keep action names apart from type names.
+
+To decide the range together with the policies, configure the pair with the same `type`, read from one place:
+
+```hocon
+attribute { collectors = [
+  { collector = "PayloadScopeCollector" }
+  # the issuer's delegation type; unset, both entries lack `type` and boot is refused
+  { collector = "DelegationRangeCollector", type = ${?DELEGATION_TYPE} }
+  # the acting client, for policies that name it
+  { collector = "PayloadClaimAttributeCollector", attributes = [ { from = "act.sub", to = "actorId" } ] }
+] }
+rule { collectors = [
+  { collector = "ResourceActionScopeRuleCollector" }
+  { collector = "DelegationRangeRuleCollector", type = ${?DELEGATION_TYPE} }
+] }
+```
+
+- `DelegationRangeCollector` writes the entries' paths to `ATTR_DELEGATION_RANGE` (`"delegationRange"`, reserved by this package). A path outside the grammar is left out, which narrows the range; a token with entries of the type but no readable path gets an empty range, which contains nothing, and so does a token whose claim is there in another shape — not a list, or a list holding something other than entry objects — whatever types its entries name: a token that shares `authorization_details` with other RFC 9396 types must carry it as a list of entry objects, or it is denied everything.
+- `DelegationRangeRuleCollector` emits one [`WithinDelegationRange`](#withindelegationrange) rule for the requested path — `<resource.raw>.<action>`, so `resource: "project:p1.report:r7"` with `action: "run"` is `project:p1.report:r7.run` — when the token carries a range (an entry of the type, or the claim in another shape), and no rule otherwise. The action must be one action of the grammar: one of several elements (`report.delete`) would re-split the joined path, so a request on the parent would read as one on a child the range contains, and the rule fails instead. The rule is a group of its own and restricts (`restricts: true`), so a delegated token is allowed only what the range and the policies both allow: one no policy rule applies to is decided by `rule.onEmptyRuleSet` (`no_applicable_rule` by default), never by its range alone. A token without a range is decided as it is without the pair.
+- Give both the same `type` and `claim` (default `authorization_details`); nothing checks that they agree. Configured apart, the pair fails one of two ways. Where the rule collector finds the token's entries and the attribute collector does not, the rule finds no range and the request is denied. The other way round, no rule is emitted and **the range is not enforced**.
+- The requested path is built from the resource string the caller sent, whatever resource parser is configured. Resources written in another grammar (`projects/p1/reports/r7`) parse as no path, and every delegated request is denied.
+- The resource a request names is the caller's claim, its parent chain included. A policy that relies on the chain — containment, `in` — needs it confirmed first, by a collector of your own that reads the store it lives in ([docs/extending.md](../../docs/extending.md#writing-a-custom-attributecollector)).
+
 ## Rules
 
 ### HasPermission
@@ -156,6 +187,10 @@ new AttrMatchRule({ a: string, b: string, group?: string })
 - Pure predicate — does not read `CollectorContext`. Consuming projects provide the two values to compare through upstream `AttributeCollector`s and wire the rule through their own `RuleCollector`.
 - `ruleType` defaults to `"attr_match:${a}:${b}"`. The evaluator ORs rules within a `ruleType` and ANDs across different `ruleType`s, so the default ensures two independent comparisons are AND-combined (required together). Pass `group` explicitly when you want two comparisons to be OR-combined (for example, "identify by DID or by email") — both rules then share the provided `group` as their `ruleType`.
 
+### WithinDelegationRange
+
+Passes when an entry of `ATTR_DELEGATION_RANGE` contains the requested path, by the claims contract's containment rule ([Delegated tokens](#delegated-tokens-range-and-actor)). A range that is absent, or holds no string that contains the path, fails, and so does a requested path outside the grammar. `ruleType` is `delegation_range` and `code` is `outside_delegation_range`. It restricts: it narrows what the other rules allow and is no reason to allow on its own. `DelegationRangeRuleCollector` builds it. A deployment that needs another containment rule writes its own rule over `ATTR_DELEGATION_RANGE`, and a rule collector that emits it, in place of `DelegationRangeRuleCollector`.
+
 ## Attribute Comparison Rules
 
 The attribute comparison rules form a 2 × 5 matrix over two axes: **family** (Literal vs. Pair) and **operator** (Equal, NotEqual, In, NotIn, Compare).
@@ -263,13 +298,15 @@ Every attribute comparison rule reads each field of its config once, validates i
 | --- | --- | --- |
 | `ResourceActionPermissionRuleCollector` | `"<resource.raw>.perm:<action>"` | `[HasPermission(...)]` |
 | `ResourceActionScopeRuleCollector` | `"<action>:<resource.resourceType>"` | `[HasScope(...)]` |
+| `DelegationRangeRuleCollector` | `"<resource.raw>.<action>"`, for a token with a range | `[WithinDelegationRange(...)]`, or `[]` |
 
-`ResourceActionPermissionRuleCollector` takes no constructor arguments.
+`ResourceActionPermissionRuleCollector` takes no constructor arguments. `DelegationRangeRuleCollector` takes `{ type: string, claim?: string }` — [Delegated tokens](#delegated-tokens-range-and-actor).
 `ResourceActionScopeRuleCollector` accepts `{ scopeless?: "deny" | "skip", allowBareScopeRewrite?: boolean, claim?: string }` — `claim` names the claim whose presence says the token asserted scopes (default `scope`; set it to what `PayloadScopeCollector` reads, e.g. `scp`).
 
 - `scopeless` (default `"deny"`): it emits the `HasScope` rule for every request, so a token carrying no scope
-  claim (`scope`, or the claim `claim` names) fails it. `"skip"` emits no rule for a scopeless token — only use it in a pipeline where another rule
-  group authorizes the request, since a request that collects no rule at all is denied.
+  claim (`scope`, or the claim `claim` names) fails it. `"skip"` emits no rule for a scopeless token — only use it in a pipeline where another granting
+  rule group authorizes the request, since a request that collects no granting rule is denied: a restricting rule such as
+  [`WithinDelegationRange`](#withindelegationrange) does not authorize it.
 - `allowBareScopeRewrite` (default `false`): forwarded to [`HasScope`](#hasscope). Set it to `true` only if your
   issuer emits bare resource names (`project`) rather than `{action}:{resourceType}` scopes (`read:project`).
 
@@ -344,8 +381,10 @@ Registrations as of this writing; the source of truth is [`src/module.mts`](src/
 | `attributeCollector` | `"StaticRoleCollector"` | `(config) => new StaticRoleCollector(config)` |
 | `attributeCollector` | `"RequestContextAttributeCollector"` | `(config) => new RequestContextAttributeCollector(config)` |
 | `attributeCollector` | `"PayloadClaimAttributeCollector"` | `(config) => new PayloadClaimAttributeCollector(config)` |
+| `attributeCollector` | `"DelegationRangeCollector"` | `(config) => new DelegationRangeCollector(config)` |
 | `ruleCollector` | `"ResourceActionScopeRuleCollector"` | `(config) => new ResourceActionScopeRuleCollector(config)` |
 | `ruleCollector` | `"ResourceActionPermissionRuleCollector"` | `() => new ResourceActionPermissionRuleCollector()` |
+| `ruleCollector` | `"DelegationRangeRuleCollector"` | `(config) => new DelegationRangeRuleCollector(config)` |
 | `resourceParser` | `"DotNotationResourceParser"` | `() => new DotNotationResourceParser()` |
 
 ## See Also

package/dist/collectors/DelegationRangeCollector.d.mts

@@ -0,0 +1,29 @@
+import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/auth.policy-verifier.core";
+/** Config entry accepted by `DelegationRangeCollector`. */
+export interface DelegationRangeCollectorConfig {
+    /**
+     * The `authorization_details` type the delegation range is carried under:
+     * the type the issuer's delegation grants write. Required — the same value
+     * `DelegationRangeRuleCollector` is given.
+     */
+    type: string;
+    /** The claim the entries are read from. Defaults to `authorization_details`. */
+    claim?: string;
+}
+/**
+ * Attribute collector that reads the paths of the token's
+ * `authorization_details` entries of the configured type into a `string[]`
+ * under `ATTR_DELEGATION_RANGE`. A path outside the grammar is left out,
+ * which narrows the range; a token with entries of the type but no readable
+ * path gets an empty range, which contains nothing, and so does a token whose
+ * claim is there in another shape (`entriesOfType`). A token with no entry of
+ * the type gets no range at all, and `DelegationRangeRuleCollector` then
+ * emits no rule for it.
+ */
+export declare class DelegationRangeCollector implements AttributeCollector {
+    private readonly type;
+    private readonly claim;
+    constructor(config: DelegationRangeCollectorConfig);
+    collect(context: CollectorContext): Promise<Attributes>;
+}
+//# sourceMappingURL=DelegationRangeCollector.d.mts.map

package/dist/collectors/DelegationRangeCollector.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DelegationRangeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/DelegationRangeCollector.mts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAUzC,2DAA2D;AAC3D,MAAM,WAAW,8BAA8B;IAC9C;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,YAAW,kBAAkB;IAClE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,EAAE,8BAA8B;IAS5C,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAK7D"}

package/dist/collectors/DelegationRangeCollector.mjs

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { DEFAULT_AUTHORIZATION_DETAILS_CLAIM, entriesOfType, rangePaths, resolveRangeType, } from "../delegation/range.mjs";
+import { ATTR_DELEGATION_RANGE } from "../keys.mjs";
+import { resolveClaimName } from "./_claims.mjs";
+/**
+ * Attribute collector that reads the paths of the token's
+ * `authorization_details` entries of the configured type into a `string[]`
+ * under `ATTR_DELEGATION_RANGE`. A path outside the grammar is left out,
+ * which narrows the range; a token with entries of the type but no readable
+ * path gets an empty range, which contains nothing, and so does a token whose
+ * claim is there in another shape (`entriesOfType`). A token with no entry of
+ * the type gets no range at all, and `DelegationRangeRuleCollector` then
+ * emits no rule for it.
+ */
+export class DelegationRangeCollector {
+    type;
+    claim;
+    constructor(config) {
+        this.type = resolveRangeType("DelegationRangeCollector", config?.type);
+        this.claim = resolveClaimName("DelegationRangeCollector", config?.claim, DEFAULT_AUTHORIZATION_DETAILS_CLAIM);
+    }
+    async collect(context) {
+        const entries = entriesOfType(context.subject[this.claim], this.type);
+        if (entries === null)
+            return new Map();
+        return new Map([[ATTR_DELEGATION_RANGE, rangePaths(entries)]]);
+    }
+}

package/dist/collectors/PayloadClaimAttributeCollector.d.mts

@@ -7,48 +7,33 @@ export type PayloadClaimAttributeType = AttributeMappingType;
 /** Config entry accepted by `PayloadClaimAttributeCollector`. */
 export type PayloadClaimAttributeCollectorConfig = AttributeMappingCollectorConfig;
 /**
- * Promotes declared claims of the verified subject into attributes (#219).
+ * Promotes declared claims of the verified subject into attributes. The
+ * builtins read `scope`, `sub` and `azp`; an external IdP puts what a rule
+ * needs elsewhere — Clerk's org role under `o.rol`, Auth0's roles under a
+ * namespaced `https://example.com/roles`, Okta's groups under `groups`. This
+ * is the declaration `RequestContextAttributeCollector` takes, pointed at
+ * `CollectorContext.subject` instead of the caller's body.
  *
- * The builtins read three claims — `scope`, `sub`, `azp` — and an external
- * IdP puts what a rule needs elsewhere: Clerk's org role under `o.rol`,
- * Auth0's roles under a namespaced `https://example.com/roles`, Okta's groups
- * under `groups`. Until now every one of those meant a bespoke collector,
- * even for the common case of "read this claim, check its type, write it
- * under this key". This is the same declaration `RequestContextAttributeCollector`
- * takes, pointed at `CollectorContext.subject` instead of the caller's body:
+ * The source is the subject the configured authenticator accepted — under the
+ * built-in one, a signature-verified token unless `oauth.jwt.mode` is
+ * `"insecure-decode"` — not the caller's `requestContext`, so a mapping may land
+ * on core's keys (`scopes`, `permissions`, `roles`, `userId`, `clientId`).
+ * Keys another package reserved stay refused: that package writes them with a
+ * collector of its own — cedar's `request*` from the parsed request, this
+ * package's `delegationRange` from the claim `DelegationRangeCollector`
+ * narrows — and a claim landing on one would be a second writer with a
+ * different meaning.
  *
- * ```hocon
- * { collector = "PayloadClaimAttributeCollector"
- *   attributes = [
- *     { from = "o.rol", to = "roles", type = "string[]" }
- *     { from = "https://example.com/roles", to = "roles", type = "string[]" }
- *     { from = "tid", to = "tenantId" }
- *   ] }
- * ```
+ * Two cautions the trust argument depends on. Map only claims the IdP
+ * populates from its own registration or admin data, never from user-editable
+ * profile metadata (Clerk's `unsafe_metadata`, Auth0's `user_metadata`) — a
+ * mapping from those hands the end user their own roles. And two collectors
+ * writing one list key union it, but a scalar key written by two collectors
+ * with different values throws `AttributeConflictError` and denies every
+ * request: do not map onto `userId` / `clientId` while
+ * `PayloadSubjectIdCollector` writes them.
  *
- * ## Core's vocabulary is a valid destination here
- *
- * `RequestContextAttributeCollector` refuses to write `scopes`, `permissions`,
- * `roles`, `userId` and `clientId`, because its source is the request body
- * and those keys are what the engine decides from. This collector's source is
- * the signature-verified token — the same trust `PayloadScopeCollector` writes
- * `scopes` from — so a verified claim may land on them: `permissions` from
- * Auth0's `permissions`, `roles` from Clerk's `o.rol`, `scopes` from Okta's
- * `scp`. Two collectors writing one list key **union** it; that is the
- * deployment composing two issuer-derived sources, and it says so in config.
- *
- * Keys another package reserved — cedar's `request*` — stay refused: those
- * are derived from the parsed request, not from the subject, and a claim
- * landing on one would be a second writer with a different meaning.
- *
- * Two cautions the trust argument depends on. A signed claim is only as
- * trustworthy as what the IdP put in it: map claims the IdP populates from
- * its own registration or admin data, never from user-editable profile
- * metadata (Clerk's `unsafe_metadata`, Auth0's `user_metadata`) — a mapping
- * from those hands the end user their own roles. And the union rule is for
- * lists: a *scalar* key written by two collectors with different values
- * throws `AttributeConflictError` and denies every request, so do not map
- * onto `userId` / `clientId` while `PayloadSubjectIdCollector` writes them.
+ * Configuration, with an example: the package README, PayloadClaimAttributeCollector.
  */
 export declare class PayloadClaimAttributeCollector implements AttributeCollector {
     private readonly mappings;

package/dist/collectors/PayloadClaimAttributeCollector.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"PayloadClaimAttributeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/PayloadClaimAttributeCollector.mts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACX,kBAAkB,EAElB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EAIzB,MAAM,yBAAyB,CAAC;AAEjC,yEAAyE;AACzE,MAAM,MAAM,4BAA4B,GAAG,gBAAgB,CAAC;AAC5D,wCAAwC;AACxC,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,CAAC;AAC7D,iEAAiE;AACjE,MAAM,MAAM,oCAAoC,GAAG,+BAA+B,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,8BAA+B,YAAW,kBAAkB;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,MAAM,EAAE,oCAAoC;IASlD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAK7D"}
+{"version":3,"file":"PayloadClaimAttributeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/PayloadClaimAttributeCollector.mts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACX,kBAAkB,EAElB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EAIzB,MAAM,yBAAyB,CAAC;AAEjC,yEAAyE;AACzE,MAAM,MAAM,4BAA4B,GAAG,gBAAgB,CAAC;AAC5D,wCAAwC;AACxC,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,CAAC;AAC7D,iEAAiE;AACjE,MAAM,MAAM,oCAAoC,GAAG,+BAA+B,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,8BAA+B,YAAW,kBAAkB;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,MAAM,EAAE,oCAAoC;IASlD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAK7D"}

package/dist/collectors/PayloadClaimAttributeCollector.mjs

@@ -3,48 +3,33 @@
 import { CORE_ATTRIBUTE_KEY_OWNER, suggestUnreservedAttributeKey, } from "@o3co/auth.policy-verifier.core";
 import { parseAttributeMappings, promoteMappings, } from "./_attributeMapping.mjs";
 /**
- * Promotes declared claims of the verified subject into attributes (#219).
+ * Promotes declared claims of the verified subject into attributes. The
+ * builtins read `scope`, `sub` and `azp`; an external IdP puts what a rule
+ * needs elsewhere — Clerk's org role under `o.rol`, Auth0's roles under a
+ * namespaced `https://example.com/roles`, Okta's groups under `groups`. This
+ * is the declaration `RequestContextAttributeCollector` takes, pointed at
+ * `CollectorContext.subject` instead of the caller's body.
  *
- * The builtins read three claims — `scope`, `sub`, `azp` — and an external
- * IdP puts what a rule needs elsewhere: Clerk's org role under `o.rol`,
- * Auth0's roles under a namespaced `https://example.com/roles`, Okta's groups
- * under `groups`. Until now every one of those meant a bespoke collector,
- * even for the common case of "read this claim, check its type, write it
- * under this key". This is the same declaration `RequestContextAttributeCollector`
- * takes, pointed at `CollectorContext.subject` instead of the caller's body:
+ * The source is the subject the configured authenticator accepted — under the
+ * built-in one, a signature-verified token unless `oauth.jwt.mode` is
+ * `"insecure-decode"` — not the caller's `requestContext`, so a mapping may land
+ * on core's keys (`scopes`, `permissions`, `roles`, `userId`, `clientId`).
+ * Keys another package reserved stay refused: that package writes them with a
+ * collector of its own — cedar's `request*` from the parsed request, this
+ * package's `delegationRange` from the claim `DelegationRangeCollector`
+ * narrows — and a claim landing on one would be a second writer with a
+ * different meaning.
  *
- * ```hocon
- * { collector = "PayloadClaimAttributeCollector"
- *   attributes = [
- *     { from = "o.rol", to = "roles", type = "string[]" }
- *     { from = "https://example.com/roles", to = "roles", type = "string[]" }
- *     { from = "tid", to = "tenantId" }
- *   ] }
- * ```
+ * Two cautions the trust argument depends on. Map only claims the IdP
+ * populates from its own registration or admin data, never from user-editable
+ * profile metadata (Clerk's `unsafe_metadata`, Auth0's `user_metadata`) — a
+ * mapping from those hands the end user their own roles. And two collectors
+ * writing one list key union it, but a scalar key written by two collectors
+ * with different values throws `AttributeConflictError` and denies every
+ * request: do not map onto `userId` / `clientId` while
+ * `PayloadSubjectIdCollector` writes them.
  *
- * ## Core's vocabulary is a valid destination here
- *
- * `RequestContextAttributeCollector` refuses to write `scopes`, `permissions`,
- * `roles`, `userId` and `clientId`, because its source is the request body
- * and those keys are what the engine decides from. This collector's source is
- * the signature-verified token — the same trust `PayloadScopeCollector` writes
- * `scopes` from — so a verified claim may land on them: `permissions` from
- * Auth0's `permissions`, `roles` from Clerk's `o.rol`, `scopes` from Okta's
- * `scp`. Two collectors writing one list key **union** it; that is the
- * deployment composing two issuer-derived sources, and it says so in config.
- *
- * Keys another package reserved — cedar's `request*` — stay refused: those
- * are derived from the parsed request, not from the subject, and a claim
- * landing on one would be a second writer with a different meaning.
- *
- * Two cautions the trust argument depends on. A signed claim is only as
- * trustworthy as what the IdP put in it: map claims the IdP populates from
- * its own registration or admin data, never from user-editable profile
- * metadata (Clerk's `unsafe_metadata`, Auth0's `user_metadata`) — a mapping
- * from those hands the end user their own roles. And the union rule is for
- * lists: a *scalar* key written by two collectors with different values
- * throws `AttributeConflictError` and denies every request, so do not map
- * onto `userId` / `clientId` while `PayloadSubjectIdCollector` writes them.
+ * Configuration, with an example: the package README, PayloadClaimAttributeCollector.
  */
 export class PayloadClaimAttributeCollector {
     mappings;
@@ -62,7 +47,7 @@ function refusal(index, reservation) {
     const { key, owner, reason } = reservation;
     return (`PayloadClaimAttributeCollector: attributes[${index}] maps onto the reserved attribute "${key}", ` +
         `which belongs to ${owner}${reason === undefined ? "" : ` — ${reason}`}. ` +
-        "That package derives the key from the request, not from the subject, so a verified claim " +
-        "landing on it would be a second writer with a different meaning. " +
+        "That package writes the key with a collector of its own, so a verified claim landing on it " +
+        "would be a second writer with a different meaning. " +
         `Promote the claim under a key of your own (for example "${suggestUnreservedAttributeKey(key)}").`);
 }

package/dist/collectors/PayloadScopeCollector.d.mts

@@ -2,7 +2,7 @@ import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/aut
 /** Config entry accepted by `PayloadScopeCollector`. */
 export interface PayloadScopeCollectorConfig {
     /**
-     * The claim the scopes are read from (#219). Defaults to `scope`, the
+     * The claim the scopes are read from. Defaults to `scope`, the
      * space-delimited OAuth claim; `scp` for Okta, `permissions` for Auth0,
      * both of which are arrays of strings. Either shape is read.
      */

package/dist/collectors/PayloadSubjectIdCollector.d.mts

@@ -4,7 +4,7 @@ import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/aut
  * the subject bag into `ATTR_USER_ID` and `ATTR_CLIENT_ID`. Either claim may
  * be absent.
  *
- * The claim vocabulary lives here, not in core (#170): `SubjectAttributes` is
+ * The claim vocabulary lives here, not in core: `SubjectAttributes` is
  * a bag of unknowns, so this collector narrows what it promotes — a claim that
  * is not a non-empty string is not an identity and is left out.
  */

package/dist/collectors/PayloadSubjectIdCollector.mjs

@@ -6,7 +6,7 @@ import { ATTR_CLIENT_ID, ATTR_USER_ID } from "@o3co/auth.policy-verifier.core";
  * the subject bag into `ATTR_USER_ID` and `ATTR_CLIENT_ID`. Either claim may
  * be absent.
  *
- * The claim vocabulary lives here, not in core (#170): `SubjectAttributes` is
+ * The claim vocabulary lives here, not in core: `SubjectAttributes` is
  * a bag of unknowns, so this collector narrows what it promotes — a claim that
  * is not a non-empty string is not an identity and is left out.
  */