@rapidrest/service-core 1.0.0-rc.9 → 1.0.0

package/dist/lib/security/ACLUtils.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2020-2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { ObjectDecorators, UserUtils, sleep } from "@rapidrest/core";
 import { AccessControlListSQL } from "./AccessControlListSQL.js";
@@ -18,20 +19,19 @@ import { ConnectionManager } from "../database/ConnectionManager.js";
 import { isSqlDataSource } from "../database/ConnectionKinds.js";
 import { MongoConnection } from "../database/MongoConnection.js";
 import { MongoRepository } from "../database/MongoRepository.js";
+import { RedisCache } from "../database/RedisCache.js";
+import { Transactional, transactionContext } from "../decorators/DatabaseDecorators.js";
 const { Config, Init, Inject, Logger } = ObjectDecorators;
-const CACHE_BASE_KEY = "db.cache.AccessControlList";
 /**
  * Common utility functions for working with `AccessControlList` objects and validating user permissions.
+ *
+ * @author Jean-Philippe Steinmetz
  */
 export class ACLUtils {
     constructor() {
         this.enabled = true;
-        this.cacheTTL = 30;
         this.trustedRoles = ["admin"];
     }
-    get cacheClient() {
-        return this.connMgr?.connections.get("cache");
-    }
     get repo() {
         const conn = this.connMgr?.connections.get("acl");
         if (conn instanceof MongoConnection) {
@@ -42,10 +42,19 @@ export class ACLUtils {
         }
         return undefined;
     }
-    init() {
+    async init() {
         if (this.enabled) {
             if (!this.repo) {
-                throw new Error("Failed to initialize ACLUtils. Did you forget to configure the `acl` datastore?");
+                throw new Error("Failed to initialize ACLUtils. Did you forget to configure the `acl` datasource?");
+            }
+            // Create the cache store if caching is enabled for this entity type
+            if (!this.cache) {
+                const conn = this.connMgr?.connections.get("acl");
+                let modelClass = conn instanceof MongoConnection ? AccessControlListMongo : AccessControlListSQL;
+                this.cache = await this._objectFactory?.newInstance(RedisCache, {
+                    name: modelClass.fqn ?? modelClass.name,
+                    args: [modelClass],
+                });
             }
             this.logger?.info("RBAC system is enabled and ready.");
         }
@@ -54,50 +63,49 @@ export class ACLUtils {
         }
     }
     /**
-     * Checks to see if the provided user matches the providedUserOrRoleId.
+     * Classifies how specifically the given user matches the provided ACL record id. Used by `getRecord()` to
+     * prefer the most specific match among a record's siblings, rather than the first one in array order.
      * @param user The user to check.
      * @param userOrRoleId The ACL record id to check against.
-     * @returns `true` if the user contains a `uid` or `role` that matches the `userOrRoleId`, otherwise `false`.
+     * @returns `"exact"` for a direct uid/anonymous match, `"role"` for a role match, `"wildcard"` for a `.*`/`*`
+     * match, or `"none"` if the user doesn't match this id at all.
      */
-    userMatchesId(user, userOrRoleId) {
+    matchSpecificity(user, userOrRoleId) {
         if (!user?.uid) {
-            return userOrRoleId === "anonymous";
+            // Wildcards only ever match an *authenticated* user (see the check below) — an anonymous caller
+            // can only match a record explicitly keyed "anonymous".
+            return userOrRoleId === "anonymous" ? "exact" : "none";
         }
+        if (user.uid === userOrRoleId)
+            return "exact";
+        if (user.roles?.includes(userOrRoleId))
+            return "role";
         // Explicit wildcards — match any authenticated user; no regex engine involved
         if (userOrRoleId === ".*" || userOrRoleId === "*")
-            return true;
-        if (user.uid === userOrRoleId)
-            return true;
-        if (user.roles) {
-            for (const role of user.roles) {
-                if (role === userOrRoleId)
-                    return true;
-            }
-        }
-        return false;
+            return "wildcard";
+        return "none";
     }
     /**
      * Validates that the user has permission to perform the request operation against the URL path for the
-     * provided request. If ACLUtils has not been initialized or the `acl` datastore has not been configured
+     * provided request. If ACLUtils has not been initialized or the `acl` datasource has not been configured
      * then always returns `true`.
      *
      * @param uid The uid of the access control list to verify against.
      * @param user The user to validate.
-     * @param req The request whose URL path and method will be verified.
+     * @param req The HTTP request to check permissions for.
      */
     async checkRequestPerms(uid, user, req) {
-        let result = true;
         // If RBAC is disabled just return
         if (!this.enabled) {
-            return result;
+            return true;
         }
-        // Request-scoped cache avoids duplicate Redis/DB fetches when the same ACL uid is
-        // checked more than once within a single request (e.g. class + method @Protect).
-        if (!req._aclCache) {
-            req._aclCache = new Map();
+        if (!req) {
+            throw new Error("options.request must be set to call this function.");
         }
-        const reqCache = req._aclCache;
-        let acl = await this.findACL(uid, [], reqCache);
+        // Deny by default — if the ACL record can't be found (e.g. it failed to persist at
+        // registration time) a `@Protect`-ed route must not silently become open to everyone.
+        let result = false;
+        let acl = await this.findACL(uid, []);
         if (acl) {
             // Make sure all parents are populated
             if (!acl.parent) {
@@ -109,26 +117,18 @@ export class ACLUtils {
                 result = true;
             }
             else {
-                // Check for the FULL permission. If granted it will supersede any others. Otherwise, we'll
-                // check individually based on the request method.
-                result = await this.hasPermission(user, acl, ACLAction.FULL);
-                if (!result) {
-                    // Map the request method to an ACLAction and test for permission
-                    switch (req.method.toLowerCase()) {
-                        case "delete":
-                            result = await this.hasPermission(user, acl, ACLAction.DELETE);
-                            break;
-                        case "get":
-                            result = await this.hasPermission(user, acl, ACLAction.READ);
-                            break;
-                        case "post":
-                            result = await this.hasPermission(user, acl, ACLAction.CREATE);
-                            break;
-                        case "put":
-                            result = await this.hasPermission(user, acl, ACLAction.UPDATE);
-                            break;
-                    }
-                }
+                // Map the request method to an ACLAction and test for permission. `hasPermission` already
+                // treats `ACLAction.FULL` as a wildcard that supersedes any specific action requested.
+                const methodToAction = {
+                    delete: ACLAction.DELETE,
+                    get: ACLAction.READ,
+                    head: ACLAction.COUNT,
+                    patch: ACLAction.UPDATE,
+                    post: ACLAction.CREATE,
+                    put: ACLAction.UPDATE,
+                };
+                const action = methodToAction[req.method.toLowerCase()];
+                result = action ? await this.hasPermission(user, acl, action) : false;
             }
         }
         return result;
@@ -142,7 +142,6 @@ export class ACLUtils {
      * @returns `true` if the user has at least one of the permissions granted for the given entity, otherwise `false`.
      */
     async hasPermission(user, acl, action) {
-        let result = null;
         // If the repo isn't available, no acl was provided or the ACL string is empty just return, assume always true
         if (!this.enabled || !this.repo || !acl || acl === "") {
             return true;
@@ -154,117 +153,119 @@ export class ACLUtils {
         }
         // If a uid has been given look up the ACL associated with it and then process
         if (typeof acl === "string") {
-            const entry = await this.findACL(acl);
+            const entry = await this.findACL(acl, []);
             return entry ? await this.hasPermission(user, entry, action) : false;
         }
         // Look for the first available record for the given user
         const record = this.getRecord(acl, user);
-        // Validate the requested action against the record.
-        if (record) {
-            // A `FULL` permission grant overrides everything else
-            result = record.full;
-            if (!result) {
-                switch (action) {
-                    case ACLAction.CREATE:
-                        result = record.create;
-                        break;
-                    case ACLAction.DELETE:
-                        result = record.delete;
-                        break;
-                    case ACLAction.FULL:
-                        result =
-                            record.full ||
-                                (record.create && record.delete && record.read && record.special && record.update);
-                        break;
-                    case ACLAction.READ:
-                        result = record.read;
-                        break;
-                    case ACLAction.SPECIAL:
-                        result = record.special;
-                        break;
-                    case ACLAction.UPDATE:
-                        result = record.update;
-                        break;
-                }
-            }
-        }
-        // No matching record found — deny by default
-        return result !== null && result !== undefined ? result : false;
+        // A `FULL` ("*") grant supersedes any specific action requested.
+        return record ? record.actions.includes(ACLAction.FULL) || record.actions.includes(action) : false;
     }
     /**
      * Retrieves the access control list with the associated identifier and populates the parent(s).
      *
+     * Deliberately not `@Transactional` and never participates in a caller's transaction: it's on the hot path
+     * for every permission check (`hasPermission`/`checkRequestPerms`), not just writes, so wrapping it would
+     * add a session open/close to every authorization check. It also has no way to safely reuse a *caller's*
+     * transaction context.
+     *
      * @param entityId The unique identifier of the ACL to retrieve.
      * @param parentUids The list of already found parent UIDs. This is used to break circular dependencies.
+     * @param options Set `skipCache: true` to bypass the cache and always read the current database state —
+     * mirrors `RepoUtils`'s `RepoFindOptions.skipCache`. The result is still written back into the cache
+     * afterward, same as a normal (non-skipped) lookup.
      */
-    async findACL(entityId, parentUids = [], reqCache) {
+    async findACL(entityId, parentUids = [], options) {
         if (!this.enabled || !this.repo) {
-            return null;
-        }
-        // Check request-scoped cache first — eliminates redundant Redis/DB round trips
-        // when the same ACL uid is visited more than once within one request.
-        if (reqCache?.has(entityId)) {
-            return reqCache.get(entityId) ?? null;
-        }
-        let acl = null;
-        // Retrieve the ACL from the cache if present
-        if (this.cacheClient) {
-            const json = await this.cacheClient.get(`${CACHE_BASE_KEY}.${entityId}`);
-            if (json) {
-                try {
-                    acl = JSON.parse(json);
-                }
-                catch (err) {
-                    // We don't care if this fails
-                }
-            }
-        }
-        // If the acl wasn't found in the cache look in the database
+            return undefined;
+        }
+        // Retrieve the ACL from the cache if present. A cache hit must still fall through to the parent-chain
+        // population below (not return early) — a cached ACL was stored via its own plain, unpopulated `.parent`
+        // (see the cache write below), so skipping that step here would silently return an ACL with no parent
+        // chain, which `hasPermission()` needs to find inherited records.
+        let acl = options?.skipCache ? undefined : await this.cache?.load(entityId);
+        // If the acl wasn't found in the cache (or the cache was skipped) look in the database
         if (!acl) {
             if (this.repo instanceof MongoRepository) {
                 acl = await this.repo.findOne({ uid: entityId });
-                acl = acl ? new AccessControlListMongo(acl) : null;
+                acl = acl ? new AccessControlListMongo(acl) : undefined;
             }
             else {
-                acl = await this.repo.findOne({ uid: entityId });
-                acl = acl ? new AccessControlListSQL(acl) : null;
-            }
-            // Store a copy in the cache for faster retrieval next time
-            if (acl && this.cacheClient) {
-                void this.cacheClient.setex(`${CACHE_BASE_KEY}.${entityId}`, this.cacheTTL, JSON.stringify(acl));
+                acl = await this.repo.findOne({ where: { uid: entityId } });
+                acl = acl ? new AccessControlListSQL(acl) : undefined;
             }
         }
-        // Populate request-scoped cache before fetching the parent chain so recursive
-        // calls for the same uid are served from memory.
-        if (reqCache) {
-            reqCache.set(entityId, acl);
+        // Store a copy in the cache for faster retrieval next time.
+        if (acl && this.cache) {
+            this.cache.save(entityId, acl).catch((err) => {
+                this.logger?.warn(`ACLUtils: Cache save failed for ACL ${entityId}.`);
+                this.logger?.debug(err);
+            });
         }
         // Retrieve the parent ACL and assign it if available. Don't populate parents we've
         // already found to prevent a circular dependency.
         if (acl && acl.parentUid && !parentUids.includes(acl.parentUid)) {
             parentUids.push(acl.parentUid);
-            acl.parent = await this.findACL(acl.parentUid, parentUids, reqCache);
+            acl.parent = await this.findACL(acl.parentUid, parentUids, options);
         }
         return acl;
     }
     /**
-     * Deletes the ACL with the given identifier from the database.
+     * Deletes the ACL with the given identifier from the database, returning the document that was actually
+     * deleted (or `undefined` if none existed) — captured atomically as part of the delete itself (Mongo:
+     * `findOneAndDelete`; SQL: a `findOne` immediately followed by the `delete`, both inside this method's own
+     * `acl` transaction), not a separate, earlier read. A caller using the return value as a restore snapshot
+     * (see `RepoUtils.delete()`/`truncate()`'s `registerRollbackHook()` usage) always gets the exact row that
+     * was removed, never a possibly-stale one raced by a concurrent legitimate write between an earlier read
+     * and this delete — and restoring it later still goes through `saveACL()`'s own optimistic-lock version
+     * check, so a restore attempt can't clobber a *newer* row that appeared after this delete either.
+     *
+     * Runs in its own transaction scoped to the `acl` connection (see `Transactional`) rather than trying to
+     * join whatever transaction the caller is itself in — `acl` is frequently configured as its own, separate
+     * datastore (a documented, supported deployment shape), so a caller's session/entityManager almost never
+     * actually belongs to the same physical connection this repo does. Reusing it directly used to throw
+     * (Mongo) or silently target the wrong connection (SQL).
+     *
      * @param uid The unique identifier of the ACL to remove.
      */
     async removeACL(uid) {
-        if (this.enabled) {
-            try {
-                if (this.repo instanceof MongoRepository) {
-                    await this.repo.deleteOne({ uid });
-                }
-                else if (this.repo) {
-                    await this.repo.delete({ uid });
+        if (!this.enabled) {
+            return undefined;
+        }
+        if (!this.repo) {
+            throw new Error("repo is not set.");
+        }
+        const ctx = transactionContext.getStore();
+        let removed;
+        try {
+            if (this.repo instanceof MongoRepository) {
+                const deleted = await this.repo.findOneAndDelete({ uid }, { session: ctx?.session });
+                removed = deleted ? new AccessControlListMongo(deleted) : undefined;
+            }
+            else {
+                const repo = ctx?.entityManager ? ctx.entityManager.getRepository(AccessControlListSQL) : this.repo;
+                const existing = await repo.findOne({ where: { uid } });
+                if (existing) {
+                    await repo.delete({ uid });
+                    removed = new AccessControlListSQL(existing);
                 }
             }
-            catch (err) {
-                // It's okay if this fails because no document exists
+        }
+        catch (err) {
+            // The error "ns not found" occurs when the collection doesn't exist yet (e.g. a fresh deployment
+            // that has never written an ACL) - matches RepoUtils.truncate()'s handling of the same driver
+            // quirk. Any other error is a genuine failure and must propagate, not be silently treated as "this
+            // ACL is already gone".
+            if (err?.message !== "ns not found") {
+                throw err;
             }
         }
+        // Without this, a deleted ACL stays readable from the cache for up to `cacheTTL` seconds,
+        // so permissions the deletion was meant to revoke would continue to apply during that window.
+        if (this.cache) {
+            await this.cache.delete(uid);
+        }
+        return removed;
     }
     /**
      * Compares two ACLs to see if they have been modified and returns the total number of changes between them.
@@ -290,13 +291,8 @@ export class ACLUtils {
                 }
             }
             if (foundRecord) {
-                // Check to see if any of the permissions changed for this record
-                result += foundRecord.create !== recordA.create ? 1 : 0;
-                result += foundRecord.delete !== recordA.delete ? 1 : 0;
-                result += foundRecord.full !== recordA.full ? 1 : 0;
-                result += foundRecord.read !== recordA.read ? 1 : 0;
-                result += foundRecord.special !== recordA.special ? 1 : 0;
-                result += foundRecord.update !== recordA.update ? 1 : 0;
+                // Check to see if the granted actions changed for this record
+                result += this.actionsChanged(foundRecord.actions, recordA.actions) ? 1 : 0;
             }
             else {
                 result++;
@@ -313,13 +309,8 @@ export class ACLUtils {
                 }
             }
             if (foundRecord) {
-                // Check to see if any of the permissions changed for this record
-                result += foundRecord.create !== recordB.create ? 1 : 0;
-                result += foundRecord.delete !== recordB.delete ? 1 : 0;
-                result += foundRecord.full !== recordB.full ? 1 : 0;
-                result += foundRecord.read !== recordB.read ? 1 : 0;
-                result += foundRecord.special !== recordB.special ? 1 : 0;
-                result += foundRecord.update !== recordB.update ? 1 : 0;
+                // Check to see if the granted actions changed for this record
+                result += this.actionsChanged(foundRecord.actions, recordB.actions) ? 1 : 0;
             }
             else {
                 result++;
@@ -328,55 +319,107 @@ export class ACLUtils {
         return result;
     }
     /**
-     * Stores the given access control list into the ACL database.
+     * Compares two lists of granted actions, ignoring order, to see if they differ.
+     */
+    actionsChanged(a, b) {
+        if (a.length !== b.length) {
+            return true;
+        }
+        const sortedA = [...a].sort();
+        const sortedB = [...b].sort();
+        return sortedA.some((action, i) => action !== sortedB[i]);
+    }
+    /**
+     * Stores the given access control list into the ACL database. By default, bumps the version for optimistic
+     * locking (see below) — pass `preserveVersion: true` to instead write `acl` back with its own version
+     * exactly as given, for restoring a known-good snapshot (see `RepoUtils.delete()`/`truncate()`'s
+     * `registerRollbackHook()` usage) rather than applying a new change on top of whatever's currently stored.
+     * A restore only ever targets a uid with nothing currently at it (that's the point — the entity-side
+     * transaction it was tied to is being rolled back, so the row it deleted should no longer exist); if
+     * something *does* exist there already, the restore is refused rather than silently clobbering it.
+     *
+     * Runs in its own transaction scoped to the `acl` connection (see `Transactional`) rather than trying to
+     * join whatever transaction the caller is itself in — see `removeACL`'s doc comment for why. Callers that
+     * need the entity-side write and this ACL save to stay consistent should register a compensating action
+     * via `registerRollbackHook()`.
      *
      * @param acl The ACL to store.
+     * @param options Set `preserveVersion: true` to restore `acl` exactly as given (see above) instead of the
+     * normal optimistic-locking update semantics.
      * @return Returns the ACL that was stored in the database.
      */
-    async saveACL(acl) {
+    async saveACL(acl, options) {
         let result = null;
         if (!this.enabled || !acl) {
             return result;
         }
+        if (!this.repo) {
+            throw new Error("repo is not set.");
+        }
+        const ctx = transactionContext.getStore();
+        const preserveVersion = !!options?.preserveVersion;
         if (this.repo instanceof MongoRepository) {
             const mACL = new AccessControlListMongo(acl);
-            const existing = await this.repo.findOne({ uid: acl.uid });
-            // If no changes have been made between versions ignore this request
-            if (existing && this.diffACL(existing, acl) === 0) {
-                return existing;
+            const existing = await this.repo.findOne({ uid: acl.uid }, {
+                session: ctx?.session,
+            });
+            if (preserveVersion) {
+                if (existing) {
+                    throw new Error(`Cannot restore ACL ${acl.uid}: a document already exists at this uid.`);
+                }
             }
-            // Make sure that the versions match before we proceed
-            if (existing && existing.version !== mACL.version) {
-                throw new Error(`The acl to save must be of the same version. ACL=${acl.uid}, Expected=${existing.version}, Actual=${mACL.version}`);
+            else {
+                // If no changes have been made between versions ignore this request
+                if (existing && this.diffACL(existing, acl) === 0) {
+                    return existing;
+                }
+                // Make sure that the versions match before we proceed
+                if (existing && existing.version !== mACL.version) {
+                    throw new Error(`The acl to save must be of the same version. ACL=${acl.uid}, Expected=${existing.version}, Actual=${mACL.version}`);
+                }
             }
             const aclMongo = new AccessControlListMongo({
                 ...acl,
                 dateModifed: new Date(),
-                version: existing ? mACL.version + 1 : 0,
+                version: preserveVersion ? mACL.version : existing ? mACL.version + 1 : 0,
             });
-            result = await this.repo.save(aclMongo);
+            // ACLs are single-row-per-uid (never trackChanges) - merge by `uid` rather than requiring `_id` to
+            // have survived the `{...acl, ...}` spread above, or a stale/missing `_id` would insert a
+            // duplicate document instead of updating the one `existing` just found.
+            result = await this.repo.save(aclMongo, { session: ctx?.session, mergeByUid: true });
         }
-        else if (this.repo) {
+        else {
+            const repo = ctx?.entityManager ? ctx.entityManager.getRepository(AccessControlListSQL) : this.repo;
             const sACL = new AccessControlListSQL(acl);
-            const existing = await this.repo.findOne({ uid: acl.uid });
-            // If no changes have been made between versions ignore this request
-            if (existing && this.diffACL(existing, acl) === 0) {
-                return existing;
+            const existing = await repo.findOne({ where: { uid: acl.uid } });
+            if (preserveVersion) {
+                if (existing) {
+                    throw new Error(`Cannot restore ACL ${acl.uid}: a document already exists at this uid.`);
+                }
             }
-            // Make sure that the versions match before we proceed
-            if (existing && existing.version !== sACL.version) {
-                throw new Error(`The acl to save must be of the same version. ACL=${acl.uid}, Expected=${existing.version}, Actual=${sACL.version}`);
+            else {
+                // If no changes have been made between versions ignore this request
+                if (existing && this.diffACL(existing, acl) === 0) {
+                    return existing;
+                }
+                // Make sure that the versions match before we proceed
+                if (existing && existing.version !== sACL.version) {
+                    throw new Error(`The acl to save must be of the same version. ACL=${acl.uid}, Expected=${existing.version}, Actual=${sACL.version}`);
+                }
             }
             const aclSQL = new AccessControlListSQL({
                 ...acl,
                 dateModifed: new Date(),
-                version: existing ? sACL.version + 1 : 0,
+                version: preserveVersion ? sACL.version : existing ? sACL.version + 1 : 0,
             });
-            result = await this.repo.save(aclSQL);
+            result = await repo.save(aclSQL);
         }
-        // Store a copy in the cache for faster retrieval next time
-        if (this.cacheClient && result) {
-            void this.cacheClient.setex(`${CACHE_BASE_KEY}.${result.uid}`, this.cacheTTL, JSON.stringify(result));
+        // Store a copy in the cache for faster retrieval next time.
+        if (this.cache && result) {
+            this.cache.save(result.uid, result).catch((err) => {
+                this.logger?.warn(`ACLUtils: Cache save failed for ACL ${result?.uid}.`);
+                this.logger?.debug(err);
+            });
         }
         return result;
     }
@@ -416,6 +459,9 @@ export class ACLUtils {
                     // Copy over the new records from code
                     existing.records = defaultAcl.records;
                     defaultAcl = existing;
+                    // The user-defined override record was already created on a previous run. Look it
+                    // up so callers still receive a valid ACL to register routes against instead of `null`.
+                    result = (await this.findACL(acl.uid)) ?? null;
                 }
                 else {
                     // Create the user-defined override record
@@ -425,7 +471,7 @@ export class ACLUtils {
                         records: [],
                     });
                 }
-                // Always save the ACL into the datastore
+                // Always save the ACL into the datasource
                 await this.saveACL(defaultAcl);
                 attempts = maxAttempts;
             }
@@ -443,7 +489,49 @@ export class ACLUtils {
         return result;
     }
     /**
-     * Retrieves the first available record in the provided ACL associated with the provided user.
+     * Atomic removal of multiple ACLs in a single `acl`-scoped transaction (see `@Transactional`), returning
+     * whichever of them actually existed to be deleted (see `removeACL()`'s doc comment for why the returned
+     * documents — not a separate, earlier read — are the right thing to snapshot for a possible restore).
+     *
+     * Deliberately sequential, not batched-concurrent: every `removeACL()` call below resolves to this same
+     * `acl` datasource, so `@Transactional`'s merge logic joins all of them onto the one MongoDB
+     * `ClientSession`/SQL `EntityManager` this method opened. Running these with `Promise.all`
+     * would issue overlapping commands against one session, which drivers reject or misorder.
+     *
+     * @param uids The unique identifiers of the ACLs to remove.
+     */
+    async removeACLs(uids) {
+        const removed = [];
+        for (const uid of uids) {
+            const acl = await this.removeACL(uid);
+            if (acl) {
+                removed.push(acl);
+            }
+        }
+        return removed;
+    }
+    /**
+     * Atomic save of multiple ACLs in a single `acl`-scoped transaction (see `Transactional`). Used to restore
+     * a batch of ACL snapshots — e.g. by a `registerRollbackHook()` compensating action — if the entity-side
+     * transaction they were removed alongside subsequently fails. Always restores each ACL's own version as
+     * given (see `saveACL()`'s `preserveVersion` option) rather than bumping it, since this is a restore, not
+     * a new change.
+     *
+     * Deliberately sequential. See `removeACLs()`'s doc comment for why.
+     *
+     * @param acls The ACLs to store.
+     */
+    async saveACLs(acls) {
+        for (const acl of acls) {
+            await this.saveACL(acl, { preserveVersion: true });
+        }
+    }
+    /**
+     * Retrieves the most specific record in the provided ACL associated with the provided user: an exact
+     * uid/anonymous match beats a role match, which beats a wildcard (`.*`/`*`) match — regardless of where
+     * each record sits in `acl.records`. Without this, a wildcard grant authored before a specific record
+     * (a natural authoring order) would silently shadow that more specific record. Only falls back to the
+     * parent ACL when nothing in this ACL's own records matches at all.
      *
      * @param acl The access control list that will be searched.
      * @param user The user to find a record for.
@@ -453,10 +541,25 @@ export class ACLUtils {
         if (!acl) {
             return null;
         }
+        let roleMatch = null;
+        let wildcardMatch = null;
         for (const record of acl.records) {
-            if (this.userMatchesId(user, record.userOrRoleId)) {
+            const specificity = this.matchSpecificity(user, record.userOrRoleId);
+            if (specificity === "exact") {
                 return record;
             }
+            else if (specificity === "role") {
+                roleMatch = roleMatch ?? record;
+            }
+            else if (specificity === "wildcard") {
+                wildcardMatch = wildcardMatch ?? record;
+            }
+        }
+        if (roleMatch) {
+            return roleMatch;
+        }
+        if (wildcardMatch) {
+            return wildcardMatch;
         }
         return acl.parent ? this.getRecord(acl.parent, user) : null;
     }
@@ -493,6 +596,30 @@ __decorate([
     Init,
     __metadata("design:type", Function),
     __metadata("design:paramtypes", []),
-    __metadata("design:returntype", void 0)
+    __metadata("design:returntype", Promise)
 ], ACLUtils.prototype, "init", null);
+__decorate([
+    Transactional("acl"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], ACLUtils.prototype, "removeACL", null);
+__decorate([
+    Transactional("acl"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], ACLUtils.prototype, "saveACL", null);
+__decorate([
+    Transactional("acl"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array]),
+    __metadata("design:returntype", Promise)
+], ACLUtils.prototype, "removeACLs", null);
+__decorate([
+    Transactional("acl"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array]),
+    __metadata("design:returntype", Promise)
+], ACLUtils.prototype, "saveACLs", null);
 //# sourceMappingURL=ACLUtils.js.map