@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/security/PolicyDecisionPoint.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The Policy Decision Point (#1431, step 6).
+ *
+ * One component answers "may this subject perform this action", and the
+ * delegation ceilings run here, once. Before this, the capability path ran the
+ * agent-token and share ceilings in `UserManager.hasPermission` and the page
+ * path ran its own copies in `PolicyInformationPoint` — the same protection implemented
+ * twice, with nothing keeping the two in step.
+ *
+ * __This step moves no behaviour.__ The ordering below is exactly what
+ * `UserManager.hasPermission` did, comments and all, so the decision is
+ * identical and only its address changes. The page path joins in step 7, which
+ * is where orderings actually have to be reconciled.
+ *
+ * The roles the PEP is playing, for anyone reading this later:
+ *
+ * - __PEP__ — routes, manager doors, the availability gate. They ask and
+ *   enforce (401 vs 403); they never decide.
+ * - __PDP__ — this. Takes a subject and an action, returns permit or deny.
+ * - __PIP__ — `PolicyInformationPoint`: the subject's attributes and the
+ *   page's own rules (#1431 step 13).
+ * - __PAP__ — `ConfigurationManager` and the admin screens, where policy is
+ *   written.
+ */
+import BaseManager from '../managers/BaseManager.js';
+import type { PermissionSubject, JobSubject } from '../managers/UserManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { Decision, DecisionRequest, Policy } from '../types/Policy.js';
+import { type RoleGrant } from '../utils/roleGrants.js';
+export declare const POLICIES_KEY = "ngdpbase.access.policies";
+export declare const POLICIES_ENABLED_KEY = "ngdpbase.access.policies.enabled";
+export declare class PolicyDecisionPoint extends BaseManager {
+    /**
+     * A manager so every PEP can reach it through `engine.getManager`, the same
+     * way it reaches anything else. It holds no state of its own: a decision is
+     * derived, never stored.
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * The policies in force right now, highest priority first.
+     *
+     * - `ngdpbase.access.policies.enabled` false — its default when unset —
+     *   means none;
+     * - an entry without a string `id` is not a policy, and is skipped;
+     * - two entries with the same `id` are both kept. Merging `id` arrays by id
+     *   is the configuration merge's rule (between the layers), and within one
+     *   layer a duplicate is an authoring error that `PolicyValidator` reports —
+     *   not something to resolve silently here.
+     */
+    policies(): Policy[];
+    /**
+     * What each role permits: role name → the actions its holders are granted.
+     *
+     * It mirrors the evaluator's ROLE matching — an allow policy naming a role
+     * grants its actions, a deny policy naming it takes them away, lower
+     * priority first so a higher-priority deny lands last and wins. It does not
+     * evaluate resource patterns or the ceilings, so it is a summary for a human
+     * reading a table (the admin Security Policy Summary, a profile), never an
+     * authorisation answer — that is {@link permits} with the caller's subject.
+     *
+     * Each role used to carry an inline `permissions[]` display copy kept
+     * matched by hand (#713); this derives the table from the policies instead.
+     */
+    rolePermissions(): Map<string, Set<string>>;
+    /**
+     * What the given roles grant together, each with where it applies (#1539):
+     * an action is limited only when every role granting it is limited, and
+     * `where` collects the places those limited grants name — so `vault-owner`'s
+     * actions read "in your own vaults". A summary, never an answer.
+     */
+    grantsForRoles(roles: readonly string[]): RoleGrant[];
+    /** {@link rolePermissions} as plain sorted arrays — for template data and JSON. */
+    rolePermissionLists(): Record<string, string[]>;
+    /**
+     * Everything the given roles permit together, sorted: the union of their
+     * rows in {@link rolePermissions}, so a user's own list is exactly what the
+     * admin summary shows for the roles they hold. A summary, never an answer.
+     */
+    permissionsForRoles(roles: readonly string[]): string[];
+    /** Where a subject's attributes come from (#1431 step 13). */
+    private informationPoint;
+    /**
+     * Authorise a request: may THIS subject perform `action`? The boolean form
+     * of {@link decide} for a capability. It was `UserManager.hasPermission`
+     * until #1431 step 14; the decision was already here, only the door moved.
+     *
+     * Takes a `PermissionSubject` — the request's own identity, forwarded from
+     * `req.userContext` (WikiContext, ApiContext, ParseContext) or a
+     * `JobContext` for work with no request (#631). Roles arrive already
+     * resolved; the session middleware did that once per request.
+     *
+     * #1173 Part B: the username-string overload this method once accepted is
+     * gone. A string cannot carry `viaToken`, so the agent-token ceiling below
+     * had nothing to read and every string-form call resolved against the
+     * owner's full roles. There is one path now, and the type makes the other
+     * impossible. Callers with no subject to hand over have one of two
+     * legitimate shapes: `ANONYMOUS_SUBJECT`, or the
+     * separate question {@link userHoldsPermission} — "does the named user hold
+     * this?" — which is a lookup about somebody else, not an authorisation.
+     *
+     * @param subject - The identity being authorised, with `roles` resolved and
+     *                  `viaToken` present when a bearer token authenticated it.
+     * @param action - Action/permission to check (e.g., 'page-create', 'user-read')
+     * @returns True if the subject may perform the action under current policy
+     */
+    permits(subject: PermissionSubject | JobSubject | null | undefined, action: string): Promise<boolean>;
+    /**
+     * Does the subject HOLD this permission (#1635)? Policy alone — the
+     * step-up freshness rule is not applied. A different question from
+     * {@link permits}, which is "may it act now", and named so: an affordance
+     * (show the reveal button, show the sign-in methods section) asks this, so a
+     * person whose sign-in is not fresh still sees the way to the prompt that
+     * makes it fresh. A door never asks this.
+     */
+    holds(subject: PermissionSubject | JobSubject | null | undefined, action: string): Promise<boolean>;
+    /**
+     * Step-up (#1525, #1635), decided here — in the one place every door asks —
+     * rather than by routes in front of the doors. A permission marked
+     * `step-up: true` needs a factor satisfied within
+     * `ngdpbase.auth.step-up.max-age-minutes` that reaches the level the
+     * subject's roles require. A request subject carries its `signIn`; a
+     * delegated credential (agent token, share) never satisfies it. Work with no
+     * request (a JobSubject: timers, operator commands) has no sign-in to be
+     * fresh and is not asked.
+     *
+     * A proxy (`viaProxy`, #1762) is NOT delegated here: a person is at the
+     * keyboard, and their own fresh sign-in counts (operator, 2026-10-12). The
+     * subject's `signIn` and `aalCap` are the actor's — the session's — so the
+     * actor's sign-in must reach the level the represented person's roles
+     * require, capped at what the actor's account can reach.
+     */
+    private stepUpRefuses;
+    /** Does the named issuer of a vault link still hold `action` inside that vault (#1539)? The vault rule, resolved live. */
+    private issuerHoldsInVault;
+    /**
+     * Does this NAMED USER hold a permission? (#1173)
+     *
+     * A different question from {@link permits}, and that is why it has a
+     * different name. This one __inspects a user__ — "does bob hold
+     * `admin-system`?" — where there is no request, no token, and nothing to cap.
+     * `permits` __authorises a request__, so it must be handed the subject the
+     * request carries or an agent token's scope ceiling has nothing to read.
+     *
+     * They shared a name and one of them took a bare string, which is how #1164
+     * happened seventeen times. Splitting them means the dangerous question
+     * cannot be asked by accident. The subject is the PIP's, resolved live.
+     */
+    userHoldsPermission(username: string, action: string): Promise<boolean>;
+    /**
+     * The permissions a user's roles give them, for display (#1431 step 10).
+     *
+     * The union of their roles' rows in the admin Security Policy Summary, read
+     * live from the policies — so the profile page and the admin page can never
+     * disagree. A summary for a human, not an authorisation answer: that is
+     * always {@link permits} with the subject.
+     */
+    getUserPermissions(username: string): Promise<string[]>;
+    /** {@link getUserPermissions} with where each applies (#1539) — for the profile. */
+    getUserGrants(username: string): Promise<RoleGrant[]>;
+    /** The roles a user's summary is drawn from: theirs, live, or anonymous's. */
+    private rolesForSummary;
+    /**
+     * Decide. The order is load-bearing:
+     *
+     * 1. __The agent-token ceiling__, before anything else. A delegated token may
+     *    only ever exercise a subset of its owner's rights, so a scope it does
+     *    not carry is refused whatever policy says (#946).
+     * 2. __A share IS the policy__ for a capability check (#1222). The subject is
+     *    anonymous; what it may do is what the issuer delegated, bounded by what
+     *    the issuer holds NOW — so this returns rather than falling through to
+     *    the evaluator, and a share works on an instance whose policy grants
+     *    anonymous nothing.
+     * 3. __Roles resolved live__ when the subject asks for it (`resolveRolesNow`),
+     *    so a job authorises against the roles its principal holds at decision
+     *    time, not at enqueue time (#631, #1212).
+     * 4. __The policies__, through `PolicyEvaluator`.
+     */
+    /**
+     * The delegation ceilings alone: does the token's scope, the share's grant,
+     * or the proxy grant (#1762, {@link proxyCeiling}) permit this at all?
+     *
+     * Returns `null` when the caller carries no delegation — there is nothing to
+     * bound, and the answer is whatever policy says.
+     *
+     * The refusal reasons are the vocabulary already recorded by
+     * `PolicyInformationPoint.logAccessDecision` — `token_scope_deny`, `share_action_deny`,
+     * `share_expired`, `share_resource_deny`, `share_issuer_deny`, and for a
+     * proxy `proxy_combined_deny`, `proxy_kind_deny`, `proxy_revoked`,
+     * `proxy_scope_deny`, `proxy_actor_deny` — because they
+     * land in the audit trail, and renaming one silently changes what an
+     * assessor reads.
+     *
+     * Separate from {@link decide} because a caller sometimes needs ONLY this.
+     * `filterAccessiblePages` bounds the subject once and then applies each
+     * page's own rules; running a full decision there would refuse the whole
+     * list on a global policy that the page's frontmatter or ACL markup would
+     * have overridden.
+     */
+    ceiling(subject: PermissionSubject | JobSubject | null | undefined, request: DecisionRequest): Promise<Decision | null>;
+    /**
+     * The proxy ceiling (#1762 slice 2): someone acting for the subject's person
+     * under a proxy grant. Refused unless ALL hold, in this order:
+     *
+     * - the subject carries no token or share as well (`proxy_combined_deny`),
+     *   and the claim is a proxy — `impersonation` (#1763) admits nothing yet
+     *   (`proxy_kind_deny`);
+     * - the grant is still in force, re-read live on every decision: not
+     *   revoked, not past its end date, proxy access still on, and naming this
+     *   person and this actor, with every permission the subject was built with,
+     *   and the person represented still an active account (`proxy_revoked`);
+     * - the action is one the grant carries — the claim's scopes, each still in
+     *   the live grant (`proxy_scope_deny`);
+     * - the actor holds the action themselves, live — an inactive actor holds
+     *   nothing (`proxy_actor_deny`).
+     *
+     * Passing is not an allow: policy then runs against the represented person
+     * (`decide` falls through, as for a token), so the result is grant ∩
+     * represented ∩ actor. The actor is asked whether they HOLD the action —
+     * policy alone — because step-up is asked of this subject, with the actor's
+     * own sign-in, once policy has said yes.
+     */
+    private proxyCeiling;
+    /** Does the named actor HOLD `action` (policy alone, live)? Step-up is the proxy subject's question, not theirs. */
+    private actorHolds;
+    /**
+     * Decide. The order is load-bearing:
+     *
+     * 1. __The ceilings__ (see {@link ceiling}), before anything else. A
+     *    delegated credential may only ever exercise a subset of what was
+     *    delegated, whatever policy says (#946, #1222); a proxy only what its
+     *    grant carries and its actor holds, and then policy for the person
+     *    represented (#1762).
+     * 2. __A share IS the policy__ for a capability check, so a passing share
+     *    returns an allow rather than falling through to the evaluator — a share
+     *    must work on an instance whose policy grants anonymous nothing.
+     * 3. __Roles resolved live__ when the subject asks for it (`resolveRolesNow`),
+     *    so a job authorises against the roles its principal holds at decision
+     *    time, not at enqueue time (#631, #1212).
+     * 4. __The policies__, through `PolicyEvaluator`.
+     */
+    decide(subject: PermissionSubject | JobSubject | null | undefined, request: DecisionRequest): Promise<Decision>;
+    /** `decide`, with the step-up rule applied or not — {@link holds} is the only caller that leaves it out. */
+    private evaluate;
+}
+export default PolicyDecisionPoint;