@authup/access 1.0.0-beta.65 → 1.0.0-beta.67

package/dist/index.d.mts

@@ -3,12 +3,14 @@ import { DecisionStrategy } from "@authup/kit";
 import { ICondition } from "@rapiq/core";
 import { Issue, IssueGroup, IssueItem } from "@ebec/core";
 import { Container } from "validup";
+import { z } from "zod";
 import { MongoFiltersParser, MongoFiltersParserInput } from "@rapiq/parser-mongo";
 //#region src/policy/data.d.ts
 export interface IPolicyData {
   set(key: string, value: unknown): void;
   has(key: string): boolean;
   get<T = unknown>(key: string): T;
+  delete(key: string): void;
   isValidated(key: string): boolean;
   setValidated(key: string): void;
   clone(): IPolicyData;
@@ -20,12 +22,25 @@ export declare class PolicyData implements IPolicyData {
   set<T = unknown>(key: string, value: T): void;
   get<T = unknown>(key: string): T;
   has(key: string): boolean;
+  delete(key: string): void;
   setValidated(key: string): void;
   isValidated(key: string): boolean;
   clone(): PolicyData;
 }
 //#endregion
 //#region src/policy/evaluation/context/types.d.ts
+/**
+ * Receives the instants at which a clock-dependent verdict could change.
+ *
+ * A `date` or `time` policy that fell back to the real clock (no `date` / `time`
+ * key in the bag) reports the next strictly-future instant its own verdict could
+ * flip, from inside the evaluation walk that already runs. A caller that caches
+ * an answer derived from such a walk learns when to stop trusting it. Reports may
+ * be early (conservative) but never late, and `invert` does not move them.
+ */
+export type PolicyTransitionSink = {
+  report(at: Date): void;
+};
 export type PolicyEvaluationContext = {
   readonly evaluators: Record<string, IPolicyEvaluator>;
   readonly path: (string | number)[];
@@ -39,12 +54,40 @@ export type PolicyEvaluationContext = {
    * query-build callers opt in.
    */
   readonly withConditions: boolean;
+  /**
+   * Row column the realm reach is LOWERED onto, for a caller whose rows carry the
+   * realm under another name (a junction's `roleRealmId` / `clientRealmId` / …).
+   * Default `realmId`. It reaches `RealmMatchPolicyEvaluator` scope mode as
+   * `attributeName`, which that mode reads only while lowering — settled
+   * evaluation takes the resource realm from the `realmMatch` data key and never
+   * consults a column name, so this can never change an evaluate() outcome.
+   */
+  readonly realmAttributeName?: string;
+  /**
+   * Optional receiver of clock transitions (see {@link PolicyTransitionSink}).
+   * Nested evaluations inherit it, since every walk propagates the context by
+   * spread.
+   */
+  readonly transitions?: PolicyTransitionSink;
 };
 export type PolicyEvaluationContextInput = Partial<PolicyEvaluationContext>;
 //#endregion
 //#region src/policy/evaluation/context/define.d.ts
 export declare function definePolicyEvaluationContext(input?: PolicyEvaluationContextInput): PolicyEvaluationContext;
 //#endregion
+//#region src/policy/evaluation/context/transition.d.ts
+export type PolicyTransitionCollector = PolicyTransitionSink & {
+  /**
+   * The earliest reported instant, or undefined when nothing reported one.
+   */
+  readonly next: Date | undefined;
+};
+/**
+ * A sink keeping the earliest reported instant, which is the moment an answer
+ * built from every evaluation it was handed to stops being current.
+ */
+export declare function createPolicyTransitionCollector(): PolicyTransitionCollector;
+//#endregion
 //#region src/policy/evaluation/types.d.ts
 export type PolicyEvaluators = Record<string, IPolicyEvaluator>;
 export type PolicyEvaluationResult = {
@@ -100,6 +143,10 @@ export interface IPolicyEvaluator {
 }
 //#endregion
 //#region src/policy/types.d.ts
+/**
+ * A policy type's configuration validator, keyed by the type it validates.
+ */
+export type PolicyValidators = Record<string, Container<Record<string, any>>>;
 export type BasePolicy<T extends string = string> = {
   /**
    * Type describing the policy.
@@ -322,22 +369,6 @@ export declare class IdentityPolicyEvaluator implements IPolicyEvaluator {
   evaluate(value: Record<string, any>, ctx: PolicyEvaluationContext): Promise<PolicyEvaluationResult>;
 }
 //#endregion
-//#region src/policy/built-in/permission-binding/types.d.ts
-export interface PermissionBindingPolicy extends BasePolicy {}
-//#endregion
-//#region src/policy/built-in/permission-binding/validator.d.ts
-export declare class PermissionBindingPolicyValidator extends Container<PermissionBindingPolicy> {
-  initialize(): void;
-}
-//#endregion
-//#region src/policy/built-in/permission-binding/module.d.ts
-export declare class PermissionBindingPolicyEvaluator implements IPolicyEvaluator {
-  protected validator: PermissionBindingPolicyValidator;
-  constructor();
-  requires(): string[];
-  evaluate(value: Record<string, any>): Promise<PolicyEvaluationResult>;
-}
-//#endregion
 //#region src/permission/realm-scope/constants.d.ts
 /**
  * Actor-relative realm reach of a permission grant.
@@ -380,7 +411,55 @@ export declare function minRealmScope(values: Array<`${RealmScope}` | null | und
  * multiple realms) requires the scope to reach EVERY listed realm (unanimous, fail-closed),
  * so any app/entity can express its realm via one or many keys under the canonical contract.
  */
-export declare function realmScopeMatches(scope: `${RealmScope}` | null | undefined, resourceRealmId: string | string[] | null | undefined, identityRealmId: string | null | undefined, identityRealmName?: string | null): boolean;
+export declare function realmScopeMatches(scope: `${RealmScope}` | null | undefined, resourceRealmId: string | Array<string | null> | null | undefined, identityRealmId: string | null | undefined, identityRealmName?: string | null): boolean;
+//#endregion
+//#region src/permission/types.d.ts
+export type BasePermission = {
+  name: string;
+  clientId?: string | null;
+  realmId?: string | null;
+  decisionStrategy?: `${DecisionStrategy}` | null;
+};
+/**
+ * A raw permission grant: one permission with its policies and realm reach, as loaded from a
+ * role/identity junction. `aggregatePermissionPolicyBindings` groups these per permission into
+ * a `PermissionPolicyBindingAggregated` (the lossless disjunction of grants).
+ */
+export type PermissionPolicyBinding = {
+  permission: BasePermission;
+  policies?: BasePolicy[];
+  /**
+   * Relative realm reach of this grant (none/own/ownOrNull/any). Absent coerces to the
+   * most restrictive `own` (fail-closed). NOT part of the binding identity key
+   * (see isPermissionPolicyBindingEqual).
+   */
+  realmScope?: `${RealmScope}`;
+};
+/**
+ * One disjunction term of an aggregated binding: a single grant's realm reach paired with its
+ * own (single) policy. A disjunction-aware consumer ORs `realmScopeMatches(realmScope) ∧ policy`
+ * across the grants of a permission.
+ */
+export type PermissionGrant = {
+  /** Relative realm reach (none/own/ownOrNull/any), normalized — fail-closed default `own`. */
+  realmScope: `${RealmScope}`;
+  /**
+   * The grant's policy: the raw junction policy (its `id` preserved, for propagation) for a
+   * single-policy grant, a composite for a multi-policy (Layer-1) binding, or `undefined`
+   * when the grant carries no restriction.
+   */
+  policy?: BasePolicy;
+};
+/**
+ * A permission together with the actor's disjunction of grants for it. Output of
+ * `aggregatePermissionPolicyBindings` — the honest, lossless replacement for the collapsed
+ * `PermissionPolicyBinding` (no top-level realmScope/policies; the access decision is the
+ * OR over `grants`).
+ */
+export type PermissionPolicyBindingAggregated = {
+  permission: BasePermission;
+  grants: PermissionGrant[];
+};
 //#endregion
 //#region src/policy/built-in/realm-match/types.d.ts
 export interface RealmMatchPolicy extends BasePolicy {
@@ -438,6 +517,37 @@ export declare class RealmMatchPolicyEvaluator implements IPolicyEvaluator {
   evaluate(value: Record<string, any>, ctx: PolicyEvaluationContext): Promise<PolicyEvaluationResult>;
 }
 //#endregion
+//#region src/policy/built-in/permission-binding/types.d.ts
+export interface PermissionBindingPolicy extends BasePolicy {}
+//#endregion
+//#region src/policy/built-in/permission-binding/validator.d.ts
+export declare class PermissionBindingPolicyValidator extends Container<PermissionBindingPolicy> {
+  initialize(): void;
+}
+//#endregion
+//#region src/policy/built-in/permission-binding/identity-evaluator.d.ts
+type IdentityPermissionProvider = {
+  getFor(identity: IdentityPolicyData): Promise<PermissionPolicyBinding[]>;
+};
+export declare class IdentityPermissionBindingPolicyEvaluator implements IPolicyEvaluator {
+  protected validator: PermissionBindingPolicyValidator;
+  protected identityEvaluator: IdentityPolicyEvaluator;
+  protected realmMatchEvaluator: RealmMatchPolicyEvaluator;
+  protected identityPermissionProvider: IdentityPermissionProvider;
+  constructor(identityPermissionProvider: IdentityPermissionProvider);
+  requires(): string[];
+  accessData(ctx: PolicyEvaluationContext): Promise<PermissionPolicyBindingAggregated | null>;
+  evaluate(value: Record<string, any>, ctx: PolicyEvaluationContext): Promise<PolicyEvaluationResult>;
+}
+//#endregion
+//#region src/policy/built-in/permission-binding/module.d.ts
+export declare class PermissionBindingPolicyEvaluator implements IPolicyEvaluator {
+  protected validator: PermissionBindingPolicyValidator;
+  constructor();
+  requires(): string[];
+  evaluate(value: Record<string, any>): Promise<PolicyEvaluationResult>;
+}
+//#endregion
 //#region src/policy/built-in/time/constants.d.ts
 export declare enum TimePolicyInterval {
   DAILY = "daily",
@@ -565,6 +675,16 @@ export declare const PolicyDefaultEvaluators: {
   readonly realmMatch: RealmMatchPolicyEvaluator;
   readonly time: TimePolicyEvaluator;
 };
+/**
+ * The configuration validator of every built-in policy type, keyed like
+ * `PolicyDefaultEvaluators`. It is what `projectAuthorizationPolicy` runs a
+ * node through, so a type absent here cannot travel in the authorization
+ * catalog. The registry is open like the evaluator one (#3635): spread it and
+ * add a custom type's validator to let that type travel. It is frozen, since
+ * a write into it would make the type projectable for every caller in the
+ * process.
+ */
+export declare const PolicyDefaultValidators: Readonly<PolicyValidators>;
 //#endregion
 //#region src/policy/input.d.ts
 /**
@@ -603,54 +723,6 @@ export declare class PermissionError extends AuthupError {
 //#region src/permission/error/check.d.ts
 export declare function isPermissionError(input: unknown): input is PermissionError;
 //#endregion
-//#region src/permission/types.d.ts
-export type BasePermission = {
-  name: string;
-  clientId?: string | null;
-  realmId?: string | null;
-  decisionStrategy?: `${DecisionStrategy}` | null;
-};
-/**
- * A raw permission grant: one permission with its policies and realm reach, as loaded from a
- * role/identity junction. `aggregatePermissionPolicyBindings` groups these per permission into
- * a `PermissionPolicyBindingAggregated` (the lossless disjunction of grants).
- */
-export type PermissionPolicyBinding = {
-  permission: BasePermission;
-  policies?: BasePolicy[];
-  /**
-   * Relative realm reach of this grant (none/own/ownOrNull/any). Absent coerces to the
-   * most restrictive `own` (fail-closed). NOT part of the binding identity key
-   * (see isPermissionPolicyBindingEqual).
-   */
-  realmScope?: `${RealmScope}`;
-};
-/**
- * One disjunction term of an aggregated binding: a single grant's realm reach paired with its
- * own (single) policy. A disjunction-aware consumer ORs `realmScopeMatches(realmScope) ∧ policy`
- * across the grants of a permission.
- */
-export type PermissionGrant = {
-  /** Relative realm reach (none/own/ownOrNull/any), normalized — fail-closed default `own`. */
-  realmScope: `${RealmScope}`;
-  /**
-   * The grant's policy: the raw junction policy (its `id` preserved, for propagation) for a
-   * single-policy grant, a composite for a multi-policy (Layer-1) binding, or `undefined`
-   * when the grant carries no restriction.
-   */
-  policy?: BasePolicy;
-};
-/**
- * A permission together with the actor's disjunction of grants for it. Output of
- * `aggregatePermissionPolicyBindings` — the honest, lossless replacement for the collapsed
- * `PermissionPolicyBinding` (no top-level realmScope/policies; the access decision is the
- * OR over `grants`).
- */
-export type PermissionPolicyBindingAggregated = {
-  permission: BasePermission;
-  grants: PermissionGrant[];
-};
-//#endregion
 //#region src/permission/helpers/aggregate.d.ts
 /**
  * Group raw permission-policy bindings by permission key into the actor's disjunction of
@@ -726,6 +798,13 @@ export type PermissionEvaluationOptions = {
    *   (`preEvaluate()`): only a tree that settles false with the current bag denies.
    */
   pendingPolicies?: 'deny' | 'permit';
+  /**
+   * Receives the instants at which a clock-dependent policy (`date`, `time`)
+   * in an evaluated tree could change its verdict, so a caller caching the
+   * outcome knows when it expires. Handed to every policy evaluation this call
+   * runs; a policy-free grant evaluates nothing and reports nothing.
+   */
+  transitions?: PolicyTransitionSink;
 };
 export type PermissionEvaluationContext = {
   name: string | string[];
@@ -748,6 +827,14 @@ export type PermissionCompileContext = {
    * compiled condition ranges over.
    */
   data?: PolicyData;
+  /**
+   * Row column the realm reach is lowered onto, when the rows this compilation
+   * ranges over carry their realm under another name — a junction's owner-realm
+   * key (`roleRealmId`, `clientRealmId`, …). Default `realmId`. Affects the
+   * `conditional` condition only; the per-row `post` fallback still reads the
+   * realm from the `realmMatch` data key its caller supplies.
+   */
+  realmAttributeName?: string;
 };
 /**
  * Outcome of compiling a permission's policy trees against the knowns bag
@@ -799,4 +886,409 @@ export declare class PermissionEvaluator implements IPermissionEvaluator {
   compile(ctx: PermissionCompileContext): Promise<PermissionCompileResult>;
 }
 //#endregion
+//#region src/permission/authorization/error.d.ts
+export declare const AUTHORIZATION_CATALOG_STALE_ERROR_INSTANCE: unique symbol;
+/**
+ * A grant references a definition or a policy the supplied catalog does not
+ * carry: the caller's cached catalog predates the definition or the junction
+ * row and must be refetched. A definition the catalog carries with
+ * `policies: null`, and one whose tree this copy cannot project, are not
+ * stale but unevaluable, and a grant of either is dropped.
+ *
+ * Recognize it with `isAuthorizationCatalogStaleError`, never `instanceof`:
+ * this package is a plain caret dependency of several workspaces, so a
+ * consumer tree may resolve two copies of it and turn the one recoverable
+ * state into an unrecoverable one.
+ */
+export declare class AuthorizationCatalogStaleError extends AuthupError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/permission/authorization/check.d.ts
+/**
+ * Marker-only: the error carries no code of its own, and it never crosses a
+ * wire boundary, so there is no shape to fall back to.
+ */
+export declare function isAuthorizationCatalogStaleError(input: unknown): input is AuthorizationCatalogStaleError;
+//#endregion
+//#region src/permission/authorization/types.d.ts
+/**
+ * One policy tree node as it travels: the type's configuration keys (the output
+ * of that type's validator), `invert`, and for a composite its children inline.
+ */
+export type AuthorizationPolicy = {
+  type: string;
+  invert?: boolean | null;
+  children?: AuthorizationPolicy[];
+  [key: string]: unknown;
+};
+export type AuthorizationDefinition = {
+  name: string;
+  realm_id: string | null;
+  client_id: string | null;
+  decision_strategy: `${DecisionStrategy}` | null;
+  /**
+   * The definition layer: the ids of the policy trees bound to the permission
+   * definition (`auth_permission_policies`). Empty means unrestricted at this
+   * layer. `null` means the server could not project one of those trees onto
+   * the wire (a policy type the catalog does not carry, or a configuration
+   * its validator refuses): the definition exists, a consumer cannot evaluate
+   * it and denies it, dropping every grant of it, until the policy is fixed.
+   */
+  policies: string[] | null;
+};
+/**
+ * Identity-free and cacheable: every permission definition with its policy trees.
+ */
+export type AuthorizationCatalog = {
+  /**
+   * Every policy tree a definition or a grant can name, keyed by the tree's
+   * own id and present exactly once however many of them reference it.
+   */
+  policies: Record<string, AuthorizationPolicy>;
+  permissions: AuthorizationDefinition[];
+};
+/**
+ * One raw grant of an identity as the introspection endpoints report it: the
+ * permission namespace it names, its realm reach and the junction policy ids.
+ * Structurally the extended `OAuth2TokenPermission` of `@authup/specs` (this
+ * package does not depend on specs).
+ */
+export type AuthorizationGrant = {
+  name: string;
+  realm_id?: string | null;
+  client_id?: string | null;
+  /**
+   * Absent or null coerces to `own`, fail-closed.
+   */
+  realm_scope?: `${RealmScope}` | null;
+  /**
+   * Absent or null means no junction policy.
+   */
+  policies?: string[] | null;
+};
+export type AuthorizationEvaluatorInput = {
+  /**
+   * An `AuthorizationCatalog`, validated by the schema.
+   */
+  catalog: unknown;
+  /**
+   * `AuthorizationGrant[]`, validated by the schema. Defaults to none, and
+   * may only be supplied together with the identity holding them.
+   */
+  grants?: unknown;
+  /**
+   * The identity the grants belong to. Omitted for an anonymous caller:
+   * no identity data is injected and no grant is bound, so only a
+   * definition whose policies need no identity can pass.
+   */
+  identity?: IdentityPolicyData;
+};
+export type AuthorizationEvaluatorOptions = {
+  /**
+   * The policy types a catalog tree may carry. Defaults to
+   * `PolicyDefaultValidators`; spread it to add a custom type.
+   */
+  validators?: PolicyValidators;
+  /**
+   * How the projected trees evaluate. Defaults to
+   * `PolicyDefaultEvaluators`; spread it to add a custom type. The
+   * permission-binding evaluator is always replaced by the one binding the
+   * introspected grants.
+   */
+  evaluators?: PolicyEvaluators;
+};
+/**
+ * Which resource realms a batch check evaluates against.
+ *
+ * A string is SYMBOLIC and resolved server-side against the caller's own
+ * identity: `own` is the realm the identity belongs to, `ownOrNull` is that
+ * realm plus `null`, the global rows every realm shares. An array is taken
+ * VERBATIM: the server resolves no realm key, so it discloses no realm's
+ * existence and the caller matches the answer against its own input with no
+ * resolution step of its own.
+ *
+ * String versus array is what discriminates the two forms, so `own` stays
+ * unambiguous even though it is a legal realm name.
+ */
+export type AuthorizationCheckRealms = `${RealmScope.OWN}` | `${RealmScope.OWN_OR_NULL}` | Array<string | null>;
+/**
+ * One permission the identity may attempt, and the requested realms it may
+ * attempt it in. Never empty: a permission reaching no requested realm is
+ * absent from the answer entirely, so absent means denied.
+ */
+export type AuthorizationCheckPermission = {
+  name: string;
+  realms: Array<string | null>;
+};
+/**
+ * The answer `POST /authorization/check` serves: the caller's own verdicts,
+ * paired with the realms they hold in.
+ *
+ * It is an upper bound on what may be ATTEMPTED rather than an entitlement,
+ * the same posture the catalog and `GET /schemas` take: it is a pre-gate, so a
+ * grant whose junction policy needs a resource row passes here and is still
+ * decided per row on the server, which stays the enforcement point.
+ */
+export type AuthorizationCheckPermissions = AuthorizationCheckPermission[];
+export type AuthorizationCheckEvaluatorInput = {
+  /**
+   * An `AuthorizationCheckPermissions`, validated by the schema.
+   */
+  permissions: unknown;
+  /**
+   * The identity the verdicts belong to, used to resolve a `realmMatch` of
+   * `own` shape: a resource realm equal to this identity's realm id or name
+   * is the identity's own realm. Omitted for an anonymous caller, which
+   * holds no verdict at all.
+   */
+  identity?: IdentityPolicyData;
+};
+//#endregion
+//#region src/permission/authorization/check-schema.d.ts
+/**
+ * The whole input `createAuthorizationCheckEvaluator` takes: the answer
+ * `POST /authorization/check` served and the identity it belongs to. Same
+ * validup-over-zod shape as the catalog's input, so a consumer can override
+ * one member's rules instead of restating the answer.
+ */
+export declare class AuthorizationCheckEvaluatorInputValidator extends Container<AuthorizationCheckEvaluatorInput> {
+  initialize(): void;
+}
+export type AuthorizationCheckEvaluatorInputParsed = {
+  permissions: AuthorizationCheckPermissions;
+  identity: AuthorizationCheckEvaluatorInput['identity'];
+};
+/**
+ * Validate the check evaluator's input, plus the one rule a per-key validator
+ * cannot express: a permission namespace appears at most once. Two entries for
+ * one name would make the answer depend on which the consumer looked up first,
+ * and the server emits one entry per name by construction.
+ */
+export declare function parseAuthorizationCheckEvaluatorInput(input: AuthorizationCheckEvaluatorInput): Promise<AuthorizationCheckEvaluatorInputParsed>;
+//#endregion
+//#region src/permission/authorization/constants.d.ts
+/**
+ * The node a policy tree travels as when the server withholds it, because the
+ * caller's realm reach does not cover the row it was read from.
+ *
+ * It is deliberately a type no consumer can project: `projectAuthorizationPolicy`
+ * refuses it, which is already the state a definition referencing it denies
+ * through and a grant naming it is dropped through, so withholding a body needs
+ * no rule of its own on the consumer side. That is a contract between the two
+ * halves rather than a server detail, which is why it is declared HERE, next to
+ * the projection that has to keep refusing it, and pinned by this package's own
+ * test.
+ */
+export declare const AUTHORIZATION_POLICY_WITHHELD_TYPE = "withheld";
+//#endregion
+//#region src/permission/authorization/module.d.ts
+/**
+ * Build a resource-server (or console) evaluator from the catalog
+ * `GET /authorization` serves, the identity's grants as the introspection
+ * endpoints report them, and the identity itself. Rejects legacy, incomplete
+ * and unsupported input. A grant referencing a definition or a policy the
+ * catalog lacks throws `AuthorizationCatalogStaleError`, the signal to
+ * refetch the catalog: the grants come from a fresh introspection while the
+ * catalog may predate the definition or the junction row. A definition the
+ * server could not project travels with `policies: null` instead of being
+ * left out, so a grant of it is dropped rather than reported stale: the
+ * definition layer cannot be evaluated here, a refetch changes nothing, and
+ * the permission denies until the policy is fixed.
+ *
+ * A tree THIS copy cannot project is the same condition read from the other
+ * side, and it is per tree: a policy type the validator registry lacks (a
+ * type newer than this package, or a custom one the caller did not register)
+ * or a configuration its validator refuses denies the definitions that reference
+ * it, exactly as `policies: null` does, and drops a grant that names it,
+ * exactly as a binding check does. One such tree never takes the evaluator
+ * down for the permissions that do not use it. A malformed catalog still
+ * throws: a duplicate permission namespace is not a data condition.
+ *
+ * Both the identity and the grants are optional. Without an identity no grant
+ * is bound and any IDENTITY key the caller supplied is REMOVED, so the
+ * binding evaluator answers with missing data exactly as the server does for
+ * an anonymous request, only a definition whose policies need no identity can
+ * pass, and a caller can never inject an identity the document did not prove.
+ * Grants without the identity they belong to are refused.
+ *
+ * The REALM_MATCH data key follows the server's own three-way rule: a
+ * resource that carries a realm passes it (null for a global row, which
+ * `own` denies), a resource with no realm dimension passes nothing and reach
+ * neutral-passes. `preEvaluate` / `preEvaluateOneOf` are the pre-gate and
+ * enforce reach only when that key is present. `compile` returns the
+ * allow/deny/conditional/post contract; a `post` collection query must be
+ * rejected or evaluated over every candidate before paging. The supplied
+ * identity is authoritative; `options.decisionStrategy` is forwarded and the
+ * policy include, exclude and pending options are refused.
+ *
+ * The policy type set is open (#3635): `options.validators` decides which
+ * trees project and `options.evaluators` how they evaluate, the built-in
+ * registries by default. A custom type needs both, the validator the server
+ * projected it with and the evaluator the server decides it with; given only
+ * the first it projects and then denies. The binding evaluator is always this
+ * function's own, since it is what binds the introspected grants.
+ */
+export declare function createAuthorizationEvaluator(input: AuthorizationEvaluatorInput, options?: AuthorizationEvaluatorOptions): Promise<IPermissionEvaluator>;
+/**
+ * An `IPermissionEvaluator` over the answer `POST /authorization/check`
+ * served: the caller's own verdicts, paired with the realms they hold in.
+ *
+ * It is what a PUBLIC client gets where the catalog is out of reach. A public
+ * client holds no secret, so it can obtain no `client_credentials` token and
+ * has no credential of its own for the catalog's gate to be satisfied by;
+ * publishing every policy predicate to it instead would be the wrong trade.
+ * The verdicts are computed by the server from the same grants and the same
+ * evaluators a request runs, so this is authoritative where the name-only
+ * fallback it replaces is merely coarse.
+ *
+ * Two properties follow from the answer being a pre-gate:
+ *
+ * It is an UPPER BOUND, so `evaluate` and `evaluateOneOf` answer exactly what
+ * the pre-gate pair answers. A check that depends on a resource row belongs to
+ * whoever holds the row, and the server decides it there; answering such a
+ * check here would mean inventing a verdict. That is the same bound the
+ * name-only fallback already had, so nothing that gates on it loosens.
+ *
+ * And a resource realm is matched against what the REQUEST asked about: a
+ * `realmMatch` naming a realm the request never carried is in no entry's list
+ * and therefore denies. That is fail-closed by construction rather than by a
+ * rule, and it is why a caller must ask about the realms its UI will ask
+ * about.
+ */
+export declare function createAuthorizationCheckEvaluator(input: AuthorizationCheckEvaluatorInput): Promise<IPermissionEvaluator>;
+//#endregion
+//#region src/permission/authorization/policy.d.ts
+/**
+ * The one definition of what a policy looks like on the wire, used by the server
+ * to build a document and by the consumer to validate one. A node is the OUTPUT
+ * of its type's validator (validup strips every unmounted key, so entity columns
+ * such as `id`, `name`, `builtIn` or `createdAt` never travel), plus its type
+ * and, for a composite, its projected children.
+ *
+ * The type set is the `validators` registry, `PolicyDefaultValidators` unless
+ * the caller hands another (#3635): a type the registry lacks is refused, so
+ * the server and a consumer that register the same custom type let it travel,
+ * and one that does not denies it. The withheld node is refused whatever the
+ * registry says, since projecting it would evaluate a tree the caller was not
+ * allowed to see.
+ *
+ * Every refusal is a `ValidupError`, the node's head and the type's own
+ * validator alike, and a child's issues are rebased onto the position it sits
+ * at, so one message names the node in the tree that is wrong.
+ */
+export declare function projectAuthorizationPolicy(input: unknown, validators?: PolicyValidators): Promise<AuthorizationPolicy>;
+/**
+ * Whether a projected tree evaluates the permission binding at any depth. A
+ * grant policy carrying one would re-enter its own permission's grants, so
+ * `createAuthorizationEvaluator` drops the grant that names it and evaluates
+ * the permission from the rest. Its one caller is that consumer: the tree is
+ * legal in a definition, where the binding check is what reach is enforced
+ * by, so the producer carries it and only the grant side is refused.
+ */
+export declare function containsBindingCheck(policy: AuthorizationPolicy): boolean;
+//#endregion
+//#region src/permission/authorization/schema.d.ts
+/**
+ * A policy node as it travels. Deliberately LOOSE: every key beyond `type` is
+ * that type's own configuration, and `projectAuthorizationPolicy` is what
+ * validates it, by running the type's own validator. Mounting a node in a
+ * validup container would strip every key the container does not mount, and
+ * the whole configuration would go with it.
+ */
+export declare const authorizationPolicySchema: z.ZodObject<{
+  type: z.ZodString;
+}, z.core.$loose>;
+/**
+ * One permission definition. `policies` carries the ids of its
+ * definition-layer trees, or `null` when the server could not project one.
+ */
+export declare const authorizationDefinitionSchema: z.ZodObject<{
+  name: z.ZodString;
+  realm_id: z.ZodNullable<z.ZodString>;
+  client_id: z.ZodNullable<z.ZodString>;
+  decision_strategy: z.ZodNullable<z.ZodEnum<typeof DecisionStrategy>>;
+  policies: z.ZodNullable<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const authorizationCatalogSchema: z.ZodObject<{
+  policies: z.ZodRecord<z.ZodString, z.ZodObject<{
+    type: z.ZodString;
+  }, z.core.$loose>>;
+  permissions: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    realm_id: z.ZodNullable<z.ZodString>;
+    client_id: z.ZodNullable<z.ZodString>;
+    decision_strategy: z.ZodNullable<z.ZodEnum<typeof DecisionStrategy>>;
+    policies: z.ZodNullable<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * One grant of the identity, as the introspection endpoints report it.
+ * Whether a grant's policy ids are declared is checked against the catalog
+ * the consumer holds, since the two travel separately.
+ */
+export declare const authorizationGrantSchema: z.ZodObject<{
+  name: z.ZodString;
+  realm_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  client_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  realm_scope: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof RealmScope>>>;
+  policies: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export declare const authorizationIdentitySchema: z.ZodObject<{
+  id: z.ZodString;
+  type: z.ZodEnum<{
+    user: "user";
+    client: "client";
+  }>;
+  realmId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  realmName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  clientId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * The whole input `createAuthorizationEvaluator` takes: the catalog
+ * `GET /authorization` serves, the grants an introspection reports and the
+ * identity it names. A validup container over zod mounts, the shape every
+ * validator in this package uses, so a consumer can reuse or override one
+ * member's rules instead of restating the document.
+ */
+export declare class AuthorizationEvaluatorInputValidator extends Container<AuthorizationEvaluatorInput> {
+  initialize(): void;
+}
+export type AuthorizationEvaluatorInputParsed = {
+  catalog: AuthorizationCatalog;
+  grants: AuthorizationGrant[];
+  identity: AuthorizationEvaluatorInput['identity'];
+};
+/**
+ * Validate the evaluator's input, plus the two rules per-key validators
+ * cannot express.
+ *
+ * Every id a definition names must be a key of `policies`: a dangling id
+ * resolves to `undefined`, which reads as "this layer carries no policy", so
+ * a catalog that merely omitted a tree would grant unrestricted access rather
+ * than fail. The lookup is own-property only, so an id such as `constructor`
+ * cannot be answered by a member of `Object.prototype`.
+ *
+ * And the identity and its grants travel together: grants without an identity
+ * belong to nobody, while an identity without a grant list is the shape an
+ * INACTIVE introspection produces (`permissions` is absent unless the
+ * credential is active), which read as "holds nothing" would authorize every
+ * definition that carries no binding check. An identity holding no grant says
+ * so with an empty array.
+ */
+export declare function parseAuthorizationEvaluatorInput(input: AuthorizationEvaluatorInput): Promise<AuthorizationEvaluatorInputParsed>;
+/**
+ * One verdict: the permission namespace and the requested realms it holds in.
+ * A realm value is a realm key the caller itself supplied, or `null` for the
+ * global rows, so nothing here is resolved or looked up.
+ */
+export declare const authorizationCheckPermissionSchema: z.ZodObject<{
+  name: z.ZodString;
+  realms: z.ZodArray<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const authorizationCheckPermissionsSchema: z.ZodArray<z.ZodObject<{
+  name: z.ZodString;
+  realms: z.ZodArray<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>>;
+//#endregion
 //# sourceMappingURL=index.d.mts.map