@o3co/auth.policy-verifier.builtins 0.7.0 → 0.8.1

package/README.ja.md

@@ -40,6 +40,31 @@ npm install @o3co/auth.policy-verifier.builtins
 
 この宣言が信頼境界です — [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` を書いてください。
 
+#### 予約済みの語彙は書き込み先にできません
+
+マッピングの `to` に**予約済み属性キー**を指定することはできません。指定した場合は**構成エラーとしてコンストラクタで拒否**されるため、そう書いたデプロイは最初のリクエストではなく起動時に失敗します:
+
+```hocon
+# 起動時に拒否される — core 自身の語彙
+{ from = "groups", to = "scopes" }
+
+# 起動時に拒否される — @o3co/auth.policy-verifier.cedar の語彙。
+# 同パッケージがロードされた時点で予約される
+{ from = "rid", to = "requestResourceId" }
+
+# 問題なし — フィールド名は自由。予約されているのは attribute キーだけ
+{ from = "groups", to = "requestGroups", type = "string[]" }
+{ 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 が効くのはこのためです。拒否メッセージは所有パッケージ名を示し、それ自体が予約されていない代替名を提案します。
+
+`context` は呼び出し側のもので、これらのキーはデプロイ側のものです。既定のサーバーでは `scopes` / `userId` / `clientId` は**署名検証済みトークン**から読まれ、`permissions` / `roles` は builtin の Rule が判断に使う権限を、cedar の 4 キーはパース済みリクエストを運びます。信頼レベルがまったく異なり、リクエストボディがそれらと同じバケツに合流してはなりません。
+
+ドキュメントで注意喚起するのではなく拒否する価値があるのはマージの挙動ゆえです。`AttributePipeline` はコレクター間で配列値の attribute を**union** します。したがって `scopes` へのマッピングは `PayloadScopeCollector` の出力を上書きして競合するのではなく、*追加*します。`context.groups = ["admin:write"]` を送った呼び出し側は、トークンが一度も持たなかった scope で認可され、判定・ログ・メトリクスのいずれにも issuer が付与した場合との区別は現れません。`AttributePipeline` の merge の doc コメントを参照してください。
+
+スカラーキーなら安全というわけでもなく、理由は 2 つあります。双方が書けば値が食い違い、`AttributeConflictError` でそのリクエストは拒否されます — fail-closed ではありますが、起動時の拒否ではなく予告のない拒否です。そして所有側のコレクターが*条件付きでしか*書かないキーには、そもそも競合相手がいません。cedar の `RequestFactsCollector` は `"document"` のような id を持たないリソースでは `requestResourceId` を書かないため、`{ from = "rid", to = "requestResourceId" }` は誰とも競合せずに着地し、Cedar の resource エンティティが呼び出し側のリクエストボディから組み立てられてしまいます。
+
 ## Rules
 
 ### HasPermission

package/README.md

@@ -40,6 +40,31 @@ Each mapping is `{ from: string; to?: string; type?: "string" | "number" | "bool
 
 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.
 
+#### Reserved vocabulary is not a valid destination
+
+A mapping's `to` may not name a **reserved attribute key**. Naming one is a **configuration error, refused at construction**, so a deployment that writes it fails at boot rather than on the first request:
+
+```hocon
+# refused at boot — core's own vocabulary
+{ from = "groups", to = "scopes" }
+
+# refused at boot — @o3co/auth.policy-verifier.cedar's vocabulary,
+# reserved as soon as that package is loaded
+{ from = "rid", to = "requestResourceId" }
+
+# fine — the field may be called anything; only the attribute key is reserved
+{ from = "groups", to = "requestGroups", type = "string[]" }
+{ 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.
+
+`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.
+
+What makes it worth refusing rather than documenting is the merge: `AttributePipeline` **unions** array-valued attributes across collectors. A mapping onto `scopes` therefore does not overwrite what `PayloadScopeCollector` produced and lose an argument with it — it *extends* it. A caller sending `context.groups = ["admin:write"]` would be authorized for a scope its token never carried, and nothing in the decision, the logs or the metrics would tell that apart from an issuer that granted it. See `AttributePipeline`'s merge doc comment.
+
+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.
+
 ## Rules
 
 ### HasPermission

package/dist/collectors/RequestContextAttributeCollector.d.mts

@@ -5,7 +5,13 @@ export type RequestContextAttributeType = "string" | "number" | "boolean" | "str
 export interface RequestContextAttributeMapping {
     /** Field to read, as a dot path (`"tenant.id"`) into `requestContext`. */
     from: string;
-    /** Attribute key to write. Defaults to `from`. */
+    /**
+     * Attribute key to write. Defaults to `from`.
+     *
+     * May not name a reserved key — core's five, plus whatever the packages a
+     * composition loaded reserved for themselves. See the class doc comment for
+     * why the caller's body may not land on vocabulary a deployment writes.
+     */
     to?: string;
     /** Expected type; a value of any other shape is not promoted. Defaults to `"string"`. */
     type?: RequestContextAttributeType;
@@ -31,6 +37,48 @@ export interface RequestContextAttributeCollectorConfig {
  * config did not name cannot reach a rule, and one whose value does not match
  * its declared type is dropped rather than passed along.
  *
+ * ## Reserved vocabulary is not a valid destination
+ *
+ * A mapping's `to` may not name a key any package has reserved. Core reserves
+ * five — `scopes`, `permissions`, `roles`, `userId`, `clientId` — and every
+ * package that owns attribute vocabulary reserves its own at module load:
+ * `packages/cedar` reserves `requestAction`, `requestResourceType`,
+ * `requestResourceId` and `requestResourceRaw`. The check is a lookup in core's
+ * registry, not a list this collector or core keeps by hand, so a package core
+ * cannot see is covered by importing it — which a composition naming that
+ * package's collectors has already done.
+ *
+ * Those keys are what the engine decides from, and under the default server
+ * `scopes` / `userId` / `clientId` are read out of the signature-verified
+ * token; `requestContext` is the request body, which anyone holding a valid
+ * token fills in as they like. The two carry different trust and must not share
+ * a bucket.
+ *
+ * The reason it is refused outright rather than left to the operator is what
+ * `AttributePipeline` does with two collectors writing one key: array-valued
+ * entries **union**. So `{ from = "groups", to = "scopes" }` does not replace
+ * the token's scopes and lose an argument with `PayloadScopeCollector` — it
+ * quietly *adds to* them, and the request that arrives with
+ * `context.groups = ["admin:write"]` is authorized for a scope its token never
+ * carried. Nothing in the decision, the logs or the metrics distinguishes that
+ * from an issuer that granted it.
+ *
+ * A scalar key is not safe either, in two different ways. Two writers that
+ * disagree throw `AttributeConflictError`, which denies — fail-closed, but an
+ * unannounced outage rather than a refusal. 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 out of the
+ * caller's own request body.
+ *
+ * This is reachable only through operator configuration, which is why it is a
+ * configuration error rather than a vulnerability. It is refused at
+ * construction — boot, not first request — so a deployment that wrote it never
+ * serves a decision. Every other destination keeps working: the *field* may be
+ * called anything (`{ from = "scopes", to = "requestedScopes" }` is fine), only
+ * the attribute key is reserved.
+ *
  * ```hocon
  * { collector = "RequestContextAttributeCollector"
  *   attributes = [

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

@@ -1 +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"}
+{"version":3,"file":"RequestContextAttributeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/RequestContextAttributeCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAElB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAQzC,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;;;;;;OAMG;IACH,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,qBAAa,gCAAiC,YAAW,kBAAkB;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;gBAE1D,MAAM,EAAE,sCAAsC;IAoCpD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAgB7D"}

package/dist/collectors/RequestContextAttributeCollector.mjs

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
 // SPDX-License-Identifier: Apache-2.0
-import { readUntrustedRequestContext } from "@o3co/auth.policy-verifier.core";
+import { attributeKeyReservation, CORE_ATTRIBUTE_KEY_OWNER, readUntrustedRequestContext, suggestUnreservedAttributeKey, } from "@o3co/auth.policy-verifier.core";
 const ATTRIBUTE_TYPES = [
     "string",
     "number",
@@ -23,6 +23,48 @@ const ATTRIBUTE_TYPES = [
  * config did not name cannot reach a rule, and one whose value does not match
  * its declared type is dropped rather than passed along.
  *
+ * ## Reserved vocabulary is not a valid destination
+ *
+ * A mapping's `to` may not name a key any package has reserved. Core reserves
+ * five — `scopes`, `permissions`, `roles`, `userId`, `clientId` — and every
+ * package that owns attribute vocabulary reserves its own at module load:
+ * `packages/cedar` reserves `requestAction`, `requestResourceType`,
+ * `requestResourceId` and `requestResourceRaw`. The check is a lookup in core's
+ * registry, not a list this collector or core keeps by hand, so a package core
+ * cannot see is covered by importing it — which a composition naming that
+ * package's collectors has already done.
+ *
+ * Those keys are what the engine decides from, and under the default server
+ * `scopes` / `userId` / `clientId` are read out of the signature-verified
+ * token; `requestContext` is the request body, which anyone holding a valid
+ * token fills in as they like. The two carry different trust and must not share
+ * a bucket.
+ *
+ * The reason it is refused outright rather than left to the operator is what
+ * `AttributePipeline` does with two collectors writing one key: array-valued
+ * entries **union**. So `{ from = "groups", to = "scopes" }` does not replace
+ * the token's scopes and lose an argument with `PayloadScopeCollector` — it
+ * quietly *adds to* them, and the request that arrives with
+ * `context.groups = ["admin:write"]` is authorized for a scope its token never
+ * carried. Nothing in the decision, the logs or the metrics distinguishes that
+ * from an issuer that granted it.
+ *
+ * A scalar key is not safe either, in two different ways. Two writers that
+ * disagree throw `AttributeConflictError`, which denies — fail-closed, but an
+ * unannounced outage rather than a refusal. 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 out of the
+ * caller's own request body.
+ *
+ * This is reachable only through operator configuration, which is why it is a
+ * configuration error rather than a vulnerability. It is refused at
+ * construction — boot, not first request — so a deployment that wrote it never
+ * serves a decision. Every other destination keeps working: the *field* may be
+ * called anything (`{ from = "scopes", to = "requestedScopes" }` is fine), only
+ * the attribute key is reserved.
+ *
  * ```hocon
  * { collector = "RequestContextAttributeCollector"
  *   attributes = [
@@ -49,7 +91,15 @@ export class RequestContextAttributeCollector {
             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 };
+            // Checked on the resolved key, not on `to`: `to` defaults to `from`,
+            // so `{ from = "scopes" }` reaches the reserved key without ever
+            // spelling it out. See the class doc comment for why this is refused.
+            const key = to ?? from;
+            const reservation = attributeKeyReservation(key);
+            if (reservation !== undefined) {
+                throw new Error(refusal(index, reservation));
+            }
+            return { from, to: key, type };
         });
     }
     async collect(context) {
@@ -69,6 +119,36 @@ export class RequestContextAttributeCollector {
         return attrs;
     }
 }
+/**
+ * Why this mapping is refused, in the words of whoever owns the key.
+ *
+ * Core's five get the account of the trust boundary they sit on. Another
+ * package's keys get its name and its own stated reason instead: asserting they
+ * are "the core vocabulary" would be false, and the operator's next move is to
+ * go read that package's docs, so the message says which one.
+ *
+ * The suggested rename is drawn from core's registry rather than spelled
+ * `request<Key>` unconditionally, because `request*` is a real package's
+ * namespace (cedar's) and advice that lands there would be refused by this same
+ * guard.
+ */
+function refusal(index, reservation) {
+    const { key, owner, reason } = reservation;
+    const head = owner === CORE_ATTRIBUTE_KEY_OWNER
+        ? `RequestContextAttributeCollector: attributes[${index}] maps onto the reserved core attribute "${key}". ` +
+            "That key is the engine's own vocabulary, written by the deployment — from the " +
+            "signature-verified token for scopes/userId/clientId, from configuration for roles/permissions — " +
+            "while requestContext is caller-supplied, and array attributes union across collectors, so this " +
+            "mapping would let the request body extend the deployment's value rather than contribute a " +
+            "separate attribute. "
+        : `RequestContextAttributeCollector: attributes[${index}] maps onto the reserved attribute "${key}", ` +
+            `which belongs to ${owner}${reason === undefined ? "" : ` — ${reason}`}. ` +
+            "That package writes the key from what the deployment established, while requestContext is " +
+            "caller-supplied: where both write it the values collide and every such request is denied, and " +
+            "where that package writes nothing for a given request the caller's value stands unopposed as " +
+            "the one the deployment was supposed to supply. ";
+    return `${head}Promote the field under a key of your own (for example "${suggestUnreservedAttributeKey(key)}").`;
+}
 /**
  * Reads a dot path, traversing own properties only. `requestContext` is
  * caller-supplied, so inherited members (`constructor`, `toString`, …) must not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/auth.policy-verifier.builtins",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@o3co/auth.policy-verifier.core": "0.7.0"
+    "@o3co/auth.policy-verifier.core": "0.8.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",