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

package/dist/rules/HasScope.d.mts

@@ -1,11 +1,52 @@
-import type { Attributes, Rule } from "@o3co/auth.policy-verifier.core";
+import type { ReadonlyAttributes, Rule } from "@o3co/auth.policy-verifier.core";
+/** Options accepted by `HasScope`. */
+export interface HasScopeOptions {
+    /**
+     * Opt in to treating a bare granted scope (one containing no `:`) as
+     * `read:<scope>` in addition to its literal value. Defaults to `false`.
+     *
+     * This exists only for deployments whose issuer emits bare resource names
+     * and that relied on the rewrite before it became opt-in. It is off by
+     * default because the rewrite invents an action the issuer never wrote:
+     * a token granted `project` is silently promoted to `read:project`.
+     */
+    allowBareScopeRewrite?: boolean;
+}
+/**
+ * Rule that passes when the token carries the required scope.
+ *
+ * ## Matching
+ *
+ * Comparison is an **exact, case-sensitive string equality** against each value
+ * in `ATTR_SCOPES`. OAuth 2.0 scope values are case-sensitive opaque strings
+ * (RFC 6749 §3.3), so the verifier compares what the issuer wrote rather than a
+ * normalized form of it:
+ *
+ * - `read:PROJECT` does **not** satisfy a `read:project` requirement.
+ * - `read:project:restricted` is a value in its own right. It does not satisfy
+ *   `read:project`, and `read:project` does not satisfy it. Nothing is split
+ *   off at the second `:`; a scope the issuer deliberately narrowed must not
+ *   collapse into the broader one.
+ *
+ * ## Bare-scope rewrite
+ *
+ * A granted scope carrying no `:` is compared literally unless
+ * `{ allowBareScopeRewrite: true }` is passed, in which case it also matches
+ * `read:<scope>`. Even then, only a scope with **no** `:` is ever rewritten —
+ * a value such as `project:restricted` is left alone, because which of its
+ * segments is the action is unknowable and guessing would over-grant.
+ *
+ * Non-string entries in `ATTR_SCOPES` never match and never throw: the map is
+ * untyped, and a malformed value must produce a denial, not a crash.
+ */
 export declare class HasScope implements Rule {
     private scope;
     readonly ruleType = "scope";
     readonly code = "invalid_scope";
     readonly message: string;
-    constructor(scope: string);
-    verify(attrs: Attributes): boolean;
-    private matchScopes;
+    private readonly allowBareScopeRewrite;
+    constructor(scope: string, options?: HasScopeOptions);
+    verify(attrs: ReadonlyAttributes): boolean;
+    private matchScope;
 }
 //# sourceMappingURL=HasScope.d.mts.map

package/dist/rules/HasScope.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"HasScope.d.mts","sourceRoot":"","sources":["../../src/rules/HasScope.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,iCAAiC,CAAC;AAGxE,qBAAa,QAAS,YAAW,IAAI;IAKxB,OAAO,CAAC,KAAK;IAJzB,QAAQ,CAAC,QAAQ,WAAW;IAC5B,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEL,KAAK,EAAE,MAAM;IAIjC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;IAKlC,OAAO,CAAC,WAAW;CASnB"}
+{"version":3,"file":"HasScope.d.mts","sourceRoot":"","sources":["../../src/rules/HasScope.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,iCAAiC,CAAC;AAGhF,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC/B;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,QAAS,YAAW,IAAI;IAQnC,OAAO,CAAC,KAAK;IAPd,QAAQ,CAAC,QAAQ,WAAW;IAC5B,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAU;gBAGvC,KAAK,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,eAAe;IAM1B,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAM1C,OAAO,CAAC,UAAU;CAYlB"}

package/dist/rules/HasScope.mjs

@@ -1,22 +1,59 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { ATTR_SCOPES } from "@o3co/auth.policy-verifier.core";
+/**
+ * Rule that passes when the token carries the required scope.
+ *
+ * ## Matching
+ *
+ * Comparison is an **exact, case-sensitive string equality** against each value
+ * in `ATTR_SCOPES`. OAuth 2.0 scope values are case-sensitive opaque strings
+ * (RFC 6749 §3.3), so the verifier compares what the issuer wrote rather than a
+ * normalized form of it:
+ *
+ * - `read:PROJECT` does **not** satisfy a `read:project` requirement.
+ * - `read:project:restricted` is a value in its own right. It does not satisfy
+ *   `read:project`, and `read:project` does not satisfy it. Nothing is split
+ *   off at the second `:`; a scope the issuer deliberately narrowed must not
+ *   collapse into the broader one.
+ *
+ * ## Bare-scope rewrite
+ *
+ * A granted scope carrying no `:` is compared literally unless
+ * `{ allowBareScopeRewrite: true }` is passed, in which case it also matches
+ * `read:<scope>`. Even then, only a scope with **no** `:` is ever rewritten —
+ * a value such as `project:restricted` is left alone, because which of its
+ * segments is the action is unknowable and guessing would over-grant.
+ *
+ * Non-string entries in `ATTR_SCOPES` never match and never throw: the map is
+ * untyped, and a malformed value must produce a denial, not a crash.
+ */
 export class HasScope {
     scope;
     ruleType = "scope";
     code = "invalid_scope";
     message;
-    constructor(scope) {
+    allowBareScopeRewrite;
+    constructor(scope, options) {
         this.scope = scope;
         this.message = `Token does not have required scope: ${scope}`;
+        this.allowBareScopeRewrite = options?.allowBareScopeRewrite ?? false;
     }
     verify(attrs) {
-        const scopes = attrs.get(ATTR_SCOPES) ?? [];
-        return scopes.some((s) => this.matchScopes(s, this.scope));
+        const scopes = attrs.get(ATTR_SCOPES);
+        if (!Array.isArray(scopes))
+            return false;
+        return scopes.some((s) => typeof s === "string" && this.matchScope(s, this.scope));
     }
-    matchScopes(scope, required) {
-        scope = scope.toLowerCase();
-        required = required.toLowerCase();
-        const parts = scope.split(":");
-        const [perm, resource] = parts.length === 1 ? ["read", parts[0]] : parts;
-        return required === `${perm}:${resource}`;
+    matchScope(granted, required) {
+        if (granted === required)
+            return true;
+        // The rewrite applies to bare scopes only. A granted scope that already
+        // contains ":" is never re-interpreted: splitting it to guess an action
+        // is what let "read:project:restricted" pass as "read:project".
+        if (this.allowBareScopeRewrite && !granted.includes(":")) {
+            return `read:${granted}` === required;
+        }
+        return false;
     }
 }

package/dist/rules/_sharedValidation.d.mts

@@ -1,6 +1,4 @@
-/**
- * Shared validation helpers for attribute-based rule constructors.
- */
+export declare function fnv1a64(s: string): string;
 export type LiteralValue = string | number | boolean;
 export type CompareOp = "lt" | "le" | "gt" | "ge";
 export declare const COMPARE_OPS: readonly CompareOp[];
@@ -69,15 +67,20 @@ export declare function requireCompareOp(className: string, value: unknown): Com
 export declare function requireOptionalGroup(className: string, value: unknown): string | undefined;
 /**
  * Computes a stable cache/dedup key for an array of LiteralValues.
- * Format: `{type}:{count}:{hashPrefix}` — SHA-256 over a canonical serialization
- * of `values`. The canonical form first deduplicates `values` (to mirror the
- * Set-based semantics of AttrLiteralIn / AttrLiteralNotIn — duplicates do not
- * change the rule's behavior, so they must not change its `ruleType`), then
- * applies `JSON.stringify(String(v))` to each remaining element before sorting
- * and joining with `,`. The per-element quoting prevents separator collisions
+ * Format: `{type}:{count}:{hashPrefix}` — `hashPrefix` is a 16-hex-character
+ * FNV-1a 64-bit hash over a canonical serialization of `values`. The canonical
+ * form first deduplicates `values` (to mirror the Set-based semantics of
+ * AttrLiteralIn / AttrLiteralNotIn — duplicates do not change the rule's
+ * behavior, so they must not change its `ruleType`), then applies
+ * `JSON.stringify(String(v))` to each remaining element before sorting and
+ * joining with `,`. The per-element quoting prevents separator collisions
  * across different arrays (e.g. `["a,b", "c"]` vs `["a", "b,c"]`).
  * The `{count}` segment reflects the post-dedup element count.
  * Caller must guarantee values is a non-empty homogeneous LiteralValue[].
+ *
+ * The hash is non-cryptographic by design, but uses 64-bit output to keep
+ * the birthday-collision bound (~2^32) far above any realistic policy size
+ * and to resist deliberate collision construction.
  */
 export declare function computeValuesKey(values: LiteralValue[]): string;
 /**

package/dist/rules/_sharedValidation.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"_sharedValidation.d.mts","sourceRoot":"","sources":["../../src/rules/_sharedValidation.mts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAarD,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAA6B,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAe/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,GAAG,EACd,KAAK,EAAE,OAAO,GACZ,YAAY,CAad;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAQvF;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CAkChG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAU7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAe1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAS/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAWxF"}
+{"version":3,"file":"_sharedValidation.d.mts","sourceRoot":"","sources":["../../src/rules/_sharedValidation.mts"],"names":[],"mappings":"AA4BA,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzC;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAarD,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAA6B,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAe/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,GAAG,EACd,KAAK,EAAE,OAAO,GACZ,YAAY,CAad;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAQvF;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CAkChG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAU7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAe1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAQ/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAWxF"}

package/dist/rules/_sharedValidation.mjs

@@ -1,4 +1,37 @@
-import { createHash } from "node:crypto";
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared validation helpers for attribute-based rule constructors.
+ */
+/**
+ * FNV-1a 64-bit non-cryptographic hash, computed with BigInt. Sync,
+ * runtime-agnostic (no `node:*` imports), deterministic. Returns 16
+ * lowercase hex characters, zero-padded.
+ *
+ * Used by `computeValuesKey` to build a stable grouping suffix for `ruleType`.
+ * The 64-bit output gives ~2^32 birthday-collision bound, which is
+ * effectively non-colliding for any realistic policy size and resists
+ * deliberate collision construction by a hostile policy author or supply
+ * chain. (A 32-bit variant was rejected during review because random short
+ * strings can be made to collide within seconds, weakening evaluator
+ * grouping when two distinct rules on the same attribute share a `ruleType`.)
+ *
+ * Iterates UTF-16 code units via `charCodeAt`. BigInt is used because
+ * 64-bit multiplication overflows IEEE-754 doubles; `Math.imul` only
+ * supports 32-bit. BigInt is available in every modern JavaScript runtime
+ * (Node 10.4+, all evergreen browsers, Cloudflare Workers, Deno, Bun).
+ */
+const FNV_OFFSET_BASIS_64 = 0xcbf29ce484222325n;
+const FNV_PRIME_64 = 0x100000001b3n;
+const FNV_MASK_64 = 0xffffffffffffffffn;
+export function fnv1a64(s) {
+    let hash = FNV_OFFSET_BASIS_64;
+    for (let i = 0; i < s.length; i++) {
+        hash ^= BigInt(s.charCodeAt(i));
+        hash = (hash * FNV_PRIME_64) & FNV_MASK_64;
+    }
+    return hash.toString(16).padStart(16, "0");
+}
 /**
  * Returns a human-readable type label for use in error messages.
  * Distinguishes null and undefined from other types instead of returning
@@ -152,15 +185,20 @@ export function requireOptionalGroup(className, value) {
 }
 /**
  * Computes a stable cache/dedup key for an array of LiteralValues.
- * Format: `{type}:{count}:{hashPrefix}` — SHA-256 over a canonical serialization
- * of `values`. The canonical form first deduplicates `values` (to mirror the
- * Set-based semantics of AttrLiteralIn / AttrLiteralNotIn — duplicates do not
- * change the rule's behavior, so they must not change its `ruleType`), then
- * applies `JSON.stringify(String(v))` to each remaining element before sorting
- * and joining with `,`. The per-element quoting prevents separator collisions
+ * Format: `{type}:{count}:{hashPrefix}` — `hashPrefix` is a 16-hex-character
+ * FNV-1a 64-bit hash over a canonical serialization of `values`. The canonical
+ * form first deduplicates `values` (to mirror the Set-based semantics of
+ * AttrLiteralIn / AttrLiteralNotIn — duplicates do not change the rule's
+ * behavior, so they must not change its `ruleType`), then applies
+ * `JSON.stringify(String(v))` to each remaining element before sorting and
+ * joining with `,`. The per-element quoting prevents separator collisions
  * across different arrays (e.g. `["a,b", "c"]` vs `["a", "b,c"]`).
  * The `{count}` segment reflects the post-dedup element count.
  * Caller must guarantee values is a non-empty homogeneous LiteralValue[].
+ *
+ * The hash is non-cryptographic by design, but uses 64-bit output to keep
+ * the birthday-collision bound (~2^32) far above any realistic policy size
+ * and to resist deliberate collision construction.
  */
 export function computeValuesKey(values) {
     const elementType = typeof values[0];
@@ -169,8 +207,7 @@ export function computeValuesKey(values) {
         .map((v) => JSON.stringify(String(v)))
         .sort()
         .join(",");
-    const hash = createHash("sha256").update(joined).digest("hex").slice(0, 8);
-    return `${elementType}:${unique.length}:${hash}`;
+    return `${elementType}:${unique.length}:${fnv1a64(joined)}`;
 }
 /**
  * Applies a numeric comparison operator between left and right.

package/dist/rules/collectors/ResourceActionPermissionRuleCollector.d.mts

@@ -1,4 +1,10 @@
 import type { CollectorContext, Rule, RuleCollector } from "@o3co/auth.policy-verifier.core";
+/**
+ * Rule collector that emits a single `HasPermission` rule for the
+ * `{resource}.perm:{action}` permission string. Use when the effective
+ * permission is encoded directly into the token's permission attribute rather
+ * than derived from scopes.
+ */
 export declare class ResourceActionPermissionRuleCollector implements RuleCollector {
     collect(context: CollectorContext): Promise<Rule[]>;
 }

package/dist/rules/collectors/ResourceActionPermissionRuleCollector.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ResourceActionPermissionRuleCollector.d.mts","sourceRoot":"","sources":["../../../src/rules/collectors/ResourceActionPermissionRuleCollector.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAG7F,qBAAa,qCAAsC,YAAW,aAAa;IACpE,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAIzD"}
+{"version":3,"file":"ResourceActionPermissionRuleCollector.d.mts","sourceRoot":"","sources":["../../../src/rules/collectors/ResourceActionPermissionRuleCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAG7F;;;;;GAKG;AACH,qBAAa,qCAAsC,YAAW,aAAa;IACpE,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAIzD"}

package/dist/rules/collectors/ResourceActionPermissionRuleCollector.mjs

@@ -1,4 +1,12 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { HasPermission } from "../HasPermission.mjs";
+/**
+ * Rule collector that emits a single `HasPermission` rule for the
+ * `{resource}.perm:{action}` permission string. Use when the effective
+ * permission is encoded directly into the token's permission attribute rather
+ * than derived from scopes.
+ */
 export class ResourceActionPermissionRuleCollector {
     async collect(context) {
         const permission = `${context.resource.raw}.perm:${context.action}`;

package/dist/rules/collectors/ResourceActionScopeRuleCollector.d.mts

@@ -1,14 +1,62 @@
 import type { CollectorContext, Rule, RuleCollector } from "@o3co/auth.policy-verifier.core";
+/** How the collector treats a token that carries no `scope` claim. */
+export type ScopelessPolicy = "deny" | "skip";
+/** Config entry accepted by `ResourceActionScopeRuleCollector`. */
+export interface ResourceActionScopeRuleCollectorConfig {
+    /**
+     * `"deny"` (default) emits the scope rule for every request, so a scopeless
+     * token fails it. `"skip"` emits no rule for a scopeless token, leaving the
+     * scope group out of AND-evaluation.
+     */
+    scopeless?: ScopelessPolicy;
+    /**
+     * Forwarded to `HasScope`. `false` (default) compares granted scopes
+     * literally; `true` additionally treats a bare granted scope `x` as
+     * `read:x`. See `HasScopeOptions.allowBareScopeRewrite`.
+     */
+    allowBareScopeRewrite?: boolean;
+}
 /**
  * Generates a HasScope rule derived from the request action and resource type.
  *
- * When the JWT payload has no `scope` claim (e.g. DID-grant tokens), no rules
- * are generated. The scope rule group is therefore absent from AND-evaluation,
- * allowing other rule groups to decide independently.
+ * ## Scope as capability ceiling
+ *
+ * The JWT `scope` claim represents what the session **can request** — a
+ * capability ceiling — not what the session **has been granted**. Whether the
+ * operation is ultimately permitted is determined by the full rule pipeline
+ * (other collectors, resource-owner policy, etc.). This collector enforces the
+ * ceiling only: it produces a `HasScope` rule for the requested
+ * `{action}:{resourceType}`, which must be satisfied by the token's scopes.
+ *
+ * ## Matching
+ *
+ * The emitted `HasScope` compares scopes exactly and case-sensitively. An
+ * issuer that emits bare resource names (`project` rather than `read:project`)
+ * must opt in with `{ allowBareScopeRewrite: true }`; without it a bare scope
+ * satisfies nothing of the `{action}:{resourceType}` form.
+ *
+ * ## Behavior for scopeless tokens
+ *
+ * By default the rule is emitted regardless of whether the token carries a
+ * `scope` claim, so a scopeless token fails it. Dropping the rule instead would
+ * remove the scope group from AND-evaluation, and in a scope-only pipeline that
+ * turns "the token asserts no capability" into "every capability is allowed".
+ *
+ * Flows where the IdP does not issue a `scope` claim (e.g. DID-grant tokens)
+ * must opt out explicitly with `{ scopeless: "skip" }`, and only in a pipeline
+ * where another rule group authorizes the request — otherwise the request is
+ * left with no applicable rule, which the evaluator denies.
+ *
+ * For pipelines that exclusively serve scopeless flows, prefer collectors that
+ * derive rules from identity claims (e.g. DID, `sub`, role) instead.
  *
- * OAuth JWTs that carry a `scope` claim are validated as before.
+ * See https://github.com/o3co/auth.provider/issues/56 for background on why
+ * the IdP asserts identity, not permissions.
  */
 export declare class ResourceActionScopeRuleCollector implements RuleCollector {
+    private readonly scopeless;
+    private readonly allowBareScopeRewrite;
+    constructor(config?: ResourceActionScopeRuleCollectorConfig);
     collect(context: CollectorContext): Promise<Rule[]>;
 }
 //# sourceMappingURL=ResourceActionScopeRuleCollector.d.mts.map

package/dist/rules/collectors/ResourceActionScopeRuleCollector.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ResourceActionScopeRuleCollector.d.mts","sourceRoot":"","sources":["../../../src/rules/collectors/ResourceActionScopeRuleCollector.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAG7F;;;;;;;;GAQG;AACH,qBAAa,gCAAiC,YAAW,aAAa;IAC/D,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAOzD"}
+{"version":3,"file":"ResourceActionScopeRuleCollector.d.mts","sourceRoot":"","sources":["../../../src/rules/collectors/ResourceActionScopeRuleCollector.mts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAG7F,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAI9C,mEAAmE;AACnE,MAAM,WAAW,sCAAsC;IACtD;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,gCAAiC,YAAW,aAAa;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAU;gBAEpC,MAAM,CAAC,EAAE,sCAAsC;IAqBrD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;CAOzD"}

package/dist/rules/collectors/ResourceActionScopeRuleCollector.mjs

@@ -1,19 +1,67 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import { HasScope } from "../HasScope.mjs";
+const SCOPELESS_POLICIES = ["deny", "skip"];
 /**
  * Generates a HasScope rule derived from the request action and resource type.
  *
- * When the JWT payload has no `scope` claim (e.g. DID-grant tokens), no rules
- * are generated. The scope rule group is therefore absent from AND-evaluation,
- * allowing other rule groups to decide independently.
+ * ## Scope as capability ceiling
  *
- * OAuth JWTs that carry a `scope` claim are validated as before.
+ * The JWT `scope` claim represents what the session **can request** — a
+ * capability ceiling — not what the session **has been granted**. Whether the
+ * operation is ultimately permitted is determined by the full rule pipeline
+ * (other collectors, resource-owner policy, etc.). This collector enforces the
+ * ceiling only: it produces a `HasScope` rule for the requested
+ * `{action}:{resourceType}`, which must be satisfied by the token's scopes.
+ *
+ * ## Matching
+ *
+ * The emitted `HasScope` compares scopes exactly and case-sensitively. An
+ * issuer that emits bare resource names (`project` rather than `read:project`)
+ * must opt in with `{ allowBareScopeRewrite: true }`; without it a bare scope
+ * satisfies nothing of the `{action}:{resourceType}` form.
+ *
+ * ## Behavior for scopeless tokens
+ *
+ * By default the rule is emitted regardless of whether the token carries a
+ * `scope` claim, so a scopeless token fails it. Dropping the rule instead would
+ * remove the scope group from AND-evaluation, and in a scope-only pipeline that
+ * turns "the token asserts no capability" into "every capability is allowed".
+ *
+ * Flows where the IdP does not issue a `scope` claim (e.g. DID-grant tokens)
+ * must opt out explicitly with `{ scopeless: "skip" }`, and only in a pipeline
+ * where another rule group authorizes the request — otherwise the request is
+ * left with no applicable rule, which the evaluator denies.
+ *
+ * For pipelines that exclusively serve scopeless flows, prefer collectors that
+ * derive rules from identity claims (e.g. DID, `sub`, role) instead.
+ *
+ * See https://github.com/o3co/auth.provider/issues/56 for background on why
+ * the IdP asserts identity, not permissions.
  */
 export class ResourceActionScopeRuleCollector {
+    scopeless;
+    allowBareScopeRewrite;
+    constructor(config) {
+        const scopeless = config?.scopeless ?? "deny";
+        if (!SCOPELESS_POLICIES.includes(scopeless)) {
+            throw new Error(`ResourceActionScopeRuleCollector: scopeless must be one of ${SCOPELESS_POLICIES.join(", ")}, got "${scopeless}"`);
+        }
+        this.scopeless = scopeless;
+        // Validate the raw value before defaulting: `?? false` alone would treat an
+        // explicit `null` as "unset" and silently accept a misconfiguration. Only
+        // an absent key may fall back to the default.
+        const rawRewrite = config?.allowBareScopeRewrite;
+        if (rawRewrite !== undefined && typeof rawRewrite !== "boolean") {
+            throw new Error(`ResourceActionScopeRuleCollector: allowBareScopeRewrite must be a boolean, got "${rawRewrite}"`);
+        }
+        this.allowBareScopeRewrite = rawRewrite ?? false;
+    }
     async collect(context) {
-        if (context.payload.scope === undefined) {
+        if (this.scopeless === "skip" && context.subject.scope === undefined) {
             return [];
         }
         const scope = `${context.action}:${context.resource.resourceType}`;
-        return [new HasScope(scope)];
+        return [new HasScope(scope, { allowBareScopeRewrite: this.allowBareScopeRewrite })];
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/auth.policy-verifier.builtins",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -31,15 +31,18 @@
     }
   },
   "dependencies": {
-    "@o3co/auth.policy-verifier.core": "0.3.1"
+    "@o3co/auth.policy-verifier.core": "0.5.0"
   },
   "devDependencies": {
-    "@types/node": "^25.1.0",
-    "vitest": "^4.1.2"
+    "@types/node": "^26.4.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "prebuild": "rimraf dist",
     "build": "tsc",
-    "test": "vitest run"
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
 }

package/dist/__tests__/collectors/PayloadScopeCollector.test.d.mts

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

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

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

package/dist/__tests__/collectors/PayloadScopeCollector.test.mjs

@@ -1,24 +0,0 @@
-import { ATTR_SCOPES } from "@o3co/auth.policy-verifier.core";
-import { describe, expect, it } from "vitest";
-import { PayloadScopeCollector } from "#/collectors/PayloadScopeCollector.mjs";
-const makeContext = (scope) => ({
-    payload: { scope },
-    resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-    action: "read",
-});
-describe("PayloadScopeCollector", () => {
-    const collector = new PayloadScopeCollector();
-    it("extracts scopes from payload", async () => {
-        const attrs = await collector.collect(makeContext("read:user write:doc"));
-        expect(attrs.get(ATTR_SCOPES)).toEqual(["read:user", "write:doc"]);
-    });
-    it("returns empty array when scope missing", async () => {
-        const ctx = {
-            payload: {},
-            resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-            action: "read",
-        };
-        const attrs = await collector.collect(ctx);
-        expect(attrs.get(ATTR_SCOPES)).toEqual([]);
-    });
-});

package/dist/__tests__/collectors/PayloadSubjectIdCollector.test.d.mts

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

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

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

package/dist/__tests__/collectors/PayloadSubjectIdCollector.test.mjs

@@ -1,33 +0,0 @@
-import { ATTR_CLIENT_ID, ATTR_USER_ID } from "@o3co/auth.policy-verifier.core";
-import { describe, expect, it } from "vitest";
-import { PayloadSubjectIdCollector } from "#/collectors/PayloadSubjectIdCollector.mjs";
-describe("PayloadSubjectIdCollector", () => {
-    const collector = new PayloadSubjectIdCollector();
-    it("extracts userId from payload.sub", async () => {
-        const ctx = {
-            payload: { sub: "u1" },
-            resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-            action: "read",
-        };
-        const attrs = await collector.collect(ctx);
-        expect(attrs.get(ATTR_USER_ID)).toBe("u1");
-    });
-    it("extracts clientId from payload.azp", async () => {
-        const ctx = {
-            payload: { azp: "c1" },
-            resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-            action: "read",
-        };
-        const attrs = await collector.collect(ctx);
-        expect(attrs.get(ATTR_CLIENT_ID)).toBe("c1");
-    });
-    it("returns empty map when neither sub nor azp present", async () => {
-        const ctx = {
-            payload: {},
-            resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-            action: "read",
-        };
-        const attrs = await collector.collect(ctx);
-        expect(attrs.size).toBe(0);
-    });
-});

package/dist/__tests__/collectors/StaticPermissionCollector.test.d.mts

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

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

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

package/dist/__tests__/collectors/StaticPermissionCollector.test.mjs

@@ -1,22 +0,0 @@
-import { ATTR_PERMISSIONS } from "@o3co/auth.policy-verifier.core";
-import { describe, expect, it } from "vitest";
-import { StaticPermissionCollector } from "#/collectors/StaticPermissionCollector.mjs";
-const stubContext = {
-    payload: {},
-    resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-    action: "read",
-};
-describe("StaticPermissionCollector", () => {
-    it("returns configured permissions", async () => {
-        const collector = new StaticPermissionCollector({
-            permissions: ["project:*.perm:read", "document:*.perm:write"],
-        });
-        const attrs = await collector.collect(stubContext);
-        expect(attrs.get(ATTR_PERMISSIONS)).toEqual(["project:*.perm:read", "document:*.perm:write"]);
-    });
-    it("returns empty array when no permissions configured", async () => {
-        const collector = new StaticPermissionCollector({ permissions: [] });
-        const attrs = await collector.collect(stubContext);
-        expect(attrs.get(ATTR_PERMISSIONS)).toEqual([]);
-    });
-});

package/dist/__tests__/collectors/StaticRoleCollector.test.d.mts

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

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

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

package/dist/__tests__/collectors/StaticRoleCollector.test.mjs

@@ -1,24 +0,0 @@
-import { ATTR_ROLES } from "@o3co/auth.policy-verifier.core";
-import { describe, expect, it } from "vitest";
-import { StaticRoleCollector } from "#/collectors/StaticRoleCollector.mjs";
-const stubContext = {
-    payload: {},
-    resource: { raw: "test:1", resourceType: "test", resourceId: "1" },
-    action: "read",
-};
-describe("StaticRoleCollector", () => {
-    it("returns configured roles", async () => {
-        const roles = [
-            { name: "admin", permissions: ["*"] },
-            { name: "viewer", permissions: ["project:*.perm:read"] },
-        ];
-        const collector = new StaticRoleCollector({ roles });
-        const attrs = await collector.collect(stubContext);
-        expect(attrs.get(ATTR_ROLES)).toEqual(roles);
-    });
-    it("returns empty array when no roles configured", async () => {
-        const collector = new StaticRoleCollector({ roles: [] });
-        const attrs = await collector.collect(stubContext);
-        expect(attrs.get(ATTR_ROLES)).toEqual([]);
-    });
-});

package/dist/__tests__/module.test.d.mts

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

package/dist/__tests__/module.test.d.mts.map

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