@o3co/auth.policy-verifier.builtins 0.2.0 → 0.3.0

package/README.ja.md

@@ -2,6 +2,8 @@
 
 auth.policy-verifier 向けの組み込み attribute collector、rule collector、および resource parser です。
 
+**Runtime:** Node.js 22+。本パッケージは `ruleType` の安定ハッシュ用に `node:crypto` を利用します。browser / edge ランタイム対応は今後の課題として別 issue で追跡します。
+
 ## インストール
 
 ```bash
@@ -54,6 +56,8 @@ new HasScope(scope: string)
 
 ### AttrMatchRule
 
+**非推奨。** 代わりに [`AttrPairEqual`](#attrpairequal) を使用してください。`AttrMatchRule` は `AttrPairEqual` を継承した薄いラッパークラスとして残されており、後方互換のため旧来の `ruleType`（`attr_match:${a}:${b}`）と旧来の `message` 文言を保持します。型 `AttrMatchRuleConfig` は `AttrPairEqualConfig` の型エイリアスです。将来のメジャーバージョンで削除されます。
+
 ```ts
 new AttrMatchRule({ a: string, b: string, group?: string })
 ```
@@ -63,6 +67,103 @@ 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` として使われます。
 
+## Attribute Comparison Rules
+
+属性比較 Rule 群は 2 軸のマトリクスで構成されます: **family**（Literal または Pair）と **operator**（Equal、NotEqual、In、NotIn、Compare）。
+
+- **Literal** Rule は、単一の名前付き属性を、コンストラクタで与えられた静的な値（または値集合）と比較します。
+- **Pair** Rule は、評価時に `Attributes` から解決される 2 つの名前付き属性を互いに比較します。
+- `In` / `NotIn` のバリアントは Literal family のみ提供します。集合に対する Pair 比較は有限リストへ自然に一般化できないため、`AttrPairIn` / `AttrPairNotIn` は意図的に存在しません。
+
+| Family  | Equal              | NotEqual              | In              | NotIn              | Compare              |
+| ------- | ------------------ | --------------------- | --------------- | ------------------ | -------------------- |
+| Literal | `AttrLiteralEqual` | `AttrLiteralNotEqual` | `AttrLiteralIn` | `AttrLiteralNotIn` | `AttrLiteralCompare` |
+| Pair    | `AttrPairEqual`    | `AttrPairNotEqual`    | —               | —                  | `AttrPairCompare`    |
+
+### AttrLiteralEqual
+
+```ts
+new AttrLiteralEqual({ a: string, v: string | number | boolean, group?: string })
+```
+
+- `code`: `"attr_not_equal"`。
+- 既定の `ruleType`: `` `attr_literal_equal:${a}:${typeof v}:${String(v)}` ``。`typeof v` セグメントは、文字列化すると同じになる異型リテラル（例: `true` と `"true"`）が同じ `ruleType` に畳み込まれるのを防ぎます。
+- `attrs.get(a)` が `v` と同じ型で厳密等価のときに通過します。型の強制変換は行いません。
+
+### AttrLiteralNotEqual
+
+```ts
+new AttrLiteralNotEqual({ a: string, v: string | number | boolean, group?: string })
+```
+
+- `code`: `"attr_equal"`。
+- 既定の `ruleType`: `` `attr_literal_not_equal:${a}:${typeof v}:${String(v)}` ``。`typeof v` セグメントは異型リテラル間の衝突を防ぎます（`AttrLiteralEqual` と同じ理由）。
+- `attrs.get(a)` が `v` と同じ型で厳密等価でないときに通過します。欠落または型不一致は `false`（safe-deny）を返します。
+
+### AttrLiteralIn
+
+```ts
+new AttrLiteralIn({ a: string, values: (string | number | boolean)[], group?: string })
+```
+
+- `code`: `"attr_not_in_set"`。
+- 既定の `ruleType`: `` `attr_literal_in:${a}:${type}:${count}:${hashPrefix}` `` — `count` は重複除去後の要素数、`hashPrefix` は重複除去かつソート済みの `values` を文字列化した内容に対する SHA-256 の先頭 8 桁。同じ `a` と内容上等価な `values`（順序・重複を無視）を持つ 2 つのインスタンスは同じ `ruleType` を持ち、評価器で OR 結合されます。
+- `values` は非空かつ同種の配列（`string[]`、`number[]`、`boolean[]` のいずれか）でなければなりません。`attrs.get(a)` が集合に含まれるときに通過します。`values` 内の重複要素は Rule の挙動に影響しません（内部では `Set` として扱われます）。
+
+### AttrLiteralNotIn
+
+```ts
+new AttrLiteralNotIn({ a: string, values: (string | number | boolean)[], group?: string })
+```
+
+- `code`: `"attr_in_set"`。
+- 既定の `ruleType`: `` `attr_literal_not_in:${a}:${type}:${count}:${hashPrefix}` `` — `AttrLiteralIn` と同じ、重複除去済みの安定ハッシュ方式。
+- `values` は非空かつ同種の配列。`attrs.get(a)` が集合に含まれないときに通過します。`values` 内の重複要素は Rule の挙動に影響しません。
+
+### AttrLiteralCompare
+
+```ts
+new AttrLiteralCompare({ a: string, op: "lt" | "le" | "gt" | "ge", v: number, group?: string })
+```
+
+- `code`: `"attr_compare_violated"`。
+- 既定の `ruleType`: `` `attr_literal_compare:${a}:${op}:${String(v)}` ``。
+- `attrs.get(a)` が数値であり `a op v` を満たすときに通過します。`v` が NaN の場合はコンストラクタ時点で拒否されます。属性側が NaN の場合は常に `false` を返します。
+
+### AttrPairEqual
+
+```ts
+new AttrPairEqual({ a: string, b: string, group?: string })
+```
+
+- `code`: `"attr_mismatch"`。
+- 既定の `ruleType`: `` `attr_pair_equal:${a}:${b}` ``。
+- `attrs.get(a)` と `attrs.get(b)` がいずれも非空文字列かつ厳密等価のときに通過します。非推奨となった `AttrMatchRule` の後継です。
+
+### AttrPairNotEqual
+
+```ts
+new AttrPairNotEqual({ a: string, b: string, group?: string })
+```
+
+- `code`: `"attr_match"`。
+- 既定の `ruleType`: `` `attr_pair_not_equal:${a}:${b}` ``。
+- `attrs.get(a)` と `attrs.get(b)` がいずれも非空文字列かつ厳密等価でないときに通過します。欠落・空文字列・非文字列はすべて `false`（safe-deny）を返します。
+
+### AttrPairCompare
+
+```ts
+new AttrPairCompare({ a: string, op: "lt" | "le" | "gt" | "ge", b: string, group?: string })
+```
+
+- `code`: `"attr_compare_violated"`。
+- 既定の `ruleType`: `` `attr_pair_compare:${a}:${op}:${b}` ``。
+- `attrs.get(a)` と `attrs.get(b)` がいずれも数値で `a op b` を満たすときに通過します。どちらかが NaN の場合は `false` を返します（JS の比較セマンティクス）。
+
+### グルーピング: 既定は AND、OR にするには `group` を指定
+
+属性比較 Rule はすべて、上記 `AttrMatchRule` と同じグルーピング規則に従います。既定では各 Rule の `ruleType` は識別用パラメータから導出されるため、異なる要件は評価器によって AND 結合されます。2 つの Rule に同じ `group` 文字列を渡すと、両者は同じ `ruleType` を持つようになり、評価器は OR 結合します（どちらか一方が成立すれば要件を満たす）。
+
 ## Rule Collectors
 
 | 名前 | 導出する permission / scope | 返り値 |

package/README.md

@@ -2,6 +2,8 @@
 
 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.
+
 ## Install
 
 ```bash
@@ -54,6 +56,8 @@ new HasScope(scope: string)
 
 ### AttrMatchRule
 
+**Deprecated.** Use [`AttrPairEqual`](#attrpairequal) instead. `AttrMatchRule` is kept as a thin wrapper class that extends `AttrPairEqual` and preserves the legacy `ruleType` (`attr_match:${a}:${b}`) and legacy `message` wording for backward compatibility. The type `AttrMatchRuleConfig` is a type alias of `AttrPairEqualConfig`. It will be removed in a future major version.
+
 ```ts
 new AttrMatchRule({ a: string, b: string, group?: string })
 ```
@@ -63,6 +67,103 @@ 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`.
 
+## 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).
+
+- **Literal** rules compare a single named attribute against a static value (or set of values) supplied at construction time.
+- **Pair** rules compare two named attributes resolved from the `Attributes` map at evaluation time.
+- `In` / `NotIn` variants exist for the Literal family only. A pair-over-set operation does not generalize cleanly to a finite list, so `AttrPairIn` / `AttrPairNotIn` are intentionally absent.
+
+| Family  | Equal              | NotEqual              | In              | NotIn              | Compare              |
+| ------- | ------------------ | --------------------- | --------------- | ------------------ | -------------------- |
+| Literal | `AttrLiteralEqual` | `AttrLiteralNotEqual` | `AttrLiteralIn` | `AttrLiteralNotIn` | `AttrLiteralCompare` |
+| Pair    | `AttrPairEqual`    | `AttrPairNotEqual`    | —               | —                  | `AttrPairCompare`    |
+
+### AttrLiteralEqual
+
+```ts
+new AttrLiteralEqual({ a: string, v: string | number | boolean, group?: string })
+```
+
+- `code`: `"attr_not_equal"`.
+- Default `ruleType`: `` `attr_literal_equal:${a}:${typeof v}:${String(v)}` ``. The `typeof v` segment prevents silent collisions between distinct-type literals that stringify the same way (e.g. `true` vs `"true"`).
+- Passes when `attrs.get(a)` is the same type and strictly equal to `v`. No type coercion.
+
+### AttrLiteralNotEqual
+
+```ts
+new AttrLiteralNotEqual({ a: string, v: string | number | boolean, group?: string })
+```
+
+- `code`: `"attr_equal"`.
+- Default `ruleType`: `` `attr_literal_not_equal:${a}:${typeof v}:${String(v)}` ``. The `typeof v` segment prevents silent collisions between distinct-type literals (same rationale as `AttrLiteralEqual`).
+- Passes when `attrs.get(a)` is the same type as `v` and strictly not equal to it. Missing or wrong-type attributes return `false` (safe-deny).
+
+### AttrLiteralIn
+
+```ts
+new AttrLiteralIn({ a: string, values: (string | number | boolean)[], group?: string })
+```
+
+- `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.
+- `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
+
+```ts
+new AttrLiteralNotIn({ a: string, values: (string | number | boolean)[], group?: string })
+```
+
+- `code`: `"attr_in_set"`.
+- Default `ruleType`: `` `attr_literal_not_in:${a}:${type}:${count}:${hashPrefix}` `` — same stable, deduplication-aware hash scheme as `AttrLiteralIn`.
+- `values` must be a non-empty, homogeneous array. Passes when `attrs.get(a)` is NOT in the set. Duplicate elements in `values` are ignored.
+
+### AttrLiteralCompare
+
+```ts
+new AttrLiteralCompare({ a: string, op: "lt" | "le" | "gt" | "ge", v: number, group?: string })
+```
+
+- `code`: `"attr_compare_violated"`.
+- Default `ruleType`: `` `attr_literal_compare:${a}:${op}:${String(v)}` ``.
+- Passes when `attrs.get(a)` is a number satisfying `a op v`. NaN as `v` is rejected at construction time. NaN attributes always return `false`.
+
+### AttrPairEqual
+
+```ts
+new AttrPairEqual({ a: string, b: string, group?: string })
+```
+
+- `code`: `"attr_mismatch"`.
+- Default `ruleType`: `` `attr_pair_equal:${a}:${b}` ``.
+- Passes when both `attrs.get(a)` and `attrs.get(b)` are non-empty strings and strictly equal. This is the successor to the deprecated `AttrMatchRule`.
+
+### AttrPairNotEqual
+
+```ts
+new AttrPairNotEqual({ a: string, b: string, group?: string })
+```
+
+- `code`: `"attr_match"`.
+- Default `ruleType`: `` `attr_pair_not_equal:${a}:${b}` ``.
+- Passes when both `attrs.get(a)` and `attrs.get(b)` are non-empty strings and strictly not equal. Missing, empty, or non-string attributes return `false` (safe-deny).
+
+### AttrPairCompare
+
+```ts
+new AttrPairCompare({ a: string, op: "lt" | "le" | "gt" | "ge", b: string, group?: string })
+```
+
+- `code`: `"attr_compare_violated"`.
+- Default `ruleType`: `` `attr_pair_compare:${a}:${op}:${b}` ``.
+- Passes when both `attrs.get(a)` and `attrs.get(b)` are numbers satisfying `a op b`. NaN on either side returns `false` (JS comparison semantics).
+
+### Grouping: AND by default, `group` for OR
+
+All attribute comparison rules follow the same grouping semantics described for `AttrMatchRule` above. By default, each rule's `ruleType` is derived from its distinguishing parameters so that distinct requirements are AND-combined by the evaluator. Pass the same `group` string to two rules to give them the same `ruleType` — the evaluator then OR-combines them (either condition satisfies the requirement).
+
 ## Rule Collectors
 
 | Name | Derives permission/scope | Returns |

package/dist/__tests__/rules/AttrLiteralCompare.test.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AttrLiteralCompare.test.d.mts.map

package/dist/__tests__/rules/AttrLiteralCompare.test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttrLiteralCompare.test.d.mts","sourceRoot":"","sources":["../../../src/__tests__/rules/AttrLiteralCompare.test.mts"],"names":[],"mappings":""}

package/dist/__tests__/rules/AttrLiteralCompare.test.mjs

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import { AttrLiteralCompare } from "#/rules/AttrLiteralCompare.mjs";
+describe("AttrLiteralCompare", () => {
+    // ---------------------------------------------------------------------------
+    // Happy path: each op at boundary values
+    // ---------------------------------------------------------------------------
+    it("op=lt: returns true when attr < v (5 < 10)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: 10 });
+        const attrs = new Map([["score", 5]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=lt: returns false when attr === v (10 < 10 is false)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: 10 });
+        const attrs = new Map([["score", 10]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=lt: returns false when attr > v (15 < 10 is false)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: 10 });
+        const attrs = new Map([["score", 15]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=le: returns true when attr === v (10 <= 10)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "le", v: 10 });
+        const attrs = new Map([["score", 10]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=le: returns true when attr < v (5 <= 10)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "le", v: 10 });
+        const attrs = new Map([["score", 5]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=le: returns false when attr > v (15 <= 10 is false)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "le", v: 10 });
+        const attrs = new Map([["score", 15]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=gt: returns true when attr > v (15 > 10)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        const attrs = new Map([["score", 15]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=gt: returns false when attr === v (10 > 10 is false)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        const attrs = new Map([["score", 10]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=gt: returns false when attr < v (5 > 10 is false)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        const attrs = new Map([["score", 5]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=ge: returns true when attr === v (10 >= 10)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "ge", v: 10 });
+        const attrs = new Map([["score", 10]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=ge: returns true when attr > v (15 >= 10)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "ge", v: 10 });
+        const attrs = new Map([["score", 15]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=ge: returns false when attr < v (5 >= 10 is false)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "ge", v: 10 });
+        const attrs = new Map([["score", 5]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // Evaluation-time safe-deny: attr is not a number
+    // ---------------------------------------------------------------------------
+    it("returns false when attr is a string (not a number)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 5 });
+        const attrs = new Map([["score", "10"]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("returns false when attr is a boolean (not a number)", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 0 });
+        const attrs = new Map([["score", true]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // Evaluation-time: NaN attribute → false for all ops
+    // ---------------------------------------------------------------------------
+    it("op=lt: returns false when attr is NaN", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: 10 });
+        const attrs = new Map([["score", NaN]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=le: returns false when attr is NaN", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "le", v: 10 });
+        const attrs = new Map([["score", NaN]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=gt: returns false when attr is NaN", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        const attrs = new Map([["score", NaN]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("op=ge: returns false when attr is NaN", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "ge", v: 10 });
+        const attrs = new Map([["score", NaN]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // Evaluation-time: Infinity / -Infinity attributes
+    // ---------------------------------------------------------------------------
+    it("op=gt: Infinity > 100 returns true", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 100 });
+        const attrs = new Map([["score", Infinity]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=lt: -Infinity < 0 returns true", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: 0 });
+        const attrs = new Map([["score", -Infinity]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("op=ge: Infinity >= Infinity returns true", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "ge", v: Infinity });
+        const attrs = new Map([["score", Infinity]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    // ---------------------------------------------------------------------------
+    // Evaluation-time safe-deny: missing / null attr
+    // ---------------------------------------------------------------------------
+    it("returns false when the target attribute is missing", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 0 });
+        const attrs = new Map();
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("returns false when the target attribute is null", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 0 });
+        const attrs = new Map([["score", null]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'a'
+    // ---------------------------------------------------------------------------
+    it("throws when 'a' is undefined", () => {
+        expect(() => new AttrLiteralCompare({ a: undefined, op: "gt", v: 0 })).toThrow(/AttrLiteralCompare.*'a'.*(non-empty string|got undefined)/);
+    });
+    it("throws when 'a' is an empty string", () => {
+        expect(() => new AttrLiteralCompare({ a: "", op: "gt", v: 0 })).toThrow(/AttrLiteralCompare.*'a'.*empty string/);
+    });
+    it("throws when 'a' is a non-string (number 42)", () => {
+        expect(() => new AttrLiteralCompare({ a: 42, op: "gt", v: 0 })).toThrow(/AttrLiteralCompare.*'a'.*got number/);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'v'
+    // ---------------------------------------------------------------------------
+    it("throws when 'v' is missing (undefined)", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: undefined })).toThrow(/AttrLiteralCompare.*'v'/);
+    });
+    it("throws when 'v' is null", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: null })).toThrow(/AttrLiteralCompare.*'v'/);
+    });
+    it("throws when 'v' is a string", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: "10" })).toThrow(/AttrLiteralCompare.*'v'/);
+    });
+    it("throws when 'v' is a boolean", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: true })).toThrow(/AttrLiteralCompare.*'v'/);
+    });
+    it("throws when 'v' is a plain object", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: {} })).toThrow(/AttrLiteralCompare.*'v'/);
+    });
+    it("throws when 'v' is NaN (fail-fast at construction)", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: NaN })).toThrow(/AttrLiteralCompare.*'v'.*NaN/);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'op'
+    // ---------------------------------------------------------------------------
+    it("throws when 'op' is missing (undefined)", () => {
+        expect(() => new AttrLiteralCompare({
+            a: "score",
+            op: undefined,
+            v: 0,
+        })).toThrow(/AttrLiteralCompare.*'op'/);
+    });
+    it("throws when 'op' is not a string (number)", () => {
+        expect(() => new AttrLiteralCompare({
+            a: "score",
+            op: 42,
+            v: 0,
+        })).toThrow(/AttrLiteralCompare.*'op'/);
+    });
+    it("throws when 'op' is an invalid string ('eq')", () => {
+        expect(() => new AttrLiteralCompare({
+            a: "score",
+            op: "eq",
+            v: 0,
+        })).toThrow(/AttrLiteralCompare.*'op'/);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'group'
+    // ---------------------------------------------------------------------------
+    it("throws when 'group' is present but is an empty string", () => {
+        expect(() => new AttrLiteralCompare({ a: "score", op: "gt", v: 0, group: "" })).toThrow(/AttrLiteralCompare.*'group'.*empty string/);
+    });
+    it("throws when 'group' is present but is a non-string (number 42)", () => {
+        expect(() => new AttrLiteralCompare({
+            a: "score",
+            op: "gt",
+            v: 0,
+            group: 42,
+        })).toThrow(/AttrLiteralCompare.*'group'.*got number/);
+    });
+    // ---------------------------------------------------------------------------
+    // ruleType: default derived from a, op, v
+    // ---------------------------------------------------------------------------
+    it("derives default ruleType from a, op, and v", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        expect(rule.ruleType).toBe("attr_literal_compare:score:gt:10");
+    });
+    it("derives default ruleType for negative v", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: -5 });
+        expect(rule.ruleType).toBe("attr_literal_compare:score:lt:-5");
+    });
+    it("derives default ruleType for Infinity v", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "lt", v: Infinity });
+        expect(rule.ruleType).toBe("attr_literal_compare:score:lt:Infinity");
+    });
+    it("distinct op or v produce distinct ruleTypes (AND semantics)", () => {
+        const r1 = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        const r2 = new AttrLiteralCompare({ a: "score", op: "ge", v: 10 });
+        const r3 = new AttrLiteralCompare({ a: "score", op: "gt", v: 20 });
+        expect(r1.ruleType).not.toBe(r2.ruleType);
+        expect(r1.ruleType).not.toBe(r3.ruleType);
+    });
+    // ---------------------------------------------------------------------------
+    // ruleType: group override
+    // ---------------------------------------------------------------------------
+    it("uses the provided group string as ruleType, overriding the default", () => {
+        const r1 = new AttrLiteralCompare({ a: "score", op: "gt", v: 10, group: "score-check" });
+        const r2 = new AttrLiteralCompare({ a: "score", op: "ge", v: 11, group: "score-check" });
+        expect(r1.ruleType).toBe("score-check");
+        expect(r2.ruleType).toBe("score-check");
+    });
+    // ---------------------------------------------------------------------------
+    // code and message fields
+    // ---------------------------------------------------------------------------
+    it("has code 'attr_compare_violated'", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        expect(rule.code).toBe("attr_compare_violated");
+    });
+    it("message contains the attribute name, op, and v", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        expect(rule.message).toContain("score");
+        expect(rule.message).toContain("gt");
+        expect(rule.message).toContain("10");
+    });
+    it("message starts with a capital letter", () => {
+        const rule = new AttrLiteralCompare({ a: "score", op: "gt", v: 10 });
+        expect(rule.message[0]).toBe(rule.message[0]?.toUpperCase());
+    });
+});

package/dist/__tests__/rules/AttrLiteralEqual.test.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AttrLiteralEqual.test.d.mts.map

package/dist/__tests__/rules/AttrLiteralEqual.test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttrLiteralEqual.test.d.mts","sourceRoot":"","sources":["../../../src/__tests__/rules/AttrLiteralEqual.test.mts"],"names":[],"mappings":""}

package/dist/__tests__/rules/AttrLiteralEqual.test.mjs

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { AttrLiteralEqual } from "#/rules/AttrLiteralEqual.mjs";
+describe("AttrLiteralEqual", () => {
+    // ---------------------------------------------------------------------------
+    // Happy path: verify() returns true
+    // ---------------------------------------------------------------------------
+    it("returns true when attr equals the configured string literal", () => {
+        const rule = new AttrLiteralEqual({ a: "role", v: "admin" });
+        const attrs = new Map([["role", "admin"]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("returns true when attr equals the configured number literal", () => {
+        const rule = new AttrLiteralEqual({ a: "age", v: 30 });
+        const attrs = new Map([["age", 30]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    it("returns true when attr equals the configured boolean literal", () => {
+        const rule = new AttrLiteralEqual({ a: "verified", v: true });
+        const attrs = new Map([["verified", true]]);
+        expect(rule.verify(attrs)).toBe(true);
+    });
+    // ---------------------------------------------------------------------------
+    // Type mismatch: no coercion
+    // ---------------------------------------------------------------------------
+    it("returns false when number literal v=30 but attr is the string '30' (no coercion)", () => {
+        const rule = new AttrLiteralEqual({ a: "age", v: 30 });
+        const attrs = new Map([["age", "30"]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("returns false when string literal v='true' but attr is the boolean true (no coercion)", () => {
+        const rule = new AttrLiteralEqual({ a: "verified", v: "true" });
+        const attrs = new Map([["verified", true]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // Evaluation-time safe-deny: missing / null attr
+    // ---------------------------------------------------------------------------
+    it("returns false when the target attribute is missing", () => {
+        const rule = new AttrLiteralEqual({ a: "role", v: "admin" });
+        const attrs = new Map();
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    it("returns false when the target attribute is null", () => {
+        const rule = new AttrLiteralEqual({ a: "role", v: "admin" });
+        const attrs = new Map([["role", null]]);
+        expect(rule.verify(attrs)).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'a'
+    // ---------------------------------------------------------------------------
+    it("throws when 'a' is undefined", () => {
+        expect(() => new AttrLiteralEqual({ a: undefined, v: "x" })).toThrow(/AttrLiteralEqual.*'a'.*(non-empty string|got undefined)/);
+    });
+    it("throws when 'a' is an empty string", () => {
+        expect(() => new AttrLiteralEqual({ a: "", v: "x" })).toThrow(/AttrLiteralEqual.*'a'.*empty string/);
+    });
+    it("throws when 'a' is a non-string (number 42)", () => {
+        expect(() => new AttrLiteralEqual({ a: 42, v: "x" })).toThrow(/AttrLiteralEqual.*'a'.*got number/);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'v'
+    // ---------------------------------------------------------------------------
+    it("throws when 'v' is null", () => {
+        expect(() => new AttrLiteralEqual({ a: "role", v: null })).toThrow(/AttrLiteralEqual.*'v'.*got null/);
+    });
+    it("throws when 'v' is undefined", () => {
+        expect(() => new AttrLiteralEqual({ a: "role", v: undefined })).toThrow(/AttrLiteralEqual.*'v'.*got undefined/);
+    });
+    it("throws when 'v' is a plain object ({})", () => {
+        expect(() => new AttrLiteralEqual({ a: "role", v: {} })).toThrow(/AttrLiteralEqual.*'v'.*got object/);
+    });
+    it("throws when 'v' is NaN", () => {
+        // NaN === NaN is always false, so AttrLiteralEqual({ v: NaN }) would be
+        // an always-deny rule. Must fail-fast at construction rather than ship
+        // a silently-broken predicate.
+        expect(() => new AttrLiteralEqual({ a: "score", v: Number.NaN })).toThrow(/must not be NaN/);
+    });
+    // ---------------------------------------------------------------------------
+    // Construction errors: invalid 'group'
+    // ---------------------------------------------------------------------------
+    it("throws when 'group' is present but is an empty string", () => {
+        expect(() => new AttrLiteralEqual({ a: "role", v: "admin", group: "" })).toThrow(/AttrLiteralEqual.*'group'.*empty string/);
+    });
+    it("throws when 'group' is present but is a non-string (number 42)", () => {
+        expect(() => new AttrLiteralEqual({ a: "role", v: "admin", group: 42 })).toThrow(/AttrLiteralEqual.*'group'.*got number/);
+    });
+    // ---------------------------------------------------------------------------
+    // ruleType: default derived from 'a', 'typeof v', and 'String(v)'
+    // ---------------------------------------------------------------------------
+    it("derives default ruleType including the type segment for a string literal", () => {
+        const rule = new AttrLiteralEqual({ a: "role", v: "admin" });
+        expect(rule.ruleType).toBe("attr_literal_equal:role:string:admin");
+    });
+    it("derives default ruleType including the type segment for a number literal", () => {
+        const rule = new AttrLiteralEqual({ a: "age", v: 30 });
+        expect(rule.ruleType).toBe("attr_literal_equal:age:number:30");
+    });
+    it("derives default ruleType including the type segment for a boolean literal", () => {
+        const rule = new AttrLiteralEqual({ a: "verified", v: true });
+        expect(rule.ruleType).toBe("attr_literal_equal:verified:boolean:true");
+    });
+    it("distinct configs produce distinct default ruleTypes (AND semantics)", () => {
+        const r1 = new AttrLiteralEqual({ a: "role", v: "admin" });
+        const r2 = new AttrLiteralEqual({ a: "role", v: "editor" });
+        expect(r1.ruleType).not.toBe(r2.ruleType);
+    });
+    it("distinguishes literals by type in ruleType (e.g. boolean true vs string 'true')", () => {
+        // Regression guard: without the typeof-segment in ruleType, these two
+        // rules would share the same default ruleType and the evaluator would
+        // silently OR them together, weakening authorization. The type tag
+        // keeps them AND-combined as intended.
+        const r1 = new AttrLiteralEqual({ a: "status", v: true });
+        const r2 = new AttrLiteralEqual({ a: "status", v: "true" });
+        expect(r1.ruleType).not.toBe(r2.ruleType);
+    });
+    // ---------------------------------------------------------------------------
+    // ruleType: group override
+    // ---------------------------------------------------------------------------
+    it("uses the provided group string as ruleType, overriding the default", () => {
+        const r1 = new AttrLiteralEqual({ a: "role", v: "admin", group: "any-admin-role" });
+        const r2 = new AttrLiteralEqual({ a: "role", v: "superuser", group: "any-admin-role" });
+        expect(r1.ruleType).toBe("any-admin-role");
+        expect(r2.ruleType).toBe("any-admin-role");
+    });
+    // ---------------------------------------------------------------------------
+    // code and message fields
+    // ---------------------------------------------------------------------------
+    it("has code 'attr_not_equal'", () => {
+        const rule = new AttrLiteralEqual({ a: "role", v: "admin" });
+        expect(rule.code).toBe("attr_not_equal");
+    });
+    it("message contains the attribute name and literal value, and starts with a capital letter", () => {
+        const rule = new AttrLiteralEqual({ a: "role", v: "admin" });
+        expect(rule.message).toContain("role");
+        expect(rule.message).toContain("admin");
+        expect(rule.message[0]).toBe(rule.message[0]?.toUpperCase());
+    });
+});

package/dist/__tests__/rules/AttrLiteralIn.test.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AttrLiteralIn.test.d.mts.map