@o3co/auth.policy-verifier.builtins 0.15.0 → 0.16.1

package/dist/collectors/RequestContextAttributeCollector.d.mts

@@ -14,68 +14,30 @@ export type RequestContextAttributeCollectorConfig = AttributeMappingCollectorCo
 /**
  * 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.
- *
- * ## 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 = [
- *     { from = "tenant.id", to = "tenantId" }
- *     { from = "groups", type = "string[]" }
- *   ] }
- * ```
+ * Core 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 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.
+ *
+ * A mapping's `to` may not name a key any package has reserved: core's five —
+ * `scopes`, `permissions`, `roles`, `userId`, `clientId` — and whatever other
+ * packages reserved before this collector is constructed (cedar's four
+ * `request*` keys, once it is imported). The check is a lookup in core's
+ * registry at construction; a later reservation is not seen. Those keys are
+ * what the engine decides from, written by the deployment, and the request
+ * body must not join them: `AttributePipeline` unions array-valued attributes,
+ * so `{ from = "groups", to = "scopes" }` would quietly add to the token's
+ * scopes; a scalar key written with a different value throws
+ * `AttributeConflictError` and denies, and where its owner writes it only
+ * sometimes (cedar's `requestResourceId` for an id-less resource) the
+ * caller's value stands unopposed. Such a mapping is a configuration error,
+ * refused at construction so the deployment fails at boot. Only the attribute
+ * key is reserved: `{ from = "scopes", to = "requestedScopes" }` is fine.
+ *
+ * Configuration, with an example: the package README, RequestContextAttributeCollector.
  */
 export declare class RequestContextAttributeCollector implements AttributeCollector {
     private readonly mappings;

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

@@ -1 +1 @@
-{"version":3,"file":"RequestContextAttributeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/RequestContextAttributeCollector.mts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACX,kBAAkB,EAElB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EAIzB,MAAM,yBAAyB,CAAC;AAEjC,yDAAyD;AACzD,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GAAG,gBAAgB,CAAC;AAE9D,mEAAmE;AACnE,MAAM,MAAM,sCAAsC,GAAG,+BAA+B,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,qBAAa,gCAAiC,YAAW,kBAAkB;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,MAAM,EAAE,sCAAsC;IAOpD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAQ7D"}
+{"version":3,"file":"RequestContextAttributeCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/RequestContextAttributeCollector.mts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACX,kBAAkB,EAElB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EAIzB,MAAM,yBAAyB,CAAC;AAEjC,yDAAyD;AACzD,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GAAG,gBAAgB,CAAC;AAE9D,mEAAmE;AACnE,MAAM,MAAM,sCAAsC,GAAG,+BAA+B,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gCAAiC,YAAW,kBAAkB;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,MAAM,EAAE,sCAAsC;IAOpD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAQ7D"}

package/dist/collectors/RequestContextAttributeCollector.mjs

@@ -5,75 +5,37 @@ import { parseAttributeMappings, promoteMappings, } from "./_attributeMapping.mj
 /**
  * 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 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 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.
  *
- * 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.
+ * A mapping's `to` may not name a key any package has reserved: core's five —
+ * `scopes`, `permissions`, `roles`, `userId`, `clientId` — and whatever other
+ * packages reserved before this collector is constructed (cedar's four
+ * `request*` keys, once it is imported). The check is a lookup in core's
+ * registry at construction; a later reservation is not seen. Those keys are
+ * what the engine decides from, written by the deployment, and the request
+ * body must not join them: `AttributePipeline` unions array-valued attributes,
+ * so `{ from = "groups", to = "scopes" }` would quietly add to the token's
+ * scopes; a scalar key written with a different value throws
+ * `AttributeConflictError` and denies, and where its owner writes it only
+ * sometimes (cedar's `requestResourceId` for an id-less resource) the
+ * caller's value stands unopposed. Such a mapping is a configuration error,
+ * refused at construction so the deployment fails at boot. Only the attribute
+ * key is reserved: `{ from = "scopes", to = "requestedScopes" }` is fine.
  *
- * ## 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 = [
- *     { from = "tenant.id", to = "tenantId" }
- *     { from = "groups", type = "string[]" }
- *   ] }
- * ```
+ * Configuration, with an example: the package README, RequestContextAttributeCollector.
  */
 export class RequestContextAttributeCollector {
     mappings;
     constructor(config) {
         // Every reserved destination is refused here — the source is the caller's
         // body. The declaration parsing is shared with the collector that reads
-        // verified claims (#219); the policy is this collector's own.
+        // verified claims; the policy is this collector's own.
         this.mappings = parseAttributeMappings("RequestContextAttributeCollector", config, refusal);
     }
     async collect(context) {
@@ -87,17 +49,13 @@ export class RequestContextAttributeCollector {
     }
 }
 /**
- * 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.
+ * Why this mapping is refused, in the words of whoever owns the key. Core's
+ * five get the trust boundary they sit on; another package's keys get its name
+ * and its own stated reason, so the operator knows whose docs to read.
  *
- * 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.
+ * The suggested rename is drawn from core's registry rather than always
+ * `request<Key>`: `request*` is cedar's namespace, and advice landing there
+ * would be refused by this same guard.
  */
 function refusal(index, reservation) {
     const { key, owner, reason } = reservation;
@@ -111,8 +69,9 @@ function refusal(index, reservation) {
         : `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. ";
+            "caller-supplied: where both write a scalar key the values collide and every such request is " +
+            "denied, where both write a list key the caller's entries join the package's, 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)}").`;
 }

package/dist/collectors/StaticPermissionCollector.d.mts

@@ -4,19 +4,17 @@ import type { AttributeCollector, Attributes, CollectorContext } from "@o3co/aut
  * `ATTR_PERMISSIONS`, independent of the JWT payload. Useful for
  * environments where permissions are static per deployment.
  *
- * The list is copied at construction (#255): a caller that mutates the config
- * or its array afterwards changes nothing this collector emits.
+ * The list is copied at construction: a caller that mutates the config or its
+ * array afterwards changes nothing this collector emits.
  *
- * Only an array is accepted (#264). Anything else — a missing field, `null`, a
+ * Only an array is accepted. Anything else — a missing field, `null`, a
  * number, an object, a string — is refused with a `TypeError` naming the
  * collector and the field, so a misconfigured deployment fails at boot. A
- * string is the case that matters: it is iterable, so copying it would split
- * `"posts.*"` into single characters, and `HasPermission` honours a lone `*`
- * as grant-all.
+ * copied string would split `"posts.*"` into single characters, and
+ * `HasPermission` honours a lone `*` as grant-all.
  *
- * The entries are not checked, and a non-string one is copied as it is. It is
- * inert: `HasPermission` skips every permission that is not a string, so such
- * an entry matches no requirement and grants nothing.
+ * Entries are not checked; a non-string one is copied as it is and is inert,
+ * since `HasPermission` skips every permission that is not a string.
  */
 export declare class StaticPermissionCollector implements AttributeCollector {
     private readonly permissions;

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

@@ -1 +1 @@
-{"version":3,"file":"StaticPermissionCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/StaticPermissionCollector.mts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;gBAEpC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE;IAUvC,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":"AAQA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;gBAEpC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE;IAUvC,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAG9D"}

package/dist/collectors/StaticPermissionCollector.mjs

@@ -6,19 +6,17 @@ import { ATTR_PERMISSIONS } from "@o3co/auth.policy-verifier.core";
  * `ATTR_PERMISSIONS`, independent of the JWT payload. Useful for
  * environments where permissions are static per deployment.
  *
- * The list is copied at construction (#255): a caller that mutates the config
- * or its array afterwards changes nothing this collector emits.
+ * The list is copied at construction: a caller that mutates the config or its
+ * array afterwards changes nothing this collector emits.
  *
- * Only an array is accepted (#264). Anything else — a missing field, `null`, a
+ * Only an array is accepted. Anything else — a missing field, `null`, a
  * number, an object, a string — is refused with a `TypeError` naming the
  * collector and the field, so a misconfigured deployment fails at boot. A
- * string is the case that matters: it is iterable, so copying it would split
- * `"posts.*"` into single characters, and `HasPermission` honours a lone `*`
- * as grant-all.
+ * copied string would split `"posts.*"` into single characters, and
+ * `HasPermission` honours a lone `*` as grant-all.
  *
- * The entries are not checked, and a non-string one is copied as it is. It is
- * inert: `HasPermission` skips every permission that is not a string, so such
- * an entry matches no requirement and grants nothing.
+ * Entries are not checked; a non-string one is copied as it is and is inert,
+ * since `HasPermission` skips every permission that is not a string.
  */
 export class StaticPermissionCollector {
     permissions;

package/dist/collectors/StaticRoleCollector.d.mts

@@ -4,18 +4,17 @@ import type { AttributeCollector, Attributes, CollectorContext, Role } from "@o3
  * `ATTR_ROLES`, independent of the JWT payload. Each role bundles a name and
  * the permissions it implies.
  *
- * The list is copied at construction, and so is each role in it and each
- * role's `permissions` array (#255): a caller that mutates the config, its
- * array or a `Role` in it afterwards changes nothing this collector emits.
+ * The list, each role in it and each role's `permissions` array are copied at
+ * construction: a caller that mutates the config, its array or a `Role` in it
+ * afterwards changes nothing this collector emits.
  *
- * Only an array is accepted (#264). Anything else — a missing field, `null`, a
- * number, an object, a string — is refused with a `TypeError` naming the
- * collector and the field, so a misconfigured deployment fails at boot. A
- * string is iterable and would otherwise be split into single characters, as
- * it would be in `StaticPermissionCollector`.
+ * Only an array is accepted. Anything else — a missing field, `null`, a
+ * number, an object, a string (which a copy would split into characters) — is
+ * refused with a `TypeError` naming the collector and the field, so a
+ * misconfigured deployment fails at boot.
  *
- * The entries are not checked: a malformed `Role` entry is copied as it is
- * (see `copyRole`). It is inert: `HasPermission` ignores a role that is not an
+ * Entries are not checked: a malformed `Role` is copied as it is (see
+ * `copyRole`) and is inert, since `HasPermission` ignores a role that is not an
  * object or whose `permissions` is not an array, and a non-string permission
  * inside a role. Each collect returns a shallow copy of the list, so its `Role`
  * copies are shared between the outputs of different collects.

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

@@ -1 +1 @@
-{"version":3,"file":"StaticRoleCollector.d.mts","sourceRoot":"","sources":["../../src/collectors/StaticRoleCollector.mts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,IAAI,EACJ,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;gBAE5B,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE;IAU/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":"AAQA,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,IAAI,EACJ,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;gBAE5B,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE;IAU/B,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAG9D"}

package/dist/collectors/StaticRoleCollector.mjs

@@ -6,18 +6,17 @@ import { ATTR_ROLES } from "@o3co/auth.policy-verifier.core";
  * `ATTR_ROLES`, independent of the JWT payload. Each role bundles a name and
  * the permissions it implies.
  *
- * The list is copied at construction, and so is each role in it and each
- * role's `permissions` array (#255): a caller that mutates the config, its
- * array or a `Role` in it afterwards changes nothing this collector emits.
+ * The list, each role in it and each role's `permissions` array are copied at
+ * construction: a caller that mutates the config, its array or a `Role` in it
+ * afterwards changes nothing this collector emits.
  *
- * Only an array is accepted (#264). Anything else — a missing field, `null`, a
- * number, an object, a string — is refused with a `TypeError` naming the
- * collector and the field, so a misconfigured deployment fails at boot. A
- * string is iterable and would otherwise be split into single characters, as
- * it would be in `StaticPermissionCollector`.
+ * Only an array is accepted. Anything else — a missing field, `null`, a
+ * number, an object, a string (which a copy would split into characters) — is
+ * refused with a `TypeError` naming the collector and the field, so a
+ * misconfigured deployment fails at boot.
  *
- * The entries are not checked: a malformed `Role` entry is copied as it is
- * (see `copyRole`). It is inert: `HasPermission` ignores a role that is not an
+ * Entries are not checked: a malformed `Role` is copied as it is (see
+ * `copyRole`) and is inert, since `HasPermission` ignores a role that is not an
  * object or whose `permissions` is not an array, and a non-string permission
  * inside a role. Each collect returns a shallow copy of the list, so its `Role`
  * copies are shared between the outputs of different collects.
@@ -40,7 +39,7 @@ export class StaticRoleCollector {
  *
  * Nothing about the entry is validated here, and a malformed one keeps its
  * shape rather than being coerced — `HasPermission` ignores a role that is not
- * an object or whose `permissions` is not an array (#180), and spreading a bare
+ * an object or whose `permissions` is not an array, and spreading a bare
  * string under `permissions` would splay it into characters it then honours.
  */
 function copyRole(role) {

package/dist/collectors/_attributeMapping.d.mts

@@ -1,4 +1,5 @@
 import type { AttributeKeyReservation, Attributes } from "@o3co/auth.policy-verifier.core";
+import "../keys.mjs";
 /** Types a field may be promoted as. */
 export type AttributeMappingType = "string" | "number" | "boolean" | "string[]";
 export declare const ATTRIBUTE_MAPPING_TYPES: readonly AttributeMappingType[];

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

@@ -1 +1 @@
-{"version":3,"file":"_attributeMapping.d.mts","sourceRoot":"","sources":["../../src/collectors/_attributeMapping.mts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAG3F,wCAAwC;AACxC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAEhF,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAKlE,CAAC;AAEF,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,WAAW,+BAA+B;IAC/C,wDAAwD;IACxD,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC/B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,uBAAuB,KAChC,MAAM,GAAG,SAAS,CAAC;AAExB;;;GAGG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,+BAA+B,GAAG,SAAS,EACnD,iBAAiB,EAAE,iBAAiB,GAClC,wBAAwB,EAAE,CA4B5B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAW/E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAC7C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,UAAU,CASZ"}
+{"version":3,"file":"_attributeMapping.d.mts","sourceRoot":"","sources":["../../src/collectors/_attributeMapping.mts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAI3F,OAAO,aAAa,CAAC;AAErB,wCAAwC;AACxC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAEhF,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAKlE,CAAC;AAEF,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,WAAW,+BAA+B;IAC/C,wDAAwD;IACxD,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC/B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,uBAAuB,KAChC,MAAM,GAAG,SAAS,CAAC;AAExB;;;GAGG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,+BAA+B,GAAG,SAAS,EACnD,iBAAiB,EAAE,iBAAiB,GAClC,wBAAwB,EAAE,CA4B5B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAW/E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAC7C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,UAAU,CASZ"}

package/dist/collectors/_attributeMapping.mjs

@@ -1,6 +1,9 @@
 // SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
 // SPDX-License-Identifier: Apache-2.0
 import { attributeKeyReservation } from "@o3co/auth.policy-verifier.core";
+// This package's own keys are reserved by loading their module, which a
+// mapping collector must not depend on the package entry to have done.
+import "../keys.mjs";
 export const ATTRIBUTE_MAPPING_TYPES = [
     "string",
     "number",

package/dist/collectors/_claims.d.mts

@@ -12,9 +12,8 @@ export declare function resolveClaimName(collector: string, raw: unknown, fallba
  * Reads a scope claim as a list. The OAuth `scope` claim is a space-delimited
  * string; Okta's `scp` and Auth0's `permissions` are arrays of strings. Either
  * shape yields the non-empty entries. Anything else — absent, a number, a list
- * carrying a non-string — asserts no capability at all, the way a non-string
- * `scope` never did: fail closed rather than pick the strings out of a value
- * that is not a scope list.
+ * carrying a non-string — asserts no capability at all: fail closed rather
+ * than pick the strings out of a value that is not a scope list.
  */
 export declare function scopesFrom(value: unknown): string[];
 //# sourceMappingURL=_claims.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"_claims.d.mts","sourceRoot":"","sources":["../../src/collectors/_claims.mts"],"names":[],"mappings":"AAaA,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAMnD"}
+{"version":3,"file":"_claims.d.mts","sourceRoot":"","sources":["../../src/collectors/_claims.mts"],"names":[],"mappings":"AAaA,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAMnD"}

package/dist/collectors/_claims.mjs

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
 // SPDX-License-Identifier: Apache-2.0
 /*
- * Which claim carries the scopes, and how its value is read (#219).
+ * Which claim carries the scopes, and how its value is read.
  * `PayloadScopeCollector` and `ResourceActionScopeRuleCollector` share the
  * default claim name and refuse the same bad `claim` option; only
  * `PayloadScopeCollector` reads the value (`scopesFrom`), while the rule
@@ -30,9 +30,8 @@ export function resolveClaimName(collector, raw, fallback) {
  * Reads a scope claim as a list. The OAuth `scope` claim is a space-delimited
  * string; Okta's `scp` and Auth0's `permissions` are arrays of strings. Either
  * shape yields the non-empty entries. Anything else — absent, a number, a list
- * carrying a non-string — asserts no capability at all, the way a non-string
- * `scope` never did: fail closed rather than pick the strings out of a value
- * that is not a scope list.
+ * carrying a non-string — asserts no capability at all: fail closed rather
+ * than pick the strings out of a value that is not a scope list.
  */
 export function scopesFrom(value) {
     if (typeof value === "string")

package/dist/delegation/range.d.mts

@@ -0,0 +1,48 @@
+/** The claim RFC 9396 carries the entries in, and the default. */
+export declare const DEFAULT_AUTHORIZATION_DETAILS_CLAIM = "authorization_details";
+/** One element of a path: a type, and an id when the path names one. */
+export interface RangeElement {
+    type: string;
+    id?: string;
+}
+/**
+ * Reads `path` as `(type(:id)?.)*action`, or `null` when it is not one:
+ *
+ * - `type` and `action` are `[a-z][a-z0-9_]*`;
+ * - `id` is `[A-Za-z0-9_~-]`, any other character percent-encoded with
+ *   upper-case hex. An id is compared as written, so `%41` and `A` are two
+ *   ids: the issuer and the resource must encode alike;
+ * - the action, the last element, carries no id.
+ */
+export declare function parseRangePath(path: string): RangeElement[] | null;
+/**
+ * The requested path — the raw resource, then the action — or `null` when the
+ * action is not one action of the grammar. The action is checked on its own
+ * before the join: an action of several elements (`report.delete`) would
+ * re-split the joined path, so a request on the parent `project:p1` would
+ * read as one on `project:p1.report`, which a range may contain.
+ */
+export declare function requestedRangePath(resource: string, action: string): string | null;
+/**
+ * Whether the range entry `entry` contains the requested `path`: a
+ * segment-wise prefix of it, each element of the same type, and an element
+ * that names no id containing the same type with any id. The entry's last
+ * element is compared as a type whether it names an action or not, so
+ * `a:1.run` contains `a:1.run.more`. Either side outside the grammar contains
+ * nothing.
+ */
+export declare function rangeContains(entry: string, path: string): boolean;
+/**
+ * The claim's entries of `type`, or `null` when the token has no range: the
+ * claim is absent, or a list of RFC 9396 entries none of which is of the type.
+ * A token cannot shed its range by spelling it badly: an entry of the type
+ * counts however malformed its path, and a claim present in another shape — not
+ * a list, or a list holding something that is not an entry object — is a range
+ * with no entries, which contains nothing.
+ */
+export declare function entriesOfType(claim: unknown, type: string): object[] | null;
+/** The entries' paths that are in the grammar; the rest are left out, which narrows the range. */
+export declare function rangePaths(entries: object[]): string[];
+/** Resolves a collector's `type` option, which has no default: it is the deployment's delegation type. */
+export declare function resolveRangeType(collector: string, raw: unknown): string;
+//# sourceMappingURL=range.d.mts.map

package/dist/delegation/range.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range.d.mts","sourceRoot":"","sources":["../../src/delegation/range.mts"],"names":[],"mappings":"AAeA,kEAAkE;AAClE,eAAO,MAAM,mCAAmC,0BAA0B,CAAC;AAE3E,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAOD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,IAAI,CAiBlE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CASlE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAK3E;AAMD,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAItD;AAED,0GAA0G;AAC1G,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAOxE"}

package/dist/delegation/range.mjs

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: 2026 1o1 Co. Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * A delegated token's range, as the provider-verifier claims contract states
+ * it (o3co/auth, docs/claims-contract.md): RFC 9396 `authorization_details`
+ * entries of one type, each carrying a path in the grammar
+ * `(type(:id)?.)*action`, and the rule by which an entry contains a requested
+ * path. Shared by `DelegationRangeCollector`, which reads the range out of
+ * the token, `DelegationRangeRuleCollector`, which decides whether a token
+ * has one, and `WithinDelegationRange`, which decides containment. Nothing is
+ * normalized: a path is compared as written, as `HasScope` compares scopes.
+ * The attribute key the range travels under is `../keys.mts`'s.
+ */
+/** The claim RFC 9396 carries the entries in, and the default. */
+export const DEFAULT_AUTHORIZATION_DETAILS_CLAIM = "authorization_details";
+/** A type, or the action that ends a path. */
+const NAME = /^[a-z][a-z0-9_]*$/;
+/** An id: unreserved characters, anything else percent-encoded in upper-case hex. */
+const ID = /^(?:[A-Za-z0-9_~-]|%[0-9A-F]{2})+$/;
+/**
+ * Reads `path` as `(type(:id)?.)*action`, or `null` when it is not one:
+ *
+ * - `type` and `action` are `[a-z][a-z0-9_]*`;
+ * - `id` is `[A-Za-z0-9_~-]`, any other character percent-encoded with
+ *   upper-case hex. An id is compared as written, so `%41` and `A` are two
+ *   ids: the issuer and the resource must encode alike;
+ * - the action, the last element, carries no id.
+ */
+export function parseRangePath(path) {
+    if (typeof path !== "string" || path === "")
+        return null;
+    const parts = path.split(".");
+    const elements = [];
+    for (const [index, part] of parts.entries()) {
+        const pieces = part.split(":");
+        if (pieces.length > 2)
+            return null;
+        const [type, id] = pieces;
+        if (!NAME.test(type))
+            return null;
+        if (id === undefined) {
+            elements.push({ type });
+            continue;
+        }
+        if (index === parts.length - 1 || !ID.test(id))
+            return null;
+        elements.push({ type, id });
+    }
+    return elements;
+}
+/**
+ * The requested path — the raw resource, then the action — or `null` when the
+ * action is not one action of the grammar. The action is checked on its own
+ * before the join: an action of several elements (`report.delete`) would
+ * re-split the joined path, so a request on the parent `project:p1` would
+ * read as one on `project:p1.report`, which a range may contain.
+ */
+export function requestedRangePath(resource, action) {
+    return NAME.test(action) ? `${resource}.${action}` : null;
+}
+/**
+ * Whether the range entry `entry` contains the requested `path`: a
+ * segment-wise prefix of it, each element of the same type, and an element
+ * that names no id containing the same type with any id. The entry's last
+ * element is compared as a type whether it names an action or not, so
+ * `a:1.run` contains `a:1.run.more`. Either side outside the grammar contains
+ * nothing.
+ */
+export function rangeContains(entry, path) {
+    const within = parseRangePath(entry);
+    const requested = parseRangePath(path);
+    if (within === null || requested === null || within.length > requested.length)
+        return false;
+    return within.every((element, index) => element.type === requested[index].type &&
+        (element.id === undefined || element.id === requested[index].id));
+}
+/**
+ * The claim's entries of `type`, or `null` when the token has no range: the
+ * claim is absent, or a list of RFC 9396 entries none of which is of the type.
+ * A token cannot shed its range by spelling it badly: an entry of the type
+ * counts however malformed its path, and a claim present in another shape — not
+ * a list, or a list holding something that is not an entry object — is a range
+ * with no entries, which contains nothing.
+ */
+export function entriesOfType(claim, type) {
+    if (claim === undefined)
+        return null;
+    if (!Array.isArray(claim) || !claim.every(isEntryObject))
+        return [];
+    const entries = claim.filter((entry) => entry.type === type);
+    return entries.length > 0 ? entries : null;
+}
+function isEntryObject(entry) {
+    return typeof entry === "object" && entry !== null && !Array.isArray(entry);
+}
+/** The entries' paths that are in the grammar; the rest are left out, which narrows the range. */
+export function rangePaths(entries) {
+    return entries
+        .map((entry) => entry.path)
+        .filter((path) => typeof path === "string" && parseRangePath(path) !== null);
+}
+/** Resolves a collector's `type` option, which has no default: it is the deployment's delegation type. */
+export function resolveRangeType(collector, raw) {
+    if (typeof raw !== "string" || raw === "") {
+        throw new Error(`${collector}: type must be the authorization_details type the delegation range is carried under, a non-empty string`);
+    }
+    return raw;
+}