@o3co/auth.policy-verifier.builtins 0.3.1 → 0.4.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 auth.policy-verifier 向けの組み込み attribute collector、rule collector、および resource parser です。
 
-**Runtime:** Node.js 22+。本パッケージは `ruleType` の安定ハッシュ用に `node:crypto` を利用します。browser / edge ランタイム対応は今後の課題として別 issue で追跡します。
+**Runtime:** `BigInt` と `Map.groupBy` をサポートするサーバー／エッジ JavaScript ランタイムが対象です — Node.js 22+（`engines.node` で宣言しており、古い Node ではインストール時にブロックされます）、Cloudflare Workers、Vercel Edge、Deno、Bun。ブラウザは設計上対象外です（認可判定はサーバー側で enforcement する必要があるため）。同梱の `server` パッケージは引き続き Node 専用です。
 
 ## インストール
 
@@ -16,16 +16,29 @@ npm install @o3co/auth.policy-verifier.builtins
 
 | 名前 | 読み取り元 | 出力 | コンストラクタ引数 |
 | --- | --- | --- | --- |
-| `PayloadScopeCollector` | `payload.scope`（スペース区切り文字列） | `ATTR_SCOPES: string[]` | なし |
-| `PayloadSubjectIdCollector` | `payload.sub`、`payload.azp` | `ATTR_USER_ID`、`ATTR_CLIENT_ID` | なし |
+| `PayloadScopeCollector` | `subject.scope`（スペース区切り文字列） | `ATTR_SCOPES: string[]` | なし |
+| `PayloadSubjectIdCollector` | `subject.sub`、`subject.azp` | `ATTR_USER_ID`、`ATTR_CLIENT_ID` | なし |
 | `StaticPermissionCollector` | — | `ATTR_PERMISSIONS: string[]` | `{ permissions: string[] }` |
 | `StaticRoleCollector` | — | `ATTR_ROLES: Role[]` | `{ roles: Role[] }` |
+| `RequestContextAttributeCollector` | `requestContext` の宣言済みフィールド | 運用者が決めたキー | `{ attributes: Mapping[] }` |
 
 `StaticPermissionCollector` と `StaticRoleCollector` は、リクエストのコンテキストに関わらず、コンストラクタに渡した値を常に出力します。
 
-### `requestContext` 向けの組み込みコレクターは提供しない
+### RequestContextAttributeCollector
 
-本エンジンは `CollectorContext.requestContext` をそのまま attribute に展開するコレクターを提供しません。`requestContext` の形は利用側プロジェクトの transport/interceptor が定めるため、その解釈はプロジェクト側の責務です。必要なフィールドごとに焦点を絞った `AttributeCollector` を実装し、その中で値の型・形状を検証し、プロジェクト固有の定数キーで格納してください。詳細と具体例は [AGENTS.md — Core Vocabulary Scope](../../AGENTS.md#core-vocabulary-scope) を参照してください。
+`CollectorContext.requestContext` の宣言済みフィールドを attribute に昇格させます:
+
+```hocon
+{ collector = "RequestContextAttributeCollector"
+  attributes = [
+    { from = "tenant.id", to = "tenantId" }     # dot path。`to` の既定値は `from`
+    { from = "groups", type = "string[]" }
+  ] }
+```
+
+各マッピングは `{ from: string; to?: string; type?: "string" | "number" | "boolean" | "string[]" }` で、`type` の既定は `"string"` です。マッピング定義が不正ならコンストラクタで throw しますが、*値* が使えない場合は throw しません — `requestContext` は呼び出し側が渡すリクエストデータなので、欠落・空文字・宣言した型に合わない値は単に昇格されません。
+
+この宣言が信頼境界です — [docs/extending.ja.md](../../docs/extending.ja.md#信頼境界-requestcontext-は呼び出し側のもの) が説明する境界の、既製の守り方がこのコレクターです。`requestContext` は自由形式かつ未検証なので、**宣言していないフィールドは attribute になりません**。dot path は own property のみを辿るため `constructor.name` のような指定は何も読みません。このコレクター自身は語彙を持ち込みません — フィールド名もキー名も運用者が決めるため、[AGENTS.md — Core Vocabulary Scope](../../AGENTS.md#core-vocabulary-scope) の方針を崩さずに実用的なものを提供できます。read-check-write を超える処理（値の導出、外部ストア参照など）が必要な場合は、同節が説明するプロジェクト側の `AttributeCollector` を書いてください。
 
 ## Rules
 
@@ -46,13 +59,15 @@ new HasPermission(permission: string)
 ### HasScope
 
 ```ts
-new HasScope(scope: string)
+new HasScope(scope: string, options?: { allowBareScopeRewrite?: boolean })
 ```
 
 - `ruleType`: `"scope"`、`code`: `"invalid_scope"`
 - `ATTR_SCOPES` を確認します。
-- `ATTR_SCOPES` 内のプレフィックスなし scope 文字列（例: `"resource"`）は、比較前に `"read:resource"` へ正規化されます。
-- 正規化後に大文字・小文字を区別しない完全一致で比較します。
+- 比較は**大文字・小文字を区別する完全一致**です。OAuth 2.0 の scope 値は大文字・小文字を区別する不透明な文字列であるため（[RFC 6749 §3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)）、`read:PROJECT` は `read:project` を満たしません。
+- `:` を 2 つ以上含む scope はそれ自体が 1 つの値であり、2 つ目の `:` 以降が切り捨てられることはありません。`read:project:restricted` は `read:project` を満たさず（意図的に絞り込まれた grant が広い方へ吸収されてはならない）、`read:project` も `read:project:restricted` を満たしません。
+- `allowBareScopeRewrite`（既定 `false`）を有効にすると、プレフィックスなしの scope `"resource"` を、そのままの値に加えて `"read:resource"` としても扱います。書き換え対象は `:` を **1 つも含まない** scope のみで、`"project:restricted"` は書き換えません（どのセグメントが action かは判別不能であり、推測は過剰付与になるため）。issuer がプレフィックスなしのリソース名を発行する場合以外は無効のままにしてください。
+- `ATTR_SCOPES` 内の文字列以外の要素は、一致もせず例外も投げません。
 
 ### AttrMatchRule
 
@@ -107,7 +122,7 @@ new AttrLiteralIn({ a: string, values: (string | number | boolean)[], group?: st
 ```
 
 - `code`: `"attr_not_in_set"`。
-- 既定の `ruleType`: `` `attr_literal_in:${a}:${type}:${count}:${hashPrefix}` `` — `count` は重複除去後の要素数、`hashPrefix` は重複除去かつソート済みの `values` を文字列化した内容に対する SHA-256 の先頭 8 桁。同じ `a` と内容上等価な `values`（順序・重複を無視）を持つ 2 つのインスタンスは同じ `ruleType` を持ち、評価器で OR 結合されます。
+- 既定の `ruleType`: `` `attr_literal_in:${a}:${type}:${count}:${hashPrefix}` `` — `count` は重複除去後の要素数、`hashPrefix` は重複除去かつソート済みの `values` を文字列化した内容に対する FNV-1a 64-bit ハッシュの 16 桁 16 進表記です。ハッシュは非暗号学的ですが、64-bit 幅により現実的な policy サイズで偶発的・意図的な衝突はいずれもほぼ起きません。`node:*` 依存はなく、対象とするサーバー／エッジランタイム（冒頭「Runtime」参照）でロードできます。同じ `a` と内容上等価な `values`（順序・重複を無視）を持つ 2 つのインスタンスは同じ `ruleType` を持ち、評価器で OR 結合されます。
 - `values` は非空かつ同種の配列（`string[]`、`number[]`、`boolean[]` のいずれか）でなければなりません。`attrs.get(a)` が集合に含まれるときに通過します。`values` 内の重複要素は Rule の挙動に影響しません（内部では `Set` として扱われます）。
 
 ### AttrLiteralNotIn
@@ -171,7 +186,14 @@ new AttrPairCompare({ a: string, op: "lt" | "le" | "gt" | "ge", b: string, group
 | `ResourceActionPermissionRuleCollector` | `"<resource.raw>.perm:<action>"` | `[HasPermission(...)]` |
 | `ResourceActionScopeRuleCollector` | `"<action>:<resource.resourceType>"` | `[HasScope(...)]` |
 
-どちらもコンストラクタ引数はありません。
+`ResourceActionPermissionRuleCollector` にコンストラクタ引数はありません。
+`ResourceActionScopeRuleCollector` は `{ scopeless?: "deny" | "skip", allowBareScopeRewrite?: boolean }` を受け取ります。
+
+- `scopeless`（既定 `"deny"`）: 既定ではリクエストごとに必ず `HasScope` ルールを生成するため、`scope` claim を持たない
+  トークンはこのルールに落ちます。`"skip"` は scopeless トークンに対してルールを生成しませんが、ルールが 1 つも集まらない
+  リクエストは deny されるため、別のルールグループが認可を担うパイプラインでのみ使ってください。
+- `allowBareScopeRewrite`（既定 `false`）: [`HasScope`](#hasscope) へそのまま渡されます。issuer が `{action}:{resourceType}`
+  形式（`read:project`）ではなくプレフィックスなしのリソース名（`project`）を発行する場合にのみ `true` にしてください。
 
 ## Resource Parser
 
@@ -183,13 +205,46 @@ new AttrPairCompare({ a: string, op: "lt" | "le" | "gt" | "ge", b: string, group
 new DotNotationResourceParser()
 ```
 
-入力形式: `"<type>[:<id>].<type>[:<id>]..."`
+文法:
+
+```text
+resource = segment *( "." segment )
+segment  = type [ ":" id ]
+type     = 1*tchar
+id       = 1*tchar
+tchar    = %x21 / %x23-2D / %x2F-39 / %x3B-5B / %x5D-7E
+           ; RFC 6749 NQCHAR から "." と ":" を除いたもの
+           ; すなわち、空白・`"`・`\`・`.`・`:` を除く印字可能 ASCII
+```
 
-例: `"foo.bar:123"` → `{ raw: "foo.bar:123", resourceType: "foo_bar", resourceId: "123" }`
+例: `"foo.bar:123"` → `{ raw: "foo.bar:123", resourceType: "foo.bar", resourceId: "123" }`
 
 - セグメントは `.` で分割されます。各セグメントには `:id` を含めることができます。
-- `resourceType` はセグメントの type を `_` で結合した文字列です。
+- `resourceType` はセグメントの type を `.` で結合した文字列です。区切り文字は書き換えず、そのまま保持されます。
 - `resourceId` は最後のセグメントの id です（存在する場合）。
+- `raw` は入力そのままです。
+
+文法に合わない入力は `ResourceParseError`（`@o3co/auth.policy-verifier.core`）を送出します。パーサーが入力を
+修復することはありません。サーバーはそのリクエストを decision ではなく `400 invalid_request` として返します。
+拒否される例:
+
+| 入力 | 理由 |
+| --- | --- |
+| `""`, `a..b`, `.a`, `a.` | 空セグメント — すべてのセグメントに type が必要 |
+| `a:`, `:1` | type または id が空 |
+| `a:1:2` | セグメント内に `:` が 2 個以上 — 末尾を切り捨てず拒否する |
+| `  a:1  `, `a : 1` | 空白 — trim せず拒否する |
+| `プロジェクト`, `a"b`, `a\b` | OAuth scope 値が持てない文字 |
+
+`resourceType` は認可の名前空間です。`ResourceActionScopeRuleCollector` はこれを
+`{action}:{resourceType}` scope に変換し、その scope が付与されていることを要求します。つまり同じ type に
+パースされる 2 つの異なるリソースは同一に認可されてしまうため、そうならないように文法を設計しています。
+`.` を区切り文字として予約することで、ネストした type `a.b` と `a_b` という名前のフラットな type が
+区別されます（以前はどちらも `a_b` でした）。これは [`HasScope`](#hasscope) が scope 値に対して適用しているのと
+同じ原則です — 書かれたものをそのまま比較し、意図を正規化して推測しない。
+
+`.` や `:`、あるいは許可集合外の文字を必要とする id は、呼び出し側でエンコードする（percent-encoding は
+この文法をそのまま通ります）か、その構文向けに書かれた `ResourceParser` で扱ってください。
 
 ## builtinCollectorsModule
 
@@ -205,7 +260,8 @@ import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
 | `attributeCollector` | `"PayloadSubjectIdCollector"` | `() => new PayloadSubjectIdCollector()` |
 | `attributeCollector` | `"StaticPermissionCollector"` | `(config) => new StaticPermissionCollector(config)` |
 | `attributeCollector` | `"StaticRoleCollector"` | `(config) => new StaticRoleCollector(config)` |
-| `ruleCollector` | `"ResourceActionScopeRuleCollector"` | `() => new ResourceActionScopeRuleCollector()` |
+| `attributeCollector` | `"RequestContextAttributeCollector"` | `(config) => new RequestContextAttributeCollector(config)` |
+| `ruleCollector` | `"ResourceActionScopeRuleCollector"` | `(config) => new ResourceActionScopeRuleCollector(config)` |
 | `ruleCollector` | `"ResourceActionPermissionRuleCollector"` | `() => new ResourceActionPermissionRuleCollector()` |
 | `resourceParser` | `"DotNotationResourceParser"` | `() => new DotNotationResourceParser()` |
 

package/README.md

@@ -2,7 +2,7 @@
 
 Built-in attribute collectors, rule collectors, and resource parser for auth.policy-verifier.
 
-**Runtime:** Node.js 22+. This package uses `node:crypto` for stable rule-type hashing; browser / edge runtime support is tracked as future work.
+**Runtime:** Server- and edge-side JavaScript runtimes that support `BigInt` and `Map.groupBy` — Node.js 22+ (declared via `engines.node` so older Node installs are blocked at install time), Cloudflare Workers, Vercel Edge, Deno, Bun. Browsers are out of scope by design: authorization decisions must be enforced server-side. The `server` companion package remains Node-only.
 
 ## Install
 
@@ -16,16 +16,29 @@ All collectors implement `AttributeCollector`.
 
 | Name | Reads from | Emits | Constructor args |
 | --- | --- | --- | --- |
-| `PayloadScopeCollector` | `payload.scope` (space-separated string) | `ATTR_SCOPES: string[]` | none |
-| `PayloadSubjectIdCollector` | `payload.sub`, `payload.azp` | `ATTR_USER_ID`, `ATTR_CLIENT_ID` | none |
+| `PayloadScopeCollector` | `subject.scope` (space-separated string) | `ATTR_SCOPES: string[]` | none |
+| `PayloadSubjectIdCollector` | `subject.sub`, `subject.azp` | `ATTR_USER_ID`, `ATTR_CLIENT_ID` | none |
 | `StaticPermissionCollector` | — | `ATTR_PERMISSIONS: string[]` | `{ permissions: string[] }` |
 | `StaticRoleCollector` | — | `ATTR_ROLES: Role[]` | `{ roles: Role[] }` |
+| `RequestContextAttributeCollector` | declared fields of `requestContext` | the operator's own keys | `{ attributes: Mapping[] }` |
 
 `StaticPermissionCollector` and `StaticRoleCollector` always emit the values supplied at construction time, regardless of request context.
 
-### No built-in collector for `requestContext`
+### RequestContextAttributeCollector
 
-The engine does not ship a collector that expands `CollectorContext.requestContext` into attributes. The shape of `requestContext` is defined by each consuming project's transport/interceptor, so interpreting it is a project concern. Write a focused `AttributeCollector` for each field you need to promote — validate its shape there, and store it under a project-specific constant key. See [AGENTS.md — Core Vocabulary Scope](../../AGENTS.md#core-vocabulary-scope) for the rationale and a worked example.
+Promotes declared fields of `CollectorContext.requestContext` into attributes:
+
+```hocon
+{ collector = "RequestContextAttributeCollector"
+  attributes = [
+    { from = "tenant.id", to = "tenantId" }     # dot path; `to` defaults to `from`
+    { from = "groups", type = "string[]" }
+  ] }
+```
+
+Each mapping is `{ from: string; to?: string; type?: "string" | "number" | "boolean" | "string[]" }`, `type` defaulting to `"string"`. A malformed mapping throws at construction; an unusable *value* does not — `requestContext` is caller-supplied request data, so a field that is missing, empty, or not of its declared type is simply not promoted.
+
+The declaration is the trust boundary — this collector is the ready-made way to stay on the right side of the one described in [docs/extending.md](../../docs/extending.md#the-trust-boundary-requestcontext-is-the-callers). `requestContext` is free-form and unvalidated, so **nothing undeclared becomes an attribute** and a configured dot path traverses own properties only (`constructor.name` reads nothing). This collector invents no vocabulary of its own: the operator names both the fields and the keys, which is what keeps [AGENTS.md — Core Vocabulary Scope](../../AGENTS.md#core-vocabulary-scope) intact while still shipping something usable. For anything beyond read-check-write — deriving a value, calling out to a store — write a focused project-side `AttributeCollector` as that section describes.
 
 ## Rules
 
@@ -37,22 +50,26 @@ new HasPermission(permission: string)
 
 - `ruleType`: `"permission"`, `code`: `"no_permission"`
 - Checks `ATTR_PERMISSIONS` (direct) and `ATTR_ROLES[].permissions` (via roles).
-- Wildcard matching (case-insensitive):
+- Matching is **exact and case-sensitive** — the same discipline `HasScope` applies to scopes and `DotNotationResourceParser` applies to resources: compare what was written, never a normalized guess at what was meant. The parser preserves case, so `Project:1.perm:read` and `project:1.perm:read` are different permissions, exactly as `Project:1` and `project:1` are different resources to a scope rule.
+- Wildcards in a **granted** permission are honoured — written match structure, not normalization; the literal halves around the `*` still compare exactly:
   - `"*"` matches any permission.
   - `"foo*"` matches any permission with prefix `foo`.
   - `"*bar"` matches any permission with suffix `bar`.
   - `"foo*bar"` matches any permission starting with `foo` and ending with `bar`.
+  - More than one `*` in a granted permission never matches (rejecting beats silently over-granting).
 
 ### HasScope
 
 ```ts
-new HasScope(scope: string)
+new HasScope(scope: string, options?: { allowBareScopeRewrite?: boolean })
 ```
 
 - `ruleType`: `"scope"`, `code`: `"invalid_scope"`
 - Checks `ATTR_SCOPES`.
-- A bare scope string `"resource"` in `ATTR_SCOPES` is normalized to `"read:resource"` before comparison.
-- Matching is case-insensitive exact match after normalization.
+- Matching is **exact and case-sensitive**. OAuth 2.0 scope values are case-sensitive opaque strings ([RFC 6749 §3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)), so `read:PROJECT` does not satisfy `read:project`.
+- A scope containing more than one `:` is a value in its own right — nothing is split off at the second `:`. `read:project:restricted` does not satisfy `read:project` (a deliberately narrowed grant must not collapse into the broader one), and `read:project` does not satisfy `read:project:restricted`.
+- `allowBareScopeRewrite` (default `false`) opts in to treating a bare granted scope `"resource"` as `"read:resource"` as well as literally. Only a scope with **no** `:` is ever rewritten; `"project:restricted"` is left alone, because which segment is the action is unknowable and guessing over-grants. Leave it off unless your issuer emits bare resource names.
+- Non-string entries in `ATTR_SCOPES` never match and never throw.
 
 ### AttrMatchRule
 
@@ -107,7 +124,7 @@ new AttrLiteralIn({ a: string, values: (string | number | boolean)[], group?: st
 ```
 
 - `code`: `"attr_not_in_set"`.
-- Default `ruleType`: `` `attr_literal_in:${a}:${type}:${count}:${hashPrefix}` `` — where `count` is the post-deduplication element count and `hashPrefix` is the first 8 hex characters of a SHA-256 over the deduplicated, sorted, stringified values. Two instances with the same `a` and logically equivalent `values` (duplicates and order do not matter) share the same `ruleType` and are OR-combined by the evaluator.
+- Default `ruleType`: `` `attr_literal_in:${a}:${type}:${count}:${hashPrefix}` `` — where `count` is the post-deduplication element count and `hashPrefix` is a 16-hex-character FNV-1a 64-bit hash over the deduplicated, sorted, stringified values. The hash is non-cryptographic but the 64-bit width makes accidental and adversarial collisions vanishingly unlikely for any realistic policy size; the package has no `node:*` dependency and loads in any supported server/edge runtime (see "Runtime" above). Two instances with the same `a` and logically equivalent `values` (duplicates and order do not matter) share the same `ruleType` and are OR-combined by the evaluator.
 - `values` must be a non-empty, homogeneous array (`string[]`, `number[]`, or `boolean[]`). Passes when `attrs.get(a)` is in the set. Duplicate elements in `values` are ignored (the rule uses `Set` semantics internally).
 
 ### AttrLiteralNotIn
@@ -171,7 +188,14 @@ All attribute comparison rules follow the same grouping semantics described for
 | `ResourceActionPermissionRuleCollector` | `"<resource.raw>.perm:<action>"` | `[HasPermission(...)]` |
 | `ResourceActionScopeRuleCollector` | `"<action>:<resource.resourceType>"` | `[HasScope(...)]` |
 
-Both collectors take no constructor arguments.
+`ResourceActionPermissionRuleCollector` takes no constructor arguments.
+`ResourceActionScopeRuleCollector` accepts `{ scopeless?: "deny" | "skip", allowBareScopeRewrite?: boolean }`.
+
+- `scopeless` (default `"deny"`): it emits the `HasScope` rule for every request, so a token carrying no `scope`
+  claim 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.
+- `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`).
 
 ## Resource Parser
 
@@ -183,13 +207,48 @@ Parses a dot-notation string into a `Resource`.
 new DotNotationResourceParser()
 ```
 
-Input format: `"<type>[:<id>].<type>[:<id>]..."`
+Grammar:
+
+```text
+resource = segment *( "." segment )
+segment  = type [ ":" id ]
+type     = 1*tchar
+id       = 1*tchar
+tchar    = %x21 / %x23-2D / %x2F-39 / %x3B-5B / %x5D-7E
+           ; RFC 6749 NQCHAR less "." and ":"
+           ; i.e. printable ASCII except space, `"`, `\`, `.` and `:`
+```
 
-Example: `"foo.bar:123"` → `{ raw: "foo.bar:123", resourceType: "foo_bar", resourceId: "123" }`
+Example: `"foo.bar:123"` → `{ raw: "foo.bar:123", resourceType: "foo.bar", resourceId: "123" }`
 
 - Segments are split by `.`. Each segment may include `:id`.
-- `resourceType` is the segment types joined with `_`.
+- `resourceType` is the segment types joined with `.` — the separator is preserved, not rewritten.
 - `resourceId` is the id of the last segment, if present.
+- `raw` is the input verbatim.
+
+Anything the grammar does not accept raises `ResourceParseError`
+(from `@o3co/auth.policy-verifier.core`); the parser never repairs its input. The server answers
+such a request `400 invalid_request`, not a decision. Refused, among others:
+
+| Input | Why |
+| --- | --- |
+| `""`, `a..b`, `.a`, `a.` | an empty segment — every segment needs a type |
+| `a:`, `:1` | an empty type or id |
+| `a:1:2` | more than one `:` in a segment — the tail is refused, not truncated away |
+| `  a:1  `, `a : 1` | whitespace — it is refused, not trimmed |
+| `プロジェクト`, `a"b`, `a\b` | a character no OAuth scope value may carry |
+
+`resourceType` is the authorization namespace: `ResourceActionScopeRuleCollector` turns it into the
+`{action}:{resourceType}` scope that must be granted. Two distinct resources that parse to the same
+type are therefore authorized identically, so the grammar is built to make that impossible —
+`.` is reserved as the separator, which keeps the nested type `a.b` distinct from the flat type
+literally named `a_b` (both were `a_b` before). This is the same principle
+[`HasScope`](#hasscope) applies to scope values: compare what was written, never a normalized guess
+at what was meant.
+
+An id that needs `.`, `:` or a character outside the set must be encoded by the caller
+(percent-encoding round-trips through this grammar) or handled by a `ResourceParser` written for
+that syntax.
 
 ## builtinCollectorsModule
 
@@ -205,7 +264,8 @@ import { builtinCollectorsModule } from "@o3co/auth.policy-verifier.builtins";
 | `attributeCollector` | `"PayloadSubjectIdCollector"` | `() => new PayloadSubjectIdCollector()` |
 | `attributeCollector` | `"StaticPermissionCollector"` | `(config) => new StaticPermissionCollector(config)` |
 | `attributeCollector` | `"StaticRoleCollector"` | `(config) => new StaticRoleCollector(config)` |
-| `ruleCollector` | `"ResourceActionScopeRuleCollector"` | `() => new ResourceActionScopeRuleCollector()` |
+| `attributeCollector` | `"RequestContextAttributeCollector"` | `(config) => new RequestContextAttributeCollector(config)` |
+| `ruleCollector` | `"ResourceActionScopeRuleCollector"` | `(config) => new ResourceActionScopeRuleCollector(config)` |
 | `ruleCollector` | `"ResourceActionPermissionRuleCollector"` | `() => new ResourceActionPermissionRuleCollector()` |
 | `resourceParser` | `"DotNotationResourceParser"` | `() => new DotNotationResourceParser()` |
 

package/dist/collectors/PayloadScopeCollector.d.mts

@@ -1,4 +1,9 @@
 import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that splits the OAuth2 `scope` claim (space-delimited)
+ * into a `string[]` and exposes it under `ATTR_SCOPES`. Missing or non-string
+ * `scope` yields an empty array.
+ */
 export declare class PayloadScopeCollector implements AttributeCollector {
     collect(context: CollectorContext): Promise<Attributes>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"PayloadScopeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/PayloadScopeCollector.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC,qBAAa,qBAAsB,YAAW,kBAAkB;IACzD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAK7D"}
+{"version":3,"file":"PayloadScopeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/PayloadScopeCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IACzD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAK7D"}

package/dist/collectors/PayloadScopeCollector.mjs

@@ -1,7 +1,14 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { ATTR_SCOPES } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that splits the OAuth2 `scope` claim (space-delimited)
+ * into a `string[]` and exposes it under `ATTR_SCOPES`. Missing or non-string
+ * `scope` yields an empty array.
+ */
 export class PayloadScopeCollector {
     async collect(context) {
-        const scope = context.payload.scope;
+        const scope = context.subject.scope;
         const scopes = typeof scope === "string" && scope ? scope.split(" ").filter(Boolean) : [];
         return new Map([[ATTR_SCOPES, scopes]]);
     }

package/dist/collectors/PayloadSubjectIdCollector.d.mts

@@ -1,4 +1,13 @@
 import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that extracts the OAuth/OIDC `sub` and `azp` claims from
+ * 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
+ * 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.
+ */
 export declare class PayloadSubjectIdCollector implements AttributeCollector {
     collect(context: CollectorContext): Promise<Attributes>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"PayloadSubjectIdCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/PayloadSubjectIdCollector.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC,qBAAa,yBAA0B,YAAW,kBAAkB;IAC7D,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAU7D"}
+{"version":3,"file":"PayloadSubjectIdCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/PayloadSubjectIdCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IAC7D,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAW7D"}

package/dist/collectors/PayloadSubjectIdCollector.mjs

@@ -1,12 +1,24 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { ATTR_CLIENT_ID, ATTR_USER_ID } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that extracts the OAuth/OIDC `sub` and `azp` claims from
+ * 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
+ * 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.
+ */
 export class PayloadSubjectIdCollector {
     async collect(context) {
         const attrs = new Map();
-        if (context.payload.sub) {
-            attrs.set(ATTR_USER_ID, context.payload.sub);
+        const { sub, azp } = context.subject;
+        if (typeof sub === "string" && sub) {
+            attrs.set(ATTR_USER_ID, sub);
         }
-        if (context.payload.azp) {
-            attrs.set(ATTR_CLIENT_ID, context.payload.azp);
+        if (typeof azp === "string" && azp) {
+            attrs.set(ATTR_CLIENT_ID, azp);
         }
         return attrs;
     }

package/dist/collectors/RequestContextAttributeCollector.d.mts

@@ -0,0 +1,47 @@
+import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/auth.policy-verifier.core";
+/** Types a `requestContext` field may be promoted as. */
+export type RequestContextAttributeType = "string" | "number" | "boolean" | "string[]";
+/** One field this collector promotes out of `requestContext`. */
+export interface RequestContextAttributeMapping {
+    /** Field to read, as a dot path (`"tenant.id"`) into `requestContext`. */
+    from: string;
+    /** Attribute key to write. Defaults to `from`. */
+    to?: string;
+    /** Expected type; a value of any other shape is not promoted. Defaults to `"string"`. */
+    type?: RequestContextAttributeType;
+}
+/** Config entry accepted by `RequestContextAttributeCollector`. */
+export interface RequestContextAttributeCollectorConfig {
+    /** The fields to promote. Must declare at least one. */
+    attributes: RequestContextAttributeMapping[];
+}
+/**
+ * Promotes declared fields of `CollectorContext.requestContext` into attributes.
+ *
+ * `requestContext` is the free-form container the transport fills in, and until
+ * now nothing built-in consumed it: any environment or relationship attribute
+ * meant writing a bespoke collector, even for the common case of "read this
+ * field, check its type, write it under this key".
+ *
+ * Core deliberately assumes no shape for `requestContext` and keeps its `ATTR_*`
+ * vocabulary to OAuth/OIDC/RBAC standards, so this collector invents no
+ * vocabulary either: the operator declares which fields to read and what to call
+ * them, and nothing undeclared is promoted. That declaration is also the trust
+ * boundary — `requestContext` is caller-supplied and unvalidated, so a field the
+ * config did not name cannot reach a rule, and one whose value does not match
+ * its declared type is dropped rather than passed along.
+ *
+ * ```hocon
+ * { collector = "RequestContextAttributeCollector"
+ *   attributes = [
+ *     { from = "tenant.id", to = "tenantId" }
+ *     { from = "groups", type = "string[]" }
+ *   ] }
+ * ```
+ */
+export declare class RequestContextAttributeCollector implements AttributeCollector {
+    private readonly mappings;
+    constructor(config: RequestContextAttributeCollectorConfig);
+    collect(context: CollectorContext): Promise<Attributes>;
+}
+//# sourceMappingURL=RequestContextAttributeCollector.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RequestContextAttributeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/RequestContextAttributeCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC,yDAAyD;AACzD,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AASvF,iEAAiE;AACjE,MAAM,WAAW,8BAA8B;IAC9C,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,IAAI,CAAC,EAAE,2BAA2B,CAAC;CACnC;AAED,mEAAmE;AACnE,MAAM,WAAW,sCAAsC;IACtD,wDAAwD;IACxD,UAAU,EAAE,8BAA8B,EAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,gCAAiC,YAAW,kBAAkB;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;gBAE1D,MAAM,EAAE,sCAAsC;IA4BpD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAgB7D"}

package/dist/collectors/RequestContextAttributeCollector.mjs

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readUntrustedRequestContext } from "@o3co/auth.policy-verifier.core";
+const ATTRIBUTE_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "string[]",
+];
+/**
+ * Promotes declared fields of `CollectorContext.requestContext` into attributes.
+ *
+ * `requestContext` is the free-form container the transport fills in, and until
+ * now nothing built-in consumed it: any environment or relationship attribute
+ * meant writing a bespoke collector, even for the common case of "read this
+ * field, check its type, write it under this key".
+ *
+ * Core deliberately assumes no shape for `requestContext` and keeps its `ATTR_*`
+ * vocabulary to OAuth/OIDC/RBAC standards, so this collector invents no
+ * vocabulary either: the operator declares which fields to read and what to call
+ * them, and nothing undeclared is promoted. That declaration is also the trust
+ * boundary — `requestContext` is caller-supplied and unvalidated, so a field the
+ * config did not name cannot reach a rule, and one whose value does not match
+ * its declared type is dropped rather than passed along.
+ *
+ * ```hocon
+ * { collector = "RequestContextAttributeCollector"
+ *   attributes = [
+ *     { from = "tenant.id", to = "tenantId" }
+ *     { from = "groups", type = "string[]" }
+ *   ] }
+ * ```
+ */
+export class RequestContextAttributeCollector {
+    mappings;
+    constructor(config) {
+        const attributes = config?.attributes;
+        if (!Array.isArray(attributes) || attributes.length === 0) {
+            throw new Error("RequestContextAttributeCollector: attributes must be a non-empty array of mappings");
+        }
+        this.mappings = attributes.map((mapping, index) => {
+            const { from, to, type = "string" } = mapping ?? {};
+            if (typeof from !== "string" || from === "") {
+                throw new Error(`RequestContextAttributeCollector: attributes[${index}].from must be a non-empty string`);
+            }
+            if (to !== undefined && (typeof to !== "string" || to === "")) {
+                throw new Error(`RequestContextAttributeCollector: attributes[${index}].to must be a non-empty string`);
+            }
+            if (!ATTRIBUTE_TYPES.includes(type)) {
+                throw new Error(`RequestContextAttributeCollector: attributes[${index}].type must be one of ${ATTRIBUTE_TYPES.join(", ")}, got "${type}"`);
+            }
+            return { from, to: to ?? from, type };
+        });
+    }
+    async collect(context) {
+        const attrs = new Map();
+        // The unwrap is the acknowledgement `UntrustedRequestContext` asks for:
+        // everything below this line is the caller's own data, which is why the
+        // mapping list — not the request — decides what becomes an attribute.
+        const requestContext = readUntrustedRequestContext(context.requestContext);
+        if (requestContext === undefined)
+            return attrs;
+        for (const mapping of this.mappings) {
+            const raw = readPath(requestContext, mapping.from);
+            if (matchesType(raw, mapping.type)) {
+                attrs.set(mapping.to, Array.isArray(raw) ? [...raw] : raw);
+            }
+        }
+        return attrs;
+    }
+}
+/**
+ * Reads a dot path, traversing own properties only. `requestContext` is
+ * caller-supplied, so inherited members (`constructor`, `toString`, …) must not
+ * be reachable through a configured path.
+ */
+function readPath(root, path) {
+    let current = root;
+    for (const segment of path.split(".")) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        if (!Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/** Whether `value` is usable as the declared type. Empty strings count as absent. */
+function matchesType(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string" && value !== "";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "string[]":
+            return Array.isArray(value) && value.every((item) => typeof item === "string" && item !== "");
+    }
+}

package/dist/collectors/StaticPermissionCollector.d.mts

@@ -1,4 +1,9 @@
 import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that returns a configured constant permission list under
+ * `ATTR_PERMISSIONS`, independent of the JWT payload. Useful for
+ * environments where permissions are static per deployment.
+ */
 export declare class StaticPermissionCollector implements AttributeCollector {
     private permissions;
     constructor(config: {

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

@@ -1 +1 @@
-{"version":3,"file":"StaticPermissionCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/StaticPermissionCollector.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC,qBAAa,yBAA0B,YAAW,kBAAkB;IACnE,OAAO,CAAC,WAAW,CAAW;gBAElB,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE;IAIvC,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAG9D"}
+{"version":3,"file":"StaticPermissionCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/StaticPermissionCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACnE,OAAO,CAAC,WAAW,CAAW;gBAElB,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE;IAIvC,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAG9D"}

package/dist/collectors/StaticPermissionCollector.mjs

@@ -1,4 +1,11 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { ATTR_PERMISSIONS } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that returns a configured constant permission list under
+ * `ATTR_PERMISSIONS`, independent of the JWT payload. Useful for
+ * environments where permissions are static per deployment.
+ */
 export class StaticPermissionCollector {
     permissions;
     constructor(config) {

package/dist/collectors/StaticRoleCollector.d.mts

@@ -1,4 +1,9 @@
 import type { AttributeCollector, Attributes, CollectorContext, Role } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that returns a configured constant role list under
+ * `ATTR_ROLES`, independent of the JWT payload. Each role bundles a name and
+ * the permissions it implies.
+ */
 export declare class StaticRoleCollector implements AttributeCollector {
     private roles;
     constructor(config: {

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

@@ -1 +1 @@
-{"version":3,"file":"StaticRoleCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/StaticRoleCollector.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,IAAI,EACJ,MAAM,iCAAiC,CAAC;AAGzC,qBAAa,mBAAoB,YAAW,kBAAkB;IAC7D,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE;IAI/B,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAG9D"}
+{"version":3,"file":"StaticRoleCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/StaticRoleCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,IAAI,EACJ,MAAM,iCAAiC,CAAC;AAGzC;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC7D,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE;IAI/B,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAG9D"}

package/dist/collectors/StaticRoleCollector.mjs

@@ -1,4 +1,11 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { ATTR_ROLES } from "@o3co/auth.policy-verifier.core";
+/**
+ * Attribute collector that returns a configured constant role list under
+ * `ATTR_ROLES`, independent of the JWT payload. Each role bundles a name and
+ * the permissions it implies.
+ */
 export class StaticRoleCollector {
     roles;
     constructor(config) {

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 export { PayloadScopeCollector } from "./collectors/PayloadScopeCollector.mjs";
 export { PayloadSubjectIdCollector } from "./collectors/PayloadSubjectIdCollector.mjs";
+export { RequestContextAttributeCollector, type RequestContextAttributeCollectorConfig, type RequestContextAttributeMapping, type RequestContextAttributeType, } from "./collectors/RequestContextAttributeCollector.mjs";
 export { StaticPermissionCollector } from "./collectors/StaticPermissionCollector.mjs";
 export { StaticRoleCollector } from "./collectors/StaticRoleCollector.mjs";
 export { builtinCollectorsModule } from "./module.mjs";
@@ -14,7 +15,7 @@ export { AttrPairCompare, type AttrPairCompareConfig } from "./rules/AttrPairCom
 export { AttrPairEqual, type AttrPairEqualConfig } from "./rules/AttrPairEqual.mjs";
 export { AttrPairNotEqual, type AttrPairNotEqualConfig } from "./rules/AttrPairNotEqual.mjs";
 export { ResourceActionPermissionRuleCollector } from "./rules/collectors/ResourceActionPermissionRuleCollector.mjs";
-export { ResourceActionScopeRuleCollector } from "./rules/collectors/ResourceActionScopeRuleCollector.mjs";
+export { ResourceActionScopeRuleCollector, type ResourceActionScopeRuleCollectorConfig, type ScopelessPolicy, } from "./rules/collectors/ResourceActionScopeRuleCollector.mjs";
 export { HasPermission } from "./rules/HasPermission.mjs";
-export { HasScope } from "./rules/HasScope.mjs";
+export { HasScope, type HasScopeOptions } from "./rules/HasScope.mjs";
 //# sourceMappingURL=index.d.mts.map