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

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

@@ -0,0 +1,83 @@
+/**
+ * Record-level access for models declaring `userAccessRelation` — builds the read
+ * filter (`buildWhere`) and applies the write rules (`applyWriteRules`) for its three
+ * forms: string (own User/Group column), `{field, via}` (intermediate model) and
+ * `{field, through, via[, group]}` (membership). The accessGraph wins over all three:
+ * a model it covers is filtered by the graph and its own relation is ignored.
+ * One instance is held per `DataAccessor` (model + action), so the memoization here
+ * and in the embedded `AccessGraphResolver` lives as long as the owning accessor —
+ * never longer than the request, though a request may hold several accessors.
+ */
+import { ModelResource } from "../../interfaces/types.js";
+import { CriteriaWhere } from "../../interfaces/queryCriteria.js";
+import { Adminizer } from "../Adminizer.js";
+import { User } from "../../models/User.js";
+import { RecordAccessCache } from "./RecordAccessCache.js";
+export declare class RecordAccessResolver {
+    private readonly adminizer;
+    private readonly user;
+    private readonly modelResource;
+    private readonly actionVerb;
+    private readonly cache;
+    private accessGraphResolver?;
+    private resolvedMembershipMemo?;
+    private membershipTargetIdsMemo?;
+    constructor(adminizer: Adminizer, user: User, modelResource: ModelResource, actionVerb: string, cache?: RecordAccessCache);
+    /**
+     * Where-fragment confining the model to the current user's records;
+     * `{}` means no constraint (administrators, models without record access rules).
+     */
+    buildWhere(): Promise<CriteriaWhere>;
+    /**
+     * Write rules for the outgoing record: stamp the access column (string form,
+     * creation only) or validate that the chosen relation belongs to the user.
+     * Applied on create and update alike — an update may not move a record into
+     * a graph or membership target the user cannot reach.
+     */
+    applyWriteRules<T>(record: T): Promise<Partial<T>>;
+    private userAccessRelation;
+    private buildStringFormWhere;
+    private buildViaFormWhere;
+    /**
+     * String form: only an administrator — or a holder of the model's ownership-transfer
+     * token — may set the access column explicitly. For everyone else it is stamped from
+     * the current user at creation; an update never re-stamps, so a record cannot change
+     * owner through the panel.
+     */
+    private applyStringFormWrite;
+    /**
+     * Membership form: the chosen target must be one the user has a membership row
+     * for (with `group` declared, one whose group carries this action's CRUD token).
+     */
+    private validateMembershipWrite;
+    /** Via form: the chosen intermediate record must belong to the user. */
+    private validateViaWrite;
+    /**
+     * Structural resolution of the `{field, via}` form, shared by the read filter
+     * and the write validation so the two paths cannot diverge.
+     */
+    private resolveViaDeclaration;
+    /**
+     * Resolves the membership (`through`) form: `field` must point at the target
+     * model; the rest of the declaration is resolved by the shared routine.
+     */
+    private resolveMembershipDeclaration;
+    private computeMembershipDeclaration;
+    /**
+     * Target ids the current user reaches through membership rows; with a `group`
+     * declared, only memberships whose group carries this action's CRUD token count.
+     */
+    private findMembershipTargetIds;
+    /**
+     * Administrators, plus holders of the model's ownership-transfer token: they may point
+     * a record at a target of their choosing instead of the one they belong to. The token is
+     * registered only for models declaring `userAccessRelation` and granted to nobody by
+     * default, so out of the box this is administrators only.
+     */
+    private mayTransferOwnership;
+    private userGroupIds;
+    private resolveRelationTarget;
+    private getRelationModel;
+    private accessRelationModel;
+    private getAccessGraphResolver;
+}

package/lib/access-graph/RecordAccessResolver.js

@@ -0,0 +1,295 @@
+import { Adminizer } from "../Adminizer.js";
+import { AccessGraphResolver } from "./AccessGraphResolver.js";
+import { RecordAccessCache } from "./RecordAccessCache.js";
+import { grantsToken, membershipTargetIds, modelCrudToken, ownershipTransferToken, relationValueId, resolveMembership, } from "./shared.js";
+export class RecordAccessResolver {
+    adminizer;
+    user;
+    modelResource;
+    actionVerb;
+    cache;
+    accessGraphResolver;
+    // The resolver is fixed to one user/model/verb, so single keyless lazy caches
+    // suffice: a write both validates and re-filters, which would otherwise resolve
+    // the declaration and query the membership rows twice. A rejection stays cached
+    // for the resolver's lifetime — same as the AccessGraphResolver memo.
+    resolvedMembershipMemo;
+    membershipTargetIdsMemo;
+    constructor(adminizer, user, modelResource, actionVerb, cache = new RecordAccessCache()) {
+        this.adminizer = adminizer;
+        this.user = user;
+        this.modelResource = modelResource;
+        this.actionVerb = actionVerb;
+        this.cache = cache;
+    }
+    /**
+     * Where-fragment confining the model to the current user's records;
+     * `{}` means no constraint (administrators, models without record access rules).
+     */
+    async buildWhere() {
+        if (this.user.isAdministrator) {
+            return {};
+        }
+        if (AccessGraphResolver.covers(this.adminizer, this.modelResource.name)) {
+            // The graph wins over the model's own `userAccessRelation`, which is ignored
+            // for as long as a graph covers the model (a warning is logged when the graph
+            // compiles). Letting a node opt out would break the premise `isGraphParentEdge`
+            // rests on — a node is visible only because its graph parent is, which is why
+            // the populate verification of that edge may be skipped. An opted-out node
+            // stays reachable by its own rule while the premise no longer holds, and the
+            // parent record leaks through the association.
+            return this.getAccessGraphResolver().buildWhere(this.modelResource.name);
+        }
+        const userAccessRelation = this.userAccessRelation();
+        if (userAccessRelation) {
+            Adminizer.log.debug(`[userAccessRelation] Model "${this.modelResource.name}" is record-restricted: ` +
+                `user "${this.user.login}" (id: ${this.user.id}) only sees records they own.`);
+            if (typeof userAccessRelation === "string") {
+                return this.buildStringFormWhere(userAccessRelation);
+            }
+            if (userAccessRelation.through) {
+                // Membership form: filter by the targets the user has a membership row for
+                const membership = this.resolveMembershipDeclaration(userAccessRelation);
+                const targetIds = await this.findMembershipTargetIds(membership);
+                return { [userAccessRelation.field]: { in: targetIds } };
+            }
+            return this.buildViaFormWhere(userAccessRelation);
+        }
+        return {};
+    }
+    /**
+     * Write rules for the outgoing record: stamp the access column (string form,
+     * creation only) or validate that the chosen relation belongs to the user.
+     * Applied on create and update alike — an update may not move a record into
+     * a graph or membership target the user cannot reach.
+     */
+    async applyWriteRules(record) {
+        const updatedRecord = { ...record };
+        if (!this.user.isAdministrator && AccessGraphResolver.covers(this.adminizer, this.modelResource.name)) {
+            // Same precedence as the read filter: the graph wins, so the model's own write
+            // rules (including the string form's owner stamping) do not run for a graph node.
+            await this.getAccessGraphResolver().validateWriteRelation(this.modelResource.name, updatedRecord);
+            return updatedRecord;
+        }
+        const userAccessRelation = this.userAccessRelation();
+        if (userAccessRelation) {
+            if (typeof userAccessRelation === "string") {
+                this.applyStringFormWrite(updatedRecord, userAccessRelation);
+            }
+            else if (userAccessRelation.through) {
+                await this.validateMembershipWrite(updatedRecord, userAccessRelation);
+            }
+            else {
+                await this.validateViaWrite(updatedRecord, userAccessRelation);
+            }
+        }
+        return updatedRecord;
+    }
+    userAccessRelation() {
+        const value = this.modelResource.config?.userAccessRelation;
+        if (typeof value === "string" || (typeof value === "object" && value !== null)) {
+            return value;
+        }
+        return undefined;
+    }
+    buildStringFormWhere(accessField) {
+        const modelName = this.modelResource.name;
+        const relation = this.modelResource.model.attributes[accessField];
+        const relationModel = this.resolveRelationTarget(relation?.model, relation?.resourceName);
+        const relationCollection = this.resolveRelationTarget(relation?.collection, relation?.resourceName);
+        if (!relation || !["User", "Group"].includes(relationModel ?? relationCollection ?? "")) {
+            throw new Error(`Invalid userAccessRelation configuration for model ${modelName}`);
+        }
+        if (relationModel === "User") {
+            return { [accessField]: this.user.id };
+        }
+        if (relationModel === "Group") {
+            // Absent groups must fail closed: an empty IN list matches nothing, while
+            // `in: undefined` would be dropped by the adapter and widen the query.
+            return { [accessField]: { in: this.userGroupIds() } };
+        }
+        /** Warning: collection relation access is not supported and needs adapter-level processing */
+        Adminizer.log.warn(`Collection relation is not supported and was not tested. You may have an error here: ${JSON.stringify(relation, null, 2)}`);
+        if (relationCollection === "User") {
+            // Ensure user's ID is part of the associated collection to User
+            return { [accessField]: { contains: this.user.id } };
+        }
+        // Ensure user's groups intersect with the collection to Group
+        return { [accessField]: { intersects: this.userGroupIds() } };
+    }
+    async buildViaFormWhere({ field, via }) {
+        const { intermediateRelation, intermediatePk } = this.resolveViaDeclaration(field, via);
+        // Fetch all intermediate records associated with the user
+        const intermediateRecords = await this.accessRelationModel(intermediateRelation.model, intermediateRelation.resourceName).find({ where: { [via]: this.user.id } });
+        const intermediateIds = (intermediateRecords || []).map((r) => r[intermediatePk]);
+        return { [field]: { in: intermediateIds } };
+    }
+    /**
+     * String form: only an administrator — or a holder of the model's ownership-transfer
+     * token — may set the access column explicitly. For everyone else it is stamped from
+     * the current user at creation; an update never re-stamps, so a record cannot change
+     * owner through the panel.
+     */
+    applyStringFormWrite(updatedRecord, accessField) {
+        const mayTransfer = this.mayTransferOwnership();
+        if (updatedRecord[accessField] !== undefined && !mayTransfer) {
+            delete updatedRecord[accessField];
+        }
+        const relation = this.modelResource.model.attributes[accessField];
+        const relationModel = this.resolveRelationTarget(relation?.model, relation?.resourceName);
+        if (!relation || !["User", "Group"].includes(relationModel ?? "")) {
+            return;
+        }
+        if (mayTransfer || this.actionVerb !== "create") {
+            // The access column is never stamped for these callers. Leaving it empty is
+            // legal but produces a record no restricted user will ever see again.
+            if (this.actionVerb === "create" && updatedRecord[accessField] === undefined) {
+                Adminizer.log.warn(`[userAccessRelation] Model "${this.modelResource.name}" is created without "${accessField}": ` +
+                    `the record stays out of reach and will be visible to administrators only`);
+            }
+            return;
+        }
+        if (relationModel === "User") {
+            updatedRecord[accessField] = this.user.id;
+            return;
+        }
+        const userGroups = this.user.groups || [];
+        if (userGroups.length === 1) {
+            updatedRecord[accessField] = userGroups[0].id;
+        }
+        else {
+            throw new Error("Record cannot be saved because the user is associated with none or multiple groups.");
+        }
+    }
+    /**
+     * Membership form: the chosen target must be one the user has a membership row
+     * for (with `group` declared, one whose group carries this action's CRUD token).
+     */
+    async validateMembershipWrite(updatedRecord, userAccessRelation) {
+        const { field } = userAccessRelation;
+        const value = updatedRecord[field];
+        if (value === undefined || value === null || this.mayTransferOwnership()) {
+            return;
+        }
+        const membership = this.resolveMembershipDeclaration(userAccessRelation);
+        const targetIds = await this.findMembershipTargetIds(membership);
+        const chosenId = relationValueId(value, membership.targetPrimaryKey);
+        if (!targetIds.some((id) => String(id) === String(chosenId))) {
+            throw new Error(`Access denied: "${field}" does not belong to the current user`);
+        }
+    }
+    /** Via form: the chosen intermediate record must belong to the user. */
+    async validateViaWrite(updatedRecord, { field, via }) {
+        const value = updatedRecord[field];
+        if (value === undefined || value === null || this.mayTransferOwnership()) {
+            return;
+        }
+        const { intermediateRelation, intermediatePk } = this.resolveViaDeclaration(field, via);
+        const chosenId = relationValueId(value, intermediatePk);
+        const record = await this.accessRelationModel(intermediateRelation.model, intermediateRelation.resourceName).findOne({ where: { [intermediatePk]: chosenId, [via]: this.user.id } });
+        if (!record) {
+            throw new Error(`Access denied: "${field}" does not belong to the current user`);
+        }
+    }
+    /**
+     * Structural resolution of the `{field, via}` form, shared by the read filter
+     * and the write validation so the two paths cannot diverge.
+     */
+    resolveViaDeclaration(field, via) {
+        if (!via) {
+            throw new Error(`Invalid userAccessRelation configuration: "via" is required`);
+        }
+        const intermediateRelation = this.modelResource.model.attributes[field];
+        if (!intermediateRelation || !intermediateRelation.model) {
+            throw new Error(`Invalid intermediate relation configuration for field "${field}" in model ${this.modelResource.name}`);
+        }
+        const intermediateModel = this.getRelationModel(intermediateRelation.model, intermediateRelation.resourceName);
+        if (!intermediateModel) {
+            throw new Error(`Intermediate model "${intermediateRelation.model}" not found`);
+        }
+        const viaRelation = intermediateModel.attributes[via];
+        if (!viaRelation || this.resolveRelationTarget(viaRelation.model, viaRelation.resourceName) !== "User") {
+            throw new Error(`Unsupported or invalid via field "${via}" in intermediate model "${intermediateRelation.model}". ` +
+                `Currently, only relations to "User" are supported`);
+        }
+        return {
+            intermediateRelation,
+            intermediateModel,
+            intermediatePk: (intermediateModel.primaryKey ?? "id"),
+        };
+    }
+    /**
+     * Resolves the membership (`through`) form: `field` must point at the target
+     * model; the rest of the declaration is resolved by the shared routine.
+     */
+    resolveMembershipDeclaration(userAccessRelation) {
+        return this.resolvedMembershipMemo ??= this.computeMembershipDeclaration(userAccessRelation);
+    }
+    computeMembershipDeclaration(userAccessRelation) {
+        const modelName = this.modelResource.name;
+        const { field } = userAccessRelation;
+        const targetRelation = this.modelResource.model.attributes[field];
+        if (!targetRelation || !targetRelation.model) {
+            throw new Error(`Invalid intermediate relation configuration for field "${field}" in model ${modelName}`);
+        }
+        const targetResource = this.resolveRelationTarget(targetRelation.model, targetRelation.resourceName);
+        if (!targetResource) {
+            throw new Error(`Relation model "${targetRelation.model}" was not found`);
+        }
+        const membership = resolveMembership(userAccessRelation, targetResource, this.adminizer.modelHandler, (message) => new Error(message.charAt(0).toUpperCase() + message.slice(1)));
+        return {
+            ...membership,
+            targetPrimaryKey: (this.getRelationModel(targetRelation.model, targetRelation.resourceName)?.primaryKey ?? "id"),
+        };
+    }
+    /**
+     * Target ids the current user reaches through membership rows; with a `group`
+     * declared, only memberships whose group carries this action's CRUD token count.
+     */
+    findMembershipTargetIds(membership) {
+        const key = `membership:${String(this.user.id)}:${this.modelResource.name}:${this.actionVerb}:${membership.through}`;
+        return this.membershipTargetIdsMemo ??= this.cache.resolve(key, () => membershipTargetIds((resourceName) => this.adminizer.modelHandler.internal("data-accessor").get(resourceName), membership, this.user.id, membership.targetPrimaryKey, modelCrudToken(this.actionVerb, this.modelResource.name)));
+    }
+    /**
+     * Administrators, plus holders of the model's ownership-transfer token: they may point
+     * a record at a target of their choosing instead of the one they belong to. The token is
+     * registered only for models declaring `userAccessRelation` and granted to nobody by
+     * default, so out of the box this is administrators only.
+     */
+    mayTransferOwnership() {
+        if (this.user.isAdministrator) {
+            return true;
+        }
+        // Matched against the group grants directly, like the graph's `bypassToken`:
+        // `hasStaticPermission` answers "yes" to everything once `auth.enable` is false,
+        // which would drop the write rules for every user of an unauthenticated panel.
+        const tokenId = ownershipTransferToken(this.modelResource.name);
+        return (this.user.groups ?? []).some((group) => grantsToken(group.tokens ?? [], tokenId));
+    }
+    userGroupIds() {
+        return this.user.groups?.map((group) => group.id) ?? [];
+    }
+    resolveRelationTarget(modelName, resourceName) {
+        if (!modelName) {
+            return undefined;
+        }
+        return this.adminizer.modelHandler.resolveAssociationResource(modelName, resourceName);
+    }
+    getRelationModel(modelName, resourceName) {
+        const resolvedResourceName = this.resolveRelationTarget(modelName, resourceName);
+        return resolvedResourceName
+            ? this.adminizer.modelHandler.getResource(resolvedResourceName)
+            : undefined;
+    }
+    accessRelationModel(modelName, resourceName) {
+        const resolvedResourceName = this.resolveRelationTarget(modelName, resourceName);
+        if (!resolvedResourceName) {
+            throw new Error(`Relation model "${modelName}" was not found`);
+        }
+        return this.adminizer.modelHandler.internal("data-accessor").get(resolvedResourceName);
+    }
+    getAccessGraphResolver() {
+        this.accessGraphResolver ??= new AccessGraphResolver(this.adminizer, this.user, this.actionVerb, this.cache);
+        return this.accessGraphResolver;
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Shared primitives of record-level access control, used by both
+ * `RecordAccessResolver` (the `userAccessRelation` forms) and `AccessGraphResolver`
+ * (access graphs): CRUD token naming, the `Group.tokens` grant comparison and
+ * membership (`through`/`via`[/`group`]) declaration resolution.
+ */
+import { ActionType } from "../../interfaces/adminpanelConfig.js";
+import type { ModelHandler } from "../model/ModelHandler.js";
+export declare const MODEL_TOKEN_SUFFIX = "model";
+/** CRUD token id of a verb on a model; registered token ids are lowercased. */
+export declare function modelCrudToken(actionVerb: string, modelName: string): string;
+/**
+ * Token letting its holder set the access relation of a record explicitly — the panel
+ * equivalent of transferring ownership. Registered only for models that declare
+ * `userAccessRelation`, and granted to nobody by default: without it a non-administrator
+ * can neither stamp a foreign owner on create nor move a record out of reach.
+ */
+export declare function ownershipTransferToken(modelName: string): string;
+/** Maps a panel action to its CRUD token verb. */
+export declare function getTokenAction(apAction: ActionType): "create" | "delete" | "update" | "read";
+/** A relation value may arrive populated (object) or as a bare id. */
+export declare function relationValueId(value: unknown, primaryKey?: string): unknown;
+/**
+ * Like `hasAssignedPermission`, but case-insensitive for plain string grants —
+ * registered token ids are lowercased.
+ */
+export declare function grantsToken(grants: unknown[], tokenId: string): boolean;
+/** Resolved membership declaration: the `through` model with its relation aliases and FK columns. */
+export interface ResolvedMembership {
+    through: string;
+    /** Association alias in the membership model pointing at the membership target. */
+    targetAlias: string;
+    /** Its foreign-key column — plain (unpopulated) rows carry the value there. */
+    targetFk: string;
+    viaAlias: string;
+    groupAlias?: string;
+    groupFk?: string;
+}
+/** Minimal model access the shared membership queries need (an internal-scope accessor). */
+export type MembershipModelSource = (resourceName: string) => {
+    find(criteria: unknown): Promise<Record<string, unknown>[] | null | undefined>;
+};
+/**
+ * Resolves a membership declaration against the registered models: `through` must
+ * carry exactly one relation to `targetResource`, a `via` relation to User and,
+ * optionally, a `group` relation to Group. `formatError` wraps the failure text into
+ * the caller's error shape (userAccessRelation vs accessGraph wording).
+ */
+export declare function resolveMembership(declaration: {
+    through?: string;
+    via?: string;
+    group?: string;
+}, targetResource: string, modelHandler: ModelHandler, formatError: (message: string) => Error): ResolvedMembership;
+/**
+ * Target ids the user reaches through membership rows; with a `group` declared,
+ * only memberships whose group carries `grantedTokenId` count.
+ */
+export declare function membershipTargetIds(getModel: MembershipModelSource, membership: ResolvedMembership, userId: unknown, targetPrimaryKey: string, grantedTokenId: string): Promise<unknown[]>;
+/** Ids of the given groups whose token list carries `tokenId`. */
+export declare function groupsGrantingToken(getModel: MembershipModelSource, groupIds: unknown[], tokenId: string): Promise<Set<string>>;

package/lib/access-graph/shared.js

@@ -0,0 +1,121 @@
+import { parseGroupPermissionGrant } from "../../helpers/accessRightsHelper.js";
+export const MODEL_TOKEN_SUFFIX = "model";
+/** CRUD token id of a verb on a model; registered token ids are lowercased. */
+export function modelCrudToken(actionVerb, modelName) {
+    return `${actionVerb}-${modelName}-${MODEL_TOKEN_SUFFIX}`.toLowerCase();
+}
+/**
+ * Token letting its holder set the access relation of a record explicitly — the panel
+ * equivalent of transferring ownership. Registered only for models that declare
+ * `userAccessRelation`, and granted to nobody by default: without it a non-administrator
+ * can neither stamp a foreign owner on create nor move a record out of reach.
+ */
+export function ownershipTransferToken(modelName) {
+    return `transfer-${modelName}-ownership`.toLowerCase();
+}
+/** Maps a panel action to its CRUD token verb. */
+export function getTokenAction(apAction) {
+    switch (apAction) {
+        case "add":
+            return "create";
+        case "list":
+        case "view":
+            return "read";
+        case "edit":
+            return "update";
+        case "remove":
+            return "delete";
+    }
+}
+/** A relation value may arrive populated (object) or as a bare id. */
+export function relationValueId(value, primaryKey = "id") {
+    if (value && typeof value === "object") {
+        return value[primaryKey];
+    }
+    return value;
+}
+/**
+ * Like `hasAssignedPermission`, but case-insensitive for plain string grants —
+ * registered token ids are lowercased.
+ */
+export function grantsToken(grants, tokenId) {
+    return grants.some((grant) => (typeof grant === "string" && grant.toLowerCase() === tokenId) ||
+        parseGroupPermissionGrant(grant)?.tokenId === tokenId);
+}
+/**
+ * Resolves a membership declaration against the registered models: `through` must
+ * carry exactly one relation to `targetResource`, a `via` relation to User and,
+ * optionally, a `group` relation to Group. `formatError` wraps the failure text into
+ * the caller's error shape (userAccessRelation vs accessGraph wording).
+ */
+export function resolveMembership(declaration, targetResource, modelHandler, formatError) {
+    const { through, via, group } = declaration;
+    if (!through) {
+        throw formatError(`membership "through" is required`);
+    }
+    if (!via) {
+        throw formatError(`membership "via" is required`);
+    }
+    const throughRecord = modelHandler.getResourceRecord(through);
+    if (!throughRecord) {
+        throw formatError(`membership model "${through}" not found`);
+    }
+    const resolveTarget = (attribute) => attribute?.model ? modelHandler.resolveAssociationResource(attribute.model, attribute.resourceName) : undefined;
+    const throughAttributes = throughRecord.model.attributes;
+    const viaRelation = throughAttributes[via];
+    if (resolveTarget(viaRelation) !== "User") {
+        throw formatError(`unsupported or invalid via field "${via}" in membership model "${through}". ` +
+            `Currently, only relations to "User" are supported`);
+    }
+    if (group) {
+        const groupRelation = throughAttributes[group];
+        if (resolveTarget(groupRelation) !== "Group") {
+            throw formatError(`invalid group field "${group}" in membership model "${through}": a relation to "Group" is required`);
+        }
+    }
+    const targetAliases = Object.entries(throughAttributes)
+        .filter(([key, attribute]) => key !== via && key !== group && resolveTarget(attribute) === targetResource)
+        .map(([key]) => key);
+    if (targetAliases.length !== 1) {
+        throw formatError(`cannot resolve the target relation in membership model "${through}": ` +
+            `expected exactly one relation to "${targetResource}", found ${targetAliases.length}`);
+    }
+    const targetAlias = targetAliases[0];
+    return {
+        through: throughRecord.name,
+        targetAlias,
+        targetFk: throughAttributes[targetAlias].via ?? targetAlias,
+        viaAlias: via,
+        groupAlias: group,
+        groupFk: group ? (throughAttributes[group].via ?? group) : undefined,
+    };
+}
+/**
+ * Target ids the user reaches through membership rows; with a `group` declared,
+ * only memberships whose group carries `grantedTokenId` count.
+ */
+export async function membershipTargetIds(getModel, membership, userId, targetPrimaryKey, grantedTokenId) {
+    const rows = await getModel(membership.through).find({ where: { [membership.viaAlias]: userId } }) ?? [];
+    const membershipGroupId = (row) => relationValueId(row[membership.groupFk] ?? row[membership.groupAlias]);
+    let allowedRows = rows;
+    if (membership.groupAlias) {
+        const groupIds = rows
+            .map(membershipGroupId)
+            .filter((id) => id !== null && id !== undefined);
+        const grantedGroupIds = await groupsGrantingToken(getModel, Array.from(new Set(groupIds)), grantedTokenId);
+        allowedRows = rows.filter((row) => grantedGroupIds.has(String(membershipGroupId(row))));
+    }
+    return Array.from(new Set(allowedRows
+        .map((row) => relationValueId(row[membership.targetFk] ?? row[membership.targetAlias], targetPrimaryKey))
+        .filter((id) => id !== null && id !== undefined)));
+}
+/** Ids of the given groups whose token list carries `tokenId`. */
+export async function groupsGrantingToken(getModel, groupIds, tokenId) {
+    if (!groupIds.length) {
+        return new Set();
+    }
+    const groups = (await getModel("Group").find({ where: { id: { in: groupIds } } }) ?? []);
+    return new Set(groups
+        .filter((group) => grantsToken(group.tokens ?? [], tokenId))
+        .map((group) => String(group.id)));
+}

package/lib/admin-links/AdminLinkHandler.d.ts

@@ -0,0 +1,72 @@
+import type { User } from '../../models/User.js';
+import type { Adminizer } from '../Adminizer.js';
+export interface AdminLink {
+    id: string;
+    type: string;
+    name: string;
+    link: string;
+    title?: string;
+    section?: string;
+    accessRightsToken?: string;
+}
+export interface ResolvedAdminLink extends AdminLink {
+    owner: string;
+    title: string;
+}
+/** A placeholder of an admin link template, e.g. `id` in `/model/Test/edit/:id`. */
+export interface AdminLinkTemplateParam {
+    name: string;
+    description?: string;
+}
+/**
+ * A parametrized admin page, e.g. `/admin/model/Test/edit/:id`. Templates are
+ * what makes a record page reachable: the concrete URL only exists once the
+ * caller knows the record id.
+ */
+export interface AdminLinkTemplate {
+    id: string;
+    title: string;
+    /** Absolute admin path with `:param` placeholders. */
+    template: string;
+    description?: string;
+    section?: string;
+    accessRightsToken?: string;
+    /** Placeholder descriptions; placeholders absent here are still required. */
+    params?: AdminLinkTemplateParam[];
+}
+export interface ResolvedAdminLinkTemplate extends AdminLinkTemplate {
+    owner: string;
+    params: AdminLinkTemplateParam[];
+}
+/** Server-side registry of standalone admin pages contributed by applications. */
+export declare class AdminLinkHandler {
+    private readonly adminizer;
+    private readonly links;
+    private readonly templates;
+    constructor(adminizer: Adminizer);
+    add(link: AdminLink, owner?: string): string;
+    remove(id: string, owner?: string): boolean;
+    list(user: User, type?: string): Promise<ResolvedAdminLink[]>;
+    resolve(user: User, type: string, name: string): Promise<ResolvedAdminLink | undefined>;
+    addTemplate(template: AdminLinkTemplate, owner?: string): string;
+    removeTemplate(id: string, owner?: string): boolean;
+    /**
+     * Every parametrized page this user may open: model record pages, catalog
+     * items, templates registered by apps and any navigation link that carries
+     * placeholders of its own.
+     */
+    listTemplates(user: User): Promise<ResolvedAdminLinkTemplate[]>;
+    /**
+     * Turns a template id (or its title) plus placeholder values into a real
+     * admin URL, rejecting templates this user may not open.
+     */
+    resolveTemplate(user: User, id: string, params?: Record<string, unknown>): Promise<string>;
+    /** Fills the placeholders of a template with url-encoded values. */
+    buildHref(template: ResolvedAdminLinkTemplate, params?: Record<string, unknown>): string;
+    /** True for paths that change data and therefore must never be navigated to. */
+    isDestructivePath(path: string): boolean;
+    /** Templates derived from the current configuration, catalogs and navigation. */
+    private builtinTemplates;
+    private describeParams;
+    private slug;
+}