adminizer 5.0.0-build.9 → 5.1.0-build.24

package/lib/access-graph/AccessGraphResolver.d.ts

@@ -0,0 +1,136 @@
+/**
+ * accessGraph — relationship-based record access over a graph of models (ReBAC).
+ *
+ * A graph declares a root model carrying memberships plus the models that inherit its
+ * visibility down explicit parent edges (`include`). This module owns everything heavy:
+ * graph compilation and validation, the recursive `targetIds → level ids → flat where`
+ * walk, and per-request memoization of the intermediate id lists. `DataAccessor` only
+ * dispatches into it, and does so for every model the graph covers — a covered model's
+ * own `userAccessRelation` is ignored (see `RecordAccessResolver.buildWhere`).
+ */
+import { AccessGraphConfig, AdminpanelConfig } from "../../interfaces/adminpanelConfig.js";
+import { CriteriaWhere } from "../../interfaces/queryCriteria.js";
+import { Adminizer } from "../Adminizer.js";
+import { ModelHandler } from "../model/ModelHandler.js";
+import { User } from "../../models/User.js";
+import { RecordAccessCache } from "./RecordAccessCache.js";
+import { ResolvedMembership } from "./shared.js";
+/** Resolved membership declared at the graph root (through-form without `field`). */
+type CompiledMembership = ResolvedMembership;
+interface CompiledGraph {
+    key: string;
+    rootResource?: string;
+    rootPrimaryKey: string;
+    membership?: CompiledMembership;
+    bypassToken?: string;
+    /** Stage 3: compile read filters into one nested-subquery SQL when the adapter can. */
+    pushdown?: boolean;
+    /**
+     * Models whose pushdown fallback has already been logged, so the warning is emitted once
+     * per model instead of once per request. It lives on the compiled graph rather than in a
+     * module-level set so that recompiling (config change, model registration) reports again —
+     * the answer may well have changed.
+     */
+    pushdownFallbacksReported?: Set<string>;
+    resolveGraphRootIds?: AccessGraphConfig["resolveGraphRootIds"];
+    /** Structural problem: every access to the graph's models fails closed with this message. */
+    error?: string;
+}
+interface CompiledNode {
+    graphKey: string;
+    resourceName: string;
+    isRoot: boolean;
+    /** Association alias on this model pointing at its parent in the graph. */
+    parentAlias?: string;
+    /** Canonical resource name of the edge target. */
+    parentResource?: string;
+    /** Stage 2: denormalized root-id column collapsing this model's read filter to one step. */
+    graphRootField?: string;
+    primaryKey: string;
+    /** Structural problem: access to this model fails closed with this message. */
+    error?: string;
+}
+export interface CompiledAccessGraph {
+    graphs: Map<string, CompiledGraph>;
+    /** Key: normalized canonical resource name. */
+    nodes: Map<string, CompiledNode>;
+    /** Structural errors; access to the affected models fails closed until they are fixed. */
+    problems: string[];
+}
+export declare function compileAccessGraph(adminizer: Adminizer): CompiledAccessGraph | undefined;
+/**
+ * True when `fieldKey` on `resourceName` is exactly the edge the graph uses to reach that
+ * model's parent. Records behind such an edge need no verification: a child is visible
+ * only because its parent is, so the parent is inside the user's graph by construction.
+ */
+export declare function isGraphParentEdge(adminizer: Adminizer, resourceName: string, fieldKey: string, targetResourceName: string): boolean;
+/** Startup validation: fails loud on structural graph errors. */
+export declare function validateAccessGraph(adminizer: Adminizer): void;
+/**
+ * Models the resolver queries through the internal `data-accessor` scope at request
+ * time: membership models, `Group` (when narrowing by membership group), and every
+ * model that is a parent of another graph model (their id lists feed the next level).
+ * Roots are never queried — their ids come from the membership rows.
+ */
+export declare function collectAccessGraphInternalModels(graphsConfig: AdminpanelConfig["accessGraph"], modelHandler: ModelHandler): string[];
+/**
+ * Short-lived resolver: one instance is held by a `DataAccessor` (model + action), so
+ * its memoized intermediate id lists (key: graph + verb + token model + level) live as
+ * long as the owning accessor — never longer than the request, though a request may
+ * hold several accessors. Nothing is cached across requests — staleness is more
+ * dangerous than the saved queries.
+ */
+export declare class AccessGraphResolver {
+    private readonly adminizer;
+    private readonly user;
+    private readonly actionVerb;
+    /** Shared with the other resolvers of the same request when the caller supplies one. */
+    private readonly cache;
+    constructor(adminizer: Adminizer, user: User, actionVerb: string, cache?: RecordAccessCache);
+    /** Cache keys carry the user: a shared cache is per request, but never per user by construction. */
+    private cacheKey;
+    /** True when the compiled graph covers the model (including fail-closed misconfigured nodes). */
+    static covers(adminizer: Adminizer, resourceName: string): boolean;
+    /**
+     * Flat where-fragment confining the model to the records reachable from the user's
+     * memberships at the root: root ids for the root model, `{parentAlias: {in: ids}}`
+     * for everything below it. `{}` means no constraint (bypass or `"all"`).
+     */
+    buildWhere(resourceName: string): Promise<CriteriaWhere>;
+    /**
+     * Stage 3: compiles the whole walk — membership subquery plus the parent chain (cut by
+     * a graphRootField when one is on the path) — into one adapter-emitted subquery operand.
+     * Returns `"unfiltered"` for an explicit `"all"`, or `undefined` when the chain cannot
+     * be pushed down (custom-resolved ids with no chain still return a plain id array).
+     */
+    private compilePushdownOperand;
+    /**
+     * Write path: the chosen parent must be reachable for this action's verb (with a
+     * membership `group` declared, through a group carrying the action's CRUD token).
+     */
+    validateWriteRelation<T>(resourceName: string, record: T): Promise<void>;
+    private requireNode;
+    /** Ids of the model's records visible to the user, or `"all"`; memoized per level. */
+    private visibleModelIds;
+    private computeVisibleModelIds;
+    /**
+     * Root ids the user reaches: `resolveGraphRootIds` when declared (undefined falls back),
+     * otherwise the membership rows — narrowed, when `group` is declared, to memberships
+     * whose group carries this action's CRUD token for the model being accessed.
+     */
+    private resolveGraphRootIds;
+    /** `resolveGraphRootIds` may be side-effectful; call it at most once per graph per request. */
+    private customGraphRootIds;
+    /**
+     * Pushdown variant of the group narrowing: ids of every group granting this action's
+     * CRUD token for the accessed model, computed in JS (token grants are JSON) and
+     * injected into the membership subquery as a literal IN-list. The group table is a
+     * small set of role definitions, so fetching it whole is cheaper than a round trip
+     * for the membership rows the JS path would need.
+     */
+    private allGroupIdsGrantingAction;
+    /** The bypass token is matched against the token grants of the user's global groups. */
+    private hasGraphBypass;
+    private internalModel;
+}
+export {};